Автономный бэкенд: обзор

Автономный бэкенд — репозиторий одного сайта, которым владеете вы: API Worker со своей D1, сайт Astro, опубликованный контент, миграции и скрипты развёртывания. API читает только собственную базу. Статически собранным страницам ничего не нужно от Dee Wan. Маршруты Blog, поиск по сайту, секции «Последние записи», комментарии посетителей, формы и необязательный предпросмотр обращаются к Dee Wan при каждом запросе: см. Что по-прежнему зависит от Dee Wan. Эта страница описывает генерируемые исходники, а не развёртывание в Cloudflare, прошедшее приёмку.

API и статически собранные страницы — это снимок. В них то, что было опубликовано на момент генерации, а последующие публикации попадают в них, только когда вы снова сгенерируете и развернёте проект. Актуальный контент возвращают публичный API CMS и маршруты сайта, которые его читают.

Сгенерированный API проверяет длину и шаблон текста по заданным правилам. После изменения правил нужно заново сгенерировать и развернуть бэкенд; подробнее — в справочнике API.

Для настройки отключаться не нужно. Расширение бэкенда описывает реестр собственных расширений и работу с подключённым репозиторием. Контракт отключения описывает остановку управляемой регенерации.

Генерация, передача исходников и развёртывание

Это разные шаги. Исходники генерируются на вашей машине. CMS их не компилирует.

Шаг	Способ	Что происходит
Сгенерировать автономный бэкенд	npm run backend:generate (ниже)	Локальная SQLite-копия CMS открывается только для чтения. Проект генерируется и проверяется на временной целевой базе. Нет push или развёртывания. --model <id> ограничивает результат одной моделью.
Впервые сгенерировать и опубликовать	npm run backend:deliver	Локально генерирует проект, отправляет его в ваш репозиторий и запускает первое развёртывание. --media переносит публичные медиа в ваше хранилище.
Опубликовать уже сгенерированный коммит	npm run wire:github -- --managed (публикация через GitHub)	Отправляет уже сгенерированный проект, проверяет удалённый коммит и запускает развёртывание именно этого коммита.
Развернуть из существующего репозитория	Настройки → Код и публикация → Параметры разработчика → Standalone-бэкенд → Развернуть	Вызывает build webhook. dee-wan-build.yml в репозитории забирает определения, запускает уже закоммиченный в нём регенератор, создаёт коммит и развёртывает. Нужен репозиторий, где уже есть сгенерированные исходники.
Генерация исходников на стороне CMS	Настройки → Код и публикация → Сгенерировать исходники через GitHub	Недоступна. У Worker CMS нет среды сборки исходников, он отвечает source_build_runtime_unavailable.

npm run backend:generate -- --site <site-id> --source <cms.sqlite> --dest <output-directory> --db <scratch.sqlite>

Сайту с активным релизом управляемого рендерера нужен ещё --template-artifacts <dir>: локальная копия артефактов шаблона этого релиза. Каждый артефакт должен быть обычным файлом в настоящем каталоге по своему ключу (managed/<site>/<candidate>/<role>.json). Генератор не переходит по символическим ссылкам. Без этого параметра генерация отклоняется с managed_release_custody_unavailable. npm run backend:deliver принимает тот же флаг. Генерация с --model не экспортирует управляемый рендерер. Команда npm run backend:generate:all не позволяет передать этот флаг, поэтому генерация такого сайта этой командой отклоняется.

Генерация читает согласованный временный снимок SQLite. Последующие изменения в работающей CMS не прерывают сборку и не попадают в результат. Пакетная генерация использует один снимок для всех сайтов. Удаление полей из сгенерированной схемы требует --allow-destructive как для отдельной модели, так и для сайта целиком.

Каждый из этих способов сохраняет исходники в каталог или отправляет их в Git-репозиторий. Скачивания архива нет. npm run backend:deliver использует авторизацию GitHub через устройство, данные доступа Cloudflare и токен записи, проверяет развёртывание и предлагает отключение.

Эти команды выполняются в репозитории Dee Wan. У генерируемого репозитория свои команды, они перечислены в разделе Снимок, миграции, развёртывание и откат. Публикация через GitHub разделяет GitHub App административного интерфейса и авторизацию CLI через устройство.

Повтор запроса с тем же идентификатором попытки использует уже закреплённый исходный код и не запускает вторую сборку. Если ответ webhook не пришёл вовремя, сборка могла начаться: Dee Wan сохраняет за ней слот и учётные данные для сообщения о результате. Явный отказ освобождает слот. Для зависшей попытки действует прежний срок истечения.

Сохранить подключение или отключиться

Подключённый репозиторий обновляется через управляемую регенерацию, которую нужно запускать явно. dee-wan-build.yml забирает определения сайта с токеном сборки, регенерирует, проверяет, создаёт коммит и вызывает deploy-from-repository.yml для этого точного коммита. Пока подключение сохранено, разработчики могут менять собственные и совместно используемые части проекта (owned/shared), коммитить и развёртывать их.

Отключённый репозиторий прекращает эти управляемые обновления. Репозиторный workflow развёртывает закоммиченные исходники, не загружая определения CMS. Отключение не добавляет точек расширения. Следуйте руководству по отключению: наличие репозитория само по себе не доказывает независимое хранение медиа или успешное развёртывание.

Если npm run regenerate прервался или последующая проверка завершилась ошибкой, запустите ту же команду повторно. Временная папка восстановления хранит сведения о созданных файлах до завершения генерации Prisma и проверки пользовательских расширений. Повторный запуск распознаёт собственные частичные результаты и сохраняет ваши файлы из зон owned. Если вы изменили сгенерированный файл, конфликт по-прежнему нужно разрешить: восстановление не затирает такие правки. После успешного завершения команда удаляет свой журнал и временные файлы.

В один каталог одновременно пишет только одна команда генерации. Вторая отклоняется, пока первая работает. После аварийного завершения процесса повторный запуск автоматически восстанавливает доступ к каталогу.

Сайт

Astro предварительно рендерит модели страниц из генерируемого pages.json и обслуживает их через Worker сайта. Секции hero, rich text, media/text, feature-grid и call-to-action используют принятые оформление и тему. Репозиторий создаёт навигацию, footer, redirects, robots и необязательный sitemap. Статически собранные страницы используют закоммиченный снимок страниц. Маршруты Blog, страницы поиска и страницы с секцией «Последние записи», секцией «Поиск по сайту» или комментариями посетителей отдаются на каждый запрос с данными из публичного API Dee Wan (/v1 на хосте сайта), поэтому во время работы им нужен Dee Wan; самому сгенерированному API — нет. См. что по-прежнему зависит от Dee Wan и флаг совместимости.

Собственные компоненты head/body, слоты макета, обёртки и замены секций, интеграции Astro, интерактивные компоненты islands и страницы /owned/ позволяют расширять сайт без отключения. Предпросмотр выключен до настройки previewApiOrigin. Формат страницы описан в контракте документа страницы.

Что не входит

Репозиторий не воспроизводит административный интерфейс CMS, систему пользователей, процесс согласования, хост плагинов, импорт, генерацию с помощью ИИ, исходящие вебхуки, черновики или историю. В нём нет самих медиафайлов, произвольных прикладных маршрутов или автоматического создания привязок, которые вы добавляете сами. Собственную бизнес-логику и маршруты с проверкой по схеме размещайте в предназначенных для этого частях проекта (owned).

Справочник и детали

• Справочник API: маршруты, аутентификация, токены чтения, проверки доступа, ошибки, OpenAPI, вход в бэкенд, развёртывание и откат.
• Детали реализации: файлы, зависимости, ресурсы Cloudflare, отображение таблиц, экспортированный управляемый рендерер и кеш ответов.
• Расширение бэкенда: куда помещать собственный код.
• Отделение и проверка и восстановление автономного сайта.

Хранение экспортов

Команда npm run backend:exports управляет реестром graduation.exports.json, который хранится у владельца сайта. В нём записаны неизменяемые снимки и манифесты медиафайлов. Очистка сохраняет файлы текущего экспорта, предыдущего экспорта для отката, закреплённых и самых новых экспортов, а также экспортов в пределах заданного срока хранения. Публичное и приватное хранилища учитываются отдельно; превью сохранённых экспортов тоже защищены от удаления.

Сначала создайте реестр для своего хранилища. Каждый экспорт добавляйте в него до развёртывания. Команду activate выполняйте только после проверки развёрнутого экспорта: предыдущий активный экспорт останется доступен для отката. Новый экспорт закреплён, пока вы явно не снимете закрепление командой unpin. Команда policy --days 30 --keep 10 задаёт срок хранения и число последних экспортов. clean показывает план; удаление выполняет только clean --apply. Команда удаляет лишь файлы просроченных незащищённых экспортов. Файлы, которых нет ни в одном зарегистрированном экспорте, она не трогает. Отсутствующий или изменённый манифест, неизвестный активный экспорт или другое хранилище останавливают очистку.

npm run backend:exports -- init --ledger ./exports --site <site-id> --public-dir /srv/media
npm run backend:exports -- register --ledger ./exports --artifact ./generated-site
npm run backend:exports -- activate --ledger ./exports --id <export-id>
npm run backend:exports -- clean --ledger ./exports --public-dir /srv/media

Каталоги нужно создать заранее. Для приватных файлов добавьте --private-dir. Для R2 используйте переменные окружения из справки npm run backend:exports -- --help. Учётные данные остаются на вашей машине. CMS не очищает это хранилище и не получает доступ к его учётным данным.

При запуске backend:deliver задайте EXIT_EXPORT_LEDGER_DIRECTORY. Перенос медиафайлов и развёртывание будут использовать ту же блокировку, что и очистка. Экспорт попадает в реестр до развёртывания; текущий экспорт и экспорт для отката меняются только после успешной проверки развёртывания. Если развёртывание могло начаться, но результат не подтверждён, новый экспорт остаётся закреплённым. При отказе до запуска развёртывания новое автоматическое закрепление снимается. У каждого сайта свой префикс медиафайлов и свой реестр: сайты могут использовать один бакет, не затрагивая файлы друг друга при очистке. Все процессы, записывающие экспорты одного сайта, должны использовать его реестр. Храните реестр вместе с материалами для восстановления.

Следующий шаг

Пройдите четыре пошаговых руководства, начиная с правки и публикации.

---

Стабильная версия ещё не выпущена (pre-MVP)
Коммит исходного кода: e207e63239a627fbd2ae9c414ef7c6eb19fcfe5a (с локальными изменениями)
Дата сборки (UTC): 2026-10-21T09:28:24.214Z
Коммит для обновления: не определён: в рабочей копии есть изменения. Примечания к выпуску