docs: add enterprise deployment guide

2026-06-07 17:21:09 +03:00
parent 9fa085a53e
commit 3318c89629
10 changed files with 1037 additions and 1 deletions
@@ -0,0 +1,148 @@
+# Operations Runbook
+
+Документ описывает базовые эксплуатационные проверки AWatch-rus.
+
+## Быстрая проверка
+
+Проверить доступность:
+
+```bash
+curl -fsS http://<AWATCH_HOST>/healthz
+curl -fsS http://<AWATCH_HOST>/readyz
+curl -fsS http://<AWATCH_HOST>/metrics
+```
+
+Для защищенного reverse proxy использовать утвержденный URL и способ
+аутентификации заказчика.
+
+## healthz
+
+`/healthz` используется для проверки, что процесс backend/portal отвечает.
+
+Ожидается:
+
+- HTTP 200 for healthy process;
+- structured JSON or text according to current service implementation;
+- no secrets in response.
+
+## readyz
+
+`/readyz` используется для проверки готовности обслуживать traffic.
+
+Ожидается:
+
+- ready status only when critical dependencies are acceptable;
+- degraded status when reports/data sources are degraded;
+- no false fully healthy status for degraded reports.
+
+## metrics
+
+`/metrics` используется для технического мониторинга.
+
+Проверять:
+
+- request counters;
+- latency where exposed;
+- degraded report counters where exposed;
+- error counters.
+
+## Smoke
+
+Базовые smoke scripts:
+
+```bash
+node scripts/awatch-production-hardening-smoke.mjs
+node scripts/detmir-pilot-demo-smoke.mjs
+node scripts/deployment-readiness-smoke.mjs
+```
+
+Smoke должен выполняться:
+
+- после установки;
+- после обновления;
+- перед demo;
+- после recovery.
+
+## Журналирование
+
+Проверять:
+
+```bash
+journalctl -u <AWATCH_SERVICE> --since "30 minutes ago" --no-pager
+systemctl status <AWATCH_SERVICE> --no-pager
+systemctl --failed --no-pager
+```
+
+Не публиковать в issue/README:
+
+- secrets;
+- live hostnames;
+- private IPs;
+- customer evidence;
+- user identifiers.
+
+## Типовые сбои
+
+### Portal недоступен
+
+Проверить:
+
+- process/service status;
+- reverse proxy;
+- firewall;
+- TLS certificate;
+- bind address;
+- recent logs.
+
+### Reports degraded
+
+Проверить:
+
+- data source freshness;
+- worktime/report API timeout;
+- stale cache usage;
+- coverage;
+- errors in logs.
+
+### Нет данных
+
+Проверить:
+
+- выбранный период;
+- source availability;
+- agent heartbeat;
+- expected nodes;
+- ingestion/storage status.
+
+### Ролевая ошибка доступа
+
+Проверить:
+
+- selected role;
+- `X-AWatch-Role` header where used;
+- portal role gates;
+- API endpoint scope.
+
+## Диагностика
+
+Минимальный набор:
+
+```bash
+curl -i http://<AWATCH_HOST>/healthz
+curl -i http://<AWATCH_HOST>/readyz
+curl -i http://<AWATCH_HOST>/api/reports?role=executive
+curl -i http://<AWATCH_HOST>/api/actions?role=executive
+```
+
+Для production использовать TLS endpoint and approved auth.
+
+## Эскалация
+
+Эскалировать, если:
+
+- `/healthz` недоступен;
+- `/readyz` постоянно degraded;
+- reports timeout повторяется;
+- source freshness ниже пилотного SLA;
+- backup restore не проходит;
+- role gate отдает лишние данные.