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-настройки tenant.
• RuntimeLogs: файловые логи compose (только evobgp-all + volume).
• 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.
• Автообнаружение пиров (peer discovery):
  • peer_discovery_enabled (bool) — генерирует в evobgp_peers.conf dynamic BGP listener (neighbor range + import none / export none).
  • peer_discovery_ranges_v4 / peer_discovery_ranges_v6 — CIDR через пробел/запятую (обязательны при enabled).
  • peer_discovery_require_external (bool, default true) — neighbor range … external.
  • Live-сессии evobgp_dyn_* попадают в GET /v1/peers/discovered; оператор одобряет (POST …/approve → обычный bgp_peer + peer_reconcile) или отклоняет.
  • Идентичность pending: Neighbor ID (BGP Identifier), иначе neighbor+ASN.
  • UI: Сеть → вкладка «На одобрение»; настройки — Параметры → BIRD.
• Tenant settings — глобальный default. Per-speaker override: meta_json.bird_bgp_source_ipv4 / node_ipv4 в карточке спикера (Web UI → Сеть → Спикеры); pipeline накладывает overlay при сборке бандла для реплики. См. remote-speakers.md.

Web UI: настройки tenant и интерфейса

Маршрут	Назначение
/settings	Только браузер: API-токен, тема (localStorage). Tenant KV здесь не редактируются.
/tenant-settings	Все tenant-параметры из /v1/settings: вкладки BIRD, Ревизии, Файловые логи (автоочистка FS), Дополнительно (custom KV). Пункт nav «Параметры».
/network → Control plane	Краткая сводка BIRD + ссылка на /tenant-settings?tab=bird.
/operations	Ревизии, diff, jobs; вкладка «Система» перенесена в /tenant-settings.

Web UI: файловые runtime-логи

• Мониторинг → вкладка «Файловые логи» (/monitoring?tab=runtime-logs).
• Подвкладки: Файлы (список, preview хвоста, очистка operator) и Audit очистки (история из БД, в т.ч. auto:scheduler).
• Автоочистка: Параметры → Файловые логи — порог MiB, UTC cron, режим truncate/delete; scheduler в evobgp-all.
• При 503 на списке файлов: FS API недоступен (не evobgp-all или нет volume); GET /v1/runtime-logs/cleanup-audit работает без volume.
• Deploy: EVOBGP_RUNTIME_LOGS_DIR, bind-mount на evobgp-all, sidecar stack-runtime-logs — quickstart.md, access.md.

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
• Runtime log-файлы (sidecar + API): EVOBGP_RUNTIME_LOGS_HOST_DIR на хосте, mount в evobgp-all → /opt/evobgp/runtime-logs; см. access.md и quickstart.md