denozord/EvoBGP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 131 Wiki Activity

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.

Browse Source
This commit is contained in:
Denozordec
2026-04-04 01:11:15 +07:00
parent fbe9cd3f3c
commit 4480d64a7f
1 changed files with 137 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/plans/evobgp_архитектура_0e73ef02.plan.md
+137 -33
View File
@@ -21,7 +21,7 @@ todos:
content: Compose profiles reference + microVPS; сервисы bird2 + evobgp-agent; сеть BGP; лимиты; логи; prune content: Compose profiles reference + microVPS; сервисы bird2 + evobgp-agent; сеть BGP; лимиты; логи; prune
status: pending status: pending
- id: go-modules - id: go-modules
content: Monorepo internal/*, cmd/evobgp-all и cmd/* для reference content: Monorepo по §1 (дерево репозитория); internal/*, cmd/evobgp-all и cmd/* для reference
status: pending status: pending
- id: replica-bundle - id: replica-bundle
content: Подписанный бандл ревизии, API, evobgp-node content: Подписанный бандл ревизии, API, evobgp-node
@@ -37,23 +37,127 @@ Control-plane на **Go**, анонс префиксов через **BIRD**, п
## Содержание ## Содержание
1. [Два эталонных профиля](#1-два-эталонных-профиля-развёртывания) 1. [Структура репозитория (файлы и пакеты)](#1-структура-репозитория-файлы-и-пакеты)
2. [Логическая модель и термины](#2-логическая-модель-общая-для-обоих-профилей) 2. [Два эталонных профиля](#2-два-эталонных-профиля-развёртывания)
3. [Сервисы и контейнеры](#3-сервисы-сравнение-профилей) 3. [Логическая модель и термины](#3-логическая-модель-общая-для-обоих-профилей)
- [3.1. Топология Docker Compose](#31-топология-docker-compose) 4. [Сервисы и контейнеры](#4-сервисы-сравнение-профилей)
4. [База данных, ETL, ER-схема](#4-база-данных-etl-er-схема) - [4.1. Топология Docker Compose](#41-топология-docker-compose)
5. [Модули префиксов и FQDN](#5-модули-префиксов-as-cdn-домены) 5. [База данных, ETL, ER-схема](#5-база-данных-etl-er-схема)
6. [REST API](#6-rest-api) 6. [Модули префиксов и FQDN](#6-модули-префиксов-as-cdn-домены)
7. [Генерация BIRD и ревизии](#7-генерация-bird-и-ревизии) 7. [REST API](#7-rest-api)
8. [Эксплуатация и масштаб пиров](#8-эксплуатация-и-масштаб) 8. [Генерация BIRD и ревизии](#8-генерация-bird-и-ревизии)
9. [Реплика evobgp-node](#9-реплика-evobgp-node) 9. [Эксплуатация и масштаб пиров](#9-эксплуатация-и-масштаб)
10. [Выбор СУБД](#10-выбор-субд) 10. [Реплика evobgp-node](#10-реплика-evobgp-node)
11. [Профиль microVPS — детализация](#11-профиль-microvps-детализация) 11. [Выбор СУБД](#11-выбор-субд)
12. [Риски и этапы](#12-риски-и-этапы-внедрения) 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. Один и тот же **код** в дереве `internal/` (все подпакеты), две **упаковки** в Docker Compose.
@@ -106,7 +210,7 @@ flowchart LR
--- ---
## 2. Логическая модель (общая для обоих профилей) ## 3. Логическая модель (общая для обоих профилей)
- **BGP-сервер (ваш)** — процесс **BIRD**, который **анонсирует** префиксы и держит сессии. - **BGP-сервер (ваш)** — процесс **BIRD**, который **анонсирует** префиксы и держит сессии.
- **Клиенты** — **внешние** роутеры (BGP-пиры), подключающиеся **к вам** и **получающие** маршруты. Это не контейнеры EvoBGP. - **Клиенты** — **внешние** роутеры (BGP-пиры), подключающиеся **к вам** и **получающие** маршруты. Это не контейнеры EvoBGP.
@@ -117,7 +221,7 @@ flowchart LR
--- ---
## 3. Сервисы (сравнение профилей) ## 4. Сервисы (сравнение профилей)
| Сервис | Назначение | reference | microVPS | | Сервис | Назначение | 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 в репозитории). Целевая упаковка: **все компоненты мастера в 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 дополняет брокер | | **job_audit** | Асинхронные задачи; в reference дополняет брокер |
### 4.2. ETL ### 5.2. ETL
```mermaid ```mermaid
flowchart LR flowchart LR
@@ -272,7 +376,7 @@ flowchart LR
### 4.3. ER (упрощённо) ### 5.3. ER (упрощённо)
```mermaid ```mermaid
erDiagram 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`, задачи, бандлы нод). Наброски путей, ролей и контрактов вынесены в **[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 из справочника. - Фрагменты `bird.d/*.conf`, `include`, фильтры, `peers.conf`, community из справочника.
- Ревизия: хэш набора префиксов, артефакты, откат = новая ревизия со старым содержимым. - Ревизия: хэш набора префиксов, артефакты, откат = новая ревизия со старым содержимым.
--- ---
## 8. Эксплуатация и масштаб ## 9. Эксплуатация и масштаб
- До **~20+** клиентских пиров — строки `bgp_peer`, не отдельные хосты EvoBGP. - До **~20+** клиентских пиров — строки `bgp_peer`, не отдельные хосты EvoBGP.
- Rate-limit CDN, per-module cooldown. - Rate-limit CDN, per-module cooldown.
@@ -374,7 +478,7 @@ erDiagram
--- ---
## 9. Реплика evobgp-node ## 10. Реплика evobgp-node
1. Render на мастере упаковывает **бандл** (как для мастерского BIRD) + **manifest** (SHA-256) + **подпись** (например Ed25519). 1. Render на мастере упаковывает **бандл** (как для мастерского BIRD) + **manifest** (SHA-256) + **подпись** (например Ed25519).
2. **evobgp-node**: fetch → проверка → распаковка → `birdc configure`. 2. **evobgp-node**: fetch → проверка → распаковка → `birdc configure`.
@@ -383,7 +487,7 @@ erDiagram
--- ---
## 10. Выбор СУБД ## 11. Выбор СУБД
> **Решение по умолчанию:** **PostgreSQL** в **обоих** профилях — один тип миграций, один SQL-диалект в коде (`pgx` / `database/sql`), проще сопровождение и перенос с microVPS на reference без смены БД. > **Решение по умолчанию:** **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 ГиБ**, если его нет. > **Железо:** 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** | | **B (опция)** | Без отдельного PG — профиль **microVPS_sqlite** + тот же стек **bird2** + **evobgp-agent** |
| **C (legacy)** | BIRD только на хосте ОС — **не целевой путь**, только для отладки или жёстких ограничений Docker | | **C (legacy)** | BIRD только на хосте ОС — **не целевой путь**, только для отладки или жёстких ограничений Docker |
@@ -472,7 +576,7 @@ Raft, HTTP/`gorqlite`; для HA control-plane; не замена дефолтн
--- ---
## 12. Риски и этапы внедрения ## 13. Риски и этапы внедрения
### Риски ### Риски