From 0c29b3c8d7cb31e95963b5043c5c98ab9ee8ae09 Mon Sep 17 00:00:00 2001 From: Stream Date: Thu, 4 Jun 2026 23:30:01 +0300 Subject: [PATCH] auto-sync: 2026-06-04 23:30:01 --- tasks/orchestrator/DESIGN_STAGING_ENV.md | 70 ++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 tasks/orchestrator/DESIGN_STAGING_ENV.md diff --git a/tasks/orchestrator/DESIGN_STAGING_ENV.md b/tasks/orchestrator/DESIGN_STAGING_ENV.md new file mode 100644 index 0000000..f9af747 --- /dev/null +++ b/tasks/orchestrator/DESIGN_STAGING_ENV.md @@ -0,0 +1,70 @@ +# Дизайн: тестовая (staging) среда для orchestrator + +**Статус:** дизайн на согласовании · **Связь:** ORCH-30 (методика test-сред), ORCH-7 (self-hosting), ORCH-21 (auto-rollback) +**Дата:** 2026-06-04 · **Автор:** Стрим (по решениям Славы) + +## Решения Славы (04.06, зафиксировано) +1. **Постоянный** staging-контейнер (не эфемерный). ✅ +2. **Полная изоляция БД** задач staging от прод-очереди. ✅ +3. **Вариант b** — staging работает «как настоящий» в песочнице: отдельный тестовый проект Plane + отдельный тестовый репо Gitea. ✅ +4. Промоут staging→prod: «**смотри на принцип автономно и надёжно**» → решение Стрим (см. §4). ✅ +5. Smoke обязателен И больше: **реальные прогоны**, **изменение статусов и комменты в Plane**, **проверка доступов**, **интеграционное тестирование**. ✅ +6. **Агенты на staging — гибрид C** (04.06): по умолчанию ЗАГЛУШКИ агентов (быстро/дёшево/детерминированно — гейт проверяет что ОРК не сломан, а не качество LLM), + отдельный прогон `full-real` (по флагу, реже) с настоящим Claude CLI через `claude-cli-proxy`. Plane/Gitea на staging — настоящие (песочница), заглушка только на «мозге агента». ✅ +7. **Промоут: ручной approve ОСТАЁТСЯ на старте** (`DEPLOY_REQUIRE_MANUAL_APPROVE=true`) — хук тормозит после зелёного staging и ждёт «go» Славы. Полный авто включим позже, когда наберём доверие. ✅ + +## §1. Где живёт staging +- Контейнер `orchestrator-staging`, порт **8501** (прод — 8500), из того же compose-файла (новый service или профиль `staging`). +- Живёт 24/7. Образ — `orchestrator:candidate` (кандидат на промоут). + +## §2. Изоляция БД +- Отдельный volume / отдельный файл sqlite (`orchestrator_staging.db`), НЕ боевая очередь `jobs`/`tasks`. +- Пустая на старте + seed-фикстуры тестовых задач. Staging НИКОГДА не пишет в прод-БД. +- Отдельный `.env.staging` со своими токенами/путями. + +## §3. Песочница интеграций (вариант b) +- **Plane:** отдельный тестовый проект — рабочее имя `ORCH-SANDBOX` (свой project_id, добавить в реестр `src/projects.py` как известный проект staging-инстанса). Staging-орк реально меняет статусы и пишет комменты — но в песочном проекте, не в боевом ORCH. +- **Gitea:** отдельный репо `orchestrator-sandbox` (или `enduro-sandbox` как цель для тестовых веток). Staging-орк реально создаёт ветки/PR там, не засоряя боевые репозитории. +- **Боты/токены:** staging использует те же агент-роли, но с явной пометкой и, по возможности, отдельными токенами, чтобы по логам отличать staging-активность от прод. +- ⚠️ Webhook'и: staging-Plane-проект шлёт события на staging-эндпоинт (8501), прод — на 8500. Реестр проектов фильтрует по project_id (механизм уже есть из ORCH-6). + +## §4. Промоут staging→prod — РЕШЕНИЕ СТРИМ (принцип «автономно и надёжно») + +**Ключевой принцип: деплоем орка управляет ВНЕШНИЙ хост-хук, а НЕ сам контейнер орка.** +Причина: орк деплоит сам себя. Если контейнер сам себе делает `docker compose up -d` нового образа — он убивает свой процесс на середине деплоя и не может довести/откатить. Поэтому исполнитель деплоя — скрипт на хосте (как `enduro-deploy-hook.sh`, который уже умеет rollback через PREV_IMG). Орк может только ИНИЦИИРОВАТЬ (положить сигнал/тег), исполняет и контролирует — хост. + +**Поток (полностью автономный, с гейтами и авто-откатом):** +1. Код прошёл review → merge в main. +2. Хост-хук собирает образ → тег `orchestrator:candidate`. +3. Хост-хук поднимает/обновляет `orchestrator-staging` (8501) на candidate (изолированная БД + песочница Plane/Gitea). +4. **Гейт staging** (всё должно пройти, иначе СТОП, прод не трогаем): + - health `/health` отвечает; `/queue` живой; webhook-приём отвечает; + - **проверка доступов**: staging реально достучался до Plane (песочный проект) и Gitea (sandbox-репо) своими токенами; + - **интеграционный прогон end-to-end**: создать тестовую задачу в ORCH-SANDBOX → staging-орк создаёт ветку в sandbox-репо, **меняет статусы и пишет комменты в Plane** (проверяем по факту через Plane API), доходит до ожидаемой стадии. +5. Staging зелёный → **промоут build-once**: тот же образ перетегируется `orchestrator:latest`. +6. Хост-хук сохраняет PREV_IMG прода → `docker compose up -d orchestrator` (8500). +7. **Health-check прода после рестарта** (с хоста, retry N раз, timeout). +8. **Если прод-health не поднялся → авто-rollback** на PREV_IMG (механизм уже есть в enduro-хуке) + алерт. +9. Уведомление о результате (Plane-коммент в боевую задачу + телеграм Славе). + +**Почему «автономно И надёжно»:** всё происходит само (автономно), но прод меняется только после зелёного staging-гейта, а любой сбой прода ловится health-check'ом и откатывается на предыдущий образ внешним механизмом (надёжно). Орк физически не может необратимо убить сам себя — рубильник снаружи контейнера. + +**Опция ручного стопа:** на старте — флаг `DEPLOY_REQUIRE_MANUAL_APPROVE=true` (хук останавливается после зелёного staging и ждёт явного «go» от Славы). Когда доверие к автоматике наберётся — выключаем, идёт полный авто. Так автономность вводится постепенно, без риска на ранней стадии. + +## §5. Что гоняем (по требованию Славы — не только smoke) +- **Smoke:** health, /queue, webhook-приём живы. +- **Проверка доступов:** Plane токены (песочный проект), Gitea токены (sandbox-репо) — реальные вызовы, не моки. +- **Интеграционное тестирование end-to-end:** задача в ORCH-SANDBOX → ветка в sandbox-репо + смена статусов + комменты в Plane (верификация через Plane/Gitea API, что они реально проставлены). +- **Реальные прогоны:** не моки — staging работает как прод, но в песочнице. + +## Этапы реализации (предлагаемая разбивка на задачи Plane) +- **Этап 1 — Staging-инфра:** service `orchestrator-staging` (8501) в compose, изолированная БД/volume, `.env.staging`, поднятие/health. +- **Этап 2 — Песочница интеграций:** тестовый Plane-проект ORCH-SANDBOX + Gitea-репо orchestrator-sandbox, токены/доступы, регистрация в `src/projects.py`, маршрутизация webhook'ов на 8501. +- **Этап 3 — Тест-сьют staging:** скрипт smoke + проверка доступов + интеграционный end-to-end прогон (создание задачи → ветка → статусы → комменты, с верификацией). +- **Этап 4 — Хост-деплой-хук с промоутом и откатом:** `orchestrator-deploy-hook.sh` (по образцу enduro): build candidate → staging up → гейт §4 → promote → health → auto-rollback. Флаг ручного approve. (Пересекается с ORCH-21.) +- **Этап 5 — Встройка в конвейер/методику:** стадия `deploy-staging` ПЕРЕД `deploy-prod`, тестер привязан к staging-эндпоинту, обновить методику. + +## Открытые мелочи (уточнить по ходу, не блокеры) +- Имя песочных проекта/репо (ORCH-SANDBOX / orchestrator-sandbox — ок?). +- Отдельные ли токены ботов для staging или те же с пометкой. +- N retry и timeout health-check прода (предлагаю 10 попыток × 6 сек = 60с). +- Ресурсы хоста под постоянный staging-контейнер (лёгкий, но 24/7).