76 lines
3.5 KiB
Markdown
76 lines
3.5 KiB
Markdown
|
# onGuard24
|
||
|
|
|
||
|
|
**Версия: 1.0.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) | Краткий контекст для доработок |
|
||
|
|
|
||
|
|
**Репозиторий:** [forgejo.pvenode.ru/admin/onGuard24](https://forgejo.pvenode.ru/admin/onGuard24)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Что уже есть (функционал v1)
|
||
|
|
|
||
|
|
- Запуск HTTP API (`uvicorn`), конфиг из `.env`.
|
||
|
|
- **PostgreSQL:** пул asyncpg, таблица `ingress_events` для сырых тел webhook Grafana.
|
||
|
|
- **POST `/api/v1/ingress/grafana`** — приём JSON алерта (опционально защита `X-OnGuard-Secret`).
|
||
|
|
- **GET `/`**, **GET `/api/v1/status`** — проверки: БД, Vault, Grafana (service account), Forgejo (PAT).
|
||
|
|
- **Модули-заглушки:** `/api/v1/modules/schedules|contacts|statusboard/`.
|
||
|
|
- **Фронт (опционально):** `web/` — Vite + React, прокси на API.
|
||
|
|
|
||
|
|
Чего **ещё нет** (следующие версии): Alembic, авторизация API, доменная модель инцидентов, эскалации, фоновые задачи.
|
||
|
|
|
||
|
|
## Быстрый старт
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cd onGuard24
|
||
|
|
python3 -m venv .venv
|
||
|
|
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||
|
|
pip install -e .
|
||
|
|
```
|
||
|
|
|
||
|
|
Скопируй `.env.example` в `.env` и заполни секреты (см. ниже).
|
||
|
|
|
||
|
|
```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`).
|