INFRA.md — инфраструктура и эксплуатация оркестратора

RUNBOOK. Топология, контейнеры, порты, переменные окружения, границы. Секреты тут НЕ хранятся — только дескрипторы. Реальные значения — в .env на хосте.

Топология

                 host: mva154 (slin@82.22.50.71), network_mode: host
 ┌──────────────────────────────────────────────────────────────────────┐
 │  orchestrator        (PROD)     :8500   env_file .env                  │
 │    БД: ./data/orchestrator.db          (обслуживает ВСЕ прод-проекты)  │
 │                                                                        │
 │  orchestrator-staging (STAGING) :8501   env_file .env.staging          │
 │    БД: ./data/staging/orchestrator.db  (изолирована, только sandbox)   │
 │    profile: staging — НЕ стартует обычным `docker compose up`          │
 └──────────────────────────────────────────────────────────────────────┘
        │ webhooks                                  │ git
        ▼                                           ▼
   Plane (ag_proj)                            Gitea (localhost:3000)
   /repos/<project>  ← общий каталог репозиториев (host: /home/slin/repos)

Контейнеры

Контейнер	Роль	Порт	env_file	БД (хост)	Старт
`orchestrator`	прод	8500	`.env`	`./data/orchestrator.db`	`docker compose up -d`
`orchestrator-staging`	staging / песочница	8501	`.env.staging`	`./data/staging/orchestrator.db`	`docker compose --profile staging up -d orchestrator-staging`

Оба: network_mode: host, init: true (tini как PID 1 — reaping зомби, B-2), restart: unless-stopped.

Тома (volumes)

./data → /app/data (БД; у staging — ./data/staging)
/home/slin/repos → /repos (рабочие репозитории проектов)
/var/run/docker.sock (для docker-операций деплоя)
claude-code, node, ~/.claude* (CLI агентов, ro)
~/.orchestrator-ssh → /root/.ssh (ro, деплой по ssh)

Переменные окружения (карта; значения — в `.env`)

Переменная	Назначение
`ORCH_PLANE_API_URL` / `_TOKEN` / `_WORKSPACE_SLUG`	доступ к Plane API
`ORCH_PLANE_WEBHOOK_SECRET`	HMAC-проверка вебхуков Plane
`ORCH_GITEA_URL` / `_TOKEN` / `_WEBHOOK_SECRET`	доступ к Gitea + HMAC
`ORCH_CLAUDE_BIN`	путь к claude CLI
`ORCH_REPOS_DIR` / `ORCH_HOST_REPOS_DIR`	каталог репозиториев (в контейнере / на хосте)
`ORCH_DB_PATH`	путь к SQLite БД
`ORCH_PROJECTS_JSON`	реестр проектов (Plane id → repo + prefix); пусто → дефолт из `src/projects.py`
`DEPLOY_SSH_USER` / `_HOST` / `DEPLOY_HOOK_SCRIPT`	параметры деплой-хука

Секреты — только в .env / .env.staging на хосте, в гит НЕ коммитятся. Канон — .env.example, .env.staging.example.

Реестр проектов (`src/projects.py`, ORCH-6)

Связывает Plane project id → gitea repo + work-item prefix. Источник: ORCH_PROJECTS_JSON, fallback — встроенный дефолт. Прод видит: enduro-trails (ET), orchestrator (ORCH). Staging видит ТОЛЬКО orchestrator-sandbox (SANDBOX) — изоляция.

⚠️ Self-hosting — оркестратор дорабатывает САМ СЕБЯ

Факт: прод-инстанс orchestrator (8500) — ОДИН на ВСЕ прод-проекты (enduro-trails + orchestrator), с ОБЩЕЙ БД ./data/orchestrator.db и общей очередью задач (ORCH-1).

Следствие — групповой риск: когда орк выполняет задачу из проекта ORCH (дорабатывает себя), он бежит в том же инстансе, что обслуживает enduro-trails.

Рестарт / падение прод-контейнера орк-задачей → конвейер ВСЕХ проектов встаёт.
Кривой self-деплой (ORCH-36, Вариант B) → лежат все проекты сразу.
Общая очередь → орк-задача занимает concurrency-слоты других проектов.

Что изолировано (безопасно):

Staging (8501) — отдельная БД (./data/staging), отдельный реестр (ORCH_PROJECTS_JSON = только sandbox). Прод-проекты не видит.
Репозитории разделены, изоляция веток через git worktree (ORCH-2).

Страховки:

Стадия deploy-staging (порт 8501) — обязательный гейт перед прод-деплоем орка. Прод-деплой недостижим, пока staging-гейт не зелёный (см. STAGING.md, ORCH-35). Гейт условный: реален только для self-hosting (repo=orchestrator), для остальных проектов — no-op.

Правила для агентов при задачах ORCH:

НЕ перезапускать / не ронять прод-контейнер orchestrator в рамках задачи.
Все проверки деплоя — на staging (8501), боевой 8500 не трогать.
Деплой self — только через хук с health-check + авто-rollback (DEPLOY_HOOK.md).

Эксплуатация (быстрые команды)

# статус
docker ps --filter name=orchestrator
curl -s http://localhost:8500/health
curl -s http://localhost:8500/status   # активные задачи
curl -s http://localhost:8500/queue    # очередь

# поднять staging-песочницу
docker compose --profile staging up -d orchestrator-staging
curl -s http://localhost:8501/health

# логи
docker logs --tail 100 orchestrator

RUNBOOK 2026-06-05. Обновлять при изменении топологии/портов/переменных. См. CONTRIBUTING.md §8.

6.7 KiB Raw Permalink Blame History Unescape Escape