onGuard24/README.md

onGuard24

Версия: 1.6.0 · Модульный монолит на Python (FastAPI): ядро, приём алертов из Grafana, заготовки модулей (дежурства, контакты, светофор), PostgreSQL, проверки Vault / Grafana / Forgejo.

Документ	Назначение
CHANGELOG.md	История версий
docs/VERSIONING.md	Теги, откат к предыдущей версии
docs/ARCHITECTURE.md	Структура кода, куда что класть
docs/AI_CONTEXT.md	Краткий контекст для доработок
docs/DOMAIN.md	Сущности (инцидент, алерт, эскалация), шина событий
docs/MODULES.md	Как добавлять модули и подписки на события
docs/IRM.md	Функционал IRM: что делаем, что в Grafana
docs/CICD.md	Forgejo Actions: деплой на сервер, откат по тегу

Репозиторий: forgejo.pvenode.ru/admin/onGuard24

---

Что уже есть (функционал v1)

• Запуск HTTP API (uvicorn), конфиг из .env.
• PostgreSQL: пул asyncpg, таблица ingress_events для сырых тел webhook Grafana; схема через Alembic (отдельные ревизии в alembic/versions/).
• POST /api/v1/ingress/grafana — приём JSON алерта (опционально защита X-OnGuard-Secret).
• GET /, GET /api/v1/status — проверки: БД, Vault, Grafana (service account), Forgejo (PAT).
• Модули (API + веб-UI): IRM — инциденты, задачи, эскалации, дежурства, контакты, светофор; JSON под /api/v1/modules/..., UI под /ui/modules/<slug>/ (см. docs/MODULES.md, docs/IRM.md).
• Фронт (опционально): web/ — Vite + React, прокси на API.

Чего ещё нет (следующие версии): авторизация публичных API (кроме секрета webhook), полноценная бизнес-логика IRM в коде (эскалации, дежурства, светофор), фоновые задачи. Доменные сущности и задел под модули описаны в docs/DOMAIN.md.

Быстрый старт

cd onGuard24
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

Скопируй .env.example в .env и заполни секреты (см. ниже). Перед первым запуском с БД примените миграции (в т.ч. таблицы IRM: incidents, tasks, escalation_policies):

alembic upgrade head

python -m uvicorn onguard24.main:app --reload --host 0.0.0.0 --port 8080

Или: python -m onguard24.main (читает HTTP_ADDR из .env).

API

Метод	Путь	Описание
GET	/	HTML: проверки database / vault / grafana / forgejo
GET	/?format=json	Тот же статус + ссылки в JSON
GET	/health, /api/v1/health	Liveness
GET	/api/v1/status	JSON: интеграции + БД
POST	/api/v1/ingress/grafana	Webhook Grafana (JSON), опционально X-OnGuard-Secret
GET	/api/v1/modules/schedules/	Заглушка модуля дежурств
GET	/api/v1/modules/contacts/	Заглушка контактов
GET	/api/v1/modules/statusboard/	Заглушка «светофора»

Переменные окружения

См. .env.example. Основные: DATABASE_URL, HTTP_ADDR, VAULT_*, GRAFANA_*, FORGEJO_*, опционально GRAFANA_WEBHOOK_SECRET.

Grafana

• GRAFANA_URL, GRAFANA_SERVICE_ACCOUNT_TOKEN — HTTP API (service account), не пароль пользователя.

Forgejo (Gitea API)

• FORGEJO_URL, FORGEJO_TOKEN — PAT; рекомендуется scope read:user для полного ответа /api/v1/user (см. README в предыдущих версиях и integrations/forgejo_api.py).

Фронтенд (опционально)

cd web && npm install && npm run dev

Vite проксирует /api на http://127.0.0.1:8080 (см. web/vite.config.ts).

Миграции БД (Alembic)

• URL БД: переменная DATABASE_URL (как у приложения; в alembic/env.py используется синхронный драйвер postgresql+psycopg). К URL автоматически добавляется client_encoding=utf8, чтобы миграции не падали с TypeError: ... bytes-like object, если на сервере PostgreSQL включён режим вроде SQL_ASCII.
• Применить схему: alembic upgrade head.
• Новая ревизия: alembic revision -m "описание" и правка файла в alembic/versions/.

Приложение не выполняет DDL при старте — только пул соединений.

Тесты

pip install -e ".[dev]"
pytest

Покрытие: /health, /api/v1/status, webhook Grafana; внешние вызовы (Vault, Grafana, Forgejo) в тестах статуса подменяются моками.

Docker и CI/CD

docker compose build && docker compose up -d

Деплой через Forgejo Actions (тег v*, SSH на сервер): см. docs/CICD.md. Откат: вручную запустить workflow Deploy с полем ref = нужный старый тег.