EvoBGP/docs/manual.md

Полное руководство по 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. Сквозной поток данных

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

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.

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

1. Создать/обновить модуль и его источники.
2. Дождаться или инициировать refresh.
3. Проверить ревизию и diff.
4. Выполнить apply на целевой спикер.
5. Проверить 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.

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

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

1. Статус API и БД.
2. Состояние jobs (module_refresh, deploy_apply), ошибки в job meta.
3. Состояние внешних источников (CDN/DoH/ASN).
4. Состояние 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/*.

Рекомендации по качеству

• Для изменений API всегда обновлять docs/openapi.yaml.
• Для изменений UI держаться единого набора компонентов shadcn-svelte и Lucide.
• Для pipeline-изменений добавлять метрики стадии и явные trigger-метки job.

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