DenozordecandCursor
a0f78a3d21
Обновлены разделы документации для управления файловыми логами, включая новые эндпоинты и параметры. Добавлены описания для вкладки «Файловые логи» в интерфейсе мониторинга и обновлены настройки tenant. Улучшен доступ к логам через API и интерфейс пользователя. Co-authored-by: Cursor <[email protected]>
162 lines
9.7 KiB
Markdown
162 lines
9.7 KiB
Markdown
# Полное руководство по 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`.
|
||
- **Tenant settings** — глобальный default. **Per-speaker** override: `meta_json.bird_bgp_source_ipv4` / `node_ipv4` в карточке спикера (Web UI → Сеть → Спикеры); pipeline накладывает overlay при сборке бандла для реплики. См. [remote-speakers.md](remote-speakers.md).
|
||
|
||
### Web UI: настройки tenant и интерфейса
|
||
|
||
| Маршрут | Назначение |
|
||
|---------|------------|
|
||
| `/settings` | Только браузер: API-токен, тема (localStorage). Tenant KV здесь **не** редактируются. |
|
||
| `/tenant-settings` | Все tenant-параметры из `/v1/settings`: вкладки **BIRD**, **Ревизии** (`revision_retention_minutes`), **Дополнительно** (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 очистки**.
|
||
- При **503** на списке файлов: FS API недоступен (не `evobgp-all` или нет volume); audit из БД может отображаться отдельно.
|
||
- Deploy: `EVOBGP_RUNTIME_LOGS_DIR`, bind-mount на `evobgp-all`, sidecar `stack-runtime-logs` — [quickstart.md](quickstart.md#файловые-runtime-логи-api-v1runtime-logs), [access.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](access.md) и [quickstart.md](quickstart.md#файловые-runtime-логи-api-v1runtime-logs)
|
||
|