Политика обновлений — AiHummer Документация

Обновления проектируются так, чтобы снижать риск простоя и повреждения данных. AiHummer следует SemVer, применяет обратно совместимые миграции БД автоматически и умеет самообновляться из CDN — так что обновления становятся рутиной, а не риском.

Версионирование (SemVer)

Релизы следуют семантическому версионированию. Версию сообщают /healthz и aihummer version, поэтому всегда можно подтвердить, что именно работает, до и после обновления.

Миграции обратно совместимы и автоматичны

При старте шлюз применяет ожидающие миграции БД автоматически. Безопасность обеспечивают два свойства:

Обратная совместимость. Миграции написаны так, что более новый бинарный файл работает со схемой, в которую он мигрирует, — именно это делает автоприменение и скользящие обновления безопасными.
Только один экземпляр применяет миграции. Миграции выполняются под advisory-lock PostgreSQL, поэтому при одновременном старте нескольких шлюзов применяет их только один, а остальные ждут — никаких двойных миграций.

[!NOTE] Миграции всегда выполняются на owner-пуле базы. Ограниченная RLS-роль (AIHUMMER_DB_APP_URL) предназначена для обслуживания трафика, а не для изменений схемы.

Обновление

Новые версии забираются из релизного CDN вендора. Штатный способ обновиться — одна команда на сервере:

aihummer update --check   # только сообщить, есть ли версия новее
aihummer update           # скачать и применить

--check ничего не пишет и потому не требует root. Само применение меняет установленный корень и перезапускает службу, поэтому запускается через sudo.

Ожидаемый результат: --check печатает текущую и доступную версии и завершается, ничего не меняя. aihummer update скачивает артефакт, проверяет его контрольную сумму sha256 и подпись cosign, заменяет бинарный файл, перезапускает службу — после чего aihummer version показывает новую версию. Если проверка не сошлась, обновление прерывается до замены файла: работающая версия остаётся нетронутой.

Автообновление включено по умолчанию

С версии 1.2.6 автообновление включено из коробки — и для шлюза, и для каждого плагина. Раньше инстанс не получал починок, пока оператор не заходил на сервер руками, и это была самая частая причина «у нас старая версия».

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

[!NOTE] Обновиться раньше очередной проверки можно в любой момент — командой aihummer update выше. Проверка подписи и контрольной суммы при этом ровно та же, что при автоматическом обновлении.

Если автообновление вам не подходит, договоритесь об этом с вендором: режим меняется на его стороне и приезжает на инстанс подписанным. Самостоятельная правка настройки на инстансе не сработает — она будет отвергнута.

Откат

Что откатывается — по отдельности:

Бинарный файл — можно вернуть на предыдущую версию (артефакты предыдущих релизов доступны на CDN; переустановите нужную версию).
Схема БД — миграции обратно совместимы, поэтому предыдущий бинарный файл работает с новой схемой; отдельного отката схемы не выполняется.
Плагины — версии управляются на каждую установку; при необходимости верните предыдущую версию плагина из каталога.
Конфигурация — не меняется при обновлении; восстанавливается из резервной копии при необходимости.

Развёртывания без простоя

AiHummer создан для обновления без простоя:

Запускайте 2+ шлюза за прокси. Обновляйте их по очереди; проба готовности (/readyz) держит перезапускающийся узел вне ротации, пока он не начнёт обслуживать.
Планировщик — единственный лидер. Фоновое планирование выбирает одного лидера через advisory-lock PostgreSQL, поэтому несколько шлюзов не дублируют запланированную работу.
Доставка идемпотентна. Надёжная доставка вместе с ключами идемпотентности означает, что ответ не отправится дважды при перезапуске — именно это делает скользящее обновление ваших шлюзов безопасным.

Куда дальше

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