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
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. Риски и этапы внедрения
### Риски