наблюдаемость: завершить базовый контур Community

Добавить структурированные журналы, метрики, трассировку и безопасный канал критических ошибок. Усилить границы рантайма, тесты, проверку зависимостей и сценарии развёртывания.
2026-07-31 01:01:14 +03:00
parent 99bd05c145
commit 0e8f1ca03a
160 changed files with 13506 additions and 1499 deletions
@@ -22,6 +22,8 @@ admin-api  -> PostgreSQL
 mcp-server -> PostgreSQL
 admin-api  -> Valkey/Redis, опционально
 mcp-server -> Valkey/Redis, опционально
+admin-api  -> внешний OTLP endpoint, опционально
+mcp-server -> внешний OTLP endpoint, опционально
 ```

 ## Файлы запуска
@@ -152,6 +154,8 @@ docker compose up -d
 ```bash
 curl http://127.0.0.1:3001/health
 curl http://127.0.0.1:3002/health
+curl http://127.0.0.1:3001/ready
+curl http://127.0.0.1:3002/ready
 ```

 Ожидаемые ответы:
@@ -169,7 +173,22 @@ curl -I http://127.0.0.1:3000/

 ## Эксплуатация

- Делайте регулярные бэкапы PostgreSQL.
+- `/health` проверяет, что процесс жив; `/ready` дополнительно проверяет доступность PostgreSQL и используется Docker Compose.
+- CD перед каждым обновлением создаёт согласованный комплект в `backups/<UTC-время>`: дамп PostgreSQL, том артефактов, окружение, Compose и контрольные суммы. Хранятся последние пять локальных комплектов.
+- Копируйте комплекты резервных копий на отдельный хост или в объектное хранилище.
+- Проверенное восстановление выполняется только с явным подтверждением:
+
+```bash
+CRANK_RESTORE_CONFIRM=restore ./scripts/restore-community.sh /opt/crank /opt/crank/backups/20260721T120000Z
+```
+
+- Обновления схемы выполняются под блокировкой, одной транзакцией и фиксируются в `__crank_core_migrations`. Миграции Community должны оставаться обратно совместимыми с предыдущей версией приложения.
 - Не храните реальные секреты в Git.
- Для rollback используйте конкретные image tags, а не только `main`.
+- CD использует неизменяемые теги коммитов и автоматически возвращает прежнюю конфигурацию и образы при провале readiness.
 - `CRANK_PUBLISH_BIND=0.0.0.0` нужен только если reverse proxy работает на другом host.
+- OTLP Collector и хранилище трасс не входят в Community Compose. Для
+  внешнего приёмника задайте `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`; секретные
+  headers передавайте через OpenBao, а не через файлы репозитория.
+- GlitchTip и другие Sentry-совместимые приёмники также не входят в Community
+  Compose. Для отправки только критических ошибок передайте
+  `CRANK_SENTRY_DSN` через OpenBao; пустое значение отключает канал.