Обновления и уведомления

Консоль → Обновления доступна глобальным администраторам. Здесь видны установленная и последняя стабильная версия, последняя проверка, состояние планировщика и ошибки. Баннер сообщает о новом релизе после входа. Встроенные уведомления не зависят от включения автоустановки; email, push и внешние webhooks этим механизмом не отправляются.

Режимы

• Уведомлять: планировщик каждые 6 часов спрашивает хаб ProAnimaStudio, какая версия одобрена для этой установки (при недоступности хаба — GitHub Releases). «Проверить сейчас» ставит внеочередной запрос.
• Обновить вручную: кнопка открывает подтверждение с конкретной версией и предупреждением о прерывании передач. Подтверждённый запрос содержит версию и SHA-256 выбранного архива; подмена опубликованных байтов отклоняется.
• Автообновление: явное включение и выбор часа UTC, по умолчанию 03:00–03:59 UTC. Не более одной попытки установки за календарный день UTC. Пропущенное окно не догоняется среди рабочего дня. Автообновление по умолчанию выключено.

Устанавливаются только опубликованные stable releases ProAnima/Arkvory, подписанные ключом выпуска (см. ниже); prerelease, draft, downgrade, произвольные URL, ветки и команды не принимаются. Pin сохраняется; снять его можно локально через configure --unpin. Релиз со сменой схемы БД ставится теми же путями (веб, окно автообновления, update, пакеты), но только после свежей проверенной копии — см. ниже. Runtime Node.js, PostgreSQL major и системные зависимости обслуживаются отдельно.

Хаб, подпись и статистика

ADR 0060. Какую версию ставить, решает человек в хабе ProAnimaStudio (https://hub.proanima.net): он продвигает опубликованный релиз в канал stable или beta для доли установок или ставит канал на паузу. Файлы по-прежнему лежат в GitHub Releases. Хаб выдаёт на них короткоживущие ссылки, поэтому установке не нужен GitHub-токен.

• Подпись. Манифест каждого релиза подписан ключом Ed25519 студии. Установка проверяет подпись встроенным открытым ключом, затем SHA-256 архива. Неподписанный или подменённый релиз не ставится ни из хаба, ни с GitHub.
• Хаб недоступен (сеть, тайм-аут, ошибка сервера): берётся последний стабильный релиз GitHub, с той же проверкой подписи. Для приватного репозитория тогда нужен <root>/github-token.txt (Contents: read). Отказ хаба (4xx) или неверная подпись — ошибка, а не обход.
• Статистика (включена по умолчанию): случайный id установки при проверке обновлений и событие «обновление установлено». Без статистики id не отправляется, и версия приходит, только когда её раскатили на всех. IP, имена и содержимое хаб не хранит.

arkvory configure --root <root> --statistics off            # выключить статистику (или в консоли)
arkvory configure --root <root> --update-channel beta       # получать бета-версии
arkvory configure --root <root> --hub-off                   # без хаба: только GitHub, без обратной связи
arkvory configure --root <root> --hub-url https://hub.example # свой хаб

Настройки лежат в config/hub.json, id установки — в config/install-id. Адрес хаба для обратной связи консоли записывается и в runtime.json (ARKVORY_HUB_URL) и действует после перезапуска служб.

Выпуск (для сопровождающего):

1. npm run release:local -- X.Y.Z проверяет, собирает и подписывает релиз ключом ~/.proanima/arkvory-release-signing.key. Черновик, созданный GitHub Actions, подписывается командой npm run release:sign -- sign-draft X.Y.Z.
2. Опубликуйте черновик на GitHub.
3. В консоли хаба одобрите версию для канала и доли установок.

Ключ — единственный: храните его резервную копию вне машины. Без него новые версии ставятся на существующие серверы только вручную.

Обратная связь

Кнопка Обратная связь в верхней панели консоли отправляет сообщение разработчикам через хаб. Что можно приложить:

• адрес для ответа;
• до 6 снимков экрана PNG, JPEG, WebP или GIF по 8 МБ: вставка из буфера (Ctrl+V), перетаскивание или выбор файла;
• журнал страницы — ошибки, предупреждения и неудачные запросы, с замаскированными ключами;
• для администратора — журнал сервера и сводку системы.

Всё, что уйдёт, видно в форме под «Показать, что будет приложено». Сообщения ограничены лимитами хаба: 15 МБ на сообщение, 5 сообщений за 10 минут с одного сервера.

Смена схемы БД

Порядок (ADR 0059):

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

Условия: vault подключён и доступен, агент в сети, хотя бы одна копия уже завершена. При ежедневных копиях снимок изменений и проверка занимают минуты. Предел ожидания — 6 часов. Всё это время консоль показывает «Устанавливаем релиз».

Ситуация	Что происходит
Нет vault, агента или первой копии; копия не удалась или повреждена	Отказ до любых изменений: службы работают, консоль показывает «Установка отклонена…», автообновление повторит попытку на следующие сутки
Миграция упала	Её транзакция откатывается, прежняя версия запускается снова на прежней схеме
Новая версия не запустилась после миграции	Журнал maintenance-required: исправьте причину и выполните recover (он идёт вперёд) или восстановите точку из журнала прежней версией (BACKUP_RECOVERY)

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

Без встроенного vault остаётся ручной путь: копия оператора, затем upgrade --backup-record <файл> (deploy/README). С 0.2.0 переход один раз ручной: в 0.2.0 нет API резервных копий, поэтому update, консоль и пакет откажут до изменений. Сделайте копию оператора (остановленные службы, БД и весь storage root) и запустите установщик новой версии — тогда работают её журнал, откат и регистрация агента копий:

# Linux, пакет: payload новой версии уже в /usr/lib/proanima-arkvory
sudo /opt/proanima-arkvory/runtime/node /usr/lib/proanima-arkvory/arkvory-setup.mjs upgrade \
  --root /opt/proanima-arkvory --artifact /usr/lib/proanima-arkvory --backup-record /secure/record.txt
sudo dpkg --configure -a   # только deb: завершить настройку пакета

# Windows, установщик: payload новой версии в Program Files
& "$env:ProgramData\ProAnima\Arkvory\runtime\node.exe" "$env:ProgramFiles\ProAnima\Arkvory\arkvory-setup.mjs" upgrade `
  --root "$env:ProgramData\ProAnima\Arkvory" --artifact "$env:ProgramFiles\ProAnima\Arkvory" --backup-record D:\secure\record.txt

# Архив или Compose: каталог распакованного релиза
node <release>/arkvory-setup.mjs upgrade --root <root> --artifact <release> --backup-record <файл>

После этого подключите vault (configure --backup-vault … --vault-key-file …) и дождитесь первой копии: следующие смены схемы пройдут сами.

Этот путь проверяет гейт deployment-stand (tests/deployment/upgrade-stand.mjs). На хосте с systemd ставится .deb последнего опубликованного релиза, его хеш сверяется с native-linux.json того же релиза. Затем стенд проверяет:

• без vault пакет кандидата отказывает, старый релиз продолжает отдавать данные;
• после подключения vault и первой копии пакет снимает и проверяет свежую копию, мигрирует и запускает кандидата;
• данные сохранились, а реестр образов, raw-файлы, Git LFS и npm работают на новой схеме.

Предыдущий релиз берётся из ARKVORY_PREVIOUS_RELEASE (каталог его файлов) или с GitHub.

Установка и подключение

Новые установки автоматически создают защищённый mailbox и подключают планировщик. Linux/systemd и Windows Task Scheduler запускают updates-poll раз в минуту. Включение расписания проверки не включает автоматическую установку. Вывод на Linux собирает journald (journalctl -u arkvory-update); на Windows запуск без консоли перезапускает себя с выводом в logs/updater.log установки (ротация 20 MiB × 5, как у WinSW), аргументы задачи не меняются.

Существующие установки после перехода на релиз с этим механизмом подключаются администратором сервера:

node <root>/manage.mjs updates-connect --root <root>

Подключение обновляет runtime-конфигурацию и разрешения служб, регистрирует недостающие службы текущего релиза (агент резервных копий после обновления с 0.2.x, ADR 0057), останавливает и запускает API/worker и агента, проверяет готовность и регистрирует расписание. Выполняйте его в окно обслуживания. Команда использует текущий установленный релиз; старый релиз, ещё не содержащий новые адаптеры и Compose mounts, предварительно обновляют обычным installer/CLI.

На Linux без systemd и в непривилегированном Compose установка остаётся доступна, но планировщик подключает оператор: запускать node <root>/manage.mjs updates-poll --root <root> каждую минуту от владельца установки с доступом к container engine. Не передавайте Docker socket веб-сервису. На Docker Desktop задача должна работать в контексте пользователя его движка; системный Docker/Podman обслуживается планировщиком хоста. Консоль показывает отсутствие heartbeat спустя 5 минут и запрещает новые запросы.

<root>/github-token.txt (Contents:read) нужен только для обхода через GitHub, когда хаб недоступен, и для установок с --hub-off. Файл доступен только администратору/планировщику; его содержимое не передаётся в API или браузер. Ошибка проверки не удаляет сведения о последнем найденном релизе, но помечает их устаревшими. Проверка повторяется через 6 часов или вручную.

Безопасность и восстановление

API читает только updates/status/snapshot.json и пишет в updates/inbox. Папка status принадлежит администратору и доступна приложению только для чтения; inbox — единственная дополнительная область записи. В Compose это раздельные bind mounts. Развёртывание и GitHub credential остаются вне контейнера приложения.

На POSIX native inbox принадлежит service account и имеет mode 0700. В Compose host updater и контейнер могут иметь разные UID: корень установки остаётся 0700, status — 0755/0644, а только inbox имеет 0777 внутри закрытого корня и отдельного bind mount. Команды не содержат секретов и публикуются с mode 0644 для чтения владельцем хоста. Не открывайте корень установки другим пользователям и не публикуйте inbox отдельной сетевой шарой. Windows использует ACL корня и каталогов.

Один активный запрос публикуется атомарно. Планировщик под общим operation.lock переносит его в приватный update-request.json, проверяет revision и выполняет разрешённый сценарий. Статус 202 означает принятие в очередь, а не успешную установку. Повтор последнего ID возвращает квитанцию без новой операции; после других команд устаревший revision отклоняется. Клиент должен генерировать новый UUID только для нового намерения.

Обновление сохраняет прежние проверки архива, journal, readiness API/worker и попытку rollback при обычном отказе. Потеря связи браузера не отменяет принятую установку. После подключения страница снова читает статус. Неопределённая остановка процесса сохраняет lock и принятый запрос; автоматическое продолжение запрещено.

После аварии оператор проверяет процессы, службы, installation.json, journal.json и оставшийся lock. При необходимости выполняет штатный recover: при смене схемы он до начала миграции возвращает прежнюю версию, а после — завершает обновление вперёд. Только после согласования состояния можно выполнить updates-reset для удаления принятого запроса. Команда не удаляет operation.lock и не разрешает обход незавершённого journal. Блокировка записывает операцию, которая её взяла. Блокировку операции обновления (updates-*, update, recover, upgrade, apply-installer, а также cluster-release: всё, что они меняют, записано в journal или повторяется заново) без незавершённого journal, взятую процессом, который больше не работает (на этом хосте) или другим узлом HA-кластера (тот изолирован, ADR 0072), следующая операция снимает сама с предупреждением. Из двух процессов, нашедших её одновременно, снимает один: блокировка сначала атомарно переименовывается. Блокировку прерванного configure, install или cluster-node (journal они не ведут, настройки могли остаться записанными наполовину), сохранённую после неподтверждённого завершения и блокировки прежних релизов (без хоста или операции) снимает только оператор. Команда оператора (configure, update, recover и другие) до 2 минут ждёт, пока блокировку отпустит работающая операция, например проверка обновлений по таймеру; сам таймер не ждёт и повторяет попытку через минуту. Сохранённая блокировка, незавершённый journal и блокировка завершившегося процесса отказывают сразу. cluster-node и cluster-release берут блокировку, пока том смонтирован на этом узле (она лежит на томе): службы останавливаются после завершения идущего обновления, а не посреди него; перед размонтированием блокировка отпускается. Пропавший heartbeat не считается успешным обновлением. На Windows directory fsync недоступен через Node; после потери питания требуется сверка файлов установки.

API и SDK

Метод	Адрес	Результат
GET / HEAD	/api/v1/system/updates	snapshot и pending; null snapshot означает неподключённый updater
POST	/api/v1/system/updates/requests	202 {id}; команды check, configure, apply

Все методы требуют глобального administrator. Managed service keys и делегированное repository/service administration доступа не дают. Предоставление роли administrator теперь также означает право управления установленным кодом через доверенные релизы. Reader gateway запрещает POST; контрольной директорией подключается только основной API.

const status = await client.updates.status();
if (status.snapshot) {
  await client.updates.request({
    id: crypto.randomUUID(),
    expectedRevision: status.snapshot.revision,
    kind: 'configure',
    automatic: true,
    hourUTC: 3,
  });
}

apply дополнительно требует version и sha256 из snapshot.latest. Конфликт revision — 409, занятая очередь или недоступный updater — 503. После сетевой ошибки сначала прочитайте статус и сопоставьте ID; не создавайте повторную установку вслепую. Снимок имеет фиксированный размерный предел, а публичный контракт не содержит физических путей и секретов.

Механизм рассчитан на standalone writer/worker. Он не является rolling update или координатором HA; reader-узлы и shared-root установки требуют операторского согласования по READ_GATEWAYS.