feat: live последние события на Dashboard; retention, health, runbook

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-28 11:29:31 +10:00
parent 9ed0670863
commit 108e1756c4
14 changed files with 625 additions and 249 deletions
@@ -0,0 +1,79 @@
+# Runbook: эксплуатация SAC
+
+Краткие процедуры для prod (`sac.kalinamall.ru`, native install в `/opt/security-alert-center`).
+
+## Деплой приложения
+
+```bash
+sudo /opt/sac-deploy.sh
+```
+
+Скрипт: `git pull` / `reset --hard`, `pip install`, `alembic upgrade head`, `npm run build`, `systemctl restart sac-api`.
+
+Проверка:
+
+```bash
+curl -sS https://sac.kalinamall.ru/health | jq .
+```
+
+Ожидается `status: ok`, `database: ok`. При устаревших heartbeat агентов — `status: degraded`, поле `hosts_stale` > 0.
+
+## Резервное копирование PostgreSQL
+
+```bash
+sudo -u postgres pg_dump -Fc sac > /var/backups/sac-$(date +%Y%m%d).dump
+```
+
+Восстановление (на тестовый инстанс):
+
+```bash
+sudo -u postgres pg_restore -d sac_test --clean /var/backups/sac-YYYYMMDD.dump
+```
+
+Перед restore на prod — остановить API: `sudo systemctl stop sac-api`.
+
+## Retention (очистка БД)
+
+Политика по умолчанию (`config/sac-api.env`):
+
+| Данные | Срок |
+|--------|------|
+| `events` | 90 дней (`SAC_EVENTS_RETENTION_DAYS`) |
+| `problems` со статусом `resolved` | 180 дней (`SAC_PROBLEMS_RETENTION_DAYS`) |
+
+Ручной прогон:
+
+```bash
+sudo -u sac bash -c '
+  set -a; source /opt/security-alert-center/config/sac-api.env; set +a
+  cd /opt/security-alert-center/backend
+  .venv/bin/python -m app.jobs.retention
+'
+```
+
+Установка ежедневного timer (один раз):
+
+```bash
+sudo cp /opt/security-alert-center/deploy/systemd/sac-retention.service /etc/systemd/system/
+sudo cp /opt/security-alert-center/deploy/systemd/sac-retention.timer /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now sac-retention.timer
+systemctl list-timers sac-retention.timer
+```
+
+## Health и мониторинг
+
+| Endpoint | Назначение |
+|----------|------------|
+| `GET /health` | БД, версия, `hosts_stale`, `last_event_received_at` |
+| `GET /api/v1/stream/events` | SSE для UI (счётчики + `last_event_id` каждые 5 с) |
+
+Агенты: `GET /health` без JWT. UI Dashboard: блок «Последние события» подгружается при смене `last_event_id` в SSE.
+
+## Типовые проблемы
+
+**События в Telegram есть, в UI нет** — проверить ingest (лог агента `SAC: accepted`), режим `UseSAC`, обновить Dashboard (live ~5 с).
+
+**422 на ingest** — см. `Logs/sac-last-post.json` на Windows-агенте; обновить `Sac-Client.ps1` (RDP) или `sac-client.sh` (Linux).
+
+**Устаревший heartbeat** — увеличить `SAC_HEARTBEAT_STALE_MINUTES` или проверить `agent.heartbeat` на хосте.
@@ -89,7 +89,7 @@

 - [x] `d2-1` UI Problems: список, фильтры, `Ack/Resolve`, карточка с таймлайном
 - [x] `d2-2` Dashboard: top hosts/types, `open vs resolved 24h`, drill-down
- [ ] `d2-3` Ops: retention, health checks, runbook backup/restore/deploy
+- [x] `d2-3` Ops: retention, health checks, runbook backup/restore/deploy
 - [ ] `dod` DoD: нет дублей `event_id`, Problems e2e, 3 правила, UI MVP, docs, push в kalinamall

 ### Отображение хостов (`display_name`, как `SERVER_DISPLAY_NAME` у ssh)
@@ -120,9 +120,9 @@
 - [x] `11:00–12:00` карточка проблемы + таймлайн событий
 - [x] `13:00–14:30` Dashboard: виджеты top hosts/types
 - [x] `14:30–16:00` Dashboard: `open/resolved 24h` + drill-down
- [ ] `16:00–17:00` retention job (`events 30–90d`, `problems 180d+`)
+- [x] `16:00–17:00` retention job (`events 30–90d`, `problems 180d+`)
 - [ ] `17:00–18:00` health checks (DB/worker/heartbeat stale)
- [ ] `18:00–19:00` runbook + финальный push в kalinamall + freeze dev
+- [x] `18:00–19:00` runbook + финальный push в kalinamall + freeze dev

 ### Неделя после freeze (только тестирование)