orchestrator/docs/work-items/ORCH-057/07-infra-requirements.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-057	architecture	architect	proposed	2026-06-10	claude-opus-4-8

07 — Инфра-требования: ORCH-057 — нормализация legacy root-owned файлов при миграции на uid 1000

Work Item: ORCH-057 · Repo: orchestrator · Стадия: architecture

When-applicable. Топология контейнеров не меняется (init-контейнер/правка docker-compose.yml отвергнуты — ADR-001 D4). Файл фиксирует новые env-флаги и обязательную операторскую процедуру нормализации legacy root-файлов как шаг миграции uid.

I-1. Топология / окружения

Без изменений. Контейнеры orchestrator (8500) / orchestrator-staging (8501), user: "1000:1000", bind-mount /home/slin/repos → /repos, network_mode: host — как есть. Init-контейнер / root-entrypoint сознательно НЕ вводятся (реинтродуцировали бы root-контекст, убранный ORCH-040, и потребовали бы self-deploy compose с групповым риском — ADR-001 D4, Альтернативы).

I-2. Переменные окружения / секреты

Новые env-флаги (аддитивно в src/config.py, дефолты сохраняют поведение до ORCH-057). Добавить в .env.example (секретов нет):

Env	Дефолт	Назначение
ORCH_FS_NORMALIZE_ENABLED	true	kill-switch всего слоя ORCH-057
ORCH_FS_NORMALIZE_REPOS	`` (пусто)	scope CSV; пусто → self-hosting only (enduro не затронут)
ORCH_FS_TARGET_UID	1000	целевой uid (фолбэк к os.getuid())
ORCH_FS_NORMALIZE_AUTO	false	детект-only; true → попытка chown при наличии CAP_CHOWN
ORCH_FS_SCAN_ROOTS	`` (пусто)	CSV-переопределение корней обхода
ORCH_FS_SCAN_CACHE_TTL_S	300	TTL детект-кэша

Секреты не вводятся.

I-3. Деплой / рестарт

• Self-hosting инвариант (NFR-1): код задачи не рестартит/не роняет прод-контейнер orchestrator, не трогает main/force-push/прод-образ. chown из кода возможен лишь при наличии прав (под uid 1000 — no-op).
• Изменение только src/** + docs → штатный деплой self через staging-гейт (8501), затем прод-рестарт в окно тишины (GET /status без активных задач). Правки docker-compose.yml/ entrypoint в задаче нет → нет дополнительного инфра-риска сверх обычного self-деплоя.
• Обязательная операторская процедура нормализации (host-prerequisite миграции uid) — выполняется под root на хосте mva154 один раз при миграции uid / на новой среде, ПЕРЕД стартом app. Каноничный текст — в docs/operations/INFRA.md (раздел «Миграция uid: обязательная нормализация legacy root-файлов»). Команды покрывают все корни:

  sudo chown -R 1000:1000 /home/slin/repos/_wt
  sudo chown -R 1000:1000 /home/slin/repos/orchestrator/.git \
                          /home/slin/repos/enduro-trails/.git
  sudo chown -R 1000:1000 /home/slin/repos/orchestrator        # incl. data/runs/*.log
  # Проверка: find /home/slin/repos/_wt ! -uid 1000 -print -quit   (пусто = ок)
  

  Идемпотентна (повтор на корректной среде — no-op). Помечена обязательным пунктом чеклиста деплоя/миграции self.

I-4. CI/CD

Без изменений в .gitea/workflows/. Новые юнит-тесты (tests/test_fs_normalize.py, tests/test_git_worktree_perm_error.py — см. 04-test-plan.yaml) гоняются существующим pytest tests/ -q. Новых системных зависимостей образа нет.