- Added support for remote speaker configuration in the README and documentation.
- Implemented a new endpoint for retrieving the bundle signing public key.
- Updated the `evobgp-agent` to include a `serve` command for Panel→Node sync API.
- Enhanced CI workflow to validate remote speaker compose files.
- Introduced new fields in the API and UI for managing speaker metadata, including dispatch status and sync status.
- Improved error handling and response formatting in speaker-related API endpoints.
- Updated documentation to reflect changes in remote speaker functionality and usage guidelines.

2026-05-21 12:42:06 +07:00

7.9 KiB

Raw Blame History

Полное руководство по EvoBGP

Этот документ объединяет эксплуатационное и разработческое описание системы: что делает каждый процесс, как двигаются данные, какие API использовать и где искать причины инцидентов.

1. Назначение системы

EvoBGP управляет генерацией и применением BGP-конфигураций на основе модулей источников префиксов (AS_PREFIXES, CDN_CIDRS, DOMAINS, IP_RANGES).

Система разделена на:

control plane: API, БД, jobs, рендер ревизий, публикация и подписание бандлов;
data plane: BIRD и связанный агент/нода для применения ревизий.

2. Компоненты и роли бинарников (`cmd/*`)

`evobgp-api`

Основной HTTP API.
Поднимает маршруты из internal/httpapi.
Работает с store/repository, jobs и аутентификацией.

`evobgp-all`

Монолитный режим: API + scheduler + ingest + render + deploy в одном процессе.
Удобен для компактных окружений (microvps).

`evobgp-scheduler`

Периодически запускает module_refresh по расписанию/интервалам.
В reference-профиле может стучаться в API и/или работать через store.

`evobgp-ingest`

Периодически делает prefetch внешних CDN-источников (ETag/доступность).

`evobgp-render`

Ведёт рендер-цикл; в режиме autopublish может назначать последнюю ревизию на спикеры.

`evobgp-deploy`

Диагностирует drift: различия между опубликованной и применённой ревизией.

`evobgp-node`

CLI-нода для edge: загрузка бандла, верификация подписи, применение.

`evobgp-agent`

Локальный агент рядом с BIRD (наблюдение и служебные операции).

3. Карта внутренних модулей (`internal/*`)

API и доступ

internal/httpapi: маршруты, auth, CORS, problem+json, CRUD, jobs endpoints.

Данные

internal/store: бизнес-контракты бэкенда.
internal/repository: PostgreSQL-реализация.
internal/db: коннект и миграции.

Jobs/pipeline

internal/jobs: очередь задач и worker.
internal/pipeline: module_refresh, сбор источников, материализация, рендер-превью.
internal/scheduler, internal/ingest, internal/render, internal/deploy: фоновые циклы.

BIRD и бандлы

internal/birdfmt: генерация конфигурации BIRD.
internal/birddeploy: применение конфигурации и интеграция с birdc.
internal/bundle, internal/signing: упаковка и криптографическая проверка.

Наблюдаемость и служебные

internal/observability: метрики/middleware.
internal/asnresolve: внешние резолвы ASN.
internal/broker: задел под внешний брокер.
internal/config, internal/platform: параметры среды и платформенные адаптеры.

4. Сквозной поток данных

Оператор меняет данные модуля (CRUD источников, peers/speakers, настройки).
Включённый модуль триггерит module_refresh.
jobs.Worker вызывает pipeline.RefreshModule.
Pipeline собирает префиксы всех enabled-модулей tenant, строит materialized snapshot.
Создаётся ревизия и BIRD preview.
По операциям deploy/apply ревизия применяется на спикере.
Нода получает бандл, проверяет подпись, применяет локально.

5. API: ключевые группы и сценарии

Источник истины контракта: docs/openapi.yaml.

Основные группы endpoint-ов

Modules: модули и их общие параметры.
AS Entries, CDN Sources, Domain Entries, IP Range Entries: источники префиксов.
Peers, Speakers: сетевая топология применения.
Revisions, Deploy, Jobs: жизненный цикл ревизий и фоновых задач.
Settings: глобальные KV-настройки.
Node: edge-флоу бандлов/enrollment.

Типовой сценарий оператора

Создать/обновить модуль и его источники.
Дождаться или инициировать refresh.
Проверить ревизию и diff.
Выполнить apply на целевой спикер.
Проверить health/monitoring/jobs.

6. Настройки и доступ

Аутентификация/роли

Роли и правила доступа: docs/access.md.
Для мутаций критичных сущностей требуется editor/operator.

Настройки (`/v1/settings`)

KV c ключами BIRD и дополнительными feature flags.
Ключевые параметры BIRD: bird_router_id, bird_local_ipv4, bird_local_ipv6, bird_local_asn, bird_bgp_source_ipv4, bird_bgp_source_ipv6.
Tenant settings — глобальный default. Per-speaker override: meta_json.bird_bgp_source_ipv4 / node_ipv4 в карточке спикера (Web UI → Сеть → Спикеры); pipeline накладывает overlay при сборке бандла для реплики. См. remote-speakers.md.

7. Эксплуатация и runbook

Что проверять при инцидентах

Статус API и БД.
Состояние jobs (module_refresh, deploy_apply), ошибки в job meta.
Состояние внешних источников (CDN/DoH/ASN).
Состояние BIRD и применённой ревизии на спикере.

Частые причины проблем

Невалидные данные источников (непарсящийся JSON/plaintext для CDN).
Неполные настройки BIRD.
Ошибки внешних upstream (RIPEstat/DoH/CDN).
Расхождение published/applied ревизии.

8. Разработка и расширение

Где вносить изменения

Новый endpoint: internal/httpapi + обновление docs/openapi.yaml.
Новая логика источника: internal/pipeline + соответствующие CRUD/store/repository.
Новая операция UI: web/src/routes/* и web/src/lib/components/*.

9. Индекс исходников (быстрый вход)

Архитектура: docs/architecture.md
API обзор: docs/api.md
Контракт API: docs/openapi.yaml
Доступ/роли: docs/access.md
Web запуск: web/README.md
Compose: deploy/compose/docker-compose.yaml

7.9 KiB Raw Blame History Unescape Escape