Управление игровыми сборками

Этот раздел описывает полный рабочий цикл игровой сборки: от каталога с готовым клиентом до обновления, которое увидит лаунчер. Он рассчитан на текущую схему Wraithbound с wraithbound-publisher, launcher-server, S3 и CDN.

Главное за минуту

У каждой сборки есть постоянный buildId, а у каждого её состояния — отдельный неизменяемый releaseId. Публикация состоит из двух независимых действий:

Publisher загружает новый неизменяемый релиз в S3 и устанавливает его подписанный manifest в launcher-server.
Администратор проверяет результат и нажимает «Опубликовать». Только после этого launcher-server переключает активный релиз.

Не меняйте файлы уже опубликованного releaseId. Любое изменение клиента, профиля, Java или assets выпускается с новым releaseId и увеличенным generation.

Термины

Термин	Что означает
`serverId` / `buildId`	Постоянный числовой ID сервера на сайте. Например, `4`
`releaseId`	Уникальное имя конкретной версии сборки, например `2026.09.09.1`
`generation`	Монотонно растущий номер релиза: `1`, `2`, `3` и далее
`profile.json`	Правила запуска, classpath, Java, управляемые каталоги и адрес игрового сервера
manifest	Перечень файлов с размером, SHA-256, категорией и политикой обновления
signed envelope	Protobuf manifest с Ed25519-подписью
installed release	Релиз загружен и известен launcher-server, но ещё не обязательно активен
active release	Релиз, который сейчас получают пользовательские лаунчеры

Где лежат исходники

На production-машине launcher-server используется следующая раскладка:

/var/lib/wraithbound-launcher/builds/
├── clients/
│   └── Architechnica/              # готовый каталог игрового клиента
├── profiles/
│   └── 4/
│       └── profile.json            # профиль buildId 4
├── assets/
│   ├── indexes/
│   └── objects/
└── runtimes/
    └── java-17-win32-x64/

/etc/wraithbound/builds/
└── 4.toml                          # серверная конфигурация publisher

Имя TOML-файла всегда равно buildId. Запрос из админки содержит только этот ID; launcher-server сам находит разрешённый /etc/wraithbound/builds/4.toml. Передать произвольный путь из браузера невозможно. В репозитории есть готовый пример:

deploy/systemd/builds/architechnica.toml.example

Для локальной публикации с Windows используется аналогичная конфигурация:

apps/launcher/deployment/launcher/publisher.toml

Подготовка новой сборки

1. Создайте сервер на сайте

Создайте запись игрового сервера в административной панели сайта и запомните её числовой ID. Этот ID используется во всей цепочке как serverId и buildId. Например, если сервер получил ID 4, должны совпасть:

profile:       /var/lib/wraithbound-launcher/builds/profiles/4/profile.json
publisher:     build.server_id = 4
worker config: /etc/wraithbound/builds/4.toml
admin buildId: 4

Не используйте название сервера вместо ID. Название можно менять, числовой ID сборки должен оставаться стабильным.

2. Подготовьте чистый клиент

Скопируйте в clients/<Название> только то, что должен получить пользователь:

Minecraft JAR и библиотеки;
Forge/loader и необходимые bootstrap-библиотеки;
моды;
natives для поддерживаемой платформы;
начальные конфигурации, если ими должен управлять лаунчер;
ресурсы сборки.

Перед публикацией удалите временные данные: logs, crash-reports, saves, скриншоты, кэши, дампы и локальные настройки разработчика.

Каталог assets хранится отдельно и не должен дублироваться внутри каждой сборки. Java также хранится отдельным runtime и повторно используется разными сборками.

3. Создайте `profile.json`

Минимальный рабочий профиль Architechnica выглядит так:

{
  "title": "Architechnica",
  "uuid": "cab71d2f-15e6-4c09-8f35-2ecb5f93a5d8",
  "version": "1.7.10",
  "dir": "Architechnica",
  "assetIndex": "1.7.10",
  "update": [],
  "updateExclusions": ["options.txt", "optionsof.txt"],
  "updateVerify": [
    "config",
    "libraries",
    "minecraft.jar",
    "mods",
    "natives",
    "resourcepacks",
    "resources"
  ],
  "jvmArgs": [
    "-Dfile.encoding=UTF-8",
    "-XX:+DisableAttachMechanism"
  ],
  "classPath": ["libraries", "minecraft.jar"],
  "clientArgs": ["--tweakClass", "cpw.mods.fml.common.launcher.FMLTweaker"],
  "servers": [
    {
      "serverAddress": "play.wraithbound.com",
      "serverPort": 25565,
      "isDefault": true
    }
  ],
  "recommendJavaVersion": 17,
  "minJavaVersion": 17,
  "maxJavaVersion": 21,
  "settings": {
    "ram": 4096,
    "autoEnter": false,
    "fullScreen": false
  },
  "mainClass": "com.gtnewhorizons.retrofuturabootstrap.MainStartOnFirstThread"
}

JSON не поддерживает комментарии. Для нового профиля создайте новый UUID и не переиспользуйте UUID другой сборки.

Поля профиля

Поле	Как использовать
`title`	Название клиента в лаунчере и операциях
`uuid`	Постоянный UUID профиля
`version`	Версия Minecraft
`dir`	Локальная папка клиента внутри `storage/common`
`assetIndex`	Имя файла в `assets/indexes`, без `.json`
`update`	Пути, которые восстанавливаются при каждом обновлении
`updateVerify`	Управляемые пути: проверка размера/SHA-256 и восстановление
`updateExclusions`	Пользовательские пути, которые нельзя проверять, заменять или удалять
`jvmArgs`	Постоянные аргументы JVM
`classPath`	JAR-файлы или каталоги с JAR-файлами
`clientArgs`	Дополнительные аргументы Minecraft/Forge
`servers`	Адрес входа в Minecraft; один элемент отмечается `isDefault`
`recommendJavaVersion`	Runtime, который подготовит лаунчер
`minJavaVersion`, `maxJavaVersion`	Допустимый диапазон Java
`settings.ram`	RAM по умолчанию в МБ; пользовательская настройка сервера может её переопределить
`mainClass`	Главный Java-класс конкретной сборки

Селекторы в update, updateVerify и updateExclusions — не glob-шаблоны. mods означает каталог и всё его содержимое. Нельзя использовать .., обратные слеши, абсолютные пути или *.

Как выбрать файловую политику

Добавляйте в updateVerify то, что обязано точно совпадать с релизом: библиотеки, JAR, моды и natives.
Добавляйте в update файлы, которые могут меняться во время игры, но должны восстанавливаться перед следующим запуском.
Добавляйте в updateExclusions только пользовательские настройки, которые действительно нужно сохранить.
Если весь config исключён, обновление не сможет доставлять изменения конфигов. Если весь config проверяется, пользовательские изменения будут восстановлены до опубликованного состояния.

Лаунчер дополнительно сохраняет logs, crash-reports, screenshots, saves, resourcepacks, shaderpacks и options.txt по умолчанию.

4. Подготовьте assets

Структура должна соответствовать обычным Minecraft assets:

assets/
├── indexes/1.7.10.json
└── objects/ab/abcdef...             # object key из index

Если в TOML указано download_from_mojang = true, publisher скачает отсутствующий официальный index и его objects. Уже проверенные объекты будут переиспользованы. Кастомные ресурсы, отсутствующие в официальном asset index, держите в каталоге клиента или добавляйте в собственный корректный index; случайные файлы из общего каталога assets в manifest не попадут.

5. Подготовьте Java runtime

Runtime должен быть распакованным каталогом, а не ZIP-файлом:

runtimes/java-17-win32-x64/
└── bin/
    ├── java.exe
    └── javaw.exe

Publisher умеет скачать ZIP по HTTPS, проверить его SHA-256 и распаковать при отсутствии runtime. Значение sha256 берётся у конкретного дистрибутива Java; не копируйте hash от другой версии архива.

6. Создайте publisher TOML

schema_version = 1

[storage]
region = "ru-1"
endpoint = "https://s3.twcstorage.ru"
prefix = "launcher"
force_path_style = true
concurrency = 8

[build]
server_id = 4
source = "/var/lib/wraithbound-launcher/builds/clients/Architechnica"
profile = "/var/lib/wraithbound-launcher/builds/profiles/4/profile.json"
excludes = [
  "assets/**",
  "logs/**",
  "crash-reports/**",
  "screenshots/**",
  "options.txt",
  "optionsof.txt",
  "natives/linux/**",
  "natives/macosx/**"
]
optionals = []

[release]
id = "2026.09.09.1"
generation = 1
loader = "forge"

[[release.mirrors]]
id = "wraithbound-cdn"
base_url = "https://cdn.wraithbound.com/launcher"
priority = 1

[signing]

[control_plane]
endpoint = "https://private-launcher-admin.example"

[assets]
source = "/var/lib/wraithbound-launcher/builds/assets"
download_from_mojang = true

[runtime]
id = "java-17-win32-x64"
source = "/var/lib/wraithbound-launcher/builds/runtimes/java-17-win32-x64"
version = "17"
download_url = "https://example.org/OpenJDK17U-jre_x64_windows_hotspot.zip"
sha256 = "64-символьный-sha256-архива"
strip_components = 1
excludes = []
executable_path = "bin/javaw.exe"

Bucket можно задать через storage.bucket, WB_PUBLISHER_S3_BUCKET или WRAITHBOUND_S3_BUCKET. В production предпочтительно передавать bucket и все секреты через окружение/deployment, а не копировать их в разные TOML-файлы.

Не записывайте в TOML и Git S3 secret key, admin token или приватный Ed25519 ключ. CDN URL, S3 endpoint, region, prefix и bucket name секретами не являются.

7. Выставьте права на сервере

sudo chown -R wraithbound:wraithbound /var/lib/wraithbound-launcher/builds
sudo chown root:wraithbound /etc/wraithbound/builds/4.toml
sudo chmod 0640 /etc/wraithbound/builds/4.toml

Процесс wraithbound должен читать исходники, профиль, assets, runtime и TOML. Запись нужна в каталоги, куда publisher докачивает assets/runtime, и во временный рабочий каталог.

Предварительная проверка

Соберите publisher один раз:

cd E:\Wraithbound\wraithbound-launcher-platform
cargo build --locked --release -p wraithbound-manifest-builder --bin wraithbound-publisher

Проверьте конфигурацию без обращения к S3:

target\release\wraithbound-publisher.exe check `
  --config apps\launcher\deployment\launcher\publisher.toml

Затем постройте полный план без загрузки:

target\release\wraithbound-publisher.exe publish `
  --config apps\launcher\deployment\launcher\publisher.toml `
  --dry-run

--dry-run должен вывести профиль, количество объектов и общий размер. Для диагностики точных S3 keys можно временно добавить --list-objects, но такой вывод содержит локальные пути и получается очень большим.

Что делает кнопка «Подготовить»

На странице /admin/launcher/builds кнопка «Подготовить» ставит buildId в ограниченную очередь launcher-server. Worker выполняет:

wraithbound-publisher --json prepare --config /etc/wraithbound/builds/<buildId>.toml

Эта операция:

проверяет TOML, профиль и локальные каталоги;
получает недостающие Minecraft assets;
получает и проверяет Java runtime;
показывает этапы в разделе «Операции».

Она не загружает релиз в S3, не устанавливает signed envelope и не меняет активный релиз. Поэтому после «Подготовить» пользователи ещё ничего не увидят.

Публикация первого релиза

1. Подготовьте секреты в текущей консоли

$env:AWS_ACCESS_KEY_ID = '<access-key>'
$env:AWS_SECRET_ACCESS_KEY = '<secret-key>'
$env:WB_PUBLISHER_SIGNING_KEY = 'C:\secure\wraithbound-release.key'
$env:WB_LAUNCHER_ADMIN_TOKEN_FILE = 'C:\secure\launcher-admin-token'
$env:WB_LAUNCHER_CONTROL_PLANE_URL = 'https://private-launcher-admin.example'

Admin endpoint должен быть доступен только publisher/CI через VPN, приватную сеть или SSH tunnel. Публичный launcher API не должен проксировать admin RPC.

2. Проверьте релиз

target\release\wraithbound-publisher.exe check --config publisher.toml

target\release\wraithbound-publisher.exe publish `
  --config publisher.toml `
  --dry-run

3. Загрузите и установите релиз

target\release\wraithbound-publisher.exe publish --config publisher.toml

Команда выполняет порядок metadata-last:

подготавливает assets и runtime;
строит manifests и считает SHA-256;
загружает игровые файлы, assets и runtime;
загружает profile.json и manifests;
подписывает protobuf envelope;
устанавливает envelope в launcher-server через InstallBuildRelease.

Если S3-загрузка завершилась ошибкой, control plane не переключается. Если объект с тем же key уже существует, publisher сверяет metadata sha256 и переиспользует только точное совпадение.

4. Активируйте релиз

Откройте /admin/launcher/builds, найдите сборку, нажмите «Опубликовать» и выберите установленный релиз. Launcher-server ещё раз проверит подпись и атомарно переключит active release. После активации проверьте один реальный лаунчер: получение профиля, загрузку с CDN, scanner, Java, Guardian и запуск Minecraft.

Как выпустить обновление сборки

Для каждого обновления используйте один и тот же безопасный порядок.

Сделайте резервную копию или Git-снимок исходного каталога сборки.
Добавьте/замените моды, конфиги, библиотеки и другие файлы.
При необходимости измените profile.json.
Задайте новый release.id.
Увеличьте release.generation относительно всех предыдущих релизов.
Выполните check.
Выполните publish --dry-run и проверьте размер/число объектов.
Выполните настоящий publish.
Убедитесь, что операция установки завершилась и релиз появился в админке.
Активируйте его кнопкой «Опубликовать».
Проверьте обновление на тестовом лаунчере.

Пример без редактирования TOML — release ID и generation передаются командой:

target\release\wraithbound-publisher.exe publish `
  --config publisher.toml `
  --release-id 2026.09.09.2 `
  --generation 2 `
  --dry-run

target\release\wraithbound-publisher.exe publish `
  --config publisher.toml `
  --release-id 2026.09.09.2 `
  --generation 2

Хорошая схема releaseId: YYYY.MM.DD.N, где N — номер выпуска за день. generation при этом остаётся отдельным возрастающим числом для этой сборки.

Что произойдёт у пользователя

После активации launcher-server возвращает новый signed release. Лаунчер:

сравнивает локальные файлы с новым manifest;
скачивает только отсутствующие и изменённые объекты;
сохраняет исключённые пользовательские данные;
повторно проверяет клиент и Java;
формирует актуальную Guardian policy;
запускает Minecraft.

Неизменившиеся S3/CDN-объекты не скачиваются повторно, даже если они входят в новый release manifest.

Откат

Откат не требует повторной загрузки старой сборки:

Откройте /admin/launcher/builds.
Нажмите «Откатить» у нужной сборки.
Выберите ранее установленный релиз.
Подтвердите действие.
Проверьте активный release ID и запуск тестового клиента.

Launcher-server переключает active pointer на ранее проверенный signed envelope. Старые файлы должны оставаться в S3, поэтому publisher намеренно не выполняет remote prune.

Не удаляйте старый release-каталог из S3 сразу после обновления. Иначе откат переключит manifest, но CDN не сможет отдать соответствующие файлы.

Блокировка сборки и обслуживание

Блокировка сборки применяется к одному buildId. Используйте её, когда конкретный клиент повреждён или запуск нужно временно остановить. В админке обязательно укажите понятную оператору причину; там же блокировка снимается. Режим обслуживания применяется шире:

install-disabled — запрещает подготовку/установку затронутых сборок;
launch-disabled — запрещает запуск Minecraft;
full — полностью блокирует пользовательский сценарий и показывает обязательное окно обслуживания.

Перед включением обслуживания проверьте, какие buildId затронуты. После работ отключите режим отдельным действием в том же разделе админки.

S3 и CDN

В текущей production-схеме разделены два namespace:

launcher/control-plane/             # каталог launcher-server, операции, manifests
launcher/                           # versioned client/assets/runtime objects publisher

Публичное зеркало для лаунчера:

https://cdn.wraithbound.com/launcher

Лаунчер получает только подписанные HTTPS URL. S3 access key, secret key, admin token и приватный ключ подписи не передаются в Electron renderer и не включаются в launcher.config.json. Для publisher выдайте отдельную S3 identity с доступом только на content prefix. Launcher-server использует свою identity для control-plane prefix. Не запускайте два пишущих launcher-server на одном prefix: распределённой блокировки между репликами пока нет.

Публикация через GitHub Actions

Workflow находится в:

.github/workflows/publish-launcher-build.yml

Он запускается вручную и принимает:

config_path — отслеживаемый Git TOML для сборки;
release_id — новый неизменяемый ID;
generation — новый номер поколения;
dry_run — только проверить план или выполнить публикацию.

Для self-hosted Windows runner настройте secrets:

WB_PUBLISHER_S3_ACCESS_KEY_ID
WB_PUBLISHER_S3_SECRET_ACCESS_KEY
WB_PUBLISHER_S3_SESSION_TOKEN       # только если используется
WB_PUBLISHER_SIGNING_KEY
WB_LAUNCHER_ADMIN_TOKEN

И repository variable:

WB_LAUNCHER_CONTROL_PLANE_URL

Сначала запускайте workflow с dry_run = true. После проверки повторите с теми же release_id/generation и dry_run = false. Активация всё равно остаётся ручным действием в админке.

Проверка после публикации

Минимальный production-чеклист:

launcher-server имеет состояние active (running);
/health/live и /health/ready возвращают успех;
в журнале launcher-server нет S3/signature ошибок;
новый релиз отображается в админке как установленный;
active release ID изменился только после ручной активации;
signed envelope читается публичным launcher API;
CDN отдаёт один файл релиза без авторизации и без redirect на S3 console;
чистая установка клиента завершается;
повторный запуск не скачивает неизменившиеся файлы;
Minecraft стартует нужным mainClass и подключается к нужному серверу;
откат на предыдущий релиз работает.

Команды для launcher-server:

sudo systemctl status wraithbound-launcher-server --no-pager
curl --fail http://127.0.0.1:8081/health/live
curl --fail http://127.0.0.1:8081/health/ready
sudo journalctl -u wraithbound-launcher-server -n 200 --no-pager

Для локальной проверки контрактов без production S3:

.\scripts\smoke.ps1

Частые ошибки

Ошибка	Что проверить
Сборка не появляется в админке	Publisher должен успешно выполнить `InstallBuildRelease`; одна кнопка «Подготовить» релиз не создаёт
`build config not found`	Есть ли `/etc/wraithbound/builds/<buildId>.toml`, совпадает ли имя с ID
`AccessDenied` / S3 error	Bucket, region, endpoint, prefix, права identity и доступность credential-файла
`releaseId already exists`	Создайте новый ID; существующий релиз неизменяем
Ошибка generation	Укажите число больше предыдущего и не используйте его повторно
Signature/trust error	Publisher должен подписывать доверенным active ключом; private seed и public registry должны соответствовать
CDN возвращает 404	Проверьте `release.mirrors.base_url`, content prefix и наличие exact object key в S3
Обновлённый файл не скачался	Он мог попасть в `build.excludes` или `profile.updateExclusions`
Пользовательский конфиг перезаписан	Уберите его из управляемой области или точечно добавьте в `updateExclusions`
Новый релиз установлен, но лаунчер видит старый	Релиз ещё не активирован либо CDN/API кэширует старый ответ
Prepare долго висит	Смотрите «Операции» и journal; проверьте сеть до Mojang/Java URL и timeout worker
Minecraft не запускается после загрузки	Проверьте `mainClass`, classpath, Java range, natives и игровые логи

Чего нельзя делать

Не публикуйте поверх существующего releaseId.
Не уменьшайте и не переиспользуйте generation.
Не активируйте релиз до успешной загрузки всех объектов.
Не удаляйте прошлый релиз до истечения периода безопасного отката.
Не храните credentials или signing seed в Git, TOML сборки и Electron config.
Не указывайте S3 origin вместо CDN первым production mirror без осознанной причины.
Не добавляйте весь изменяемый пользовательский каталог в updateVerify.
Не считайте кнопку «Подготовить» публикацией.

Платформа

Эксплуатация

Управление игровыми сборками

Главное за минуту

Термины

Где лежат исходники

Подготовка новой сборки

1. Создайте сервер на сайте

2. Подготовьте чистый клиент

3. Создайте `profile.json`

Поля профиля

Как выбрать файловую политику

4. Подготовьте assets

5. Подготовьте Java runtime

6. Создайте publisher TOML

7. Выставьте права на сервере

Предварительная проверка

Что делает кнопка «Подготовить»

Публикация первого релиза

1. Подготовьте секреты в текущей консоли

2. Проверьте релиз

3. Загрузите и установите релиз

4. Активируйте релиз

Как выпустить обновление сборки

Что произойдёт у пользователя

Откат

Блокировка сборки и обслуживание

S3 и CDN

Публикация через GitHub Actions

Проверка после публикации

Частые ошибки

Чего нельзя делать

Рекомендуемый рабочий регламент

​Главное за минуту

​Термины

​Где лежат исходники

​Подготовка новой сборки

​1. Создайте сервер на сайте

​2. Подготовьте чистый клиент

​3. Создайте profile.json

​Поля профиля

​Как выбрать файловую политику

​4. Подготовьте assets

​5. Подготовьте Java runtime

​6. Создайте publisher TOML

​7. Выставьте права на сервере

​Предварительная проверка

​Что делает кнопка «Подготовить»

​Публикация первого релиза

​1. Подготовьте секреты в текущей консоли

​2. Проверьте релиз

​3. Загрузите и установите релиз

​4. Активируйте релиз

​Как выпустить обновление сборки

​Что произойдёт у пользователя

​Откат

​Блокировка сборки и обслуживание

​S3 и CDN

​Публикация через GitHub Actions

​Проверка после публикации

​Частые ошибки

​Чего нельзя делать

​Рекомендуемый рабочий регламент

Главное за минуту

Термины

Где лежат исходники

Подготовка новой сборки

1. Создайте сервер на сайте

2. Подготовьте чистый клиент

3. Создайте `profile.json`

Поля профиля

Как выбрать файловую политику

4. Подготовьте assets

5. Подготовьте Java runtime

6. Создайте publisher TOML

7. Выставьте права на сервере

Предварительная проверка

Что делает кнопка «Подготовить»

Публикация первого релиза

1. Подготовьте секреты в текущей консоли

2. Проверьте релиз

3. Загрузите и установите релиз

4. Активируйте релиз

Как выпустить обновление сборки

Что произойдёт у пользователя

Откат

Блокировка сборки и обслуживание

S3 и CDN

Публикация через GitHub Actions

Проверка после публикации

Частые ошибки

Чего нельзя делать

Рекомендуемый рабочий регламент