docs(docs): describe durable jobs, telemetry, and bundle limits
Зафиксированы очередь job, семантика метрик, лимиты бандла и исходящих запросов, а также чеклист продакшена для пула соединений. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
DenozordecandCursor committed
1 parent
bda45d633e
commit
240d83fc61
15 files changed
+839
-17
No files matched your search
+33
-8
@@ -2,6 +2,16 @@
|
||||
|
||||
Примеры команд для **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 — для готового стека.
|
||||
@@ -103,7 +113,7 @@ docker compose --profile microvps down -v
|
||||
|
||||
## Вариант 1b: microVPS ~1 ГиБ RAM — полный набор + Web UI
|
||||
|
||||
Один монолит **`evobgp-all`** (те же in-process воркеры, что и в варианте 1), плюс **статическая панель** за nginx (`evobgp-web-microvps`), **NATS JetStream** (как в reference, для `EVOBGP_BROKER_URL` и будущей интеграции) и **Prometheus** со скрейпом метрик с `evobgp-all`. Отдельные контейнеры `evobgp-scheduler` / `evobgp-ingest` / … не нужны — это не дублирование логики, а тот же код в одном процессе.
|
||||
Один монолит **`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`.
|
||||
|
||||
@@ -126,19 +136,19 @@ Copy-Item .env.web-sec.example .env.web-sec -Force
|
||||
4. Запускайте compose с двумя env-файлами:
|
||||
|
||||
```powershell
|
||||
# С ужатыми лимитами и EVOBGP_BROKER_URL=nats://… (ориентир под ~1 ГиБ RAM на хосте)
|
||||
# С текущими лимитами (пригодность для хоста ~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, без принудительной подстановки брокера в `evobgp-all`):
|
||||
Только профиль `microvps-full` и **без** файла `docker-compose.microvps-full.yaml` (лимиты как в базовом compose):
|
||||
|
||||
```powershell
|
||||
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
|
||||
```
|
||||
|
||||
При необходимости задайте брокер вручную для `evobgp-all` (override или `.env` рядом с compose): `EVOBGP_BROKER_URL=nats://nats:4222`.
|
||||
Если NATS нужен внешним клиентам, добавьте `--profile nats` к командам `pull` и `up`. Проверьте таких клиентов до изменения рабочего стека. `EVOBGP_BROKER_URL` в текущем приложении только записывается в лог и не включает брокерную очередь. Для standalone `stack.microvps-full.yaml` и production example сервис NATS также включается профилем `nats`. Перенос существующей истории Prometheus при обновлении описан в [docker-resources.md](docker-resources.md).
|
||||
|
||||
| Порт | Назначение |
|
||||
|------|------------|
|
||||
@@ -146,7 +156,7 @@ docker compose --env-file .env --env-file .env.web-sec --profile microvps-full u
|
||||
| **443** | HTTPS Web UI (Traefik + Let's Encrypt) |
|
||||
| **8080** | Прямой HTTP API (`evobgp-all`) |
|
||||
| **9090** | Prometheus (`prometheus-microvps`) |
|
||||
| **4222** | NATS |
|
||||
| **4222** | NATS (только с профилем `nats`) |
|
||||
| **179** | BGP (BIRD2), как в варианте 1 |
|
||||
|
||||
Проверка UI:
|
||||
@@ -188,7 +198,7 @@ docker compose --env-file .env --env-file .env.web-sec -f docker-compose.yaml -f
|
||||
|
||||
## Вариант 2: Docker, профиль reference
|
||||
|
||||
Эталонное разбиение: отдельные контейнеры `evobgp-api`, `evobgp-scheduler`, `evobgp-ingest`, `evobgp-render`, `evobgp-deploy`, сервис **NATS JetStream** (в compose; привязка очереди задач к брокеру — следующая итерация), веб UI за nginx, опционально Prometheus.
|
||||
Эталонное разбиение: отдельные контейнеры `evobgp-api`, `evobgp-scheduler`, `evobgp-ingest`, `evobgp-render`, `evobgp-deploy`, веб UI за nginx и Prometheus. **NATS JetStream** доступен по дополнительному профилю `nats`; очередь задач пока не использует брокер.
|
||||
|
||||
```powershell
|
||||
cd deploy\compose
|
||||
@@ -204,11 +214,26 @@ docker compose --profile reference up -d
|
||||
|------|------------|
|
||||
| 8080 | HTTP API (`evobgp-api`) |
|
||||
| 3000 | Веб UI (`evobgp-web` → nginx, прокси на API) |
|
||||
| 4222 | NATS |
|
||||
| 4222 | NATS (только с профилем `nats`) |
|
||||
| 9090 | Prometheus (в compose) |
|
||||
| 179 | BGP (BIRD2) |
|
||||
|
||||
**Воркеры reference:** `evobgp-scheduler` ходит в API по HTTP (`EVOBGP_CONTROL_PLANE_URL`, `EVOBGP_SCHEDULER_BEARER`); в [docker-compose.yaml](../deploy/compose/docker-compose.yaml) для локального запуска включены `EVOBGP_DEV_INSECURE=1` на API и токен `dev` у планировщика. `evobgp-ingest` обновляет ETag CDN-источников; `evobgp-render` по умолчанию не трогает `published_revision` (включите `EVOBGP_RENDER_AUTOPUBLISH=1` осознанно); `evobgp-deploy` пишет в лог расхождение applied vs published. Очередь `jobs` остаётся in-process у **evobgp-api**; общий брокер — в планах.
|
||||
**Воркеры 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 с явным окружением сервиса:
|
||||
|
||||
```yaml
|
||||
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.
|
||||
|
||||
|
||||
Reference in new issue
Block a user