EvoBGP/docs/quickstart.md

Быстрый запуск

Примеры команд для PowerShell. Репозиторий: корень EvoBGP, Docker Compose лежит в deploy\compose.

Фоновый collector BGP/health опрашивает speaker с интервалом 20 секунд (EVOBGP_TELEMETRY_INTERVAL_SEC, допустимо 15–300) и ограничивает параллелизм четырьмя workers (EVOBGP_TELEMETRY_WORKERS, допустимо 1–32). Данные старше трёх интервалов считаются устаревшими. Для локального BIRD задайте EVOBGP_TELEMETRY_LOCAL_ID как стабильный уникальный ID именно BIRD-узла, если несколько control-plane инстансов используют одну PostgreSQL БД; одинаковый ID допустим только для инстансов, читающих один и тот же BIRD. Без ID используется hostname контейнера и путь сокета, поэтому после пересоздания контейнера старый локальный snapshot может остаться до очистки.

Требования

• Docker с поддержкой Compose v2 — для готового стека.
• Go 1.22+ (версию см. в go.mod) — для локального запуска бинарников из исходников.
• Node.js и npm — для разработки веб-интерфейса в web/.
• PostgreSQL — если запускаете API вне Compose; строка подключения в EVOBGP_DATABASE_URL.

Готовые образы без сборки (Container Registry Gitea)

После успешного CD (push в main или master, job publish) образы публикуются в Container Registry вашего Gitea. В workflow зафиксирован хост реестра git.shx.one; имя владельца в пути образа — в нижнем регистре, как у github.repository_owner в CI (например, пользователь Denozord → префикс denozord).

Шаблон имени и теги

git.shx.one/<owner>/<имя_образа>:<тег>

Теги: latest, короткий SHA коммита (7 символов), sha-<полный_sha> — см. .gitea/README.md.

Платформа образов из CI: linux/amd64 (на другой архитектуре pull пройдёт, но запуск может быть невозможен без своей сборки).

Вход в реестр (если пакеты не публичные)

На сервере или в PowerShell перед docker pull:

docker login git.shx.one

Укажите учётную запись Gitea и PAT / пароль приложения с правом чтения пакетов (или токен, который принимает ваш реестр).

Ссылки и команды docker pull

Ниже пример для владельца denozord — замените сегмент пути на своего владельца репозитория в нижнем регистре. В веб-интерфейсе все контейнерные пакеты можно открыть разом: список пакетов denozord на git.shx.one. Если прямая ссылка на версию latest не открывается (зависит от версии Gitea), откройте общий список пакетов и выберите нужный образ по имени.

Образ	Назначение	Страница пакета (пример)	Pull
evobgp-api	HTTP API (с bird/birdc в образе для parse-check)	packages/…/evobgp-api	docker pull git.shx.one/denozord/evobgp-api:latest
evobgp-all	Монолит microVPS: API + in-process воркеры scheduler/ingest/render/deploy	packages/…/evobgp-all	docker pull git.shx.one/denozord/evobgp-all:latest
evobgp-scheduler	Планировщик (reference)	packages/…/evobgp-scheduler	docker pull git.shx.one/denozord/evobgp-scheduler:latest
evobgp-ingest	Ingest CDN / ETag	packages/…/evobgp-ingest	docker pull git.shx.one/denozord/evobgp-ingest:latest
evobgp-render	Render	packages/…/evobgp-render	docker pull git.shx.one/denozord/evobgp-render:latest
evobgp-deploy	Deploy	packages/…/evobgp-deploy	docker pull git.shx.one/denozord/evobgp-deploy:latest
evobgp-node	Нода на площадке	packages/…/evobgp-node	docker pull git.shx.one/denozord/evobgp-node:latest
evobgp-web	Статика UI + nginx (прокси на evobgp-api)	packages/…/evobgp-web	docker pull git.shx.one/denozord/evobgp-web:latest
evobgp-web-all	Тот же UI, прокси на evobgp-all (профиль microvps-full)	packages/…/evobgp-web-all	docker pull git.shx.one/denozord/evobgp-web-all:latest
evobgp-agent	Агент (bird2 в образе)	packages/…/evobgp-agent	docker pull git.shx.one/denozord/evobgp-agent:latest
evobgp-bird2	Только BIRD2	packages/…/evobgp-bird2	docker pull git.shx.one/denozord/evobgp-bird2:latest

На Linux-сервере команды docker pull и docker login такие же (выполняйте в обычном shell).

Запуск контейнера с готового образа (минимум)

После pull, например только API (порты и переменные подставьте свои):

docker run --rm -p 8080:8080 `
  -e EVOBGP_DATABASE_URL="postgres://user:pass@host:5432/evobgp?sslmode=disable" `
  -e EVOBGP_HTTP_ADDR=":8080" `
  git.shx.one/denozord/evobgp-api:latest

Compose в deploy/compose поднимает стек только из образов реестра (image:, без локальной сборки). Префикс и тег задаются через .env рядом с compose-файлами (шаблон — deploy/compose/.env.example): EVOBGP_REGISTRY=git.shx.one/<owner> (владелец в нижнем регистре), EVOBGP_IMAGE_TAG=latest или SHA. Перед первым запуском: docker login git.shx.one, затем docker compose pull и docker compose ... up -d. Имена пакетов и CI — .gitea/README.md.

Вариант 1: Docker, профиль microvps

Один процесс evobgp-all (HTTP API + in-process воркеры scheduler, ingest, render, deploy), PostgreSQL, BIRD2, evobgp-agent.

cd deploy\compose
Copy-Item .env.example .env -Force   # или создайте .env вручную; укажите EVOBGP_REGISTRY / EVOBGP_IMAGE_TAG
docker login git.shx.one
docker compose --profile microvps pull
docker compose --profile microvps up -d

Ожидаемые сервисы:

• API: http://localhost:8080 (внутри контейнера EVOBGP_HTTP_ADDR=:8080).
• BGP: порт 179/tcp проброшен с контейнера BIRD (для отладки; в проде часто нужен network_mode: host или отдельная сеть — см. комментарии в docker-compose.yaml).

Проверка живости (без ключа):

Invoke-RestMethod -Uri "http://localhost:8080/v1/health"

Остановка:

docker compose --profile microvps down

Полная очистка томов (осторожно, удалит данные БД):

docker compose --profile microvps down -v

Вариант 1b: microVPS ~1 ГиБ RAM — полный набор + Web UI

Один монолит evobgp-all (те же in-process воркеры, что и в варианте 1), плюс статическая панель за nginx (evobgp-web-microvps) и Prometheus со скрейпом метрик с evobgp-all. Отдельные контейнеры evobgp-scheduler / evobgp-ingest / … не нужны — это тот же код в одном процессе. NATS JetStream запускается только с дополнительным профилем nats.

Рекомендация: на хосте с ровно 1 ГиБ включите swap (1–2 ГиБ), иначе при пиках возможен OOM. На 2+ ГиБ можно поднять тот же профиль без второго файла — останутся более мягкие лимиты из основного docker-compose.yaml.

Из каталога deploy\compose (как в варианте 1: .env из .env.example, при необходимости docker login git.shx.one):

1. Подготовьте отдельный файл параметров защищенного UI:

Copy-Item .env.web-sec.example .env.web-sec -Force

2. Заполните в .env.web-sec:

• WEBUI_DOMAIN — домен панели;
• WEBUI_IP_WHITELIST — список разрешенных IP/CIDR через запятую;
• LETSENCRYPT_EMAIL — email для ACME;
• CF_DNS_API_TOKEN — Cloudflare token для DNS challenge (минимальные права Zone:DNS:Edit на нужной зоне).

3. В Cloudflare для WEBUI_DOMAIN используйте запись в режиме DNS only (серый облачок), указывающую на публичный IP VPS.

4. Запускайте compose с двумя env-файлами:

# С текущими лимитами (пригодность для хоста ~1 ГиБ требует замера под нагрузкой)
docker compose --env-file .env --env-file .env.web-sec -f docker-compose.yaml -f docker-compose.microvps-full.yaml --profile microvps-full pull
docker compose --env-file .env --env-file .env.web-sec -f docker-compose.yaml -f docker-compose.microvps-full.yaml --profile microvps-full up -d

Только профиль microvps-full и без файла docker-compose.microvps-full.yaml (лимиты как в базовом compose):

docker compose --env-file .env --env-file .env.web-sec --profile microvps-full pull
docker compose --env-file .env --env-file .env.web-sec --profile microvps-full up -d

Если NATS нужен внешним клиентам, добавьте --profile nats к командам pull и up. Проверьте таких клиентов до изменения рабочего стека. EVOBGP_BROKER_URL в текущем приложении только записывается в лог и не включает брокерную очередь. Для standalone stack.microvps-full.yaml и production example сервис NATS также включается профилем nats. Перенос существующей истории Prometheus при обновлении описан в docker-resources.md.

Порт	Назначение
80	HTTP вход (редирект на HTTPS через Traefik)
443	HTTPS Web UI (Traefik + Let's Encrypt)
8080	Прямой HTTP API (evobgp-all)
9090	Prometheus (prometheus-microvps)
4222	NATS (только с профилем nats)
179	BGP (BIRD2), как в варианте 1

Проверка UI:

• http://<WEBUI_DOMAIN> должен редиректить на https://<WEBUI_DOMAIN>;
• с IP из WEBUI_IP_WHITELIST UI доступен по HTTPS;
• с неразрешенного IP Traefik вернет 403.
• исключение: GET /v1/firewall/install.sh, GET /v1/firewall/sync-script, POST /v1/firewall/enroll — публичные, без whitelist (см. firewall.md).

Health API: http://<IP>:8080/v1/health.

Файловые runtime-логи (API /v1/runtime-logs/*)

В профиле microvps-full и в standalone stack.microvps-full.yaml sidecar stack-runtime-logs пишет docker logs каждого сервиса в *.log на хосте. Каталог по умолчанию — ./runtime-logs рядом с compose-файлами; на production-хосте задайте EVOBGP_RUNTIME_LOGS_HOST_DIR=/opt/evobgp/runtime-logs (см. deploy/compose/.env.stack.microvps-full.example).

Контейнер evobgp-all монтирует тот же каталог в /opt/evobgp/runtime-logs и включает FS API при EVOBGP_SERVICE=evobgp-all и EVOBGP_RUNTIME_LOGS_DIR=/opt/evobgp/runtime-logs (уже в compose). Просмотр и очистка — в Web UI (Monitoring → «Файловые логи») или через REST; детали — docs/access.md.

На evobgp-api (профиль reference) volume не монтируется — эндпоинты отвечают 503 (runtime_logs_unavailable).

Auto-updater для standalone stack (без рестарта BIRD2)

Для stack.microvps-full.yaml можно включить автообновление только выбранных сервисов (например, evobgp-all,evobgp-web) по digest образов в registry.

В файле deploy\compose\.env.stack.microvps-full:

• AUTO_UPDATE_ENABLED=1 — включить updater;
• AUTO_UPDATE_INTERVAL_SEC=300 — период проверки;
• AUTO_UPDATE_SERVICES=evobgp-all,evobgp-web — allowlist сервисов;
• AUTO_UPDATE_PROTECTED_SERVICES=bird2 — список защищённых сервисов (по умолчанию bird2).

Updater делает pull и при изменении образа выполняет up -d --no-deps только для сервиса из allowlist. bird2 в обновление не попадает, пока явно указан в protected-списке.

Важно: updater использует доступ к docker.sock (высокие привилегии), включайте осознанно.

Остановка (если поднимали с двумя -f):

docker compose --env-file .env --env-file .env.web-sec -f docker-compose.yaml -f docker-compose.microvps-full.yaml --profile microvps-full down

Вариант 2: Docker, профиль reference

Эталонное разбиение: отдельные контейнеры evobgp-api, evobgp-scheduler, evobgp-ingest, evobgp-render, evobgp-deploy, веб UI за nginx и Prometheus. NATS JetStream доступен по дополнительному профилю nats; очередь задач пока не использует брокер.

cd deploy\compose
Copy-Item .env.example .env -Force
docker login git.shx.one
docker compose --profile reference pull
docker compose --profile reference up -d

Полезные порты:

Порт	Назначение
8080	HTTP API (evobgp-api)
3000	Веб UI (evobgp-web → nginx, прокси на API)
4222	NATS (только с профилем nats)
9090	Prometheus (в compose)
179	BGP (BIRD2)

Воркеры reference: evobgp-scheduler использует EVOBGP_SCHEDULER_MODE=db и общую PostgreSQL durable queue. Он доверенный DB-worker с доступом к tenants; API workers выполняют сохранённые задания. HTTP-вариант включается явно: EVOBGP_SCHEDULER_MODE=http, EVOBGP_CONTROL_PLANE_URL, EVOBGP_SCHEDULER_BEARER и EVOBGP_SCHEDULER_TENANT_ID. Токен должен принадлежать именно указанному tenant и иметь право bgp:modules:write; HTTP scheduler не перечисляет остальные tenants и не подменяет scope через заголовки. При обновлении старой HTTP-конфигурации нужно указать tenant или перейти на db; без tenant HTTP-режим завершится с ошибкой. local предназначен только для разработки без PostgreSQL, не для split deploy. evobgp-ingest обновляет ETag CDN-источников; evobgp-render по умолчанию не трогает published_revision (EVOBGP_RENDER_AUTOPUBLISH=1 включается осознанно); evobgp-deploy пишет в лог расхождение applied vs published.

Reference Compose фиксирует DB-режим. Простое добавление HTTP-переменных в .env его не переключает. Для HTTP-варианта используйте отдельный Compose override с явным окружением сервиса:

services:
  evobgp-scheduler:
    environment:
      EVOBGP_SCHEDULER_MODE: http
      EVOBGP_CONTROL_PLANE_URL: ${EVOBGP_CONTROL_PLANE_URL:?required}
      EVOBGP_SCHEDULER_BEARER: ${EVOBGP_SCHEDULER_BEARER:?required}
      EVOBGP_SCHEDULER_TENANT_ID: ${EVOBGP_SCHEDULER_TENANT_ID:?required}

Подключайте override через дополнительный -f при запуске Compose. DB-режим предназначен для всех tenants, которым доверяет оператор общей БД; HTTP-режим работает только с указанным tenant и его токеном.

В evobgp-all (microvps) те же пакеты крутятся в одном процессе и используют общий jobs.Registry без HTTP.

Удалённые BGP-спикеры

Реплики на отдельных VPS (bird2 + agent + Traefik): см. remote-speakers.md. На CP включите EVOBGP_NODE_DISPATCH_ENABLED=1 и зафиксируйте EVOBGP_BUNDLE_SEED_HEX. Compose: deploy/compose/docker-compose.remote-speaker.yaml.

Вариант 3: Локально без Docker (только API)

1. Поднимите PostgreSQL и создайте БД (или используйте существующую).
2. Установите переменные окружения в текущей сессии 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:

cd <корень-клона-репозитория>
go run .\cmd\evobgp-api

Или монолит microVPS (тот же API плюс горутины тех же воркеров scheduler/ingest/render/deploy):

go run .\cmd\evobgp-all

При старте в лог выводится публичный ключ бандла (base64) — его нужно передать на сторону evobgp-node для проверки подписи. При включённом демо-сиде (EVOBGP_SEED_DEMO не равен 0, поведение по умолчанию) сервер также печатает подсказку с примером EVOBGP_API_KEYS.

Для разработки без настройки ключей (только демо-данные):

$env:EVOBGP_DEV_INSECURE = "1"
go run .\cmd\evobgp-api

Запросы с заголовком Authorization: Bearer dev получают роль operator в демо-tenant. Не включайте в продакшене.

Вариант 4: Веб-интерфейс (разработка)

cd web
npm install
npm run dev

Укажите в окружении API список разрешённых origin для CORS (пример для Vite на порту 5173):

$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:

.\scripts\build-openapi-html.ps1

Подробности — OPENAPI-GITEA.md.

Дальше

• access.md — как выдать ключи и настроить ноду.
• architecture.md — состав сервисов и пакетов.