Обновления

ProAnimaStudio объявляет каждый стабильный релиз Arkvory через хаб. Ваш сервер спрашивает хаб, какую версию ему можно установить, скачивает релиз, проверяет его подпись и устанавливает. Ничего не устанавливается, пока вы сами не запустите установку или не включите автоматические обновления. По умолчанию автоматические обновления выключены.

Обновление не является постепенным (rolling update). Службы ненадолго останавливаются, а выполняющиеся передачи прерываются. Клиенты, которые умеют продолжать передачу, продолжают её. Обновляйтесь в окно обслуживания.

Как работают обновления

• Релизы. Устанавливаются только опубликованные стабильные релизы с версией x.y.z. Предварительные релизы, ветки, произвольные адреса и более старые версии отклоняются.
• Решает хаб. Каждые 6 часов сервер спрашивает у хаба, какая версия одобрена для него. Хаб придерживает новую версию или выпускает её постепенно. Сами файлы приходят с GitHub по недолговечным ссылкам, которые выдаёт хаб. Для этого серверу не нужен токен GitHub.
• Подпись. Манифест каждого релиза подписан ProAnimaStudio. Сервер проверяет подпись открытым ключом, встроенным в установленную программу, а затем SHA-256 архива. Релиз без подписи или изменённый не устанавливается, откуда бы он ни пришёл — из хаба или с GitHub. Целостность не опирается на доверие к хабу.
• Программа обновления на хосте. Таймер на сервере (arkvory-update.timer в Linux, задача ProAnimaArkvoryUpdate в Windows) каждую минуту запускает программу обновления. Она подхватывает запросы из консоли, проверяет наличие релизов, когда с последней проверки прошло 6 часов, и запускает автоматическое обновление в его час. Проверки выполняются, даже когда автоматическая установка выключена.

Что делает обновление

1. Пока службы работают, оно скачивает релиз, проверяет подпись и SHA-256 и распаковывает файлы в releases/<версия>/ в корне установки. В Compose оно собирает новый образ.
2. Если релиз меняет схему базы данных, оно сначала делает и проверяет свежую резервную копию. См. Резервная копия перед обновлением.
3. Оно останавливает агент резервного копирования, обработчик и API. На завершение каждому отводится до 120 секунд.
4. Оно переключает установку на новую версию. Изменение схемы выполняет миграцию именно сейчас.
5. Оно запускает API и обработчик и ждёт, пока API три раза подряд сообщит о готовности. Затем запускает агент резервного копирования. Агент в проверку не входит: если он не отчитывается примерно 90 секунд, обновление печатает предупреждение и остаётся.
6. Если статистика включена, оно отправляет в хаб анонимное событие updated. Сбой на этом шаге никогда не отменяет обновление.

Старая версия остаётся в releases/. Все данные, ключи и конфигурация остаются прежними.

Проверка обновлений

Войдите в консоль как администратор и откройте Обновления. На странице показаны Установленная версия, Последний стабильный релиз и Последняя проверка. Нажмите Проверить сейчас, чтобы спросить хаб прямо сейчас. После входа баннер со ссылкой Посмотреть обновление сообщает, что появился более новый релиз.

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

На сервере arkvory status --root <корень> показывает установленную версию, настройку автоматических обновлений и закрепление.

Если страница сообщает, что программа обновления на хосте не подключена, выполните arkvory updates-connect --root <корень>. Она подключает консоль и таймер обновления в установке, которую обновили со старого релиза. Если страница сообщает, что программа обновления перестала отчитываться, значит, таймер или задача не запускались 5 минут. См. Устранение неполадок.

Установка вручную

В консоли

1. Откройте Обновления и убедитесь, что Последний стабильный релиз показывает нужную версию.
2. Нажмите Установить обновление. В диалоге указана версия и есть предупреждение о том, что передачи могут прерваться.
3. Нажмите Установить этот релиз. Консоль отправляет версию и SHA-256, которые вы видели. Если опубликованные байты с тех пор изменились, запрос отклоняется.
4. Подождите. Запрос принимается сразу; программа обновления на хосте подхватывает его в течение минуты. Пока службы перезапускаются, страница может потерять соединение, а затем восстановит его сама. Не отправляйте второй запрос.

Если версия закреплена, консоль отказывается от установки. См. Закрепление версии.

Командой

sudo arkvory update --root /opt/proanima-arkvory
sudo arkvory update --root /opt/proanima-arkvory --version 1.2.3

Без --version команда устанавливает версию, которую хаб одобрил для этого сервера. С --version она устанавливает именно эту стабильную версию, которая должна быть новее установленной. При сбое обновления команда завершается с кодом ошибки. Как запускать команду на каждой платформе, описано на странице Настройка.

Автоматические обновления

Включить автоматические обновления можно тремя способами:

• В консоли откройте Обновления, в разделе Автообновление включите Автоматически устанавливать совместимые стабильные релизы, выберите Час обслуживания (UTC) и нажмите Сохранить настройки.
• На сервере: arkvory configure --root <корень> --enable-updates.
• При установке скриптом: --automatic для install.sh, -AutomaticUpdates для install.ps1.

Выключите их в консоли или командой arkvory configure --root <корень> --disable-updates.

Правило	Значение
Окно	Выбранный час по UTC. По умолчанию — с 03:00 до 03:59 UTC. Час задаёт только консоль
Попытки	Не более одной за сутки UTC, успешной или нет. Пропущенное окно позже в тот же день не наверстывается
Пропускается, когда	Версия закреплена, последняя проверка не удалась или более новый релиз не известен
Релиз	Самый новый релиз, который хаб одобрил при последней проверке

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

Резервная копия перед обновлением

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

Релиз, который меняет схему базы данных, устанавливается только после свежей проверенной резервной копии. Программа обновления делает это, пока службы ещё работают:

1. Она просит агент резервного копирования сделать новую резервную копию и ждёт, пока копия будет создана и проверена. Ожидание длится до 6 часов. Всё это время консоль показывает, что релиз устанавливается.
2. Только после этого она останавливает службы, выполняет миграцию базы данных и запускает новую версию.

Для резервной копии нужны три вещи: подключённое доступное хранилище копий, агент резервного копирования в сети и хотя бы одна ранее завершённая резервная копия. Первая полная копия терабайтов данных — это запланированная работа, а не побочный эффект обновления. Если чего-то из трёх нет, обновление отклоняется до каких-либо изменений. Службы продолжают работать, консоль показывает, что установку отклонили, а автоматическое обновление пробует снова на следующий день. Подключите хранилище копий и выполните первую резервную копию: см. Резервные копии.

Изменения, пришедшие после снимка и до остановки служб, в эту копию не попадают. Копия важна, только если новая версия не запустится после миграции: см. Откат и восстановление.

Обновление со своей резервной копией

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

sudo arkvory upgrade --root /opt/proanima-arkvory --version 1.2.3 --backup-record /secure/backup-record.txt

Файл — ваша собственная заметка. Программа обновления только проверяет, что он существует; он не доказывает, что копия полна. Журнал и откат такие же, как у update. Эта команда работает только вперёд и отклоняется, если версия закреплена на другой версии.

Откат и восстановление

Автоматический откат

• Схема не менялась. Если новая версия не становится готовой, программа обновления останавливает её, восстанавливает предыдущий релиз, ждёт готовности и сообщает Update failed; previous release restored.
• Схема менялась, миграция не удалась. Миграция выполняется в одной транзакции. Неудавшаяся миграция откатывается, и предыдущий релиз снова запускается на неизменённой схеме.
• Схема менялась, новая версия не запускается после миграции. Предыдущий релиз не может читать новую схему, поэтому автоматического пути назад нет. Программа обновления помечает журнал maintenance-required и называет точку резервной копии. Устраните причину и выполните recover, который завершит обновление. Либо восстановите точку резервной копии, названную в journal.json, и запустите предыдущую версию.

В Arkvory нет команды понижения версии. Команда отклоняет более старую версию. Предыдущая версия остаётся в releases/ только для автоматического отката.

Восстановление после прерванного обновления

Сбой или отключение питания во время обновления оставляют две вещи: блокировку operation.lock и запись journal.json в корне установки. Новые обновления и большинство команд отказываются работать, пока вы не выполните восстановление. Никогда не удаляйте блокировку, пока не узнаете состояние.

Если обновление не выполнялось (журнал завершён или отсутствует), а процесс, взявший блокировку, уже не работает — например, была остановлена проверка обновлений или в кластере блокировку взял изолированный сервер, — следующая команда снимет блокировку сама и запишет предупреждение.

1. Остановите таймер обновления, чтобы не начался новый запуск. В Linux: sudo systemctl stop arkvory-update.timer. В Windows: Disable-ScheduledTask -TaskName ProAnimaArkvoryUpdate. В установке Compose без таймера остановите свою запланированную задачу.
2. Убедитесь, что процесс программы обновления не работает. Сохраните journal.json и журналы.
3. Только после этого удалите operation.lock.
4. Выполните arkvory recover --root <корень>. Она движется в том направлении, которое допускает журнал:
   • для обновления без изменения схемы либо до начала миграции она возвращается к предыдущей версии,
   • после начала миграции она идёт вперёд: повторяет миграцию, которую безопасно повторять, и запускает новую версию.
5. Проверьте, что службы готовы и тестовое скачивание работает. Снова запустите таймер: sudo systemctl start arkvory-update.timer или Enable-ScheduledTask -TaskName ProAnimaArkvoryUpdate.

Если запрос из консоли, который начал обновление, всё ещё сохранён, arkvory updates-reset --root <корень> удаляет его. Выполняйте эту команду только после проверки состояния. Блокировку она не удаляет.

Закрепление версии

Закрепите версию, чтобы остановить любое обновление до другой версии.

sudo arkvory configure --root <корень> --pin                  # закрепить установленную версию
sudo arkvory configure --root <корень> --pin --version 1.2.3  # закрепить другую стабильную версию
sudo arkvory configure --root <корень> --unpin

Пока версия закреплена:

• автоматические обновления ничего не делают,
• консоль отказывается устанавливать релиз и просит снять закрепление на сервере,
• arkvory update устанавливает закреплённую версию и отклоняет другую --version,
• проверки продолжаются, поэтому консоль по-прежнему показывает более новые релизы.

Чтобы установить более новую версию после закрепления более старой, закрепите новую версию и выполните arkvory update. Закрепить можно и при установке скриптом: --pin для install.sh, -Pin для install.ps1.

Хаб, канал и статистика

Что сервер отправляет в хаб

Когда	Что отправляется
Проверка обновлений, каждые 6 часов или по запросу	Запрос обновления для проекта arkvory с установленной версией, операционной системой (linux или windows), процессором (x86_64 или aarch64) и каналом. Если статистика включена, добавляется заголовок X-Install-Id со случайным ID установки
Обновление завершено, при включённой статистике	Одно событие updated с ID установки, новой версией, операционной системой, процессором и каналом
Скачивание релиза	Хаб отвечает ссылкой на GitHub. Файлы приходят оттуда

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

При выключенной статистике сервер не отправляет ни ID установки, ни события. Тогда хаб предлагает версию только после того, как выпустил её для всех установок.

Параметры

Настройка	По умолчанию	Как изменить
Статистика	включена	Консоль: Отправлять анонимную статистику в ProAnimaStudio в разделе Автообновление. Команда: --statistics off или --statistics on
Канал	stable	--update-channel beta, чтобы получать версии, которые ProAnimaStudio предлагает раньше, --update-channel stable, чтобы вернуться
Адрес хаба	https://hub.proanima.net	--hub-url https://hub.example для собственного хаба, --hub-off, чтобы использовать только GitHub. Адрес должен использовать HTTPS

Все они — параметры arkvory configure --root <корень> и вступают в силу без перезапуска. Настройки хранятся в config/hub.json. Смена адреса хаба также меняет, куда консоль отправляет обратную связь, после следующего перезапуска служб.

Если хаб недоступен

Если хаб не отвечает (сбой сети, тайм-аут или ошибка сервера), программа обновления читает последний стабильный релиз на GitHub и записывает предупреждение в журнал. Проверки подписи и SHA-256 она делает те же. Отказ хаба (статус 4xx), отсутствующий файл или неверная подпись — это ошибка, и запасного пути нет.

Если для релизов на GitHub нужна аутентификация, создайте в корне установки файл github-token.txt с токеном, который может читать содержимое репозитория. Читать файл могут только администраторы. Программа обновления его использует, службы — нет, и он никогда не передаётся параметром команды. С --hub-off программа обновления всегда использует GitHub.

Серверу нужен доступ по HTTPS к hub.proanima.net, api.github.com, github.com и узлам скачивания GitHub.

Установки без интернета

Сервер без доступа в интернет не может проверять релизы. Страница Обновления тогда показывает, что проверка не удалась. На службы это не влияет. Обновляйте из файлов.

1. На компьютере с доступом в интернет скачайте комплект для платформы вашего сервера: Arkvory-Linux.tar.gz или Arkvory-Windows.zip. Сравните их SHA-256 с release-checksums.json релиза.

2. Скопируйте комплект на сервер и распакуйте его. В каталоге лежат arkvory-release.json, arkvory-runtime.zip и arkvory-setup.mjs. В комплекте нет файла подписи. Скачайте arkvory-release.json.sig с той же страницы релиза и положите рядом с arkvory-release.json: тогда программа обновления проверит и подпись.

3. Выполните обновление, указав абсолютный путь к каталогу:

   sudo arkvory update --root /opt/proanima-arkvory --artifact /media/release

   & 'C:\Program Files\ProAnima\Arkvory\arkvory.ps1' update --root C:\ProgramData\ProAnima\Arkvory --artifact D:\release

Программа обновления сверяет SHA-256 архива с манифестом. Подпись она проверяет, только если arkvory-release.json.sig лежит рядом с манифестом. Локальный каталог — ваш собственный выбор, поэтому обновление не требует подписи. Без неё единственное доказательство происхождения — сравнение комплекта с release-checksums.json на шаге 1. Действуют те же правила для изменения схемы: сначала нужна проверенная резервная копия.

Нативный пакет или Arkvory-Setup-x64.exe несёт свой релиз и не требует доступа в интернет. Обновление Compose собирает образ на хосте. Docker Hub нужен ему, только если базового образа node:24.21.0-bookworm-slim на хосте ещё нет.

Обновление по платформам

Windows

Запустите более новый Arkvory-Setup-x64.exe поверх установленного. Установщик находит данные и не спрашивает владельца заново. Он обновляет программы, службы и релиз базы данных так же, как обновление из консоли. Установщик более старой версии отклоняется, а установщик той же версии восстанавливает службы. Не запускайте установщик, пока выполняется обновление. Установщик доступен только на английском и русском языках. Можно также обновиться из консоли или командой.

Пакеты для Linux

Скачайте более новый пакет со страницы релиза и установите его так же, как первый: sudo apt install ./Arkvory-amd64.deb или sudo dnf install ./Arkvory-x86_64.rpm. Репозитория apt или dnf нет, поэтому apt upgrade и dnf upgrade новых версий не находят. Шаг настройки пакета выполняет то же обновление, что и команда, с релизом из пакета. Работающие службы продолжают обслуживать запросы до переключения.

Если обновление отклонено, например потому, что для изменения схемы нужна несуществующая резервная копия, старая версия продолжает работать, а шаг настройки завершается ошибкой. Устраните причину, затем повторите шаг командой sudo dpkg --configure -a в Debian и Ubuntu или повторной установкой того же пакета в системах RPM.

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

Установка скриптом

В установке скриптом нет команды arkvory. Обновляйте из консоли или выполняйте manage.mjs update с Node.js установки. См. Настройка.

Docker Compose

Обновляйте из консоли или командой manage.mjs update. Программа обновления собирает образ новой версии, заменяет контейнеры backup, worker и api и сохраняет тома. Установке Compose без root нужен запланированный updates-poll. См. Docker Compose.

После обновления

• Проверьте arkvory status --root <корень> и войдите в консоль.
• Удалите ненужные версии из releases/. Оставьте текущую версию и предыдущую, названную в journal.json. Старые версии, скачанные файлы и промежуточные данные программа обновления никогда не удаляет.
• Обновление не обновляет Node.js установки скриптом, программы PostgreSQL, операционную систему или движок контейнеров. Обновляйте их отдельно. Смена основной версии PostgreSQL — это отдельная миграция: сначала сделайте резервную копию.

Устранение неполадок

Что вы видите	Что делать
Страница сообщает, что программа обновления на хосте не подключена	Выполните arkvory updates-connect --root <корень> в окно обслуживания
Страница сообщает, что программа обновления перестала отчитываться	Проверьте таймер или задачу. В Linux: systemctl status arkvory-update.timer и journalctl -u arkvory-update. В Windows: задача ProAnimaArkvoryUpdate и logs\updater.log. Убедитесь, что не остался operation.lock
Проверка релиза не удалась	Проверьте доступ сервера к хабу и GitHub. Службы это не затрагивает
Установка отклонена, потому что нужна резервная копия	Подключите хранилище копий, дождитесь первой резервной копии, снова проверьте состояние. См. Резервная копия перед обновлением
Обновление не удалось	Прочитайте journal.json, журнал программы обновления и журналы служб, прежде чем пробовать снова
Требуется ручное восстановление	Следуйте разделу Восстановление после прерванного обновления
Настройки изменились, пока запрос ждал	Обновите страницу и отправьте запрос снова
Installation is locked	Выполняется другая операция, либо она завершилась аварийно. См. Восстановление после прерванного обновления
Interrupted deployment; use recover after inspecting journal.json	Прежнее обновление не завершилось. Сначала выполните восстановление
Downgrades are forbidden	Версия не новее установленной
Version is pinned	Снимите закрепление или установите закреплённую версию
Interrupted update request; inspect installation and use updates-reset	Запрос из консоли принят, но не завершён. Проверьте состояние, затем выполните updates-reset

Другие подсказки есть на страницах Устранение неполадок и Самовосстановление.