diff --git a/README.md b/README.md new file mode 100644 index 0000000..3eebb08 --- /dev/null +++ b/README.md @@ -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)). + +Лицензия и условия использования — по политике владельца репозитория. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..9307cd4 --- /dev/null +++ b/docs/README.md @@ -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. diff --git a/docs/access.md b/docs/access.md new file mode 100644 index 0000000..9bbf615 --- /dev/null +++ b/docs/access.md @@ -0,0 +1,98 @@ +# Предоставление доступа + +Как выдавать доступ к control plane API, веб-клиентам и репликам BIRD (`evobgp-node`). Секреты храните в менеджере секретов, переменных окружения оркестратора или зашифрованных файлах — не коммитьте реальные ключи в Git. + +## API-ключи (`EVOBGP_API_KEYS`) + +Формат переменной окружения: список записей через **запятую** без пробелов внутри логики парсера (пробелы вокруг записей допускаются при обрезке). Каждая запись: + +```text +|| +``` + +- **token** — произвольная строка, передаётся клиентом как `Authorization: Bearer `. +- **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 "" -speaker-id "" +``` + +## 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) — запуск с примером ключей. diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..a398a4c --- /dev/null +++ b/docs/api.md @@ -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 `** (см. [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) — продуктовые возможности. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..d33c16c --- /dev/null +++ b/docs/architecture.md @@ -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) — ключи и роли. diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 0000000..d2be374 --- /dev/null +++ b/docs/overview.md @@ -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) — ранние таблицы эндпоинтов (черновик). diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..5fbcfd7 --- /dev/null +++ b/docs/quickstart.md @@ -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) — состав сервисов и пакетов. diff --git a/web/README.md b/web/README.md index f77bfa2..9395075 100644 --- a/web/README.md +++ b/web/README.md @@ -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!