---
work_item: ORCH-057
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-10
model_used: 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`. Новых системных зависимостей образа нет.