mirror of
https://github.com/oqyude/nixos.git
synced 2026-10-11 22:37:25 +03:00
oqyude
61b3724752
Comprehensive batch addressing the 16-task backlog in
.agent/tasks/manifest.json. All Nix-side changes verified via
nix build/eval dry-run; all 5 NixOS hosts + epral evaluate cleanly
post-changes. No regressions.
Wave 1 (non-functional cleanup):
T1/A1 — configurations/mobile.nix:12: fix `import ../lib/xlib.nix`
(broken path) → `import ../lib/xlib`. Unblocks nixOnDroid
configurations.epral. R1.1 invariant.
T8/C3 — modules/containers/3x-ui.nix: remove `podman-update-3xui_app`
systemd service and commented timer. Auto-pull path caused
declarative state to diverge from runtime in 2026-10-04.
R1.5 invariant.
T13/D3 — modules/server/nginx.nix:368-371: remove dead
`networking.firewall.allowedTCPPorts = [80 443]`.
`firewall.enable = false` on sapphira (R1.3), so openFirewall
rules are no-op. Replace with R1.3 comment.
T6/C1 — .agent/decisions/notes/3x-ui-xray-26.9.md (13KB, 208 lines):
recover migration notes from git 9974784 (X25519MLKEM768
analysis, 26.7→26.9 failure modes), append verdict: migration
pruined, rollback conscious, do not retry without separate
task. R1.5 / C1.
T9/C4 — .agent/rules/project-rules.md: add R1.8 — Xray-core version is
state of 3x-ui panel, not Nix. Update trap entry for
3x-ui.nix:54 to reference R1.8.
T11/D1, T12/D2 — .agent/checkpoints.json + .agent/tasks/manifest.json:
verify R1.3 (router port-forwards 22/80/443/8443/22000) and
R1.4 (100.64.0.0 = Tailscale sapphira) wording already
satisfies acceptance criteria. Flip status pending → completed.
T4 (storage guard, FUNCTIONAL CHANGE):
New helper in lib/xlib/helpers.nix:
mkStorageGuard = xlib: {
RequiresMountsFor = [ xlib.dirs.server-home ];
ConditionPathIsMountPoint = [ "!${xlib.dirs.server-home}" ];
};
Applied to 13 systemd units via path-style override:
- modules/server/{postgresql,samba,homebox,gitea,navidrome,
syncthing,uptime-kuma,immich,nextcloud,calibre-web}.nix
- modules/containers/3x-ui.nix (podman-3xui_app)
- modules/containers/tape-rotation.nix (podman-taperotation-{backend,frontend})
Anchor: xlib.dirs.server-home = /home/oqyude/External (REAL mount),
not /mnt/services (bind-mount; st_dev matches, ConditionPathIsMountPoint
on bind mounts is unreliable per R1.2 note).
Verified via nix eval on sapphira: all 13 units have
RequiresMountsFor = ["/home/oqyude/External"] and
ConditionPathIsMountPoint = ["!/home/oqyude/External"].
Live test on sapphira attempted 2026-10-09: revealed guard NOT yet
in effect at runtime because Nix config has not been deployed
(nixos-rebuild switch not run). postgresql started despite External
being unmounted. Implementation correct, deployment pending user
action.
T7/C2 (read-only diag, no code change):
3x-ui version facts recorded in conversation (sapphira journal +
/var/lib/containers/storage/overlay/.../diff/app/bin/xray-linux-amd64):
- Active Xray: 26.7.28 (go1.26.5 linux/amd64) — R1.5 validated at runtime
- Stale binary: 26.9.30 (go1.27.1) — leftover from failed 26.9 migration
- Panel DB (x-ui.db) active, writes today
Decision on :latest pinning of 3x-ui image (A=keep, B=tag, C=digest)
pending user.
T3/A3 (nftables on otreca — config analysis + proposal):
Diagnostic attempted via ssh otreca-tailscale (100.64.1.0) and
otreca public (109.248.161.5:22): BOTH UNREACHABLE. Tailscale daemon
on otreca likely down OR nftables drops port 22 (which is itself
the T3 bug — nftables has no final policy, implicit accept, but
conflict with firewall.enable = true per R1.6).
Proposal written: .agent/decisions/proposals/vds-nftables-fix.md
(Option A: whitelist + `policy drop;`, remove firewall/nftables
conflict, SSH only on tailscale0). Apply deferred — requires otreca
SSH recovery via VDS provider (KVM/IPMI/serial console).
T5/B2 (backups documentation):
.agent/decisions/0002-backups-external.md (draft): catalog of what
is declared in Nix vs. what is external; awaiting answer to open
question 5.6 (where are backups, how are they verified).
T15/E2 (CI checks):
.ci/checks.sh (executable, ~140 lines) with 3 checks from
analysis-report.md §5:
- #1: no `:latest` in container images (with R1.5 whitelist
for 3x-ui). FAIL — 4 violations:
localhost/kokoro-tts:latest
ghcr.io/openhands/openhands:latest
docker.io/elizaroveugene/taperotation-backend:latest
docker.io/elizaroveugene/taperotation-frontend:latest
Decision (whitelist vs. pin) pending user.
- #2: nix flake check (skipped with --no-build).
- #7: secrets/ files match .sops.yaml path_regex. PASS.
T16/E3 (archive commented modules):
13 of 14 commented modules in modules/server/default.nix:37-50
existed as files. git mv them to archive/{server-modules,containers}/.
1 (stirling-pdf.nix) didn't exist; just removed the comment.
modules/server/default.nix:37-50 cleaned of 14 commented lines.
Added 3-line comment recording the archive date and reason.
Verified: nixosConfigurations.sapphira still evaluates.
Post-change state:
$ nix build .#nixosConfigurations.{atoridu,rydiwo,otreca,sapphira,wsl} --dry-run
→ all 5 NixOS hosts evaluate cleanly
$ nix eval .#nixOnDroidConfigurations.epral.config.system.stateVersion
→ "24.05"
Pending (user input required — not in this commit):
- T4 deploy: run `nixos-rebuild switch` on sapphira to activate guard
- T7: pick A/B/C for 3x-ui :latest pinning
- T3: recover otreca SSH via VDS provider, then apply Option A
- T10/C5: decide fate of reality443Forwarding
- T5: answer 5.6 about backup location/verification
- T15: whitelist or pin 4 :latest images
Untracked files NOT committed (in .gitignore):
.temp/t4-live-test*.sh, .temp/cleanup-*.sh — throwaway test scripts
from T4 live test attempts. Preserved locally for reference; see
AGENTS.md convention ("Создавать `.temp/` в корне проекта — Для
временных файлов агента. Всегда в `.gitignore`").
Also untracked, committed:
.agent/reviews/2026-10-10-review-dev-diff-vs-16644fc.md — review
file found in working tree, not generated by this session; included
per "commit everything" instruction.
166 lines
11 KiB
Markdown
166 lines
11 KiB
Markdown
# Project Rules
|
||
|
||
Правила, которым агент обязан следовать во всех фазах. Источник: старый
|
||
`AGENTS.md` (накоплен при проходе по репозиторию 2026-10-05, ответы владельца
|
||
учтены 2026-10-05). Дополнения и уточнения — через `/adr`.
|
||
|
||
## Обязательные правила
|
||
|
||
### R1. Не ломать подтверждённые инварианты
|
||
|
||
1. **Все `outputs` флейка должны вычисляться.** `configurations/mobile.nix:12`
|
||
импортировал несуществующий `lib/xlib.nix` — был сломан, `epral` не
|
||
собирался. Закреплено через `nix flake check`.
|
||
2. **Носитель данных (`/home/oqyude/External`) обязан быть смонтирован** до
|
||
старта `postgresql`, `n8n`, `samba`, `homebox`, `minecraft`, `3x-ui`,
|
||
`tape-rotation`. `mkServiceStorage` даёт `bind,x-systemd.automount,nofail`
|
||
— без guard'а сервис стартует на пустой БД. Задача `B1` в `manifest.json`.
|
||
3. **Сетевая граница sapphira — роутер.** `firewall.enable = false` намеренно.
|
||
Роутер пробрасывает ровно 5 портов: **443, 80, 22000 (syncthing),
|
||
8443 (xray), 22 (ssh)**. `nginx.nix:225` (`allowedTCPPorts = [80 443]`) мёртв.
|
||
`openFirewall`/`allowedTCPPorts` на sapphira не имеют эффекта.
|
||
4. **`100.64.0.0` = Tailscale-адрес sapphira**, назначен вручную. Не сеть, не
|
||
ошибка. Используется в `nginx.nix`, `nextcloud.nix` (`trusted_proxies`),
|
||
`vds/systemd.nix`, `vds/nginx.nix`. При смене — править 4 файла.
|
||
5. **3x-ui заморожен.** Панель на последней версии (образ `:latest`),
|
||
ядро Xray на 26.7.x. Миграция на 26.9.x провалена. Обходные скрипты
|
||
(timer, migrateScript) отключены осознанно. **Не** обновлять ядро через
|
||
панель без записи в `decisions/` или `notes/`.
|
||
6. **nftables на VDS требует явной финальной политики.** Текущий ruleset
|
||
(`vds.nix:73-91`) — без явного последнего правила и без `policy` → неявный
|
||
accept. На otreca одновременно `nftables.enable = true` и `firewall.*` —
|
||
проверить, кто реально владеет ruleset'ом, перед правкой.
|
||
7. **sops-пути — через `config.sops.secrets.<name>.path`.** Любой
|
||
`path =` override на sops-блоке делает хардкод-потребителя молча
|
||
сломанным: rebuild зелёный, сервис стартует, контент пустой. См. ADR-0001.
|
||
8. **Версия ядра Xray — состояние UI-панели 3x-ui, не Nix.** Ядро
|
||
ставится через UI панели (UI → xray version) и хранится в её
|
||
sqlite-БД. Перед любым деплоем/ребутом 3x-ui на sapphira —
|
||
проверить версию ядра в панели. Nix декларирует панель (`:latest`),
|
||
но не ядро.
|
||
|
||
### R2. home-manager `Service` ≠ `serviceConfig`
|
||
|
||
`home/modules/opencode.nix:339-350` (`c73a698`): в home-manager нельзя писать
|
||
`serviceConfig = { ... }` — рендерится литеральная секция `[serviceConfig]`,
|
||
которую systemd молча игнорирует («Unknown section 'serviceConfig'. Ignoring.»).
|
||
Правильно: `systemd.user.services.opencode-web.Service = { ... }`. В home-manager
|
||
cgroup-опции (`MemoryHigh`, `OOMScoreAdjust`, …) пишутся в
|
||
`systemd.user.services.<name>.Service`, **не** в `serviceConfig`. Ошибка
|
||
не диагностируется — она просто не применяется.
|
||
|
||
### R3. Sops-цикл ключа задокументировать
|
||
|
||
`/etc/ssh/id_ed25519` одновременно: `hostKeys` для sshd, `sops.age.sshKeyPaths`
|
||
для расшифровки, цель `ssh_key_private_known`, цель `ssh_key_public_host`.
|
||
Как разворачивается на чистой машине — **одноразовый bootstrap**. Должен быть
|
||
задокументирован, иначе при переустановке хоста агент не выведет.
|
||
|
||
### R4. Перед деплоем External-диска — `findmnt`
|
||
|
||
Перед рестартом сервисов, использующих `mkServiceStorage` (postgresql, samba,
|
||
homebox, gitea, navidrome, syncthing, uptime-kuma, immich, nextcloud,
|
||
calibre-web, 3x-ui, tape-rotation):
|
||
|
||
```bash
|
||
findmnt /home/oqyude/External
|
||
findmnt /mnt/services
|
||
```
|
||
|
||
До реализации guard'а (задача B1) — это единственная защита от старта на
|
||
пустой БД.
|
||
|
||
### R5. Проверка целостности sops-секретов
|
||
|
||
Любая правка `users.nix` или потребителя sops-секрета требует:
|
||
|
||
```bash
|
||
sops --version
|
||
nix build .#nixosConfigurations.<хост>.config.system.build.toplevel --dry-run
|
||
```
|
||
|
||
Расшифровка sops-секретов зависит от `/etc/ssh/id_ed25519` (см. R3).
|
||
Циклическая зависимость — см. «Где НЕ лезть без ответа».
|
||
|
||
## Ловушки (выглядит сломанным, намеренно)
|
||
|
||
Прежде чем чинить — проверить этот список. Здесь лежат решения, которые
|
||
иначе «поправляются» обратно и ломают рабочую систему.
|
||
|
||
| Где | Что выглядит ошибкой | На самом деле |
|
||
|---|---|---|
|
||
| `server.nix:130` | `firewall.enable = false` при 20 сервисах на `0.0.0.0` | Роутер фильтрует, см. R1.3 |
|
||
| `mobile.nix:95`, `wsl.nix:59` | `stateVersion` 24.05 / 24.11 vs 26.05 | Каждый хост зафиксирован на своей версии |
|
||
| `users.nix:66` | `uid = if hostname == "sapphira" then 1001 else …` | Костыль под 1000 = удалённый `yuyus`; удалять только после миграции ФС |
|
||
| `3x-ui.nix:54` | `image = …:latest` | Панель намеренно latest; ядро Xray — состояние панели, см. R1.8 |
|
||
| `3x-ui.nix:33-35` | `reality443Forwarding = true` на VDS | Следствие отката `c8d4a12`; смысл утрачен, см. задачу C5 |
|
||
| `server/default.nix:33-47` | 15 закомментированных модулей | Отключены осознанно, см. задачу E3 |
|
||
| `opencode.nix:339` | `systemd.user.services.opencode-web.Service` | `serviceConfig` рендерится в секцию `[serviceConfig]`, systemd молча игнорирует (`c73a698`); см. R2 |
|
||
| `vds.nix:73-91` | nftables без финального правила | Известный пробел, см. задачу A3 |
|
||
| `100.64.0.0` | Первый адрес CGNAT `/10` | Tailscale-адрес sapphira, см. R1.4 |
|
||
| `server.nix:61-63` | `z /mnt/services 0777` | World-writable точка монтирования; см. задачу B1 |
|
||
|
||
## Куда лезть по задаче
|
||
|
||
| Задача | Файл |
|
||
|---|---|
|
||
| Добавить хост | `configurations/default.nix` + `configurations/<host>.nix` + `configurations/{hardware,disko}/<host>.nix` |
|
||
| Добавить системный сервис | `modules/server/<name>.nix`, добавить в `modules/server/default.nix:imports` |
|
||
| Добавить home-пакет для пользователя | `home/<device_type>.nix` (через `lib.mkIf` или просто список) |
|
||
| Добавить опцию, читаемую несколькими модулями | `modules/options.nix` |
|
||
| Изменить mount/имя пользователя | `lib/xlib/dirs.nix`, `lib/xlib/device.nix` |
|
||
| Изменить домен / сертификат | `modules/server/coredns.nix` + `modules/server/nginx.nix` (или `vds/`) |
|
||
| Sops-секрет | положить в `secrets/<name>.<yaml\|json\|env\|ini>`; `users.nix:99` уже подключает `secrets/default.yaml`; dotenv/json-секреты — через `mkUserSecret` |
|
||
|
||
## Где НЕ лезть без ответа владельца
|
||
|
||
- `secrets/` (sops-encrypted, расшифровываются `/etc/ssh/id_ed25519` → циклический bootstrap).
|
||
- `let deploy` без проверки deploy-rs нод: `rydiwo` (ноутбук, может быть выключен).
|
||
- Любая правка, противоречащая «Подтверждённым инвариантам» выше (R1).
|
||
- `vetymae` / `lamet` / `therima` / `soptur` в `dirs.nix` — природа неясна (открытый вопрос 2.2/5.5).
|
||
- `192.168.1.20` в 30 местах — менять только при готовности править все места (открытый вопрос 6.6).
|
||
- Ядро Xray 26.7.x → 26.9.x — миграция провалена, не повторять без отдельной задачи.
|
||
|
||
## Проверки
|
||
|
||
```bash
|
||
# все outputs вычисляются
|
||
nix flake check
|
||
|
||
# правки применились на целевой хост
|
||
nix build .#nixosConfigurations.<host>.config.system.build.toplevel
|
||
|
||
# nixOnDroid
|
||
nix build .#nixOnDroidConfigurations.epral.config.system.build.toplevel
|
||
|
||
# внешний диск смонтирован (до рестарта сервисов на нём)
|
||
findmnt /home/oqyude/External
|
||
findmnt /mnt/services
|
||
|
||
# state of guard-зависимостей (когда будет todo B1)
|
||
systemctl show postgresql -p Requires -p After | tr ' ' '\n' | grep -E 'mnt-|home-oqyude'
|
||
|
||
# sops
|
||
sops --version
|
||
```
|
||
|
||
## Конвенции проекта
|
||
|
||
- `xlib` (в `lib/xlib/`) — чистые данные: identity (`device`), capability flags,
|
||
директории, helper'ы. Передаётся в каждый модуль через `specialArgs`.
|
||
Конфиг не может переопределить `xlib` — единственная точка изменения это
|
||
`configurations/default.nix`.
|
||
- `device.type` ∈ { minimal, primary, secondary, server, vds, wsl, termux }.
|
||
`modules/defaultModule` импортирует `modules/<type>/` через
|
||
`lib.optional (!isDesktop && type != "minimal") (./. + "/${type}")`.
|
||
- `mkXlib` (`lib/xlib/default.nix:38-77`) — единственная точка сборки xlib.
|
||
- Опция живёт в `modules/options.nix`, если её **устанавливает** один модуль,
|
||
а **читает** другой. `host.reader.X.enable` живёт в `essentials/ssh.nix`,
|
||
потому что его объявляет и использует один модуль.
|
||
- `home/<type>.nix` = единственный источник «что есть на этом хосте» для
|
||
пользователя; добавление пакета в новый тип = правильный файл, а не
|
||
`home/default.nix`.
|
||
- `.sops.yaml`: один age-ключ (`*default`), `path_regex: secrets/[^/]+\.(yaml|json|env|ini)$`.
|
||
Покрывает только плоские файлы в `secrets/` (без подкаталогов). Дополнительные
|
||
секреты dotenv/json — через `mkUserSecret` (`users.nix:33-41`).
|