diff --git a/docs/RUNBOOK.md b/docs/RUNBOOK.md new file mode 100644 index 0000000..a14c067 --- /dev/null +++ b/docs/RUNBOOK.md @@ -0,0 +1,160 @@ +# Buryan Hub: дежурная книга + +Что построено за спринт, как проверить и что делать, если сломалось. + +--- + +## 1. Где смотреть + +| Что | Адрес | +|---|---| +| Панель (снаружи, за входом) | `https://status.buryans.ru/hub/` | +| Панель (изнутри) | `http://192.168.1.10:9120/` | +| Графики | `http://192.168.1.113:3000/d/buryan-hub` | +| Метрики | `http://192.168.1.10:9120/metrics` | +| Тревоги | `http://192.168.1.134:9093` | + +В чате: бот **Инфраструктура** — `!status`, `!gaps`, `!users`, `!sources`, +`!history <сервис>`, `!backups`, `!disk`. + +--- + +## 2. Как устроено + +``` +сервисы → коннекторы (каждые 10 мин) → ядро (PostgreSQL) → события + ↓ + метрики → Prometheus → Grafana + проблемы → сверка (03:30) → бот Инфраструктура + пожелания → боты → папка проекта +``` + +Ядро — единственная точка, где сходятся события всех сервисов: 12 +источников, карточки объектов, связи, история, журнал действий. + +--- + +## 3. Ежедневные задачи + +| Время | Задача | Лог | +|---|---|---| +| 01:00 | бэкап контейнеров (LXC) | `/var/log/lxc-*.log` | +| 02:00 | дамп PostgreSQL (все базы) | `cron-pg.log` | +| 02:30 | бэкап базы ядра | `/var/log/hub-backup.log` | +| 02:40 | проверка бэкапа PG | `/var/log/hub-pg-verify.log` | +| 02:45 | бэкап данных ботов | `/var/log/hub-backup.log` | +| 03:00 | бэкап Matrix | `/root/matrix-backups/logs` | +| 03:05 | проверка бэкапа ботов | `/var/log/hub-bots-verify.log` | +| 03:15 | сверка служб | `/var/log/hub-reconcile.log` | +| 03:20 | проверка Matrix (офсайт, восстановление) | `/var/log/hub-matrix-backup.log` | +| 03:45 | связка карточек | `/var/log/hub-linker.log` | +| 04:00 | офсайт (restic) | `offsite-backup.log` | +| 04:15 | каталог библиотек | `/var/log/hub-catalog.log` | +| 07:30 | инвентаризация | `/var/log/hub-inventory.log` | +| 08:00 (пн) | аудит доступов | `/var/log/hub-identity.log` | +| 08:30 | дайджест событий | `/var/log/hub-digest.log` | +| 19:00 | «продолжить просмотр» | `/var/log/hub-resume.log` | +| 20:00 (вс) | недельный отчёт | `/var/log/hub-weekly-core.log` | +| 23:00 | экспорт данных в проект | `/var/log/hub-export.log` | +| каждые 10 мин | коннекторы | `/var/log/hub-connectors.log` | + +Состояние всех задач — на панели, блок «Задачи». + +--- + +## 4. Если что-то сломалось + +### Сервис не отвечает + +``` +python3 /opt/hub-core/reconcile.py # проверить всё разом +systemctl status hub-core hub-bots # живы ли службы +``` + +Сверка сама поднимает остановленные контейнеры и пишет действия в журнал. + +### События перестали идти + +``` +python3 /opt/hub-core/connectors.py # ручной прогон с отчётом +``` + +Смотреть `/var/log/hub-connectors.log` и блок «Источники событий» на панели: +если у источника пропала свежая дата — он замолчал. + +### Бэкап не восстановился + +Каждый бэкап имеет свою проверку — она присылает `backup.failed` боту +Инфраструктура. Ручной прогон: + +``` +bash /opt/hub-core/pg_verify_cron.sh # PostgreSQL: сверка таблиц +bash /opt/hub-core/matrix_verify.sh # Matrix: разворот в тестовую базу +bash /opt/hub-core/bots_verify.sh # данные ботов: распаковка +bash /opt/hub-core/lxc_verify.sh # контейнер: поднять и удалить +bash /opt/hub-core/offsite_verify.sh # офсайт restic +``` + +### Тревога не пришла + +Проверить цепочку по очереди: + +``` +curl -s http://192.168.1.134:9090/api/v1/alertmanagers # Prometheus видит Alertmanager +curl -s http://192.168.1.134:9093/api/v2/alerts # тревога в Alertmanager +curl -s -X POST -d '{}' http://127.0.0.1:9110/alertmanager # вебхук жив +``` + +Помнить: при перезапуске Prometheus активные тревоги «теряют» закрытие — +Alertmanager закроет их сам через 5 минут. + +### Панель не открывается + +``` +systemctl restart hub-core +curl -s http://127.0.0.1:9120/health +nginx -t && systemctl reload nginx +``` + +--- + +## 5. Где что лежит + +| Что | Путь | +|---|---| +| Код ядра | `/opt/hub-core/` | +| Код ботов | `/opt/hub-bots/hub/` | +| Настройки ядра | `/etc/hub-core/` (600) | +| Настройки ботов | `/etc/hub-bots/` (600) | +| Данные ботов | `/var/lib/hub-bots/` | +| Бэкапы | `/mnt/backups/{postgresql,hub-core,hub-bots,matrix,dump}` | +| Данные в проект | `/root/buryan-infra/data/` | +| Репозиторий | `/root/buryan-infra/` | + +--- + +## 6. Что осталось открытым + +| Что | Нужно | +|---|---| +| LLM | ключ → `/etc/hub-core/llm.env` | +| Telegram | `api_id`, `api_hash`, каналы → `/etc/hub-core/telegram.env` | +| Камеры | RTSP-адреса | +| MQTT в Home Assistant | включить интеграцию в UI (инструкция в `ops/homeassistant/`) | +| Thin pool 82% | решить судьбу снапшота `vm-115` (25 ГБ) | +| Immich/Paperless для семьи | создать учётные записи | + +--- + +## 7. Что проверено на живом + +* ядро принимает события, создаёт карточки, находит их поиском; +* импорт файла запускает сканирование Jellyfin (автодействие); +* сверка находит проблемы и сообщает о них боту; +* все шесть бэкапов проверены на восстановление; +* тревога Prometheus доходит до Matrix, закрытие — тоже; +* панель открывается снаружи за входом Authentik; +* боты пишут пожелания в папку проекта. + +Чего **не** проверено: ночной прогон задач по расписанию (создавались и +запускались вручную вечером) — первая настоящая ночь покажет. diff --git a/ops/hub-core/core.py b/ops/hub-core/core.py index a0ebd32..64e86dc 100644 --- a/ops/hub-core/core.py +++ b/ops/hub-core/core.py @@ -10,6 +10,7 @@ import json import os import threading +import time import urllib.request from datetime import datetime, timezone from http.server import BaseHTTPRequestHandler, HTTPServer @@ -369,6 +370,42 @@ def do_metrics(): return "\n".join(lines) + "\n" + + +JOBS = { + "коннекторы": ("/var/log/hub-connectors.log", 1), + "сверка": ("/var/log/hub-reconcile.log", 30), + "связка карточек": ("/var/log/hub-linker.log", 30), + "дайджест": ("/var/log/hub-digest.log", 30), + "инвентаризация": ("/var/log/hub-inventory.log", 30), + "каталог": ("/var/log/hub-catalog.log", 30), + "экспорт": ("/var/log/hub-export.log", 30), + "бэкап базы": ("/var/log/hub-backup.log", 30), + "проверка бэкапа PG": ("/var/log/hub-pg-verify.log", 30), + "проверка бэкапа ботов": ("/var/log/hub-bots-verify.log", 30), + "бэкап Matrix": ("/var/log/hub-matrix-backup.log", 30), + "офсайт": ("/var/log/hub-offsite-verify.log", 24 * 8), + "просмотр": ("/var/log/hub-resume.log", 30), + "недельный отчёт": ("/var/log/hub-weekly-core.log", 24 * 8), + "аудит доступов": ("/var/log/hub-identity.log", 24 * 8), + "восстановление CT": ("/var/log/hub-lxc-verify.log", 24 * 8), +} + + +def jobs_status(): + """Состояние задач: когда последний раз отработали.""" + now = time.time() + rows = [] + for name, (path, limit_h) in JOBS.items(): + try: + age_h = (now - os.path.getmtime(path)) / 3600 + state = "ок" if age_h <= limit_h else "просрочено" + except OSError: + age_h, state = None, "не запускалась" + rows.append((name, age_h, limit_h, state)) + return rows + + def render_panel(): """HTML-страница: состояние системы в одном месте.""" try: @@ -407,6 +444,7 @@ def render_panel(): identity = idrow[0] if idrow else None except Exception: identity = None + jobs = jobs_status() cur.execute("select count(*) from entity_links") links = cur.fetchone()[0] cur.execute("""select at, kind, target, detail, status from actions @@ -417,6 +455,7 @@ def render_panel(): except Exception as e: entities = events = events24 = open_problems = 0 problems, recent, by_source, actions, links, inventory, identity = [], [], [], [], 0, None, None + jobs = [] err = str(e)[:200] def esc(x): @@ -427,6 +466,11 @@ def render_panel(): f"{esc(typ)}{esc(title)}" for at, src, typ, title in recent) or "событий пока нет" + job_rows = "".join( + f"{esc(n)}{(str(round(a, 1)) + ' ч') if a is not None else '—'}" + f"{lim} ч{esc(st)}" + for n, a, lim, st in jobs) or "нет данных" + identity_text = "аудит ещё не запускался" if isinstance(identity, dict) and identity.get("table"): identity_text = identity["table"] @@ -487,6 +531,8 @@ th{{color:#7d8b99;font-weight:500}}
{open_problems}проблем
{links}связей
+

Задачи

+{job_rows}
задачапоследний запускпределсостояние

Проблемы

{prow}
проверкачто не так

Графики

Дашборд: Grafana — Buryan Hub