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

docs: update README to include information about the EvoBGP web interface, linking to quickstart and access documentation for setup and configuration.
CI / changes (push) Successful in 5s
Details
CI / go (push) Successful in 19s
Details
CI / openapi (push) Has been skipped
Details
CI / bird2 (push) Successful in 16s
Details

Browse Source
This commit is contained in:
Denozordec
2026-04-05 17:10:21 +07:00
parent 6a55f72ab3
commit 5d21f013cf
8 changed files with 602 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+42
View File
@@ -0,0 +1,42 @@
# EvoBGP
Control plane для управления префиксами, модулями ingest, ревизиями конфигурации BIRD и выкладкой на BGP-спикеры. Репозиторий включает HTTP API на Go, веб-интерфейс (`web/`), CLI для реплик (`evobgp-node`), агент и Docker Compose для локального и эталонного развёртывания.
## Документация
| Документ | Содержание |
|----------|------------|
| [docs/README.md](docs/README.md) | Оглавление и навигация по разделам |
| [docs/overview.md](docs/overview.md) | Ключевые возможности продукта |
| [docs/quickstart.md](docs/quickstart.md) | Быстрый запуск (Docker, локально, фронтенд) |
| [docs/architecture.md](docs/architecture.md) | Архитектура компонентов и потоков данных |
| [docs/api.md](docs/api.md) | Как работать с REST API и OpenAPI |
| [docs/access.md](docs/access.md) | API-ключи, роли, нода, CORS, безопасность |
Контракт HTTP API: [docs/openapi.yaml](docs/openapi.yaml). Человекочитаемый просмотр: [docs/openapi.html](docs/openapi.html) (см. [docs/OPENAPI-GITEA.md](docs/OPENAPI-GITEA.md)).
## Быстрый старт (Docker)
Из каталога [deploy/compose](deploy/compose) (PowerShell):
```powershell
cd deploy\compose
docker compose --profile microvps up -d --build
```
Профиль **microvps** поднимает `evobgp-all`, PostgreSQL, BIRD2 и агент. API по умолчанию: `http://localhost:8080`.
Эталонный стек (несколько сервисов, NATS, веб UI, Prometheus):
```powershell
docker compose --profile reference up -d --build
```
Подробности портов и переменных окружения — в [docs/quickstart.md](docs/quickstart.md) и в комментариях в [deploy/compose/docker-compose.yaml](deploy/compose/docker-compose.yaml).
## Разработка
- **Go:** модуль `evobgp`, точки входа в `cmd/`.
- **Веб:** SvelteKit в каталоге `web/` (см. [web/README.md](web/README.md)).
Лицензия и условия использования — по политике владельца репозитория.
docs/README.md
+26
View File
@@ -0,0 +1,26 @@
# Документация EvoBGP
Структурированные материалы по проекту на русском языке. Детальный перечень полей и ответов HTTP API — в [openapi.yaml](openapi.yaml) (OpenAPI 3.1).
## По роли читателя
- **Оператор / DevOps** — [quickstart.md](quickstart.md), [architecture.md](architecture.md), [access.md](access.md), [deploy/compose/docker-compose.yaml](../deploy/compose/docker-compose.yaml).
- **Разработчик бэкенда или интегратор API** — [api.md](api.md), [access.md](access.md), [openapi.yaml](openapi.yaml), исходники маршрутов в `internal/httpapi/`.
- **Разработчик фронтенда** — [quickstart.md](quickstart.md) (раздел про `web/` и CORS), [api.md](api.md), [../web/README.md](../web/README.md).
## Оглавление
| Раздел | Описание |
|--------|----------|
| [overview.md](overview.md) | Ключевые возможности системы |
| [quickstart.md](quickstart.md) | Быстрый запуск: Docker, локальный Go, веб |
| [architecture.md](architecture.md) | Компоненты, потоки данных, пакеты |
| [api.md](api.md) | REST: префикс `/v1`, публичные маршруты, ссылки на OpenAPI |
| [access.md](access.md) | Выдача доступа: API-ключи, роли, нода, CORS |
| [openapi.yaml](openapi.yaml) | Источник правды по контракту API |
| [OPENAPI-GITEA.md](OPENAPI-GITEA.md) | Как открыть HTML-документацию API (в т.ч. из Gitea) |
| [evobgp-api-sketches.md](evobgp-api-sketches.md) | Ранний черновик идей API (контекст, не замена OpenAPI) |
## Репозиторий и CI
- [../.gitea/README.md](../.gitea/README.md) — Gitea Actions, требования к runner.
docs/access.md
+98
View File
@@ -0,0 +1,98 @@
# Предоставление доступа
Как выдавать доступ к control plane API, веб-клиентам и репликам BIRD (`evobgp-node`). Секреты храните в менеджере секретов, переменных окружения оркестратора или зашифрованных файлах — не коммитьте реальные ключи в Git.
## API-ключи (`EVOBGP_API_KEYS`)
Формат переменной окружения: список записей через **запятую** без пробелов внутри логики парсера (пробелы вокруг записей допускаются при обрезке). Каждая запись:
```text
<token>|<tenant_id>|<role>
```
- **token** — произвольная строка, передаётся клиентом как `Authorization: Bearer <token>`.
- **tenant_id** — идентификатор арендатора; все операции store привязываются к этому tenant для данного ключа.
- **role** — одна из ролей ниже (регистр для проверки уровня в коде приводится к lower case).
Пример для двух ключей одного tenant:
```text
opkey|01ARZ3NDEKTSV4RRFFQ69G5FAV|operator,nodekey|01ARZ3NDEKTSV4RRFFQ69G5FAV|node
```
При включённом демо-сиде сервер при старте может вывести в лог готовую подсказку с реальным `tenant_id` из БД — см. лог `evobgp-api` / `evobgp-all`.
### Роли
| Роль | Уровень | Назначение |
|------|---------|------------|
| `viewer` | 1 | Только чтение (списки, GET сущностей) там, где это разрешено политикой обработчиков. |
| `editor` | 2 | Чтение + создание/изменение CRUD (модули, записи, peers и т.д.), без опасных операций уровня оператора. |
| `operator` | 3 | Полный операторский доступ: apply, rollback, настройки, отмена задач и т.п. (как задано в handlers). |
| `node` | отдельная | Только API для реплики: latest revision, скачивание бандла, enroll. Роль **`node` запрещена** для обычного CRUD — ответ `403 Forbidden`. |
Обратное ограничение: для эндпоинтов ноды требуется именно роль **`node`**; остальные роли получают отказ.
### Режим разработки `EVOBGP_DEV_INSECURE`
Если установлено `EVOBGP_DEV_INSECURE=1` и в store доступен демо-tenant (`DemoIDs`), то запрос с заголовком **`Authorization: Bearer dev`** получает контекст **`operator`** для этого tenant.
**Запрещено** в продакшене: любой, кто знает заголовок, получает полные права оператора на демо-данные.
### Детерминированный ключ подписи бандлов (тесты)
`EVOBGP_BUNDLE_SEED_HEX` — необязательная hex-строка для инициализации ключа подписи бандлов (удобно в CI и локальных прогонах). В проде обычно используется случайная генерация при старте, если seed не задан.
## Публичный ключ бандла для нод
При старте API в лог печатается строка **bundle signing public key (base64)**. Её нужно передать администратору реплики и использовать в `evobgp-node`:
```text
evobgp-node verify-bundle -f bundle.tar.gz -pubkey-base64 "<из_лога_API>"
evobgp-node apply-bundle -f bundle.tar.gz -extract-dir /path/to/dir -pubkey-base64 "<...>"
```
Команда `pull-bundle` использует **тот же Bearer-токен**, что зарегистрирован с ролью **`node`**:
```text
evobgp-node pull-bundle -base-url http://control.example:8080 -token "<node_token>" -speaker-id "<uuid>"
```
## CORS для веб-интерфейса
Браузерные запросы с другого origin требуют заголовков CORS на API. Задайте список разрешённых origin через **`EVOBGP_CORS_ORIGINS`** (через запятую), например:
```text
http://localhost:5173,http://127.0.0.1:5173,https://ui.example.com
```
Разрешённые заголовки включают `Authorization`, `Content-Type`, `Idempotency-Key`, `Accept`, `X-Tenant-Id` (см. `internal/httpapi/cors.go`).
## Заголовок `X-Tenant-Id` (спецификация vs реализация)
В [openapi.yaml](openapi.yaml) описано использование **`X-Tenant-Id`** для супер-ролей при работе от имени разных арендаторов. В **текущем коде** после аутентификации tenant берётся **только из записи API-ключа**; заголовок `X-Tenant-Id` **не переопределяет** tenant в обработчиках. До появления поддержки в коде не рассчитывайте на переключение tenant через этот заголовок.
## Доступ к репозиторию и CI
Чтобы коллега мог читать код, открывать PR и видеть результаты Gitea Actions:
- Выдайте права на репозиторий в вашей forge (Gitea/GitHub/GitLab): как минимум **Read** для просмотра, **Write** для веток и PR.
- Требования к runner и описание workflow — [.gitea/README.md](../.gitea/README.md).
Секреты для публикации образов или внешних сервисов в базовом CI не обязательны; добавляйте их отдельно под свои workflow.
## Краткая матрица (ориентир)
| Действие | viewer | editor | operator | node |
|----------|--------|--------|----------|------|
| GET модули, ревизии, peers, speakers | да | да | да | нет |
| POST/PATCH/DELETE CRUD сущностей | нет | да | да | нет |
| apply, rollback, PATCH settings | нет | нет | да | нет |
| bundle, latest revision, enroll | нет | нет | нет | да |
Точные проверки по каждому маршруту — в коде `internal/httpapi` и в схеме безопасности операций в OpenAPI.
## Связанные документы
- [api.md](api.md) — список групп эндпоинтов.
- [quickstart.md](quickstart.md) — запуск с примером ключей.
docs/api.md
+126
View File
@@ -0,0 +1,126 @@
# REST API: обзор и ссылки
Полный контракт запросов и ответов описан в **[openapi.yaml](openapi.yaml)** (OpenAPI 3.1). Этот файл — **источник правды**. Краткий контекст и ранние таблицы — в [evobgp-api-sketches.md](evobgp-api-sketches.md) (черновик, не заменяет OpenAPI).
## Базовый URL и версия
- Все функциональные маршруты API используют префикс **`/v1`** (например `https://api.example.com/v1/modules`).
- Версия сборки: **`GET /v1/version`** (публичный маршрут, без Bearer).
## Публичные маршруты (без `Authorization`)
| Метод | Путь | Назначение |
|-------|------|------------|
| `GET` | `/v1/health` | Liveness |
| `GET` | `/v1/ready` | Readiness (зависимости, например БД) |
| `GET` | `/v1/version` | Версия / метаданные сборки |
Дополнительно на корне сервера (вне `/v1`):
| Метод | Путь | Назначение |
|-------|------|------------|
| `GET` | `/metrics` | Метрики Prometheus |
Все остальные запросы под **`/v1/...`**, кроме перечисленных выше трёх `GET`, проходят через middleware и требуют **`Authorization: Bearer <api_key>`** (см. [access.md](access.md)).
## Группы маршрутов (соответствие тегам OpenAPI)
Ниже — обзор того, что реализовано в коде (`internal/httpapi/routes.go`, `routes_crud.go`). Детали тел, кодов ответов и схем — только в OpenAPI.
### Modules
- `GET /v1/modules`, `GET /v1/modules/{module_id}`
- `POST /v1/modules`, `PATCH /v1/modules/{module_id}`, `DELETE /v1/modules/{module_id}`
- `GET|POST|PATCH|DELETE` для `.../cdn-sources`, `.../as-entries`, `.../domain-entries`, `.../ip-range-entries`
- `POST /v1/modules/{module_id}/refresh`
### DoH profiles
- `GET|POST /v1/doh-profiles`
- `GET|PATCH|DELETE /v1/doh-profiles/{id}`
### Communities
- `GET|POST /v1/communities`
- `GET|PATCH|DELETE /v1/communities/{id}`
### Peers
- `GET /v1/peers`, `POST /v1/peers`
- `GET|PATCH|DELETE /v1/peers/{id}`
### Speakers
- `GET /v1/speakers`, `POST /v1/speakers`
- `GET|PATCH /v1/speakers/{speaker_id}` (в коде идентификатор в пути — `speaker_id`; в части маршрутов apply используется `{id}` — смотрите OpenAPI и реализацию)
Уточнение по коду: для apply на одном спикере зарегистрирован маршрут `POST /speakers/{id}/apply` внутри v1 mux → **`POST /v1/speakers/{id}/apply`**.
### Revisions
- `GET /v1/revisions`, `GET /v1/revisions/{revision_id}`
- `GET /v1/revisions/{revision_id}/prefixes`
- `GET /v1/revisions/{revision_id}/preview`
- `GET /v1/revisions/{revision_a}/diff/{revision_b}`
- `POST /v1/revisions/{revision_id}/rollback`
### Deploy и BIRD
- `POST /v1/apply`
- `POST /v1/speakers/{id}/apply`
- `POST /v1/bird/reload`
### Jobs
- `GET /v1/jobs`, `GET /v1/jobs/{job_id}`
- `POST /v1/jobs/{job_id}/cancel`
### Node (роль `node`)
- `GET /v1/speakers/{speaker_id}/revisions/latest`
- `GET /v1/speakers/{speaker_id}/bundle/{revision_id}`
- `POST /v1/nodes/enroll`
### Settings
- `GET /v1/settings`, `PATCH /v1/settings`
## Соглашения из OpenAPI
- Ошибки в стиле **RFC 9457** (`application/problem+json`): `type`, `title`, `status`, `detail`, и т.д.
- Пагинация списков: query-параметры `cursor`, `limit`; в ответе часто `items`, `next_cursor`, `has_more`.
- Заголовок **`Idempotency-Key`** для идемпотентных мутаций (рекомендации — в описаниях операций в OpenAPI).
- Заголовок **`X-Tenant-Id`** описан в спецификации для супер-ролей; в **текущей реализации Go** tenant берётся **только из API-ключа**, заголовок в обработчиках не переключает контекст (см. [access.md](access.md)).
## Как смотреть документацию API
- Статическая страница Redoc: [openapi.html](openapi.html) (инструкции для Gitea и пересборки — [OPENAPI-GITEA.md](OPENAPI-GITEA.md)).
- Пересборка после правок YAML (из корня репозитория, PowerShell):
```powershell
.\scripts\build-openapi-html.ps1
```
## Примеры вызовов
PowerShell, список модулей (подставьте свой токен и URL):
```powershell
$base = "http://localhost:8080"
$token = "opkey"
$h = @{ Authorization = "Bearer $token" }
Invoke-RestMethod -Uri "$base/v1/modules" -Headers $h
```
Эквивалент с `curl` (если установлен):
```text
curl -s -H "Authorization: Bearer opkey" http://localhost:8080/v1/modules
```
CORS для браузерных клиентов настраивается переменной **`EVOBGP_CORS_ORIGINS`** на стороне API.
## Связанные документы
- [access.md](access.md) — ключи и роли.
- [overview.md](overview.md) — продуктовые возможности.
docs/architecture.md
+108
View File
@@ -0,0 +1,108 @@
# Архитектура EvoBGP
Высокоуровневое описание компонентов и потоков. Детальный продуктовый и инфраструктурный чертёж также зафиксирован во внутреннем плане репозитория: `.cursor/plans/evobgp_архитектура_0e73ef02.plan.md` (удобно для истории решений; пользовательская навигация — через этот раздел и [overview.md](overview.md)).
## Назначение слоёв
- **Control plane** — HTTP API, хранилище состояния (PostgreSQL), фоновые задачи (jobs), подпись артефактов (бандлы), observability.
- **Data plane** — демон BIRD, локальные конфиги в `/etc/bird`, сокет управления `birdc`, агент `evobgp-agent` для наблюдения/сопутствующих действий.
- **Edge интеграция** — CLI `evobgp-node` на машине спикера: получение бандла по API, проверка подписи, применение конфигурации.
## Компоненты (бинарники `cmd/`)
| Бинарник | Роль |
|----------|------|
| `evobgp-api` | Только HTTP API и связанная логика в одном процессе. |
| `evobgp-all` | Режим одной VPS: тот же API + in-process запуск заглушек scheduler, ingest, render, deploy. |
| `evobgp-scheduler` | Планировщик cron/интервалов модулей (в коде сейчас **stub**). |
| `evobgp-ingest` | Воркеры загрузки внешних источников (CDN и т.д.) (**stub**). |
| `evobgp-render` | Генерация артефактов BIRD из ревизий (**stub**). |
| `evobgp-deploy` | Выкладка на спикеры / взаимодействие с BIRD на стороне деплоя (**stub**). |
| `evobgp-node` | CLI реплики: `pull-bundle`, `verify-bundle`, `apply-bundle`. |
| `evobgp-agent` | Локальный агент рядом с BIRD (например `watch` по сокету). |
В Docker Compose профиль **reference** запускает отдельные контейнеры под `evobgp-api` и четыре воркера; профиль **microvps** использует один контейнер `evobgp-all`.
## Пакеты `internal/` (сжатая карта)
| Пакет | Назначение |
|-------|------------|
| `httpapi` | Маршруты REST, аутентификация, CORS, привязка к store и jobs. |
| `store` | Абстракция бэкенда данных; реализации в памяти и через репозиторий. |
| `repository` | Доступ к PostgreSQL, сущности и миграции на уровне приложения. |
| `db` | Подключение к БД и применение миграций. |
| `jobs` | Реестр и выполнение асинхронных задач, связанных с API. |
| `bundle` | Упаковка и проверка бандлов для нод. |
| `signing` | Криптографическая проверка подписей. |
| `birdfmt` | Форматирование и фрагменты конфигурации BIRD, вызовы `birdc`. |
| `birddeploy` | Логика применения конфигурации к BIRD (используется в цепочке деплоя). |
| `config` | Переменные окружения `EVOBGP_*`. |
| `observability` | Метрики Prometheus, HTTP middleware. |
| `broker` | Заготовка под NATS/Redis (логирование подключения в воркерах). |
## Диаграмма: эталонный Compose (reference)
```mermaid
flowchart LR
subgraph clients [Clients]
WebUI[Web_UI]
Operator[Operator_API_client]
NodeCLI[evobgp_node]
end
subgraph control [Control_plane]
API[evobgp_api]
Sched[evobgp_scheduler_stub]
Ingest[evobgp_ingest_stub]
Render[evobgp_render_stub]
Deploy[evobgp_deploy_stub]
PG[(PostgreSQL)]
NATS[NATS_JetStream]
end
subgraph data [Data_plane]
BIRD[BIRD2]
Agent[evobgp_agent]
end
WebUI --> API
Operator --> API
NodeCLI --> API
API --> PG
Sched --> NATS
Ingest --> NATS
Render --> NATS
Deploy --> NATS
Sched --> PG
Ingest --> PG
Render --> PG
Deploy --> PG
Agent --> BIRD
```
На практике воркеры **пока не выполняют** полноценную работу с очередью — они резервируют место в топологии и пишут в лог. API и БД уже обеспечивают основной сценарий разработки и тестов.
## Диаграмма: microvps (`evobgp-all`)
```mermaid
flowchart LR
Client[HTTP_clients]
All[evobgp_all_process]
PG[(PostgreSQL)]
BIRD[BIRD2]
Client --> All
All --> PG
All --> BIRD
```
Внутри процесса `evobgp-all` горутины scheduler/ingest/render/deploy — те же **stub**, что и отдельные бинарники.
## Поток: ревизия и бандл для ноды
1. Оператор (роль `operator` или выше по политике) изменяет модули и запускает цепочку, приводящую к новой **ревизии** (часть шагов может быть асинхронной через jobs — см. OpenAPI).
2. Control plane формирует **подписанный бандл** для пары спикер + ревизия.
3. `evobgp-node pull-bundle` с ключом роли `node` запрашивает `GET /v1/speakers/{id}/revisions/latest` и затем `GET /v1/speakers/{id}/bundle/{revision_id}`.
4. Локально выполняется проверка подписи (публичный ключ выдаётся при старте API) и применение к BIRD (`apply-bundle`).
## Связанные документы
- [quickstart.md](quickstart.md) — как поднять стек.
- [api.md](api.md) — точки входа HTTP.
- [access.md](access.md) — ключи и роли.
docs/overview.md
+70
View File
@@ -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) — ранние таблицы эндпоинтов (черновик).
docs/quickstart.md
+130
View File
@@ -0,0 +1,130 @@
# Быстрый запуск
Примеры команд для **PowerShell**. Репозиторий: корень `EvoBGP`, Docker Compose лежит в `deploy\compose`.
## Требования
- **Docker** с поддержкой Compose v2 — для готового стека.
- **Go 1.22+** (версию см. в `go.mod`) — для локального запуска бинарников из исходников.
- **Node.js** и npm — для разработки веб-интерфейса в `web/`.
- **PostgreSQL** — если запускаете API вне Compose; строка подключения в `EVOBGP_DATABASE_URL`.
## Вариант 1: Docker, профиль microvps
Один процесс `evobgp-all` (HTTP API + in-process заглушки воркеров), PostgreSQL, BIRD2, `evobgp-agent`.
```powershell
cd deploy\compose
docker compose --profile microvps up -d --build
```
Ожидаемые сервисы:
- **API:** `http://localhost:8080` (внутри контейнера `EVOBGP_HTTP_ADDR=:8080`).
- **BGP:** порт **179/tcp** проброшен с контейнера BIRD (для отладки; в проде часто нужен `network_mode: host` или отдельная сеть — см. комментарии в `docker-compose.yaml`).
Проверка живости (без ключа):
```powershell
Invoke-RestMethod -Uri "http://localhost:8080/v1/health"
```
Остановка:
```powershell
docker compose --profile microvps down
```
Полная очистка томов (осторожно, удалит данные БД):
```powershell
docker compose --profile microvps down -v
```
## Вариант 2: Docker, профиль reference
Эталонное разбиение: отдельные контейнеры `evobgp-api`, `evobgp-scheduler`, `evobgp-ingest`, `evobgp-render`, `evobgp-deploy`, NATS JetStream, веб UI за nginx, опционально Prometheus.
```powershell
cd deploy\compose
docker compose --profile reference up -d --build
```
Полезные порты:
| Порт | Назначение |
|------|------------|
| 8080 | HTTP API (`evobgp-api`) |
| 3000 | Веб UI (`evobgp-web` → nginx, прокси на API) |
| 4222 | NATS |
| 9090 | Prometheus (в compose) |
| 179 | BGP (BIRD2) |
**Важно:** процессы `evobgp-scheduler`, `evobgp-ingest`, `evobgp-render`, `evobgp-deploy` в текущей версии кода — **заглушки** (логирование и периодический тик). Реальная очередь задач и брокер подключаются в будущих итерациях; API и БД при этом уже работают.
## Вариант 3: Локально без Docker (только API)
1. Поднимите PostgreSQL и создайте БД (или используйте существующую).
2. Установите переменные окружения в текущей сессии PowerShell:
```powershell
$env:EVOBGP_DATABASE_URL = "postgres://user:pass@localhost:5432/evobgp?sslmode=disable"
$env:EVOBGP_HTTP_ADDR = ":8080"
# Ключи обязательны для защищённых маршрутов (пример формата см. access.md)
$env:EVOBGP_API_KEYS = "op|YOUR_TENANT_ID|operator"
```
3. Запуск только HTTP API:
```powershell
cd <корень-клона-репозитория>
go run .\cmd\evobgp-api
```
Или монолит **microVPS** (тот же API плюс горутины заглушек scheduler/ingest/render/deploy):
```powershell
go run .\cmd\evobgp-all
```
При старте в лог выводится **публичный ключ бандла** (base64) — его нужно передать на сторону `evobgp-node` для проверки подписи. При включённом демо-сиде (`EVOBGP_SEED_DEMO` не равен `0`, поведение по умолчанию) сервер также печатает подсказку с примером `EVOBGP_API_KEYS`.
Для разработки без настройки ключей (только демо-данные):
```powershell
$env:EVOBGP_DEV_INSECURE = "1"
go run .\cmd\evobgp-api
```
Запросы с заголовком `Authorization: Bearer dev` получают роль operator в демо-tenant. **Не включайте в продакшене.**
## Вариант 4: Веб-интерфейс (разработка)
```powershell
cd web
npm install
npm run dev
```
Укажите в окружении API список разрешённых origin для CORS (пример для Vite на порту 5173):
```powershell
$env:EVOBGP_CORS_ORIGINS = "http://localhost:5173,http://127.0.0.1:5173"
```
В эталонном Compose для `evobgp-api` уже заданы origin для 5173 и 3000 — см. `deploy/compose/docker-compose.yaml`.
## Пересборка HTML из OpenAPI
После правок `docs/openapi.yaml`:
```powershell
.\scripts\build-openapi-html.ps1
```
Подробности — [OPENAPI-GITEA.md](OPENAPI-GITEA.md).
## Дальше
- [access.md](access.md) — как выдать ключи и настроить ноду.
- [architecture.md](architecture.md) — состав сервисов и пакетов.
web/README.md
+2
View File
@@ -2,6 +2,8 @@
Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli).
Это веб-интерфейс **EvoBGP**. Запуск вместе с API, CORS и портами — в [../docs/quickstart.md](../docs/quickstart.md); доступ и ключи — [../docs/access.md](../docs/access.md).
## Creating a project
If you're seeing this, you've probably already done this step. Congrats!