Release 1.7.0: Grafana catalog, ingress/IRM, tests

docs/CICD.md

@@ -18,6 +18,24 @@
 2. Зарегистрировать **runner** с меткой `ubuntu-latest` (или изменить `runs-on` в YAML на вашу метку, например `self-hosted`).
 3. Если образы `actions/checkout` недоступны, в настройках Actions задайте зеркало GitHub или используйте встроенные экшены Forgejo (см. документацию вашей версии).
 
+### Образ act_runner (Docker Hub)
+
+Используйте **`gitea/act_runner`** (например тег **`nightly`**), а не `docker.gitea.com/...:latest` — последний часто недоступен.
+
+```bash
+sudo docker pull gitea/act_runner:nightly
+sudo docker run -d --restart always --name act_runner \
+  -e GITEA_INSTANCE_URL="https://forgejo.pvenode.ru" \
+  -e GITEA_RUNNER_REGISTRATION_TOKEN="ТОКЕН_ИЗ_UI" \
+  -e GITEA_RUNNER_NAME="pvestandt9" \
+  -e GITEA_RUNNER_LABELS="ubuntu-latest:docker://catthehacker/ubuntu:act-22.04" \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -v act_runner_data:/data \
+  gitea/act_runner:nightly
+```
+
+Стабильные теги: [hub.docker.com/r/gitea/act_runner/tags](https://hub.docker.com/r/gitea/act_runner/tags).
+
 ## Секреты репозитория
 
 **Настройки репозитория → Actions → Secrets:**

docs/GRAFANA_TOPOLOGY.md

@@ -0,0 +1,54 @@
+# Каталог Grafana в onGuard24
+
+Иерархия **инстанс → организация → папки → правила алертинга** подтягивается **по HTTP API** Grafana и сохраняется в PostgreSQL. Вебхук при этом не заменяет синхронизацию: вебхук даёт события, каталог — актуальную структуру правил.
+
+## Что нужно
+
+1. Миграция **`004_grafana_catalog`** (выполняется при старте контейнера через `alembic upgrade head`).
+2. В `.env` у источника Grafana заданы **`api_url`** и **`api_token`** (service account с правами читать папки и alert rules — обычно роль Viewer/Editor и доступ к Alerting).
+3. Источник попадает в **`iter_grafana_sources`**: `GRAFANA_SOURCES_JSON` или пара `GRAFANA_URL` + `GRAFANA_SERVICE_ACCOUNT_TOKEN` (slug `default`).
+
+## API
+
+| Метод | Путь | Назначение |
+|--------|------|------------|
+| POST | `/api/v1/modules/grafana-catalog/sync` | Синхронизация. Тело: `{}` — все источники с токеном; `{"instance_slug":"default"}` — один slug. |
+| GET | `/api/v1/modules/grafana-catalog/meta` | Последние метаданные синхронизации по всем slug. |
+| GET | `/api/v1/modules/grafana-catalog/tree?instance_slug=default` | Дерево: папки и правила, сгруппированные по `namespace_uid` (обычно UID папки правил). |
+
+## Проверка на https://onguard24.pvenode.ru/
+
+1. Убедитесь, что задеплоена версия с модулем **Каталог Grafana** (пункт в боковом меню).
+2. Выполните синхронизацию (с сервера или с машины с доступом к API):
+
+```bash
+curl -sS -X POST "https://onguard24.pvenode.ru/api/v1/modules/grafana-catalog/sync" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+Ответ: `results[]` с полями `ok`, `folders`, `rules`, при ошибке — `error`.
+
+3. Посмотреть дерево:
+
+```bash
+curl -sS "https://onguard24.pvenode.ru/api/v1/modules/grafana-catalog/tree?instance_slug=default" | python3 -m json.tool
+```
+
+(Если используете только `GRAFANA_URL`, slug источника — **`default`**.)
+
+4. В UI: **Каталог Grafana** — таблица последних синхронизаций.
+
+## Связь с вебхуком
+
+- В инцидентах по-прежнему используется **`externalURL` / лейблы** из тела вебхука.
+- Каталог позволяет в UI/API сопоставлять **`rule_uid`** и папку с сохранённым снимком (после доработок привязки).
+
+## Ограничения
+
+- Один токен = **одна Grafana-организация** (контекст `GET /api/org`). Обход нескольких org на одном инстансе — отдельные токены или админ-API (не в этой версии).
+- Эндпоинты Ruler: пробуются `/api/ruler/grafana/api/v1/rules` и `/api/ruler/Grafana/api/v1/rules` (зависит от версии Grafana).
+
+## Автоматический cron
+
+Периодический `POST .../sync` пока не встроен: можно повесить **системный cron**, **Forgejo scheduled workflow** или внешний оркестратор.

docs/IRM.md

@@ -25,8 +25,15 @@
 
 ## Что настроить в Grafana (обязательно для приёма алертов)
 
-1. **Alerting → Contact points → New** — тип **Webhook**, URL: `https://<ваш-хост>/api/v1/ingress/grafana`, метод POST, Optional HTTP headers если задан `GRAFANA_WEBHOOK_SECRET`: `X-OnGuard-Secret: <секрет>`.
-2. **Notification policies** — направить нужные правила на этот contact point (или default policy).
-3. Убедиться, что сеть до onGuard24 доступна (firewall, TLS).
+### Один URL для всех инстансов и организаций
+
+1. **Contact point → Webhook**, URL: **`https://<ваш-хост>/api/v1/ingress/grafana`** (POST). **Не нужно** заводить slug в `.env`: источник в БД определяется из JSON Grafana — **`externalURL`** (хост Grafana), при наличии **`orgId`** / **`org_id`**, иначе лейблы первого алерта (`__org_id__`, `grafana_org`, `tenant`, `cluster`, `namespace`).
+2. В **`grafana.ini`** / настройках сервера корректно задайте **`root_url` / `external URL`**, чтобы в вебхук попадал нужный хост (за NPM — публичный URL).
+3. Опционально **`X-OnGuard-Secret`** (если задан **`GRAFANA_WEBHOOK_SECRET`**) и **`X-OnGuard-Service`** (имя сервиса в инциденте).
+4. **Notification policies** — привязать правила к contact point.
+
+### Дополнительно: путь `/ingress/grafana/<slug>`
+
+Явный ярлык в URL **не требует** записи в `GRAFANA_SOURCES_JSON`. **`GRAFANA_SOURCES_JSON`** нужен в основном для **`/api/v1/status`** (проверка API каждого инстанса) и для **отдельного `webhook_secret` на slug**.
 
 Подробнее: [MODULES.md](MODULES.md), [DOMAIN.md](DOMAIN.md).