Периодический бэкап/restore SQLite-стора (единственный bind-mount — единственная копия)

[Postlog]

Приоритет: high · Размер: M · Бэклог-ранг: 2/20

Проблема

Bind-mount db/ (docker-compose.prod.yml:17-18) — единственная копия всех юзеров, sub_id-привязок, токенов панелей и роутинг-конфига. Бэкапа нет нигде (grep по репозиторию пуст). WAL активен (DSN в open.go), поэтому наивная копия файла на середине записи неконсистентна. Потеря/повреждение = ручное переразвёртывание каждого юзера против 3x-ui, а recreate минтит новые subId → у каждого клиента ломается ссылка.

Почему важно

Необратимая полная потеря данных с восстановлением только вручную на stateful internet-facing сервисе. Самый высокоимпактный ops-пробел.

Предлагаемое решение

Добавить периодический консистентный бэкап (sqlite3 .backup / VACUUM INTO, либо litestream-sidecar) в off-host хранилище с документированным restore-путём; минимум — WAL-safe команда бэкапа в README. Опционально — admin export-эндпоинт как follow-up.

Затронутые файлы

• docker-compose.prod.yml, internal/repository/open.go, README.md, docs/subgen.md

---

_{Из аудита кодовой базы subgen (10 подсистем → adversarial-верификация, 71 находка). Бэклог-ранг указан для приоритизации.}

[Postlog]

🛠 План реализации

Issue #84 — Периодический бэкап/restore SQLite-стора (db/ bind-mount — единственная копия данных).

Резюме

Добавить WAL-safe команду консистентного бэкапа subctl backup (через SQL VACUUM INTO поверх того же *sql.DB, без внешнего sqlite3-бинаря, которого в distroless-образе нет), плюс хост-side cron, шлющий снимок в off-host хранилище, и задокументированный restore-путь. Изменения кода минимальны (одна подкоманда в cmd/subctl); основная масса — ops-обвязка и документация.

Контекст из кода (сверено с репозиторием)

• Стор — единственный bind-mount ./db:/app/db в docker-compose.prod.yml:17; бэкапа в репозитории нет (grep пуст — подтверждено).
• DSN включает journal_mode(WAL) (internal/repository/open.go:26), драйвер — modernc.org/sqlite (pure-Go, CGO off). Поэтому наивный cp db/subgen.db на середине записи неконсистентен (часть данных в -wal).
• Рантайм-образ — gcr.io/distroless/static-debian12:nonroot (Dockerfile): нет shell, нет sqlite3, нет litestream. Значит вариант «cron внутри образа с sqlite3 .backup» и «litestream-sidecar» требуют смены базового образа — отвергаем как несоразмерные. Берём то, что уже умеет процесс: SQL.
• Уже есть CLI-бинарь cmd/subctl/main.go с флаговым диспатчем (-dump-fleet, -print), читающий тот же .env + стор через repository.Open. Это естественное место для backup.
• repository.Open(ctx, path) зовёт migrations.Apply на старте — для бэкапа это безвредно (миграции идемпотентны), но чище открыть read-only хэндл (см. ниже).
• Деплой — .github/workflows/deploy.yml; db/ «is never touched» при деплое (комментарий в workflow подтверждает). Бэкап-крон живёт на хосте, не в workflow.

Решение (выбор; см. ADR ниже)

VACUUM INTO '<dest>' — единственная команда, которая: (a) консистентна при активном WAL (читает целостный снимок в рамках транзакции движка), (b) работает через database/sql на modernc-драйвере (это обычный SQL, не спец-API sqlite3 .backup/online-backup C-API), (c) выдаёт компактный (vacuum'нутый) одиночный файл без -wal/-shm, готовый к копированию/архивации. Запускается командой subctl backup, а периодичность и off-host доставку обеспечивает хост-side cron, дёргающий контейнер.

---

Пошаговый план (снизу вверх)

1. cmd/subctl/main.go — подкоманда backup

Добавить флаг и ветку диспатча по образцу существующих (-dump-fleet/-print):

• Новый флаг: backupTo := flag.String("backup", "", "VACUUM the store into this path (WAL-safe consistent snapshot) and exit").
• В проверке «nothing to do» добавить *backupTo к условию.
• Ветка:

  if *backupTo != "" {
      return backup(ctx, cfg.DBPath, *backupTo)
  }

• Функция backup(ctx, srcPath, destPath string) error:
  • dest не должен существовать (VACUUM INTO падает, если файл есть) — проверить os.Stat, при существовании вернуть понятную ошибку (это CLI-утилита оператора, человеко-текст здесь уместен — cmd/* не слой repository/service/handler, на него правило «человеко-текст только в хендлерах» не распространяется; тем не менее держим лаконично).
  • Создать каталог назначения (os.MkdirAll(filepath.Dir(destPath), 0o750)).
  • Открыть стор. Важно: не звать repository.Open (оно запускает миграции и берёт write-DSN). Открыть отдельный read-DSN напрямую: sql.Open("sqlite", srcPath+"?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)"), SetMaxOpenConns(1). Не запускать миграции (бэкап не должен мутировать прод-стор).
  • Выполнить db.ExecContext(ctx, "VACUUM INTO ?", destPath) (параметр — путь; modernc поддерживает биндинг в VACUUM INTO). Если возникнут проблемы с биндингом — fallback на безопасно экранированный литерал через одинарные кавычки с экранированием '; биндинг предпочтителен.
  • Залогировать (это CLI — log/fmt, не slog-хендлер) путь и размер результата, вернуть nil.
• Альтернатива открытию read-DSN вручную: вынести низкоуровневую функцию в internal/repository (см. шаг 2), чтобы DSN не дублировался строкой. Предпочесть это.

2. internal/repository — экспортировать WAL-safe бэкап (чтобы DSN не дублировать)

Добавить internal/repository/backup.go:

// BackupInto writes a consistent snapshot of the SQLite store at srcPath into
// destPath using `VACUUM INTO` — safe to run while the service holds the DB open
// in WAL mode (the snapshot is taken inside a read transaction). It opens its own
// read connection (no migrations are run) and does NOT mutate the source.
func BackupInto(ctx context.Context, srcPath, destPath string) error

• Открывает свой *sql.DB на read-DSN (busy_timeout + journal_mode(WAL), без foreign_keys — не нужен для read), SetMaxOpenConns(1), defer Close.
• db.ExecContext(ctx, "VACUUM INTO ?", destPath) с врапом ошибки (fmt.Errorf("vacuum into: %w", err) — техническая, без человеко-текста; это repository-слой).
• Никаких sentinel'ов в entity не требуется: это инфраструктурная операция, доменных классов ошибок у неё нет. «dest уже существует» проверяет вызывающий (CLI) до вызова.

Тогда cmd/subctl просто зовёт repository.BackupInto(ctx, cfg.DBPath, *backupTo) после своей проверки dest/MkdirAll.

Это единственный код-дельта. Слои не нарушены: repository остаётся I/O-слоем БД, CLI — тонкий вызыватель.

3. Ops-обвязка: хост-side cron + off-host доставка

Не код Go. Документируется в README/docs/subgen.md как обязательная процедура; артефакты — пример-скрипт. Предлагаемая раскладка:

• Скрипт scripts/backup.sh (новый; в git, секретов не содержит): запускает бэкап в работающем контейнере и забирает файл на хост:

  #!/usr/bin/env sh
  set -eu
  TS=$(date -u +%Y%m%dT%H%M%SZ)
  DEST="/app/db/backups/subgen-$TS.db"      # под bind-mount => появляется на хосте в ./db/backups
  docker compose -f "$COMPOSE" exec -T subgen /app/subgen -backup "$DEST"
  # затем off-host: rclone/rsync/scp ./db/backups/subgen-$TS.db в внешнее хранилище
  # ретенция: удалять снимки старше N дней

  • Запись VACUUM INTO в /app/db/backups/... ложится в тот же bind-mount → файл сразу виден на хосте в ./db/backups/, его и шлём off-host (rclone к S3/любому remote, либо scp на отдельный хост — конкретный transport оставляем оператору, в доке даём rclone-пример как дефолт).
  • docker compose exec использует уже запущенный контейнер (нет второго открытия write-стора). -T отключает TTY (для cron).
• Cron на хосте (пример crontab-строки в доке): 0 */6 * * * cd <DIR> && COMPOSE=docker-compose.yml /usr/local/bin/subgen-backup.sh >> /var/log/subgen-backup.log 2>&1 — раз в 6 часов (дефолт; обосновать в доке, оператор тюнит).
• Ретенция — в скрипте: find ./db/backups -name 'subgen-*.db' -mtime +14 -delete (14 дней локально; off-host хранилище — своя ретенция).

Замечание про compose exec vs run: exec бьёт в живой контейнер (правильно — нам нужен снимок прод-стора при работающем сервисе; WAL это позволяет). run --rm поднял бы второй экземпляр, открывающий тот же файл, — допустимо (read-DSN), но exec проще и не плодит контейнеры.

4. Restore-путь (документация + проверка)

Restore — ручная процедура, кодом не автоматизируем (редкая, разрушительная, требует подтверждения оператора). Документировать пошагово в README.md и docs/subgen.md:

1. docker compose down (остановить subgen — нельзя восстанавливать под живой записью).
2. Сохранить текущий повреждённый стор в сторону: mv db/subgen.db db/subgen.db.broken (плюс -wal/-shm, если есть).
3. Положить снимок на место: cp <backup>.db db/subgen.db (снимок от VACUUM INTO — целостный одиночный файл без -wal).
4. chown 65532:65532 db/subgen.db (nonroot uid образа — как в docker-compose.yml-комментарии).
5. docker compose up -d; проверить /healthz и админку.

Так как VACUUM INTO даёт обычный SQLite-файл, никакой спец-распаковки/replay WAL не нужно — restore = подмена файла.

---

Миграции БД

Не требуются. Issue про бэкап существующего стора, схему не меняем. Новых migrations/NNNN-*.sql нет.

OpenAPI / ogen

Не требуются в этом issue. Admin export-эндпоинт упомянут в issue как опциональный follow-up — выносим в отдельный issue, не сюда (держим этот PR размера M и ops-сфокусированным). Если делать позже: read-ручка GET /admin/api/backup под /admin/api/*-гейтом, стримящая VACUUM INTO во временный файл и отдающая его как application/octet-stream attachment; контракт — в openapi/, затем go generate ./internal/oas/. Здесь не реализуем.

Тесты

• internal/repository/backup_test.go — TestBackupInto (table-driven, один тест на метод):
  • success.snapshot — поднять временный стор (есть хелпер-пакет internal/repository/dbtest; использовать его для seed), записать пару строк, вызвать BackupInto в temp-dest, открыть dest отдельным sql.Open и убедиться, что данные совпадают (snapshot консистентен).
  • error.dest_exists — если решим класть проверку «dest существует» внутрь BackupInto (а не в CLI), кейс на ошибку; если проверка в CLI — этот кейс там не нужен, тогда покрываем «dest в несуществующем каталоге → ошибка vacuum».
  • error.bad_src — несуществующий/битый srcPath → обёрнутая ошибка (wantErr: true, без sentinel).
  • Это integration-уровня тест на реальном temp-SQLite (как open_test.go рядом) — гоняется make integration/make test. Моки/contract.go не нужны: BackupInto бьёт в реальный движок, мокать SQLite смысла нет (и противоречит «тестируем публичный метод как есть»).
• CLI (cmd/subctl) — отдельный тест не обязателен (тонкая обёртка над repository.BackupInto + os.Stat/MkdirAll); если покрывать — smoke на функцию backup(...) через temp-пути. По образцу репозитория cmd/* обычно без unit-тестов — не гольдплейтить.
• apitest — не нужен: бэкап не ходит в 3x-ui и не пересекает HTTP-контракт.
• contract.go + mockgen — не нужны (нет новой зависимости-интерфейса; BackupInto работает с database/sql напрямую внутри repository-слоя, как Open).

Документация

• CHANGELOG.md — новая запись сверху:
  ## 2026-06-12 — WAL-safe бэкап SQLite-стора + cron/restore (#84) + 1–2 строки сути + ссылка на ADR.
• ADR — да, нетривиальное решение (выбор между VACUUM INTO / sqlite3 .backup / litestream-sidecar / наивный cp, плюс «cron на хосте vs в образе»): docs/decisions/0006-sqlite-backup.md по шаблону 0000-template.md. Секции:
  • Context — единственный bind-mount, WAL, distroless без shell/sqlite3, нет бэкапа.
  • Considered Options — (1) наивный cp (отвергнут: WAL-inconsistent); (2) sqlite3 .backup/litestream-sidecar (отвергнут: distroless без shell/бинаря, рост образа/сложности); (3) VACUUM INTO через subctl + хост-cron (выбран: zero новых зависимостей, работает на pure-Go драйвере, консистентен при WAL, одиночный файл); (4) admin export-эндпоинт (отложен в follow-up).
  • Decision — вариант 3.
  • Consequences — нужен хост-cron (operator-owned, вне CI), restore ручной, off-host transport на усмотрение оператора; образ не меняется.
• README.md — раздел «Backups & restore»: команда subctl -backup, пример cron + off-host, restore-чеклист.
• docs/subgen.md — ops-врезка про бэкап/restore (рядом с разделом про db/ и деплой).
• scripts/backup.sh — пример-скрипт (в git; без секретов).

Риски и edge-cases

• VACUUM INTO биндинг пути: проверить, что modernc принимает ?-параметр в VACUUM INTO ?. Если нет — экранированный литерал (одинарные кавычки, удвоение '). Покрыть тестом success.snapshot.
• Место на диске: VACUUM INTO пишет полную копию (vacuum'нутую) — на маленьком стор-файле некритично, но в доке упомянуть, что dest должен иметь место; ретенция чистит старое.
• dest уже существует → VACUUM INTO падает. Поэтому timestamp в имени (коллизий нет) + предпроверка в CLI.
• Права nonroot (uid 65532): файл, записанный процессом в bind-mount, принадлежит 65532 — на хосте читается; для off-host копирования cron должен иметь доступ (документировать; обычно root-cron хоста читает свободно).
• Бэкап при активной записи: WAL гарантирует, что VACUUM INTO видит согласованный снимок; долгая запись лишь немного задержит старт vacuum (busy_timeout=5000). Приемлемо.
• Не запускать миграции при бэкапе: read-DSN без migrations.Apply — иначе бэкап-команда мутировала бы прод-стор (накат миграций) при первом запуске после деплоя. Учтено (шаг 2 открывает свой хэндл).
• Секреты в бэкапе: снимок содержит panel-токены/sub_id/HMAC-данные — он такой же секрет, как db/. В доке явно: off-host хранилище должно быть приватным/шифрованным; backups-каталог в .gitignore (как db/). Проверить, что db/ уже игнорится и db/backups/ под ним покрыт.

Зависимости / порядок

Самодостаточно, блокеров нет. Admin export-эндпоинт (упомянут в issue как опциональный) — отдельный follow-up issue, не входит в этот PR.