Update Builder CLI: автоматическая сборка и публикация патчей

Консольный режим UpNova Update Builder: инкрементальная сборка патчей, UpdateInfo.xml, выбор уровня сжатия и автоматическая выгрузка на S3, Cloudflare R2 или SFTP одной командой.

Автоматизируем создание патчей, отслеживание изменений и доставку обновлений на сервер — без ручной сборки каждого релиза.

При регулярном выпуске обновлений одна из самых трудоёмких задач — подготовка файлов для распространения. Необходимо определить, что изменилось, создать архивы, обновить информацию о версии и загрузить результат на сервер.

UpNova Update Builder позволяет автоматизировать этот процесс. Помимо привычного графического интерфейса, инструмент поддерживает консольный режим (CLI), благодаря которому сборку и публикацию обновлений можно запускать одной командой.

Это особенно удобно для игровых проектов, автоматизированных сборок, CI-пайплайнов и команд, которые регулярно выпускают новые версии продукта.

UpNova Update Builder — окно программы для сборки и публикации обновлений — *UpNova Update Builder: инструмент для сборки и публикации обновлений.*

1. Что умеет консольный режим UpdateBuilder

CLI выполняет полный цикл подготовки обновления: от анализа исходных файлов до выгрузки готового патча на сервер.

Основные возможности:

Инкрементальная сборка. Программа определяет новые, изменённые и удалённые файлы, чтобы не упаковывать весь проект заново.
Автоматическое версионирование. При сборке создаётся UpdateInfo.xml с информацией о следующей версии патча.
Настраиваемое ZIP-сжатие. Можно выбрать подходящий баланс между скоростью сборки и размером архивов.
Автоматическая публикация. Поддерживается выгрузка на S3-совместимые хранилища и SFTP.
Гибкое управление обновлением. Можно определить, какие файлы участвуют в быстром обновлении и для каких требуется проверка хеша.
Поддержка автоматизации. CLI можно запускать из .bat, PowerShell, Планировщика задач Windows и CI.
Логирование. Результаты операций сохраняются в файлы журналов, а коды завершения позволяют автоматически выявлять ошибки.

Для работы в консольном режиме не требуется отдельный набор утилит: используется тот же UpdateBuilder.exe, что и для графического интерфейса.

2. Первоначальная настройка

UpdateBuilder работает в Windows и распространяется в виде одного исполняемого файла — UpdateBuilder.exe. Дополнительные DLL рядом с ним не требуются.

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

Если планируется автоматическая публикация, необходимо один раз настроить подключение к хранилищу.

Настройка хранилища

Запустите UpdateBuilder.exe в обычном графическом режиме.
Откройте настройки, нажав на значок шестерёнки в верхней части окна.
Выберите тип хранилища: S3-совместимое или SFTP.
Заполните параметры подключения.
Сохраните настройки.

Для S3-совместимого хранилища указываются endpoint, бакет, регион, Access Key ID и при необходимости префикс удалённого каталога.

Поддерживаются в том числе AWS S3, Cloudflare R2 и MinIO. Для Cloudflare R2 в качестве региона используется auto.

Настройки сохраняются в файле UpdateBuilder.config.xml рядом с программой и автоматически используются при запуске CLI.

Настройка удалённого хранилища S3 или SFTP в UpdateBuilder — *Настройка удалённого хранилища выполняется один раз через графический интерфейс.*

Важно: Secret Key или SFTP-пароль не записывается в конфигурационный файл. Секрет необходимо передать отдельно при публикации.

3. Первая сборка патча через CLI

Для запуска консольного режима используются два обязательных параметра:

--patch — папка с исходными файлами обновления;
--out — папка, в которой будет создан результат сборки.

Пример команды:

UpdateBuilder.exe --console --patch D:patch --out D:out

После запуска UpdateBuilder автоматически выполнит несколько операций.

Шаг 1. Анализ файлов. Программа просканирует содержимое D:patch и вычислит контрольные суммы CRC32.

Шаг 2. Поиск изменений. Если в директории результата уже присутствует UpdateInfo.xml предыдущей сборки, UpdateBuilder определит новые, изменённые и удалённые файлы.

Шаг 3. Создание архивов. Новые и изменённые файлы будут упакованы — каждый в отдельный ZIP-архив.

Шаг 4. Обновление версии. Будет создан UpdateInfo.xml с информацией о следующей версии патча.

В результате директория D:out будет содержать подготовленные архивы и метаданные обновления.

Результат сборки UpdateBuilder: ZIP-архивы и UpdateInfo.xml — *UpdateBuilder формирует готовую структуру файлов для распространения обновления.*

4. Управление уровнем сжатия

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

UpdateBuilder позволяет настраивать уровень ZIP-сжатия через параметр --level.

Пример:

UpdateBuilder.exe --console --patch D:patch --out D:out --level 6

Уровень	Особенности	Рекомендуемый сценарий
`1–3`	Быстрое сжатие	Частые тестовые сборки
`6`	Баланс скорости и размера	Регулярные обновления
`9`	Максимальное сжатие, медленнее	Приоритет минимального размера

Рекомендуемое значение — 6. Оно обеспечивает практичный баланс между скоростью создания патчей и размером архивов.

Если --level не указан, UpdateBuilder использует значение из UpdateBuilder.config.xml. По умолчанию это уровень 9.

5. Автоматическая выгрузка обновлений

После создания патча его можно автоматически опубликовать в настроенном хранилище (через UI).

Для этого достаточно добавить параметр --upload:

UpdateBuilder.exe --console --patch D:patch --out D:out --upload

После сборки UpdateBuilder сравнит содержимое локальной папки результата с удалённым хранилищем.

При синхронизации программа:

Загружает новые файлы.
Обновляет изменённые файлы.
Удаляет лишние файлы на сервере.
В последнюю очередь загружает UpdateInfo.xml.

Последовательность публикации важна: файл с метаданными новой версии отправляется после остальных файлов обновления.

Таким образом, сборка и выгрузка объединяются в одну операцию.

Обратите внимание: функциональность автоматической загрузки патчей в удалённое хранилище на данный момент является экспериментальной.

При использовании этой возможности рекомендуем:

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

Безопасная передача ключей доступа

Для публикации необходим Secret Key или пароль SFTP. При этом UpdateBuilder не сохраняет его в конфигурационном файле или других файлах на диске.

Предусмотрены два способа передачи.

Вариант 1. Переменная окружения

Командная строка Windows:

set UPDATEBUILDER_SECRET_KEY=ваш-пароль
UpdateBuilder.exe --console --patch D:patch --out D:out --upload

PowerShell:

$env:UPDATEBUILDER_SECRET_KEY = "ваш-пароль"
.UpdateBuilder.exe --console --patch D:patch --out D:out --upload

Этот способ удобен для автоматизированных сценариев. В CI секрет рекомендуется получать из защищённого хранилища переменных, а не записывать непосредственно в скрипт.

Вариант 2. Интерактивный ввод

Если переменная окружения не задана, перед публикацией UpdateBuilder предложит ввести секрет вручную:

Введите Secret Key / пароль (не сохраняется): ********

Введённое значение используется в памяти процесса. Если оставить поле пустым, публикация отменится.

6. Гибкая настройка файлов обновления

Для управления поведением обновлений UpdateBuilder поддерживает два дополнительных параметра:

--quicklist — список файлов и каталогов для быстрого обновления;
--checkhashlist — список файлов и каталогов, для которых включается проверка хеша после обновления.

Оба параметра принимают путь к обычному текстовому файлу.

Пример списка

Создадим quicklist.txt:

# Основные файлы приложения
bin/game.exe
bin/system
configs

# Дополнительные файлы
MyPatch/readme.txt

Поддерживаются отдельные файлы и целые каталоги. Если указана директория, правило применяется ко всему её содержимому, включая вложенные папки.

Дополнительно:

Строки с # считаются комментариями.
Пустые строки игнорируются.
Допускаются разделители / и .
Регистр символов не имеет значения.
Некорректные или отсутствующие пути выводятся в лог.

Важно: при использовании списка соответствующий флаг включается только для перечисленных файлов. Для остальных он выключается.

Пример запуска:

UpdateBuilder.exe --console --patch D:patch --out D:out --quicklist D:listsquicklist.txt --checkhashlist D:listscheckhashlist.txt

Если соответствующий параметр не указан, используются флаги из предыдущего патча, а для новых файлов они включены.

7. Использование UpdateBuilder в автоматизации

Одно из главных преимуществ CLI — возможность встроить сборку патчей в существующие процессы выпуска релизов.

Например, после подготовки файлов можно автоматически запустить UpdateBuilder из BAT-скрипта или CI.

Пример BAT-скрипта

@echo off

UpdateBuilder.exe --console --patch D:patch --out D:out --level 6 --upload

if errorlevel 1 (
    echo Ошибка сборки или публикации
    exit /b 1
)

echo Обновление успешно подготовлено

Такой скрипт можно запускать вручную или использовать как этап автоматизированного процесса.

UpdateBuilder возвращает стандартные коды завершения:

Код	Значение
`0`	Операция завершилась успешно
`1`	Во время сборки или публикации произошла ошибка

Благодаря этому CI может определить, завершилась ли публикация успешно, и остановить процесс при возникновении проблемы.

Отслеживание прогресса

Во время сборки UpdateBuilder отображает текущий этап, процент выполнения, количество обработанных файлов и другую информацию.

Например:

== build ==
[████████████████████░░░░]  80% (4/5) data/f4.txt
[████████████████████████] 100% (5/5) data/f5.txt
build: 5/5 (2.1KB) за 00:00:00
Версия патча: 5

Полные журналы операций сохраняются в папку Logs рядом с исполняемым файлом — отдельный лог для каждого запуска.

8. Параметры командной строки

Для удобства все возможности CLI собраны в одной таблице.

Общий синтаксис:

UpdateBuilder.exe --console --patch <папка> --out <папка> [--upload] [--quicklist <файл>] [--checkhashlist <файл>] [--level <1-9>]

Параметр	Назначение
`--console`	Запуск в консольном режиме
`--patch`	Путь к исходным файлам обновления
`--out`	Каталог для готовых архивов и метаданных
`--upload`	Автоматическая публикация после сборки
`--quicklist`	Список файлов для быстрого обновления
`--checkhashlist`	Список файлов с проверкой хеша
`--level`	Уровень ZIP-сжатия от 1 до 9
`--help`, `-h`	Вывод справки

Для просмотра доступных параметров используйте:

UpdateBuilder.exe --help

9. Возможные ошибки и их решение

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

Ниже перечислены распространённые сообщения UpdateBuilder.

Сообщение	Что проверить
`Required arguments`	Указаны ли `--patch` и `--out`
`Patch folder not found`	Существует ли исходная директория
`Patch folder and output folder must not match or be nested`	Не совпадают ли папки и не вложены ли друг в друга
`Выгрузка не настроена`	Заполнены ли параметры хранилища
`Секрет не задан`	Передан ли пароль или Secret Key
`Не найдено в патче`	Корректны ли пути в текстовых списках
`Сборка завершена с ошибками: N`	Какие файлы не удалось упаковать

Для подробной диагностики рекомендуется изучать соответствующий файл в папке Logs.

10. Полный пример автоматизированной сборки

Рассмотрим сценарий, при котором необходимо подготовить обновление игрового клиента, использовать стандартный уровень сжатия, применить списки флагов и опубликовать результат.

Все действия выполняются одной командой:

UpdateBuilder.exe --console ^
  --patch D:GameRelease ^
  --out D:GameUpdates ^
  --level 6 ^
  --quicklist D:GameListsquicklist.txt ^
  --checkhashlist D:GameListscheckhashlist.txt ^
  --upload

При наличии настроенного подключения к хранилищу и переданного секрета UpdateBuilder:

Проверит текущие файлы игрового клиента.
Определит изменения относительно предыдущей сборки.
Упакует новые и изменённые файлы.
Применит заданные правила обновления.
Сформирует метаданные следующей версии.
Синхронизирует результат с удалённым хранилищем.
Сохранит информацию о выполненных операциях в лог.

Такой подход позволяет включить создание патчей в автоматизированный выпуск обновлений без ручного выполнения каждого этапа.

Оптимизации и улучшения UpdateBuilder

Помимо добавления консольного режима, в UpdateBuilder был внесён ряд оптимизаций и улучшений, направленных на повышение удобства работы и эффективности подготовки обновлений.

Основные изменения:

Улучшение процесса сборки патчей. Инкрементальная обработка позволяет работать только с новыми и изменёнными файлами, избегая повторной упаковки неизменённого содержимого.
Гибкая настройка сжатия. Добавлена возможность выбирать уровень ZIP-сжатия в зависимости от задач проекта — от быстрых тестовых сборок до подготовки релизов.
Оптимизация публикации обновлений. При синхронизации с удалённым хранилищем передаются только новые и изменённые файлы, а не весь набор данных.
Улучшение диагностики. Подробные логи, отображение прогресса и коды завершения позволяют проще отслеживать выполнение операций и находить ошибки.
Повышение удобства автоматизации. Сборку и публикацию теперь можно объединить в один процесс, интегрировав UpdateBuilder в существующие скрипты и CI-пайплайны.

В результате UpdateBuilder стал более гибким инструментом для регулярного выпуска обновлений, а подготовка и публикация патчей требует меньше ручных действий.

Заключение

Консольный режим расширяет возможности UpNova UpdateBuilder, позволяя использовать инструмент не только для ручной подготовки патчей, но и как часть автоматизированной инфраструктуры выпуска обновлений.

Вместо последовательного выполнения операций разработчик получает единый процесс: анализ изменённых файлов, создание архивов, управление параметрами патча и публикация результата.

Ключевое преимущество — возможность запускать полноценную сборку и доставку обновления одной командой, сохраняя при этом гибкость настройки и контроль над процессом.

Это позволяет сократить количество повторяющихся ручных действий и упростить регулярный выпуск новых версий.

UpNova UpdateBuilder — часть экосистемы UpNova.

Update Builder: автоматическая сборка и публикация обновлений через CLI