orchestrator/docs/operations/INFRA.md

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_WEB_URL	внешний (браузерный) web-URL Plane для кликабельных ссылок на issue в уведомлениях (ORCH-017); пусто → фолбэк на ORCH_PLANE_API_URL, loopback-фолбэк → ссылка опускается
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
ORCH_AGENT_MODEL_DEFAULT	LLM-модель агентов по умолчанию (ORCH-41); дефолт claude-opus-4-8
ORCH_AGENT_MODEL_<AGENT>	per-agent модель (ANALYST/ARCHITECT/DEVELOPER/REVIEWER/TESTER/DEPLOYER); пусто → default
ORCH_AGENT_EFFORT_DEFAULT	режим работы --effort по умолчанию (ORCH-41): low|medium|high|xhigh|max; дефолт high
ORCH_AGENT_EFFORT_<AGENT>	per-agent effort; дефолт: думающие → high, tester/deployer → medium
ORCH_AGENT_FALLBACK_MODEL	опц. фолбэк-модель при overloaded (--fallback-model); пусто → без флага
ORCH_PREFLIGHT_CHECK_AUTH	вкл/выкл token-free auth-проверку preflight (ORCH-044); дефолт true. Аварийный тумблер: false → preflight как до ORCH-044 (только --version)
ORCH_CLAUDE_CREDENTIALS_PATH	явный путь к .credentials.json (ORCH-044); пусто → <AGENT_HOME>/.claude/.credentials.json, где AGENT_HOME=/home/slin — HOME, под которым launcher реально спавнит claude (не HOME процесса орка)
ORCH_AUTH_EXPIRY_SKEW_SECONDS	запас на рассинхрон часов при сравнении claudeAiOauth.expiresAt (ORCH-044); дефолт 0
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) — изоляция.

Модель и effort агентов (src/config.py + src/agents/launcher.py, ORCH-41)

Модель LLM и режим работы (--effort) каждого агента конфигурируемы — глобально per-agent (env) и per-project (через ORCH_PROJECTS_JSON).

Приоритет резолвинга (resolve_agent_model / resolve_agent_effort):

1. per-project override — agent_models / agent_efforts в записи ORCH_PROJECTS_JSON;
2. per-agent env — ORCH_AGENT_MODEL_<AGENT> / ORCH_AGENT_EFFORT_<AGENT> (если непусто);
3. глобальный дефолт — ORCH_AGENT_MODEL_DEFAULT (claude-opus-4-8) / ORCH_AGENT_EFFORT_DEFAULT (high);
4. пусто → флаг не передаётся, действует дефолт CLI.

Значения effort: low < medium < high < xhigh < max — рычаг «качество vs стоимость/время». Дефолтная раскладка: думающие агенты (analyst/architect/developer/reviewer) → high, механические (tester/deployer) → medium. Невалидное значение → лог-warning, флаг опускается.

Per-project override в ORCH_PROJECTS_JSON (поля agent_models / agent_efforts опциональны, старые записи работают):

{"plane_project_id":"...","repo":"orchestrator","work_item_prefix":"ORCH",
 "agent_models":{"developer":"claude-opus-4-8","reviewer":"claude-sonnet-4-6"},
 "agent_efforts":{"developer":"xhigh","tester":"low"}}

⚠️ Бюджет (ORCH-38): claude-opus-4-8 дефолт в коде; реальное переключение прод-env делается отдельно после согласования.

Preflight auth-гейт (src/preflight.py, ORCH-044)

claude --version отвечает успешно даже когда claude разлогинен (версия — локальная инфа), поэтому до ORCH-044 preflight был слеп к авторизации: разлогиненный инстанс клеймил job и тихо умирал с пустым логом, блокируя общую очередь всех проектов.

ORCH-044 добавляет token-free проверку (без сети, без prompt-ping — BR-1):

1. Проактивно (основной гейт): после успешного --version читается <AGENT_HOME>/.claude/.credentials.json (путь — ORCH_CLAUDE_CREDENTIALS_PATH или дефолт от AGENT_HOME=/home/slin, не HOME процесса орка). Нет файла / битый JSON / нет claudeAiOauth.accessToken ⇒ check()=(False, …). claudeAiOauth.expiresAt (epoch ms) <= now + ORCH_AUTH_EXPIRY_SKEW_SECONDS ⇒ протух ⇒ FAIL. Нет expiresAt ⇒ OK (не плодим ложные срабатывания). Результат кешируется тем же ORCH_PREFLIGHT_CACHE_TTL, что и --version.
2. Постфактум (защитная сетка): если агент всё же стартовал при протухшей сессии, launcher детектит маркер (not logged in / please run /login / unauthorized / 401) в run-логе и сбрасывает preflight-кеш, чтобы следующий тик переоценил auth. Auth-провал не считается transient и не крутит circuit breaker — гейт здесь preflight.

При auth=fail job не клеймится (_drain_once уже корректен при ok=False), reason виден в /queue (preflight_reason). Аварийный тумблер ORCH_PREFLIGHT_CHECK_AUTH=false возвращает version-only поведение.

⚠️ Риск ложноположительного auth-fail (R-1): неверный путь к credentials заблокирует клейм всех проектов (общая очередь). Митигация: единый источник AGENT_HOME, тумблер, обязательная проверка на staging (8501) перед прод-деплоем. ADR — docs/work-items/ORCH-044/06-adr/ADR-001-preflight-auth-and-empty-result-failure.md.

ℹ️ --effort (P2) в ORCH-044 не трогается — вынесен в ORCH-50.

⚠️ 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:

1. НЕ перезапускать / не ронять прод-контейнер orchestrator в рамках задачи.
2. Все проверки деплоя — на staging (8501), боевой 8500 не трогать.
3. Деплой 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.