first cycle lab release

2026-10-04 00:30:09 +07:00
parent 85f6897365
commit d134daafd8
92 changed files with 5623 additions and 9 deletions
@@ -0,0 +1,74 @@
+# Phase 5: backups и восстановление
+
+Phase 5 завершена для NeoForge 21.1.252 / Minecraft 1.21.1. Реализованы
+`./mcpack backup`, `./mcpack restore` и обязательный gate `backupBeforeApply`
+для будущего deployment. Контракт и проверенная инструкция: [backups.md](backups.md).
+
+## Проверка с реальным Docker
+
+Проверка 2026-10-03 выполнялась на отдельном root `.tools/phase4-server`,
+project `minecraft-lab-phase4`, port 25566, full release 0.0.4. Основной
+Phase 0 сервер на 25565 не останавливался и остался healthy.
+
+- Запущенный сервер был корректно остановлен; backup всего runtime
+  опубликован после tar/zstd listing и пробной распаковки.
+- Snapshot содержит runtime archive, metadata, полную копию release 0.0.4
+  и checksums всех файлов. Исключений нет.
+- После backup сервер автоматически вернулся на исходный release в healthy;
+  `mc-health` подтвердил Minecraft 1.21.1.
+- Затем намеренно подставлена команда tar с exit 42. Backup вернул non-zero,
+  оставил сервер остановленным, не создал дополнительный окончательный
+  snapshot и удалил временный staging. Metadata операции фиксирует failed.
+- Старый тестовый контейнер удалён через down. Snapshot восстановлен в новый
+  `.tools/phase5-restored-server` без распаковки поверх существующего root.
+- До запуска совпали все 416 inventory entries (160 файлов, включая 23 файла
+  world): пути, bytes/SHA256, mode, UID и GID. В наборе есть владельцы
+  1000:1000 и 0:0; обе группы сохранились.
+- Подтверждены `mod-state/phase5.json` и unmanaged config вне world,
+  server.properties, ops.json, whitelist.json. Локальный host `.env` не
+  копировался: при запуске использован уже настроенный файл прежнего test root.
+- Восстановленная копия запущена с собственным сохранённым `release/`:
+  NeoForge 21.1.252, Minecraft 1.21.1, статус healthy и успешный `mc-health`.
+- После проверки восстановленный контейнер/network удалены через down.
+  Оба тестовых runtime и snapshot сохранены для дальнейших проверок.
+
+Проверенный snapshot:
+
+```text
+.tools/phase4-server/backups/20261003T134409150Z-edd387d7-f947-4c3d-8ffc-bc02649cdfdc
+archive bytes: 162695375
+archive SHA256: e52c82adb379942ed2b63fb0cd361dd7d2cfd153314b26b026bafd942c87c9ce
+release manifest SHA256: 5933ed34f35473026a32f0c3eab9a8b86b6fb484461bac2f670e0a74930aaa0c
+```
+
+Свидетельства: `.tools/phase5-evidence/backup.log`, `failed-backup.log`,
+`failure-verification.txt`, `restore-verification.txt`, `resumed-health.txt`,
+`restored-health.txt`, `restored-start.log`, `primary-server-status.txt`,
+`integration.log`. Сценарий — `scripts/verify-phase5.sh`; он требует специально
+подготовленного test root Phase 4 и ещё не существующего restore destination.
+Его нельзя запускать как универсальную команду на primary сервере.
+
+## Автоматические проверки
+
+`npm test`: 37 tests pass. Backup/restore tests проверяют общий lifecycle lock,
+stop/archive/verify/resume, stopped/absent state, разные snapshot ID,
+восстановление bytes/modes/ownership и связанного release, запрет существующей
+цели, повреждённый archive, неполное checksum coverage, ошибку tar/stop/resume,
+unsupported links, проверку target до остановки и отказ применения до backup.
+
+Gate test доказывает, что callback будущего apply не вызывается при ошибке
+архива и вызывается только после verified snapshot под той же блокировкой.
+При ошибке callback status учитывает текущее состояние контейнера и не
+запускает старую сборку автоматически. SSH apply сам пока не реализован.
+Build, mod commands и runtime regression tests также проходят. Node/Bash
+syntax и `git diff --check` пройдены.
+
+## Оставшиеся границы
+
+Автоматическое удаление snapshot, off-host копии, retention, rollback и
+переключение active release — последующие фазы. Пока runtime не поддерживает
+links/special files в backup. Atomic publication защищает от обычной ошибки
+процесса, но fsync для гарантии при отключении питания не реализован.
+Primary старого spike wrapper не мигрирован на full-release binding.
+Следующая Phase 6 — расширенная диагностика healthcheck, crash/restart-loop
+и timeout с полезными logs.