195 lines
22 KiB
Markdown
195 lines
22 KiB
Markdown
# Site Engine
|
||
|
||
Движок сайтов на Markdown + YAML: страницы собираются из **layouts** и **fragments**, контент и структура живут в файлах, результат — статический сайт. Подключение агента по MCP — часть архитектуры (этап M3).
|
||
|
||
Документы проекта лежат в `docs/`: ТЗ v0.1, архитектурное ревью и журнал принятых решений (ADR-001…006). Код следует журналу решений.
|
||
|
||
## Быстрый старт
|
||
|
||
```bash
|
||
pip install -e ".[dev]" # ядру нужны jinja2, PyYAML, markdown-it-py, click
|
||
site-engine validate examples/studio-site
|
||
site-engine build examples/studio-site --out /tmp/studio-dist
|
||
site-engine preview examples/studio-site drafts/next > /tmp/draft.html
|
||
site-engine fragments # 15 встроенных фрагментов
|
||
make test # или: pytest
|
||
```
|
||
|
||
Результат сборки: `OUT/<build_id>/` и симлинк `OUT/current`, который переключается атомарно. Неудачная сборка `current` не трогает.
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
site-engine/
|
||
├── pyproject.toml # зависимости ядра и extras: server, mcp, images, dev
|
||
├── Makefile Dockerfile # Dockerfile — для M2+ (админка, формы, MCP)
|
||
├── docs/ # ТЗ, ревью, журнал решений
|
||
├── examples/studio-site/ # сайт-пример из SiteMap.md (услуги, формы, коллекция, редирект)
|
||
├── .env.example # переменные окружения для админки
|
||
├── tests/ # 206 тестов: ядро, сборка, безопасность, запись, вход и редактор
|
||
└── src/site_engine/
|
||
├── cli.py # validate · build · preview · fragments
|
||
├── errors.py # Issue/Report: код, путь к полю, серьёзность, подсказка
|
||
├── core/
|
||
│ ├── values.py # Literal | Binding | LinkRef | Query (ADR-002)
|
||
│ ├── models.py # Block, Page, Entry, Fragment, Layout, Collection…
|
||
│ ├── registry.py # чистая загрузка каталога сайта в память (ADR-001)
|
||
│ ├── routes.py # нормализация маршрутов, таблица, коллизии
|
||
│ ├── resolve.py # привязки, ссылки, запросы MVP
|
||
│ ├── validate.py # workspace-проверки, release-проверки, правила сайта
|
||
│ ├── draft_check.py # проверка при сохранении: новый текст файла против реестра
|
||
│ ├── page_ops.py # добавить, переместить, удалить блок по id в сыром front matter
|
||
│ └── render.py # Jinja SandboxedEnvironment, разрешение props по схеме
|
||
├── build/pipeline.py # load → validate → render → релиз → атомарный current
|
||
├── parsing/ # безопасный YAML, front matter, Markdown (raw HTML выключен)
|
||
├── storage/ # safe_join, atomic_write, SiteLock, .engine/history
|
||
├── services/ # auth (вход админа), ContentService (if_match, история), publish; stubs: changeset, forms
|
||
├── builtin/ # base.css и 15 фрагментов ядра (ADR-006)
|
||
├── db/ # SQLAlchemy-модели служебных таблиц (M2)
|
||
├── web/ # FastAPI-фабрика; admin/: handlers (вход, обзор), editor (страницы, блоки, записи, публикация), forms, шаблоны, routes-адаптер
|
||
└── mcp/ # перечень инструментов MVP (M3)
|
||
```
|
||
|
||
## Запуск в Docker
|
||
|
||
Один том `/data`, в нём три каталога. Всё, что важно сохранить, лежит на хосте в `./data`.
|
||
|
||
| На хосте | В контейнере | Что это |
|
||
|---|---|---|
|
||
| `data/site` | `/data/site` | Ваш сайт: `site.yaml`, `pages/`, `content/`, фрагменты. Его правит редактор |
|
||
| `data/dist` | `/data/dist` | Опубликованные релизы и симлинк `current` |
|
||
| `data/state` | `/data/state` | Состояние входа и журнал `audit.jsonl` |
|
||
|
||
```bash
|
||
docker build -t site-engine .
|
||
docker run --rm -it site-engine site-engine hash-password # спросит пароль, напечатает хеш
|
||
docker run --rm site-engine site-engine gen-secret # ключ подписи сессий
|
||
cp .env.example .env # впишите хеш и ключ
|
||
|
||
mkdir -p data && cp -r examples/studio-site data/site # или положите свой сайт в data/site
|
||
docker run -d --name site-engine -p 8181:8000 --env-file .env -v "$PWD/data:/data" site-engine
|
||
```
|
||
|
||
Админка: `http://localhost:8181/admin/` (на обзоре сверху показаны абсолютные пути, которыми пользуется приложение), опубликованный сайт: `http://localhost:8181/`. Проверка того, что видит контейнер:
|
||
|
||
```bash
|
||
docker logs site-engine # строка «site-engine: site=/data/site, dist=/data/dist, state=/data/state, admin=on»
|
||
docker exec site-engine env | grep '^SITE_' # SITE_ROOT, SITE_DIST, SITE_STATE_DIR должны начинаться с /data/
|
||
```
|
||
|
||
Если вместо `/data/...` там относительные пути (`examples/studio-site`, `dist`), эти строки остались в вашем `.env` от старой версии: удалите `SITE_ROOT`, `SITE_DIST`, `SITE_STATE_DIR` из `.env`, так как значения из `--env-file` перекрывают значения из образа. При старте приложение само пишет об этом предупреждение.
|
||
|
||
Правила для `.env` при `docker run --env-file`:
|
||
|
||
- **Без кавычек.** Docker не снимает их, они станут частью значения.
|
||
- **Без комментариев в конце строки.** `KEY=value # текст` даёт значение «value # текст».
|
||
- **Знак `$` в хеше экранировать не нужно.** (Для `docker compose` и его `.env` его нужно удваивать: `$$`.)
|
||
|
||
Приложение проверяет эти значения строго: хеш, ключ, логин, флаг Secure и host с лишними символами не принимаются молча, `/admin/` не включается, а в `docker logs` пишется причина.
|
||
|
||
| Симптом | Причина |
|
||
|---|---|
|
||
| `/admin/` даёт 404 | Не заданы `SITE_ADMIN_PASSWORD_HASH` и `SITE_SECRET_KEY`, ключ короче 32 символов или в значении кавычки или комментарий; причина в `docker logs`: «админка отключена: …» |
|
||
| «Сайт не загружен» на обзоре | В `data/site` нет `site.yaml` или том не смонтирован; на обзоре виден абсолютный путь, который проверял движок |
|
||
| Опубликованного сайта нет на хосте | Том не смонтирован (`-v "$PWD/data:/data"`): релизы лежат внутри контейнера и пропадут вместе с ним |
|
||
| После ввода пароля снова страница входа | Cookie с флагом Secure не принимается по `http://` с адреса не `localhost`: поставьте `SITE_COOKIE_SECURE=0` |
|
||
| Ответ 422 с `"loc": ["query","request"]` | Образ собран из версии до исправления: пересоберите `docker build` |
|
||
|
||
Контейнер работает от root, поэтому файлы в `data/` на Linux будут принадлежать root. Чтобы этого избежать, добавьте `--user "$(id -u):$(id -g)"`.
|
||
|
||
## Вход в админку
|
||
|
||
Самый простой вариант: **один администратор, без ролей**, логин и хеш пароля задаются переменными окружения, БД для входа не нужна.
|
||
|
||
```bash
|
||
site-engine hash-password # спросит пароль (от 12 символов) и напечатает scrypt-хеш
|
||
site-engine gen-secret # ключ подписи сессий
|
||
cp .env.example .env # впишите SITE_ADMIN_PASSWORD_HASH и SITE_SECRET_KEY
|
||
SITE_COOKIE_SECURE=0 uvicorn site_engine.web.app:create_app --factory --env-file .env # локально по http
|
||
```
|
||
|
||
Без `SITE_ADMIN_PASSWORD_HASH` и `SITE_SECRET_KEY` (не короче 32 символов) `/admin/` не включается вообще: нет пароля — нет входа. После входа `/admin/` показывает страницы сайта со статусами, коллекции и результат проверки (только чтение; редактор — следующий шаг).
|
||
|
||
| Мера | Как сделано |
|
||
|---|---|
|
||
| Пароль | scrypt (N=2^15, r=8, p=1), соль на каждый хеш, сравнение за постоянное время |
|
||
| Сессия | Подписанная cookie `se_session`: HttpOnly, SameSite=Strict, Secure (выключается только `SITE_COOKIE_SECURE=0`), Path=/admin, срок `SITE_SESSION_HOURS` (по умолчанию 8) |
|
||
| Выход | Увеличивает «эпоху» в `.engine/auth_epoch`: все выданные cookie сразу недействительны, в том числе украденные |
|
||
| Перебор | 5 неудач за 15 минут блокируют IP (429 + Retry-After), общий порог 30 на все адреса; хеш считается и при неверном логине, поэтому по времени логин не угадать |
|
||
| CSRF | POST принимается только с Origin или Referer того же хоста; выход дополнительно требует токен, привязанный к сессии |
|
||
| Заголовки | CSP без inline, `frame-ancestors 'none'`, `no-store`, `X-Frame-Options: DENY`, `nosniff` |
|
||
| Аудит | `.engine/audit.jsonl`: вход, неудача, блокировка, выход; без паролей и без введённого логина |
|
||
|
||
Ограничения этого варианта:
|
||
|
||
- Один пользователь, роль всегда `admin`; таблицы `users` и `api_tokens` из `db/models.py` пока не используются.
|
||
- Окно попыток хранится в памяти процесса: при нескольких воркерах у каждого свой счётчик, после перезапуска он обнуляется.
|
||
- За обратным прокси `request.client.host` — адрес прокси, поэтому ограничение по IP работает как общее. Доверие к `X-Forwarded-For` нужно включать явно (задача M2).
|
||
- Выход завершает все сессии администратора сразу, отдельного списка устройств нет.
|
||
- Отдельная смена пароля: сгенерировать новый хеш и перезапустить сервис; чтобы разлогинить всех, поменяйте `SITE_SECRET_KEY`.
|
||
|
||
## Редактор
|
||
|
||
После входа в `/admin/` доступны страницы, контент и публикация. Все правки идут через `ContentService`: блокировка сайта, `if_match` по хешу файла, проверка синтаксиса, история в `.engine/history/`, атомарная запись. Редактор пишет только в `pages/` и `content/`; фрагменты, layouts, схемы и `site.yaml` через него изменить нельзя.
|
||
|
||
| Экран | Что умеет |
|
||
|---|---|
|
||
| Страницы | Список со статусами и адресами; создание черновика (путь, заголовок, layout) |
|
||
| Страница | Заголовок, статус, layout, адрес, описание, текст Markdown; блоки по регионам и слотам: добавить, ↑/↓, скрыть и показать, удалить; предпросмотр в изолированном фрейме; список проблем страницы |
|
||
| Блок | Форма строится из манифеста фрагмента: текст, Markdown, число, список, группа, выбор, ссылка (страница, запись, адрес), запрос к коллекции, ассет; у каждого поля поле «привязка» (`entry.title`, `page.body`…); якорь, заметка, скрыть, `requires` по флагам сайта |
|
||
| Контент | Записи коллекций: поля по схеме, статус, текст Markdown, создание черновика, предпросмотр |
|
||
| Публикация | Сборка релиза, список релизов, возврат к прежнему релизу |
|
||
|
||
Гарантии, которые проверены тестами:
|
||
|
||
- **Без потерь.** Форма открывается из файла и отправляется обратно без изменений: у каждого блока примера, всех страниц и записей YAML остаётся тем же по смыслу. Неизвестные ключи не пропадают, привязки сохраняются.
|
||
- **Конфликты.** Если файл изменили в другом окне, правка получит 409, а чужие изменения не будут перезаписаны.
|
||
- **Проверка при сохранении.** Нельзя сохранить неизвестный фрагмент, несуществующий layout, блок в закреплённый регион, значение не того типа, `{{ }}` в данных, привязку к чужому корню. Пропуск обязательного поля не блокирует сохранение (ADR-003), но он виден в «Проверке страницы», и сборка релиза с ним не пройдёт; опубликованный сайт при этом не меняется.
|
||
- **Безопасность.** Каждый POST требует CSRF-токен и Origin своего хоста; id страниц, блоков и записей проверяются регулярным выражением и поиском в реестре, до пути на диске недоступны; предпросмотр отдаётся в `sandbox`-фрейме с CSP без скриптов; в аудит попадают id и тип действия, но не содержимое.
|
||
|
||
Что работает иначе, чем можно ожидать:
|
||
|
||
- **Без JS.** Порядок блоков меняется кнопками ↑/↓, элементы списков добавляются через «пустую строку» формы. Скачать htmx и SortableJS в окружении без сети было нельзя, поэтому редактор целиком работает на обычных формах. Если положить `htmx.min.js` в `src/site_engine/web/admin/static/`, админка включит `hx-boost` сама (проверено только разметкой, с настоящим htmx не запускалось).
|
||
- **Первая правка файла переформатирует его YAML** в блочный стиль: `{id: b_1, fragment: hero}` станет несколькими строками. Смысл и порядок ключей сохраняются.
|
||
- **Ассеты** выбираются по пути из подсказки, загрузки файлов в редакторе пока нет.
|
||
- **Блоки не переносятся между регионами**, только внутри своего списка.
|
||
- **Запись коллекции со «лишним» ключом**, которого нет в схеме, нельзя сохранить в статусе `published`, пока ключ не уберут из файла: так требует ADR-003.
|
||
|
||
## Что реализовано
|
||
|
||
| Этап | Состояние |
|
||
|---|---|
|
||
| M0 Контракт и прототип | Готово: формат файлов, модель блоков, load → validate → render, CLI, 15 фрагментов, сайт-пример |
|
||
| M1 Публикуемый движок | Частично: маршруты, ссылки, редиректы, sitemap, атомарная публикация, откат (`services/publish.py`), превью страницы через CLI. Нет: превью по токену, 404-страница из коробки, тема |
|
||
| M2 Коллекции, заявки, доступ | Частично: коллекции, display templates, запросы, формы (разметка, версия формы в релизе), **вход одного администратора с аудитом входов и обзорная страница админки**. Нет: роли, приём заявок, outbox, аудит правок |
|
||
| M3 MCP и редактор | Готово: редактор страниц, блоков и записей на `ContentService`, предпросмотр, публикация и откат из админки. Нет: `patch_page`, changeset (rename, delete), MCP-сервера, перетаскивания, загрузки файлов |
|
||
| M4 | Не начат |
|
||
|
||
## Что проверено, а что нет
|
||
|
||
Тесты и сборка примера выполнялись в окружении без сети: ядро (`core/`, `build/`, `parsing/`, `storage/`, `services/`) и вся логика админки (`web/admin/handlers.py`, `editor.py`, `forms.py`, шаблоны, вход, CSRF, заголовки) запущены и покрыты 206 тестами, включая сквозные через HTML-формы. Тонкий FastAPI-адаптер `web/admin/routes.py` проверен на подставном модуле `fastapi`, а `web/app.py`, `db/`, `mcp/` и `Dockerfile` только компиляцией и чтением: FastAPI, SQLAlchemy и MCP SDK в окружении не было. Ядро намеренно не зависит от pydantic: ошибки должны нести путь к полю (`pages/index.md:regions.main[b_hero].props.title`), а валидация задаётся манифестами фрагментов. Pydantic нужен на границах API (web, mcp).
|
||
|
||
## Соответствие журналу решений
|
||
|
||
| Решение | Где в коде |
|
||
|---|---|
|
||
| ADR-001: сборка не читает SQLite | `core/registry.load_site`, `build/pipeline.build_site` |
|
||
| ADR-002: 4 вида значений, `bind`, запросы MVP | `core/values.py`, `core/resolve.py`; `{{ }}` в данных запрещены (`validate.py`) |
|
||
| ADR-003: draft / release / live, версия формы в релизе | `validate_workspace` vs `validate_release`, `_forms/<id>@<версия>.json`, `switch_current` |
|
||
| ADR-004: `if_match`, блокировка сайта, история | `services/content.py`, `storage/locks.py`, `storage/history.py` |
|
||
| ADR-005: границы доверия | `SandboxedEnvironment`, Markdown без raw HTML, `safe_join`, токены темы, YAML без алиасов |
|
||
| ADR-006: 15 фрагментов, `editorial`, `requires` только `feature.*` | `builtin/fragments/`, `models.Page.editorial`, `render._feature_on` |
|
||
|
||
## Как расширять
|
||
|
||
- **Новый фрагмент:** папка `fragments/<имя>/` сайта с `fragment.yaml`, `template.html.j2`, необязательным `style.css`. `id` плоский и уникальный, затенение встроенных запрещено.
|
||
- **Новая коллекция:** `collections/<id>.yaml`, записи в `content/<id>/*.md`, при необходимости `display/<id>.yaml`.
|
||
- **Новое правило сайта:** запись в `site.yaml: rules` (сейчас `require_fragment` для коллекции и `require_field` для форм).
|
||
|
||
## Известные ограничения M0
|
||
|
||
- Поле `props` в шаблоне — объект `Props`: `props.items` читает поле «items», а не метод словаря.
|
||
- `layout.extends` проверяется на существование, наследование шаблонов делается обычным `{% extends 'layout/<id>' %}`.
|
||
- CSS и JS собираются в один бандл с хешем в имени; минификации и изоляции по страницам пока нет.
|
||
- Нет приёма заявок и MCP: сетевая поверхность записи включается только вместе с контуром «вход, роли, аудит, лимиты» (ADR-006). Вход, аудит правок и редактор уже есть; роли и приём заявок остаются на M2.
|