106 lines
6.9 KiB
Markdown
106 lines
6.9 KiB
Markdown
# Архитектура EvoBGP
|
||
|
||
Высокоуровневое описание компонентов и потоков. Детальный продуктовый и инфраструктурный чертёж также зафиксирован во внутреннем плане репозитория: `.cursor/plans/evobgp_архитектура_0e73ef02.plan.md` (удобно для истории решений; пользовательская навигация — через этот раздел и [overview.md](overview.md)).
|
||
|
||
## Назначение слоёв
|
||
|
||
- **Control plane** — HTTP API, хранилище состояния (PostgreSQL), фоновые задачи (jobs), подпись артефактов (бандлы), observability.
|
||
- **Data plane** — демон BIRD, локальные конфиги в `/etc/bird`, сокет управления `birdc`, агент `evobgp-agent` для наблюдения/сопутствующих действий.
|
||
- **Edge интеграция** — CLI `evobgp-node` на машине спикера: получение бандла по API, проверка подписи, применение конфигурации.
|
||
|
||
## Компоненты (бинарники `cmd/`)
|
||
|
||
| Бинарник | Роль |
|
||
|----------|------|
|
||
| `evobgp-api` | Только HTTP API и связанная логика в одном процессе. |
|
||
| `evobgp-all` | Тот же API + in-process **scheduler** (очередь `module_refresh` в общем Registry), **ingest** (prefetch ETag CDN), **render** (опционально auto-publish), **deploy** (лог расхождений published/applied). |
|
||
| `evobgp-scheduler` | По `refresh_interval_sec` ставит refresh: в одном процессе с API — через `jobs.Registry`; в reference Compose — **HTTP** `POST /v1/modules/{id}/refresh` (`EVOBGP_CONTROL_PLANE_URL`, `EVOBGP_SCHEDULER_BEARER`). |
|
||
| `evobgp-ingest` | Периодический conditional GET по URL CDN-источников и обновление `etag` в БД. |
|
||
| `evobgp-render` | По умолчанию только heartbeat; при `EVOBGP_RENDER_AUTOPUBLISH=1` выставляет всем спикерам tenant последнюю ревизию (упрощение для демо). |
|
||
| `evobgp-deploy` | Периодически логирует **drift**: `last_applied_revision_id` vs опубликованная ревизия для ноды. |
|
||
| `evobgp-node` | CLI реплики: `pull-bundle`, `verify-bundle`, `apply-bundle`. |
|
||
| `evobgp-agent` | Локальный агент рядом с BIRD (например `watch` по сокету). |
|
||
|
||
В Docker Compose профиль **reference** запускает отдельные контейнеры под `evobgp-api` и четыре воркера; профиль **microvps** использует один контейнер `evobgp-all`.
|
||
|
||
## Пакеты `internal/` (сжатая карта)
|
||
|
||
| Пакет | Назначение |
|
||
|-------|------------|
|
||
| `httpapi` | Маршруты REST, аутентификация, CORS, привязка к store и jobs. |
|
||
| `store` | Абстракция бэкенда данных; реализации в памяти и через репозиторий. |
|
||
| `repository` | Доступ к PostgreSQL, сущности и миграции на уровне приложения. |
|
||
| `db` | Подключение к БД и применение миграций. |
|
||
| `jobs` | Реестр и выполнение асинхронных задач, связанных с API. |
|
||
| `bundle` | Упаковка и проверка бандлов для нод. |
|
||
| `signing` | Криптографическая проверка подписей. |
|
||
| `birdfmt` | Форматирование и фрагменты конфигурации BIRD, вызовы `birdc`. |
|
||
| `birddeploy` | Логика применения конфигурации к BIRD (используется в цепочке деплоя). |
|
||
| `config` | Переменные окружения `EVOBGP_*`. |
|
||
| `observability` | Метрики Prometheus, HTTP middleware. |
|
||
| `broker` | Заготовка под NATS/Redis (логирование подключения в воркерах). |
|
||
| `pipeline` | Ingest+render в одном шаге для `module_refresh`: выборка префиксов (CDN/AS/IP/пустые DOMAINS), `CreateRenderRevision`, превью BIRD через `birdfmt`. |
|
||
|
||
## Диаграмма: эталонный Compose (reference)
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph clients [Clients]
|
||
WebUI[Web_UI]
|
||
Operator[Operator_API_client]
|
||
NodeCLI[evobgp_node]
|
||
end
|
||
subgraph control [Control_plane]
|
||
API[evobgp_api]
|
||
Sched[evobgp_scheduler]
|
||
Ingest[evobgp_ingest]
|
||
Render[evobgp_render]
|
||
Deploy[evobgp_deploy]
|
||
PG[(PostgreSQL)]
|
||
end
|
||
subgraph data [Data_plane]
|
||
BIRD[BIRD2]
|
||
Agent[evobgp_agent]
|
||
end
|
||
WebUI --> API
|
||
Operator --> API
|
||
NodeCLI --> API
|
||
API --> PG
|
||
Sched -->|HTTP_or_DB| API
|
||
Sched --> PG
|
||
Ingest --> PG
|
||
Render --> PG
|
||
Deploy --> PG
|
||
Agent --> BIRD
|
||
```
|
||
|
||
Очередь задач по-прежнему **in-memory в процессе API** (`jobs.Registry`); отдельный контейнер `evobgp-scheduler` не разделяет память с API и дергает refresh по HTTP. Полноценный брокер (NATS) и общая очередь `job_audit` между процессами — в следующих итерациях.
|
||
|
||
## Диаграмма: microvps (`evobgp-all`)
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Client[HTTP_clients]
|
||
All[evobgp_all_process]
|
||
PG[(PostgreSQL)]
|
||
BIRD[BIRD2]
|
||
Client --> All
|
||
All --> PG
|
||
All --> BIRD
|
||
```
|
||
|
||
Внутри `evobgp-all` все воркеры используют **тот же** `store` и `jobs.Registry`, что и HTTP handlers, поэтому `module_refresh` выполняется в том же процессе без HTTP.
|
||
|
||
## Поток: ревизия и бандл для ноды
|
||
|
||
1. Оператор (роль `operator` или выше по политике) изменяет модули и запускает цепочку, приводящую к новой **ревизии** (часть шагов может быть асинхронной через jobs — см. OpenAPI).
|
||
2. Control plane формирует **подписанный бандл** для пары спикер + ревизия.
|
||
3. `evobgp-node pull-bundle` с ключом роли `node` запрашивает `GET /v1/speakers/{id}/revisions/latest` и затем `GET /v1/speakers/{id}/bundle/{revision_id}`.
|
||
4. Локально выполняется проверка подписи (публичный ключ выдаётся при старте API) и применение к BIRD (`apply-bundle`).
|
||
|
||
## Связанные документы
|
||
|
||
- [quickstart.md](quickstart.md) — как поднять стек.
|
||
- [api.md](api.md) — точки входа HTTP.
|
||
- [access.md](access.md) — ключи и роли.
|