f275260b0d
- Dockerfile + entrypoint (alembic + uvicorn), compose с healthcheck - .gitea/workflows: ci (pytest), deploy (SSH + compose по тегу v*) - docs/CICD.md: секреты, pvestandt9, ручной откат через workflow_dispatch Made-with: Cursor
109 lines
6.0 KiB
Markdown
109 lines
6.0 KiB
Markdown
# onGuard24
|
||
|
||
**Версия: 1.6.0** · Модульный монолит на **Python (FastAPI)**: ядро, приём алертов из Grafana, заготовки модулей (дежурства, контакты, светофор), PostgreSQL, проверки Vault / Grafana / Forgejo.
|
||
|
||
| Документ | Назначение |
|
||
|----------|------------|
|
||
| [CHANGELOG.md](CHANGELOG.md) | История версий |
|
||
| [docs/VERSIONING.md](docs/VERSIONING.md) | Теги, откат к предыдущей версии |
|
||
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Структура кода, куда что класть |
|
||
| [docs/AI_CONTEXT.md](docs/AI_CONTEXT.md) | Краткий контекст для доработок |
|
||
| [docs/DOMAIN.md](docs/DOMAIN.md) | Сущности (инцидент, алерт, эскалация), шина событий |
|
||
| [docs/MODULES.md](docs/MODULES.md) | Как добавлять модули и подписки на события |
|
||
| [docs/IRM.md](docs/IRM.md) | Функционал IRM: что делаем, что в Grafana |
|
||
| [docs/CICD.md](docs/CICD.md) | Forgejo Actions: деплой на сервер, откат по тегу |
|
||
|
||
**Репозиторий:** [forgejo.pvenode.ru/admin/onGuard24](https://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/MODULES.md), [docs/IRM.md](docs/IRM.md)).
|
||
- **Фронт (опционально):** `web/` — Vite + React, прокси на API.
|
||
|
||
Чего **ещё нет** (следующие версии): авторизация публичных API (кроме секрета webhook), полноценная бизнес-логика IRM в коде (эскалации, дежурства, светофор), фоновые задачи. Доменные сущности и задел под модули описаны в [docs/DOMAIN.md](docs/DOMAIN.md).
|
||
|
||
## Быстрый старт
|
||
|
||
```bash
|
||
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`):
|
||
|
||
```bash
|
||
alembic upgrade head
|
||
```
|
||
|
||
```bash
|
||
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`).
|
||
|
||
## Фронтенд (опционально)
|
||
|
||
```bash
|
||
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 при старте — только пул соединений.
|
||
|
||
## Тесты
|
||
|
||
```bash
|
||
pip install -e ".[dev]"
|
||
pytest
|
||
```
|
||
|
||
Покрытие: `/health`, `/api/v1/status`, webhook Grafana; внешние вызовы (Vault, Grafana, Forgejo) в тестах статуса подменяются моками.
|
||
|
||
## Docker и CI/CD
|
||
|
||
```bash
|
||
docker compose build && docker compose up -d
|
||
```
|
||
|
||
Деплой через **Forgejo Actions** (тег `v*`, SSH на сервер): см. [docs/CICD.md](docs/CICD.md). **Откат:** вручную запустить workflow **Deploy** с полем `ref` = нужный старый тег.
|