Документация Docs/ru/how-to/release/operations.md

Эксплуатация релиза

Это руководство описывает переиспользуемый жизненный цикл сервера FOnline: готовность, развёртывание, остановку и откат. Упаковка и выпуск владеет артефактами; Persistence — механикой базы данных; резервное копирование и восстановление — нейтральной к провайдеру процедурой восстановления. Игра владеет инфраструктурой, политикой данных, целевыми показателями и инцидентами.

Решение о rollout

Запускайте foreground headless binary под настоящим supervisor. Родитель detached daemon завершается до окончания startup дочернего процесса, поэтому успешное завершение родителя не является readiness evidence. Readiness требует Start server complete! и project-owned functional probe; просто живой процесс явно не считается ready.

Останавливайте процесс корректно через SIGTERM на POSIX или SERVICE_CONTROL_STOP для Windows service и ожидайте Server stopped!. Настройка worker drain ограничивает только первый worker-pool drain, а не общий stop timeout. Rollback является новым controlled deployment единого data-compatible immutable artifact/config/data unit через тот же readiness gate. Никогда не смешивайте binaries, resources, config или data несовместимых release units.

Установите эксплуатационную границу

Engine создаёт бинарные файлы, но не создаёт сервисные учётные записи, supervisor, контейнеры, правила трафика/TLS/firewall, кластеры баз данных, резервные копии, оповещения или политику дежурств. Версионируйте всё это в проекте.

Неизменяемая единица релиза содержит принятый серверный бинарный файл, запечённые ресурсы и конфигурацию, клиентские пакеты, нативные updater payloads и manifest. Храните изменяемое состояние отдельно, если это требуется для атомарной замены или сохранения возможности отката.

Необязательный health-файл получает имя от executable и размещается под тем же writable root, что и log. Read-only Common.UserWritablePath разрешается до открытия log или config из --UserWritablePath либо marker INSTALLED рядом с executable; если путь непустой, под ним размещаются log, health-файл, cache, resource overlay, self-updated binaries и server database. Задавайте working directory и любое переопределение writable path явно: разные среды запуска не обязаны выбирать одинаковые расположения.

Выберите серверный процесс

Бинарный файл	Поведение runtime	Эксплуатационное применение
`<Game>_Server`	Оконный сервер с application frontend	Локальная разработка и диагностика под наблюдением
`<Game>_ServerHeadless`	Foreground-процесс без рендеринга; ожидает запроса выхода или ошибки запуска	Предпочтительный процесс под внешним supervisor или в контейнере
`<Game>_ServerService`	Только Windows SCM; сообщает `RUNNING` после `ServerEngine::IsStarted()`, корректно останавливается при ошибке запуска и обрабатывает `SERVICE_CONTROL_STOP`	Нативный Windows service route, который должен квалифицировать проект
`<Game>_ServerDaemon`	На не-Windows вызывает `fork()`, закрывает standard streams и вызывает `setsid()` в child; текущее приложение игнорирует возвращённый failure flag и при ошибке `fork()` может продолжить работу в исходном процессе	Устаревший detached launch, требующий project qualification, владения PID и наблюдения за child

Предпочитайте foreground headless-бинарник под supervisor. Родитель daemon завершается до окончания запуска дочернего процесса, поэтому успешный exit команды запуска не доказывает готовность. Daemon не записывает PID-файл и не реализует протокол менеджера процессов.

Windows helper регистрирует фиксированное имя SCM FOnlineServer с demand-start. Запуск service executable без распознанного control-флага регистрирует или обновляет команду из quoted executable path, текущей command line и --server-service; --server-service-delete удаляет регистрацию, а --server-service-start входит в SCM dispatcher. Зарегистрированная команда сама не использует этот start-флаг, поэтому текущий helper требует отдельной проверки на Windows: одна регистрация не доказывает запуск службы. Helper не задаёт рабочий каталог, учётную запись, зависимости, recovery actions или продуктовое имя.

Определите готовность и здоровье

Существование процесса означает liveness, но не readiness. Переиспользуемая проверка готовности требует всех следующих наблюдений:

Процесс остаётся жив и не сообщил об ошибке запуска.
После успешного запуска runtime, мира, скриптов и первоначального commit в логе появилась строка Start server complete!.
Принадлежащая проекту функциональная проверка, например handshake или вход совместимого клиента, проходит через реальный сетевой маршрут.

При Server.WriteHealthFile = True запуск записывает Starting... в <executable>_Health.txt; после _started периодический writer заменяет содержимое на версию, время, нагрузку, соединения, сущности, задачи, отклонения и метрики базы данных. Поэтому:

Starting... явно не означает готовность;
требуйте ожидаемую версию и compatibility version, разбираемое содержимое и свежее время изменения;
устаревший файл означает неизвестное или нездоровое состояние, а не доказательство смерти процесса;
задайте для Server.HealthFilePeriodMs положительный интервал, квалифицированный проектом;
если orchestrator нужен сетевой endpoint, публикуйте локальный файл через принадлежащую проекту проверку или sidecar.

Engine не предоставляет HTTP endpoint для health/drain и не создаёт оповещений. Не публикуйте файл в недоверенную сеть.

Подготовьте развёртывание

До изменения работающей среды:

Определите точные SHA игры и Engine, ID пакета и конфигурации, хеши артефактов, результат подписи, поколение updater и runtime ABI, совместимость базы данных и схемы.
Проверьте артефакт из неизменяемого хранилища, просканируйте inventory на секреты и подготовьте его без изменения активного релиза.
Разрешите целевую конфигурацию и credentials на целевом хосте согласно Security and Secrets.
Проверьте executable, ресурсы, writable directory, порт, firewall, базу данных и права service account, не выводя секреты.
При изменениях долговечного состояния следуйте Backup and Recovery: создайте согласованную с backend резервную копию или snapshot, сохраните оба recovery oplog и докажите изолированное семантическое восстановление. Operation log Engine не заменяет резервную копию.
Убедитесь, что предыдущий совместимый комплект артефакта, конфигурации и данных по-прежнему доступен, и назовите оператора, уполномоченного на откат.
Выполните ту же последовательность start/readiness/smoke/stop в репрезентативной непроизводственной среде.

Никогда не подключайте старый и новый серверы одновременно к одной изменяемой базе данных, если persistence design и migration tests игры явно не доказывают безопасность такой топологии.

Разверните и проверьте

Используйте поэтапное развёртывание, даже если конечная топология содержит один сервер:

Уберите или изолируйте instance от нового трафика средствами инфраструктуры проекта. В FOnline нет встроенного drain protocol.
Запросите корректную остановку и дождитесь выхода процесса; не перезаписывайте файлы, используемые живым процессом.
Активируйте неизменяемый каталог релиза или versioned image и соответствующую ему конфигурацию.
Запустите под ограниченной политикой перезапуска; повторяющаяся ошибка запуска является инцидентом.
Потребуйте полную проверку readiness. Состояние Windows SERVICE_RUNNING полезно как первичное свидетельство, но дополняйте его функциональной проверкой.
Возвращайте трафик постепенно; наблюдайте за перезапусками, свежестью health, соединениями и отклонениями, задачами, ошибками базы данных/updater и игровыми показателями.
Запишите manifest, среду и конфигурацию, run identity, timestamps, свидетельства и решение.

До возврата трафика проверьте Client Runtime Split and Updater. Неподдерживаемые поколения updater требуют нового полного клиентского пакета.

Остановите безопасно

На Linux/macOS отправьте SIGTERM или SIGINT headless-процессу либо дочернему процессу daemon; цикл преобразует зафиксированный signal в запрос выхода. Для Windows service используйте SERVICE_CONTROL_STOP. Принудительное завершение обходит shutdown Engine.

ServerEngine::Shutdown() останавливает networking и jobs, вызывает OnFinish, уничтожает сущности и backends, сохраняет identity/time, ожидает commits базы данных, отключает игроков и пишет Server stopped!.

Server.ShutdownGraceMs ограничивает только первый drain worker pool. Затем ожидающие на lock потоки принудительно пробуждаются, после чего продолжается неограниченное ожидание; скрипты, OnFinish, backends и commits могут продлить остановку. Выбирайте timeout менеджера по измеренному худшему случаю; принудительное убийство может потерять ожидающее состояние.

Считайте остановку корректной, только если присутствует Server stopped! и процесс завершился успешно. Сохраните логи и исследуйте timeout или crash до замены их свидетельств.

Выполните откат

Откат — новое управляемое развёртывание, а не копирование файлов поверх работающего процесса:

Остановите rollout и уберите затронутый instance из трафика.
Сохраните логи, health/crash evidence, identity релиза и конфигурации и необходимое состояние базы данных.
Корректно остановите процесс и проверьте exit.
Определите, совместим ли откат binary/config с данными. Если нет, выполните проверенную процедуру backup/restore или принадлежащий игре forward fix до запуска старого сервера.
Активируйте предыдущий артефакт с соответствующими config и updater payloads и повторите readiness probes.
Возвращайте трафик постепенно, наблюдайте и запишите инцидент и итоговое состояние релиза.

Восстанавливайте данные только по политике согласованности и допустимой потери данных проекта. Никогда не смешивайте бинарные файлы, запечённые ресурсы, config, клиентские пакеты, нативные updater payloads или данные из несовместимых release units.

Маршрутизация отказов

Наблюдение	Действие
Процесс завершается до readiness или пишет `Server startup failed, shutting down`	Не открывайте трафик; исследуйте первое startup exception, config, ресурсы, базу данных и права
Health-файл остаётся `Starting...`	Запуск не завершён; используйте логи и состояние процесса, а не файл как ready signal
Health-файл устарел после readiness	Проверьте права, scheduling и диагностику writer; сохраняйте состояние неизвестным до успешной функциональной проверки
Команда запуска daemon завершилась с нулём, но готового дочернего процесса нет	Исследуйте лог и процесс child; выход parent ожидаем и не доказывает запуск
Корректная остановка превысила timeout supervisor	Сохраните evidence, исследуйте последний маркер `Shutdown stage:`, доступность базы данных и игровой `OnFinish`; не считайте `ShutdownGraceMs` общей границей
Новый сервер готов, но клиенты не могут обновиться или подключиться	Приостановите rollout и согласуйте сеть, compatibility, поколение updater/runtime ABI и упакованные client payloads
Бинарный файл отката не читает текущее долговечное состояние	Не запускайте его с production data; следуйте принадлежащему игре решению о migration/restore

Проверьте runbook

Автоматизируйте установку точного пакета, отклонение преждевременной readiness, переход логов и health в ready, реальный handshake/login, корректную остановку, Server stopped! и успешный exit. Внедряйте ошибки запуска и недоступности базы данных.

Запустите Examples/PackagingMatrix вместе с проектными infrastructure/persistence lanes. Репетируйте откат с неизменяемыми артефактами и синтетическими данными.

Проверенные пути исходников

Source/Applications/Server{App,HeadlessApp,ServiceApp,DaemonApp}.cpp, Source/Frontend/Application{Init,Headless}.cpp, Source/Essentials/Platform.cpp, Source/Server/Server.cpp, Source/Common/Settings.inc, BuildTools/cmake/stages/Applications.cmake, BuildTools/package.py, BuildTools/tests/test_docs_release_operations.py и Examples/PackagingMatrix.