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,85 @@
+# Healthcheck — Phase 6
+
+Проверенная готовность доступна через `scripts/server.sh` с теми же абсолютными
+MC_ROOT/MC_RELEASE_DIR и host settings, что описаны в [runtime.md](runtime.md).
+
+```bash
+export MC_ROOT=/absolute/server-root
+export MC_RELEASE_DIR=/absolute/full-release
+scripts/server.sh up -d --wait --wait-timeout 120
+# Проверить уже созданный контейнер без запуска/перезапуска:
+scripts/server.sh health --wait-timeout 120
+# Первый запуск с загрузкой dependencies может требовать больше времени:
+scripts/server.sh up --wait --wait-timeout 600
+```
+
+`up/start/restart --wait` и `health` возвращают 0 только после штатного Docker
+healthcheck `mc-health` и свежих успешных Minecraft status queries. Running
+container и TCP connect сами по себе не подтверждают готовность.
+
+По умолчанию окно стабильности — 10 секунд. На всём окне должны проходить
+queries, контейнер не должен меняться или перезапускаться. Неудачный query
+или health status, отличный от healthy, сбрасывает окно; проверки повторяются
+до deadline. Пример с явно выбранным окном:
+
+```bash
+scripts/server.sh health --wait-timeout 30 --stable-seconds 3
+scripts/server.sh restart --wait --wait-timeout 120 --stable-seconds 10
+```
+
+Timeout — целое положительное число секунд; он должен быть больше окна
+стабильности. Если флаг не задан, берётся `deploy.healthcheck_timeout` из
+`platform/config.yaml` (сейчас 120). Timeout учитывает Compose launch и
+ожидание readiness; проверка входных данных и сбор диагностических логов
+выполняются отдельно. Docker queries ограничены оставшимся временем, отдельный
+status query — также максимум 10 секундами. Опрос выполняется примерно раз
+в секунду. `up --wait` запускается detached; сочетание с attach/abort options
+отклоняется. Флаги поддерживают и `--wait-timeout=120`.
+
+Обычный `up -d` без `--wait` по-прежнему означает только запуск Compose и
+не гарантирует готовность. Backup resume из Phase 5 использует `up --wait`
+и теперь проходит новую проверку перед возвращением success.
+
+## Ошибки и сохранённые свидетельства
+
+Non-zero возвращается для timeout, crash/exited, paused, restart loop,
+замены контейнера, отсутствующего container/healthcheck, ошибки Docker query
+и ошибки Compose launch. Наблюдаемый restart или изменение StartedAt/RestartCount
+во время ожидания считается нестабильным запуском и завершается ошибкой;
+количество перезапусков до начала проверки используется как baseline.
+
+На неудачном запуске выводятся пути:
+
+```text
+MC_ROOT/diagnostics/health-TIMESTAMP-UUID.json
+MC_ROOT/diagnostics/health-TIMESTAMP-UUID.log
+```
+
+Report содержит причину, elapsed/timeout/stability, последнее Docker state
+(включая exit code/OOM/restart count), результат последнего status query,
+project и SHA256 release manifest. При отказе самого Compose сохраняются
+его exit/error/signal; readiness ещё не проверена. Log содержит последние
+100 строк Compose logs. Если получение логов тоже не удалось, это записывается
+в log. Диагностика имеет mode 600, каталог создаётся с mode 700.
+
+Recovery state сообщает, что runtime и binding сохранены, active release
+не переключался, automatic rollback не выполнялся. Поле backup_snapshot
+ссылается на snapshot последней записанной backup operation, если он есть;
+null не означает, что других snapshots нет. Их можно найти в MC_ROOT/backups.
+Healthcheck не удаляет runtime, не распаковывает backup и не переключает релиз.
+После timeout контейнер может продолжать startup; исправить причину/увеличить
+timeout и повторить `health`. После crash можно запустить тот же релиз через
+`up --wait`. При restart loop сначала изучить report/log и остановить сервер
+через `scripts/server.sh stop`. Восстановление — [backups.md](backups.md).
+
+Startup и отдельный `health` удерживают общую lifecycle lock до завершения
+проверки. Другой wrapper не сможет одновременно выполнить backup/restart/down.
+Контейнер другого runtime root отклоняется до запроса игрового протокола.
+Прямые Docker/Compose команды и ручное изменение данных обходят эту блокировку.
+
+Это ограниченная проверка готовности после запуска, не постоянно работающий
+watchdog. Ручное подключение клиента и состав модов проверяются отдельно;
+SSH deployment и переключение active-release используют эту проверку
+в Phase 7: [deploy.md](deploy.md).
+
+Реальные проверки crash/restart loop/timeout — [phase6-results.md](phase6-results.md).