docs: update README to include information about the EvoBGP web interface, linking to quickstart and access documentation for setup and configuration.

2026-04-05 17:10:21 +07:00
parent 6a55f72ab3
commit 5d21f013cf
8 changed files with 602 additions and 0 deletions
@@ -0,0 +1,70 @@
+# Ключевые возможности EvoBGP
+
+EvoBGP — это control plane для описания источников префиксов (модули), сборки согласованных снимков (ревизии), генерации конфигурации BIRD и доставки подписанных артефактов на BGP-спикеры. Ниже — продуктовый обзор; точные пути и схемы запросов — в [openapi.yaml](openapi.yaml).
+
+## Модули префиксов
+
+Один **модуль** — настраиваемый экземпляр с типом и параметрами расписания. Поддерживаемые типы (поле `type` при создании):
+
+| Тип | Назначение |
+|-----|------------|
+| `AS_PREFIXES` | ASN и связанные префиксы |
+| `CDN_CIDRS` | CIDR из внешних CDN-источников (URL, виды источников) |
+| `DOMAINS` | FQDN с привязкой к BGP community; опционально DoH-профили |
+| `IP_RANGES` | Статические CIDR + `community_id` (данные в БД, без внешнего ingest по URL) |
+
+Для каждого модуля доступны CRUD-операции над вложенными коллекциями: `cdn-sources`, `as-entries`, `domain-entries`, `ip-range-entries` (в зависимости от типа модуля).
+
+Дополнительно: **принудительный refresh** (`POST .../modules/{id}/refresh`) для типов, где имеет смысл пересборка/ingest (для `IP_RANGES` поведение может быть no-op или отказ — см. реализацию и OpenAPI).
+
+## DoH-профили и BGP community
+
+- **DoH-профили** — настройки DNS-over-HTTPS для модулей с доменами; секреты в ответах API не раскрываются.
+- **Communities** — справочник BGP community в границах tenant для классификации префиксов.
+
+## Пиры и спикеры
+
+- **Peers** — BGP-соседи и политики; привязка к конкретному спикеру или ко всем.
+- **Speakers** — зарегистрированные экземпляры BIRD (роли вроде master/replica/canary в продуктовой модели).
+
+## Ревизии конфигурации
+
+- **История ревизий** — неизменяемые снимки состояния конфигурации и артефактов.
+- **Превью** — просмотр фрагментов BIRD без применения на железе.
+- **Снимок префиксов** — материализованный список префиксов для ревизии (с пагинацией).
+- **Сравнение ревизий** — diff между двумя ревизиями.
+- **Откат** — создание новой ревизии на основе выбранной прошлой (часто асинхронно, через jobs).
+
+## Применение и задачи
+
+- **Apply** — выкладка целевой ревизии на спикеры (глобально или на один спикер); типичный ответ для долгих операций — `202 Accepted` и ссылка на job.
+- **Reload BIRD** — отдельный или связанный шаг мягкой перезагрузки политики (см. OpenAPI).
+- **Jobs** — асинхронные задачи: список, статус, запрос отмены (best-effort).
+
+## Реплики: `evobgp-node` и бандлы
+
+Узлы с ролью **`node`** в API получают не общий CRUD, а узкие эндпоинты:
+
+- указатель на последнюю ревизию для спикера;
+- скачивание **подписанного бандла** (архив + манифест + подпись Ed25519).
+
+CLI `evobgp-node` поддерживает `pull-bundle`, `verify-bundle`, `apply-bundle` для проверки подписи и применения к локальному BIRD.
+
+## Веб-интерфейс
+
+Каталог `web/` — SvelteKit-приложение для операторов (статическая сборка в Docker-образе эталонного профиля). Для разработки UI обычно используется dev-сервер на порту Vite/SvelteKit с проксированием или прямым вызовом API; на стороне API задаётся CORS (`EVOBGP_CORS_ORIGINS`).
+
+## Наблюдаемость
+
+- **`GET /metrics`** — Prometheus-метрики процесса API (без префикса `/v1`).
+- Опционально — опрос `birdc` по сокету (`EVOBGP_BIRDC_SOCKET` и связанные переменные) для метрик протоколов BGP.
+
+## Глобальные настройки
+
+Эндпоинты `GET/PATCH /v1/settings` — операторские флаги и лимиты (см. OpenAPI).
+
+## Связанные документы
+
+- [api.md](api.md) — как вызывать API на практике.
+- [architecture.md](architecture.md) — из каких процессов и пакетов это собрано.
+- [evobgp-api-sketches.md](evobgp-api-sketches.md) — ранние таблицы эндпоинтов (черновик).