From 4480d64a7fbb7451080e8c2bc1383214c7df679f Mon Sep 17 00:00:00 2001 From: Denozordec Date: Sat, 4 Apr 2026 01:11:15 +0700 Subject: [PATCH] docs: update EvoBGP architecture plan with new repository structure, refined sections, and detailed service mappings for both reference and microVPS profiles. Enhanced clarity on internal package organization and deployment strategies. --- .../plans/evobgp_архитектура_0e73ef02.plan.md | 170 ++++++++++++++---- 1 file changed, 137 insertions(+), 33 deletions(-) diff --git a/.cursor/plans/evobgp_архитектура_0e73ef02.plan.md b/.cursor/plans/evobgp_архитектура_0e73ef02.plan.md index b38c64b..c6fce3f 100644 --- a/.cursor/plans/evobgp_архитектура_0e73ef02.plan.md +++ b/.cursor/plans/evobgp_архитектура_0e73ef02.plan.md @@ -21,7 +21,7 @@ todos: content: Compose profiles reference + microVPS; сервисы bird2 + evobgp-agent; сеть BGP; лимиты; логи; prune status: pending - id: go-modules - content: Monorepo internal/*, cmd/evobgp-all и cmd/* для reference + content: Monorepo по §1 (дерево репозитория); internal/*, cmd/evobgp-all и cmd/* для reference status: pending - id: replica-bundle content: Подписанный бандл ревизии, API, evobgp-node @@ -37,23 +37,127 @@ Control-plane на **Go**, анонс префиксов через **BIRD**, п ## Содержание -1. [Два эталонных профиля](#1-два-эталонных-профиля-развёртывания) -2. [Логическая модель и термины](#2-логическая-модель-общая-для-обоих-профилей) -3. [Сервисы и контейнеры](#3-сервисы-сравнение-профилей) - - [3.1. Топология Docker Compose](#31-топология-docker-compose) -4. [База данных, ETL, ER-схема](#4-база-данных-etl-er-схема) -5. [Модули префиксов и FQDN](#5-модули-префиксов-as-cdn-домены) -6. [REST API](#6-rest-api) -7. [Генерация BIRD и ревизии](#7-генерация-bird-и-ревизии) -8. [Эксплуатация и масштаб пиров](#8-эксплуатация-и-масштаб) -9. [Реплика evobgp-node](#9-реплика-evobgp-node) -10. [Выбор СУБД](#10-выбор-субд) -11. [Профиль microVPS — детализация](#11-профиль-microvps-детализация) -12. [Риски и этапы](#12-риски-и-этапы-внедрения) +1. [Структура репозитория (файлы и пакеты)](#1-структура-репозитория-файлы-и-пакеты) +2. [Два эталонных профиля](#2-два-эталонных-профиля-развёртывания) +3. [Логическая модель и термины](#3-логическая-модель-общая-для-обоих-профилей) +4. [Сервисы и контейнеры](#4-сервисы-сравнение-профилей) + - [4.1. Топология Docker Compose](#41-топология-docker-compose) +5. [База данных, ETL, ER-схема](#5-база-данных-etl-er-схема) +6. [Модули префиксов и FQDN](#6-модули-префиксов-as-cdn-домены) +7. [REST API](#7-rest-api) +8. [Генерация BIRD и ревизии](#8-генерация-bird-и-ревизии) +9. [Эксплуатация и масштаб пиров](#9-эксплуатация-и-масштаб) +10. [Реплика evobgp-node](#10-реплика-evobgp-node) +11. [Выбор СУБД](#11-выбор-субд) +12. [Профиль microVPS — детализация](#12-профиль-microvps-детализация) +13. [Риски и этапы](#13-риски-и-этапы-внедрения) --- -## 1. Два эталонных профиля развёртывания +## 1. Структура репозитория (файлы и пакеты) + +Monorepo на **Go**: общая логика в `internal/*`, отдельные бинарники в `cmd/*`. Цель — одна кодовая база для профилей **reference** (несколько процессов) и **microVPS** (`evobgp-all`). + +**Принципы:** + +- `**cmd/`** — только точки входа: флаги, переменные окружения, сборка зависимостей (DI), запуск; без доменной логики. +- `**internal/`** — весь прикладной код; внешние модули Go не могут импортировать эти пакеты (правило компилятора). +- **Слои:** `domain` (модели и инварианты без I/O) → `repository` и адаптеры к БД/внешним API → пакеты воркеров (оркестрация) → транспорт (`httpapi`, `jobs`, клиент к агенту). +- **Один код — две упаковки:** микросервисы и `evobgp-all` используют одни и те же пакеты `internal/*`; отличается только набор процессов в `cmd/*`. +- `**docs/`**, `**scripts/`** — как сейчас в репозитории (контракт API: [docs/openapi.yaml](docs/openapi.yaml), вспомогательные скрипты). +- `**deploy/**` — Dockerfiles, `docker-compose` с профилями `reference` / `microVPS`, при необходимости entrypoint’ы для **bird2** / **evobgp-agent**; инфраструктура не смешивается с `internal/`. + +**Целевое дерево каталогов** (ориентир; имена подпакетов можно уточнить при первой итерации кода, **роли** каталогов зафиксированы): + +``` +EvoBGP/ +├── cmd/ +│ ├── evobgp-api/ # REST + постановка jobs (reference) +│ ├── evobgp-scheduler/ +│ ├── evobgp-ingest/ +│ ├── evobgp-render/ +│ ├── evobgp-deploy/ +│ ├── evobgp-all/ # microVPS: те же пакеты, один процесс / несколько goroutine +│ ├── evobgp-agent/ # рядом с bird2: запись конфигов, birdc +│ └── evobgp-node/ # pull бандла, проверка подписи, apply +├── internal/ +│ ├── config/ # загрузка конфигурации (ENV, файлы) +│ ├── platform/ # логирование, метрики, трассировка, health +│ ├── db/ # пул, транзакции; embed миграций или вызов migrate +│ ├── repository/ # SQL по сущностям (tenant, module, peer, revision, jobs, …) +│ ├── domain/ # типы и правила без I/O (префиксы, community, ревизии) +│ ├── httpapi/ # роуты OpenAPI, middleware, валидация, маппинг в сервисы +│ ├── jobs/ # очередь: брокер (reference) vs PG + SKIP LOCKED (microVPS) +│ ├── scheduler/ # триггеры по расписанию модулей +│ ├── ingest/ # CDN, DoH, нормализация, запись в БД +│ ├── render/ # материализация префиксов, ревизия, текст артефактов BIRD +│ ├── birdfmt/ # шаблоны и сборка include-фрагментов (альтернатива имени: bird/) +│ ├── deploy/ # доставка на volume, взаимодействие с evobgp-agent / бандлы +│ ├── bundle/ # упаковка и подпись бандла для evobgp-node +│ └── signing/ # ключи, проверка подписи на ноде +├── migrations/ # SQL миграции PostgreSQL (единый набор для обоих профилей) +├── deploy/ +│ ├── compose/ # docker-compose с профилями +│ └── docker/ # Dockerfile на бинарь + общие слои +├── docs/ +├── scripts/ +├── go.mod +├── go.sum +└── README.md +``` + +**Соответствие сервисам плана:** + + +| Сервис (план) | Код | +| -------------------- | ------------------------------------------------------------------------------------------------ | +| **evobgp-api** | `cmd/evobgp-api`, `internal/httpapi`, `internal/jobs`, `internal/repository` | +| **evobgp-scheduler** | `cmd/evobgp-scheduler`, `internal/scheduler`, `internal/jobs`, `internal/repository` | +| **evobgp-ingest** | `cmd/evobgp-ingest`, `internal/ingest`, `internal/repository` | +| **evobgp-render** | `cmd/evobgp-render`, `internal/render`, `internal/birdfmt`, `internal/repository` | +| **evobgp-deploy** | `cmd/evobgp-deploy`, `internal/deploy`, `internal/bundle`, `internal/repository` | +| **evobgp-all** | `cmd/evobgp-all` — поднимает HTTP и воркеры, импортируя те же `internal/`* | +| **evobgp-agent** | `cmd/evobgp-agent`, `internal/deploy` (запись на volume, `birdc`) | +| **evobgp-node** | `cmd/evobgp-node`, `internal/bundle`, `internal/signing`, `internal/birdfmt` / `internal/deploy` | + + +**Поток пакетов (упрощённо):** + +```mermaid +flowchart TB + subgraph entry [cmd] + API[evobgp-api] + W[scheduler ingest render deploy] + end + subgraph internal [internal] + HTTP[httpapi] + J[jobs] + R[repository] + DBpkg[db] + REN[render] + BF[birdfmt] + DEP[deploy] + end + PG[(PostgreSQL)] + AG[evobgp-agent] + API --> HTTP + HTTP --> J + HTTP --> R + W --> J + W --> R + R --> DBpkg + DBpkg --> PG + REN --> BF + REN --> R + DEP --> R + DEP --> AG +``` + + + +--- + +## 2. Два эталонных профиля развёртывания Один и тот же **код** в дереве `internal/` (все подпакеты), две **упаковки** в Docker Compose. @@ -106,7 +210,7 @@ flowchart LR --- -## 2. Логическая модель (общая для обоих профилей) +## 3. Логическая модель (общая для обоих профилей) - **BGP-сервер (ваш)** — процесс **BIRD**, который **анонсирует** префиксы и держит сессии. - **Клиенты** — **внешние** роутеры (BGP-пиры), подключающиеся **к вам** и **получающие** маршруты. Это не контейнеры EvoBGP. @@ -117,7 +221,7 @@ flowchart LR --- -## 3. Сервисы (сравнение профилей) +## 4. Сервисы (сравнение профилей) | Сервис | Назначение | reference | microVPS | @@ -162,7 +266,7 @@ flowchart TB -### 3.1. Топология Docker Compose +### 4.1. Топология Docker Compose Целевая упаковка: **все компоненты мастера в Compose**, включая **BIRD 2** (`bird2`). Пара **bird2 + evobgp-agent** делает **общий именованный volume** (или bind-mount) для каталога конфигурации и точки управления `birdc` (см. образ/entrypoint в репозитории). @@ -218,13 +322,13 @@ flowchart TB -На **реплике** (`evobgp-node`) — тот же паттерн **bird2 + evobgp-agent** в Docker на отдельном хосте; pull бандла и `birdc configure` без полной БД (см. §9). +На **реплике** (`evobgp-node`) — тот же паттерн **bird2 + evobgp-agent** в Docker на отдельном хосте; pull бандла и `birdc configure` без полной БД (см. §10). --- -## 4. База данных, ETL, ER-схема +## 5. База данных, ETL, ER-схема -### 4.1. Группы сущностей +### 5.1. Группы сущностей | Область | Назначение | @@ -240,7 +344,7 @@ flowchart TB | **job_audit** | Асинхронные задачи; в reference дополняет брокер | -### 4.2. ETL +### 5.2. ETL ```mermaid flowchart LR @@ -272,7 +376,7 @@ flowchart LR -### 4.3. ER (упрощённо) +### 5.3. ER (упрощённо) ```mermaid erDiagram @@ -297,7 +401,7 @@ erDiagram -### 4.4. Пояснения к таблицам +### 5.4. Пояснения к таблицам | Таблица | Назначение | Ключевые поля | Кто использует | @@ -323,7 +427,7 @@ erDiagram --- -## 5. Модули префиксов (AS / CDN / домены) +## 6. Модули префиксов (AS / CDN / домены) ### Продуктовая трактовка @@ -342,7 +446,7 @@ erDiagram --- -## 6. REST API +## 7. REST API Наброски путей, ролей и контрактов вынесены в **[docs/evobgp-api-sketches.md](docs/evobgp-api-sketches.md)** (`/v1`, задачи, бандлы нод). @@ -356,14 +460,14 @@ erDiagram --- -## 7. Генерация BIRD и ревизии +## 8. Генерация BIRD и ревизии - Фрагменты `bird.d/*.conf`, `include`, фильтры, `peers.conf`, community из справочника. - Ревизия: хэш набора префиксов, артефакты, откат = новая ревизия со старым содержимым. --- -## 8. Эксплуатация и масштаб +## 9. Эксплуатация и масштаб - До **~20+** клиентских пиров — строки `bgp_peer`, не отдельные хосты EvoBGP. - Rate-limit CDN, per-module cooldown. @@ -374,7 +478,7 @@ erDiagram --- -## 9. Реплика evobgp-node +## 10. Реплика evobgp-node 1. Render на мастере упаковывает **бандл** (как для мастерского BIRD) + **manifest** (SHA-256) + **подпись** (например Ed25519). 2. **evobgp-node**: fetch → проверка → распаковка → `birdc configure`. @@ -383,7 +487,7 @@ erDiagram --- -## 10. Выбор СУБД +## 11. Выбор СУБД > **Решение по умолчанию:** **PostgreSQL** в **обоих** профилях — один тип миграций, один SQL-диалект в коде (`pgx` / `database/sql`), проще сопровождение и перенос с microVPS на reference без смены БД. @@ -424,7 +528,7 @@ Raft, HTTP/`gorqlite`; для HA control-plane; не замена дефолтн --- -## 11. Профиль microVPS — детализация +## 12. Профиль microVPS — детализация > **Железо:** 1 vCPU · ~1024 МиБ RAM · **7–10 ГиБ** SSD под Docker + данные + логи · Ubuntu 24.04. Рекомендуется **swap 512 МиБ–1 ГиБ**, если его нет. @@ -433,7 +537,7 @@ Raft, HTTP/`gorqlite`; для HA control-plane; не замена дефолтн | Вариант | Состав | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| **A (целевой)** | **evobgp-all** + **postgres** + **bird2** + **evobgp-agent** (общий volume конфигов BIRD; см. [§3.1](#31-топология-docker-compose)) | +| **A (целевой)** | **evobgp-all** + **postgres** + **bird2** + **evobgp-agent** (общий volume конфигов BIRD; см. [§4.1](#41-топология-docker-compose)) | | **B (опция)** | Без отдельного PG — профиль **microVPS_sqlite** + тот же стек **bird2** + **evobgp-agent** | | **C (legacy)** | BIRD только на хосте ОС — **не целевой путь**, только для отладки или жёстких ограничений Docker | @@ -472,7 +576,7 @@ Raft, HTTP/`gorqlite`; для HA control-plane; не замена дефолтн --- -## 12. Риски и этапы внедрения +## 13. Риски и этапы внедрения ### Риски