nixos/docs/arch/todo.md

# TODO: правки и инварианты

Источник: `docs/arch/invariants.md`. Ответы владельца от 2026-10-05 учтены.
Подтверждённые факты зафиксированы в `AGENTS.md` (корень) и `docs/arch/map.md`;
этот файл — только **незакрытые правки и неотвеченные вопросы**.
Порядок: A → B → C → D, потом E (документация для агента).

Обозначения: `[ ]` не начато, `[x]` сделано, `[!]` блокирует остальное.

---

## Подтверждено (зафиксировано в `AGENTS.md` / `map.md`)

Эти инварианты уже учтены в ядре и карте — при правке кода опираться на
зафиксированные формулировки.

- **6.1** Явная финальная политика nftables на VDS → `todo A3` ещё открыто,
  но сам «надо запилить» закреплён.
- **6.3** Firewall на sapphira выключен намеренно (граница — роутер, 5 портов:
  22, 80, 443, 8443, 22000) → формулировка в `AGENTS.md §3`, `todo D1`.
- **6.5** `100.64.0.0` = Tailscale-адрес sapphira (назначен вручную) → `AGENTS.md §5`,
  `map.md §Сеть и firewall`.
- **7.1 / 7.2** 3x-ui заморожен: панель на latest, ядро Xray на 26.7.x,
  миграция 26.9 провалена → `AGENTS.md §4`, `todo C1–C5`.

---

## Ловушки для агента: выглядит сломанным, но это намеренно

Прежде чем чинить — проверить этот список. Здесь лежат решения, которые
иначе «поправляются» обратно и ломают рабочую систему.

| Где | Что выглядит ошибкой | На самом деле |
|---|---|---|
| `configurations/server.nix:130` | `networking.firewall.enable = false` на сервере с 20 сервисами на `0.0.0.0` | Намеренно: фильтр на роутере, он пробрасывает 5 портов (см. D1) |
| `configurations/mobile.nix:95`, `wsl.nix:59` | `stateVersion` 24.05 / 24.11 против 26.05 у остальных | Каждый хост зафиксирован на своей версии; не «подровнять» |
| `modules/users.nix:66` | `uid = if hostname == "sapphira" then 1001 else …` с пометкой TODO | Осознанный костыль под старый uid 1000 = `yuyus`; удалять только после миграции ФС |
| `modules/containers/3x-ui.nix:54` | `image = …:latest` | Панель намеренно на последней версии; **ядро** Xray — на 26.7.x, миграция на 26.9 провалена |
| `modules/containers/3x-ui.nix:33-35` | `reality443Forwarding = true` на VDS при откате nginx-stream | Следствие отката `c8d4a12`; смысл утрачен, но опция объявлена — см. C5 |
| `modules/server/default.nix:33-47` | 15 закомментированных модулей с живым кодом | Отключены осознанно; см. E3 |
| `modules/server/{mealie,memos,n8n,netdata,nfs,open-webui,rsync,step-ca,transmission,trilium,zerotier}.nix` | Агент насчитает лишние порты и каталоги | Модули вне `imports` = мёртвый код |
| `home/modules/opencode.nix:339` | `systemd.user.services.opencode-web.Service` вместо привычного `serviceConfig` | `serviceConfig` рендерится в секцию `[serviceConfig]`, которую systemd **молча игнорирует** (`c73a698`) |
| `configurations/vds.nix:73-91` | nftables без финального правила | Известный пробел,см. A3 — **не** «случайно потерялось» |
| `100.64.0.0` в `nginx.nix`, `nextcloud.nix`, `vds/*` | Первый адрес CGNAT `/10`, похож на сетевой | Tailscale-адрес sapphira, назначен вручную |
| `server.nix:61-63` | `z /mnt/services 0777` | World-writable точка монтирования; см. B1 |

---

## A. Блокеры: сломано или не защищено

### [ ] A1. `mobile.nix` импортирует несуществующий файл

**Где:** `configurations/mobile.nix:12`
```nix
xlib = import ../lib/xlib.nix { lib = inputs.nixpkgs.lib; };
```
Файла `lib/xlib.nix` нет — есть каталог `lib/xlib/` с `default.nix`.
**Правка** (как в `configurations/default.nix:5`):
```nix
xlib = import ../lib/xlib { inherit lib; };
```
**Следствие:** до правки `nixOnDroidConfigurations.epral` и `.default`
не вычисляются. Устройство `epral` мертво.
**Проверка:**
```
nix eval --raw .#nixOnDroidConfigurations.epral.config.environment.etcBackupExtension   # ожидается .bak
```

### [ ] A2. Убедиться, что `nix flake check` вообще запускается

**Где:** нет CI; `checks` в `deploy/default.nix:27-29` покрывают только deploy.
**Сначала проверить**, ловит ли текущий `nix flake check` поломку из A1:
```
nix flake check
```
Ожидание, которое надо подтвердить: он **уже падает** на `epral`, то есть
проверка существует, но её не запускали. Если падает — A1 и был бы замечен.
**Проверка после A1:** та же команда должна стать зелёной.
**Затем** (E2) — превратить в привычку: прогонять перед каждым коммитом.

### [ ] A3. Явная финальная политика nftables на VDS

**Где:** `configurations/vds.nix:73-91`
**Сначала диагностика на otreca** (без неё править опасно — можно отрезать SSH):
```
nft list ruleset
systemctl status nftables firewall-nftables
```
Нужно понять, кто реально владеет набором правил: `nftables.enable = true` с
собственным ruleset **и** `networking.firewall.*` включены одновременно
(инвариант 6.2). Затем — править **один** механизм, не оба.
**Что должно получиться** (политика — на выбор владельца, два варианта):
```
# Вариант «белый список» (предпочтительно):
chain input {
  type filter hook input priority 0; policy drop;
  iif lo accept
  ct state established,related accept
  iif "tailscale0" accept
  tcp dport { 80, 443 } ct state new limit rate 20/second burst 40 packets accept
  tcp dport { 22 } ct state new accept          # только если 22 нужен на ens3
}
# Вариант «мягкий» (минимум изменений, фиксирует текущее поведение):
chain input {
  type filter hook input priority 0;
  iif lo accept
  ct state established,related accept
  tcp dport { 80, 443 } ct state new limit rate 20/second burst 40 packets accept
  tcp dport { 80, 443 } ct state new drop
  # финал accept — но ТОЛЬКО как явно помеченное «разрешено всё остальное»:
  iif "ens3" accept comment "PROVISIONAL: explicit allow-all, см. A3"
}
```
**Инвариант к записи:** последнее правило самописной цепочки всегда явное.
**Проверка:** `nft list chain inet filter input` + `ssh` с внешнего адреса.

---

## B. Защита данных

### [ ] B1. Guard на несмонтированный носитель `/mnt/services`

**Где:** `lib/xlib/helpers.nix` (`mkServiceStorage`), потребители —
`modules/server/{postgresql,n8n,samba,homebox,minecraft}.nix` + `modules/containers/3x-ui.nix`
**Проблема (подтверждена владельцем как не продуманная):** `mkServiceStorage`
даёт `bind,x-systemd.automount,nofail`. Если диск `External` (`xlib.dirs.server-home`,
ext4 по UUID, `configurations/server.nix:55-58`) не смонтирован, то `/mnt/services`
— обычный каталог, `/var/lib/<service>` пуст, и сервис **молча** стартует на чистой
базе. Пользователь увидит «потерялись данные».
**Решение (рекомендую):** добавить в `xlib/helpers.nix`
```nix
mkStorageGuard =
  { dir }:
  {
    # сервис не стартует, пока /mnt/services не смонтирован:
    # Requires+After на mnt-services.mount, который упадёт, если нет источника
    requiresMountsFor = [ dir ];
  };
```
и в каждом потребителе:
```nix
systemd.services.postgresql = xlib.helpers.mkStorageGuard { dir = xlib.dirs.services-mnt-folder; };
```
**Важно — не проверять `ConditionPathIsMountPoint=/mnt/services`:** bind-mount
внутри одной ФС не меняет `st_dev`, условие вернёт false даже при корректном
монтировании. Надёжны `requiresMountsFor` или `ConditionPathIsMountPoint` на
`xlib.dirs.server-home` (там `st_dev` действительно другой).
**Плюс операционная строка в `AGENTS.md`:** перед рестартом этих сервисов —
`findmnt /mnt/services`.
**Проверка (имитация отказа):**
```
systemctl stop postgresql
sudo umount /mnt/services            # или остановить automount
systemctl start postgresql           # ожидается FAIL, а не пустая база
```

### [ ] B2. Зафиксировать, что бэкапов в конфигурации нет

**Где:** `modules/server/postgresql.nix:23` (`postgresqlBackup.enable` закомментирован),
бэкап-сервиса в репозитории нет вообще; БД 3x-ui — sqlite на том же диске.
**Задача — не код, а запись:** в `AGENTS.md` и `invariants.md` явно сказать,
что бэкапы ведутся вне Nix. Иначе агент считает конфиг самодостаточным.
**Ждёт ответа:** где бэкапы и как их проверять (инвариант 5.6).

---

## C. 3x-ui: заморозить рабочее состояние

### [ ] C1. Вернуть расследование, потерянное при откате

**Где:** 200 строк удалены коммитом `22a19be`.
**Восстановить и дополнить выводом:**
```
git show 9974784:modules/containers/3x-ui-migration-notes.md > docs/arch/notes/3x-ui-xray-26.9.md
```
Дописать в конец: вердикт — миграция ядра 26.7 → 26.9 **провалена**, откат на
рабочее состояние (панель последняя, ядро 26.7.x), обходные скрипты отключены
осознанно; причина отказа — обязательный постквантовый обмен X25519MLKEM768,
ломающий старых клиентов.
**Инвариант:** откат кода не удаляет расследование; заметка живёт в
`docs/arch/notes/`, а не рядом с откатываемым файлом.

### [ ] C2. Зафиксировать фактические версии панели и ядра

**Где:** `modules/containers/3x-ui.nix:54`
**Сначала узнать, что реально работает** (на sapphira и на otreca):
```
podman images --format '{{.Repository}}:{{.Tag}}  {{.Id}}  {{.Created}}' | grep 3x-ui
podman inspect ghcr.io/mhsanaei/3x-ui --format '{{index .RepoDigests 0}}'
podman exec 3xui_app /app/bin/xray-linux-amd64 version
```
**Потом** заменить `:latest` на найденный тег (или digest) в коде.
**Инвариант:** образы контейнеров запинены; `latest` запрещён — обновление
образа это правка в коде, а не `podman pull` на хосте.
**Почему срочно:** `podman.autoPrune.flags = ["--all"]` (`3x-ui.nix:45-47`) +
`:latest` = рабочее состояние может смениться без единого коммита.

### [ ] C3. Убрать сервис автообновления 3x-ui

**Где:** `modules/containers/3x-ui.nix:80-90` (`podman-update-3xui_app` с
`podman pull … :latest`) и закомментированный таймер (строка 97-103).
**Предложение:** удалить сервис целиком, оставив комментарий-предупреждение.
Обновление панели через `pull` — ровно тот путь, которым в 2026-10-04
декларация разошлась с рантаймом; автоматизировать его нельзя.
**Инвариант:** ни один контейнер в этом репозитории не обновляется сам.

### [ ] C4. Записать в AGENTS.md, что ядро Xray — состояние панели, а не Nix

Версия ядра выбирается в UI панели и лежит в её sqlite-БД, то есть **вне** Nix.
Репозиторий не может её гарантировать.
**Операционное правило:** перед деплоем/рестартом 3x-ui проверять версию ядра
в панели; обновление ядра = отдельная задача с записью в
`docs/arch/notes/`, а не молчаливый `podman pull`.

### [ ] C5. Решить судьбу `reality443Forwarding`

**Где:** `modules/vds/default.nix:19` (`= true`), `modules/options.nix:66-75`,
`modules/containers/3x-ui.nix:33-35`.
Состояние после отката `c8d4a12`: опция включена, поэтому на otreca
пробрасывается `127.0.0.1:15380:443`, тогда как единственный Reality-инбаунд
контейнера слушает 8443, а публичный 8443 проброшен напрямую (`0.0.0.0:8443`).
Потребителя потока (nginx-stream) откат убрал.
**Варианты:** (а) оставить как есть и описать в инвариантах; (б) погасить опцию
в `vds/default.nix` и убрать её из `options.nix`; (в) довести до рабочего
состояния. **Ждёт решения** — связано с 6.9.

---

## D. Сетевая граница: записать то, чего нет в репозитории

### [ ] D1. Пробросы роутера — главный недостающий инвариант

Ответ владельца: на сервер пробрасываются **443, 80, 22000 (syncthing),
8443 (xray), 22 (ssh)**. Это **настоящая граница доверия**, и она живёт
в конфиге роутера, то есть вне репозитория.
**Записать в двух местах:** `docs/arch/invariants.md` (слой 6) и `AGENTS.md`.
Формулировка инварианта:
> Экспозиция наружу определяется пробросами на роутере, не `openFirewall`.
> На `sapphira` `networking.firewall.enable = false` намеренно.
> Список пробросов: 22, 80, 443, 8443 (3x-ui/Xray REALITY), 22000 (syncthing).
> Новый сервис не становится доступен из интернета, пока не добавлен проброс.
> `networking.firewall.*` на `sapphira` не имеет эффекта.

### [ ] D2. Зафиксировать `100.64.0.0` как Tailscale-адрес sapphira

Моё прежнее замечание («сеть вместо адреса») было неверным — адрес назначен
вручную. Записать как факт + список из 4 мест, которые придётся править при
смене: `modules/server/nginx.nix`, `modules/server/nextcloud.nix`,
`modules/vds/systemd.nix`, `modules/vds/nginx.nix`.
**Опционально (отложено):** вынести `192.168.1.20` в `xlib.dirs` — сейчас
зашит в ~30 местах в 6 файлах. Не срочно, это рефакторинг.

### [ ] D3. Убрать мёртвое правило firewall

**Где:** `modules/server/nginx.nix:225-228` — `allowedTCPPorts = [80 443]`
не действует при `firewall.enable = false` (`server.nix:130`).
Удалить или пометить комментарием «депенит от D1».

---

## E. Документация для агента (после прохода по invariants.md)

### [ ] E1. Написать `AGENTS.md` в корне
Собирается из подтверждённых инвариантов. Структура: карта хостов →
что где лежит → инварианты (нарушишь = сломает) → ловушки из таблицы выше →
команды проверки. Ожидаемый бюджет — до 150 строк.

### [ ] E2. Выбрать проверки, которые заменят половину инвариантов
Кандидаты из инварианта 11.2:
1. ни одного `:latest` в образах (grep по `image =`);
2. `nix flake check` зелёный — уже ловит A1;
3. домены в `coredns.nix` ↔ vhost'ы в `nginx.nix` совпадают в обе стороны;
4. для каждого потребителя `mkServiceStorage` каталог существует на `External`;
5. последнее правило самописной nftables-цепочки явное;
6. `listen.addr` — адрес интерфейса, а не сеть;
7. все файлы в `secrets/` матчат `path_regex` из `.sops.yaml`.
**Ждёт ответа:** какие из них делать, какие — избыточны.

### [ ] E3. Судьба 15 закомментированных модулей
`modules/server/default.nix:33-47` — `remnawave, coturn, mealie, memos,
minecraft, n8n, netdata, nfs, open-webui, rsync, step-ca, stirling-pdf,
transmission, trilium, zerotier`. Удалить или оставить как референс?
Они мешают агенту насчитывать порты и каталоги, которых нет.

---

## F. Ждут ответа (блокируют E1)

Индексы в `docs/arch/invariants.md`:

| № | Вопрос, который блокирует запись инварианта |
|---|---|
| 2.2 | `vetymae` / `lamet` / `therima` / `soptur` — это те же машины или хосты вне репозитория? |
| 2.5 | `stateVersion` дрейфует 24.05 / 24.11 / 25.05 / 26.05 — намеренно? |
| 2.6 | Есть ли escape hatch для per-host отличий в `xlib`, или «у всех хостов одно» — закон? |
| 3.2 | `any.nix` (minimal) действительно нуждается в home-manager + sops + disko? |
| 4.1 | Как root получает доступ по SSH — `authorizedKeys` для root в коде нет |
| 4.2 | Как разрешается цикл «ключ `/etc/ssh/id_ed25519` лежит внутри секрета, а нужен для расшифровки» |
| 4.3 | Что лежит в `secrets/`, все ли файлы покрыты `path_regex` |
| 4.4 | Как подключается вторая машина / второй человек при одном age-ключе |
| 4.5 | `users.nix:87` — личный ключ или общий «ключ от деплоя» |
| 5.1 | `/mnt/services` в режиме 0777 — осознанно? |
| 5.3 | NFS выключен, Samba работает — миграция? |
| 5.4 | NTFS-том `lamet-drive` с `mask = "0000"` — что на нём лежит |
| 5.5 | `therima` / `vetymae` / `soptur` — несуществующие остатки или сетевые шары |
| 5.6 | Где бэкапы БД и 3x-ui (→ B2) |
| 6.6 | `192.168.1.20` зашит в 30 мест — считаем константой? |
| 6.7 | DNS дублирует инвентарь сервисов — как проверяем рассинхрон |
| 6.8 | Публичные IP и SSH-алиасы в `home/termux.nix` — карта «хост → адреса» нужна? |
| 6.9 | Какой путь REALITY считается правильным (→ C5) |
| 7.4 | Почему не публиковать весь диапазон 14380-15379 |
| 8.2 | `lamet.opencodes` → `:6061` — это miniflux; ошибка или так задумано |
| 8.4 | `onlyoffice` — работает после трёх регрессов? |
| 8.5 | Что слушает `:3002` (`/whiteboard` в nextcloud) |
| 9.2 | Кто создаёт `~/Music` и `~/Storage` при `createDirectories = false` |
| 10.1 | Почему `deploy-rs` не деплоит `atoridu`, `wsl`, `epral` |