minecraft-lab/docs/phase5-results.md

Phase 5: backups и восстановление

Phase 5 завершена для NeoForge 21.1.252 / Minecraft 1.21.1. Реализованы ./mcpack backup, ./mcpack restore и обязательный gate backupBeforeApply для будущего deployment. Контракт и проверенная инструкция: 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:

.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.