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

Порядок обновления on-prem ActionPulse — проверенная копия до старта, миграции схемы PostgreSQL и ClickHouse, поэтапный запуск сервисов, границы отката.

Кому: Операторам установки
Проверено: 28.07.2026

На этой странице

Что сделать до обновления
Обновление приложения
Миграции схемы
Если миграция не прошла
Можно ли обновляться через версию
Как проверить, что обновление удалось
Откат и когда он невозможен
Частые ошибки

Обновление on-prem-установки — это замена точных ссылок на образы в вашем .env и один прогон миграций схемы. Опасны не команды, а порядок: миграции меняют данные и назад не откатываются, а хранилища состояния — PostgreSQL, ClickHouse и NATS — нельзя запускать под более старой версией, чем та, что уже открывала их том.

Эта страница описывает обновление комплекта поставки (Docker Compose). Команды ниже выполняются из каталога распакованного комплекта, если рядом не сказано иное.

Что сделать до обновления

Проверьте артефакт релиза до распаковки. Сверьте контрольную сумму архива и подписанный release-manifest.json, полученные из того же аутентифицированного релизного канала. Внутри комплекта соответствие релизу описывают VERSION и release/images.json — итоговый перечень образов в виде tag@sha256 вместе с per-platform digest’ами.
Прочитайте заметки о выпуске. Их в комплекте нет — они приходят вместе с релизом. Читать нужно не только целевой выпуск, но и все промежуточные: отдельные релизы требуют одноразовых действий оператора, и пропущенный шаг проявляется уже после запуска.
Остановите поток. Поставьте на паузу отправителей событий, потребителей и исторические импорты. Дождитесь нулевого (или заранее объяснённого) отставания в NATS и завершения мутаций ClickHouse.
Снимите свежую полную копию PostgreSQL и ClickHouse, снимок тома NATS JetStream и экспорт конфигурации потоков и потребителей.
Докажите копию восстановлением в новые, отдельные PostgreSQL и ClickHouse и восстановлением снимка JetStream на новый том. Запишите контрольные суммы, номера последовательностей, состояние потребителей и фактическое время восстановления.
Распакуйте новый комплект в отдельный каталог. Перенесите .env командой install -m 0600, затем вручную перенесите в него новые обязательные поля и новые точные ссылки на образы из новой .env.example.

Обновление приложения

Проверки идут до того, как что-либо остановлено: preflight.sh отказывает при подстановке-заглушке, коротком секрете, неточной ссылке на образ или неверном режиме файла, а config --quiet ловит ошибки самой конфигурации Compose.

cd actionpulse-onprem-new

./preflight.sh .env
docker compose -f docker-compose.onprem.yml --env-file .env config --quiet
docker compose -f docker-compose.onprem.yml --env-file .env pull

# Сначала хранилища и мигратор, затем сервисы, обслуживающие трафик.
docker compose -f docker-compose.onprem.yml --env-file .env up -d \
  postgres clickhouse redis nats query-api-migrate query-api
docker compose -f docker-compose.onprem.yml --env-file .env up -d \
  ingest-api ch-writer worker caddy
docker compose -f docker-compose.onprem.yml --env-file .env up -d

Порядок не декоративный. query-api-migrate — одноразовый контейнер (restart: no), и долгоживущий query-api объявлен зависимым от его успешного завершения. Пока миграции не прошли, HTTP-сервис не поднимется, а сервисы приёма и записи не увидят схему, которой ещё нет.

Если вы уже перевели сервисы на отдельные роли PostgreSQL, порядок такой: миграции → повторное применение postgres/roles.sql → и только затем раскатка ingest-api с его DSN. Права уровня столбцов выдаются только на уже существующие таблицы, поэтому после появления новых таблиц скрипт ролей применяют заново.

Релизы с одноразовой процедурой запускают иначе

Если выпуск включает усиление исторических импортов (миграции PostgreSQL 00046, 00047 и ClickHouse 0015), нельзя поднимать worker и ch-writer обычным up -d. Такой релиз требует остановки и дренажа импортных ролей, одноразового запуска docker compose … run --rm --no-deps worker --bootstrap-import-privacy-hmac-fingerprint и синхронной очистки унаследованных отклонённых строк импорта в ClickHouse. Точная последовательность — в OPERATIONS.md из вашего комплекта.

Миграции схемы

Миграции применяет только query-api-migrate. Он же — единственная рабочая нагрузка, получающая учётные данные мигратора: обслуживающий query-api работает под ролями чтения и записи и повысить свои права не может.

Хранилище	Механизм	Журнал применённого
PostgreSQL	goose, нумерованные файлы `migrations/pg`	таблица `goose_db_version` в PostgreSQL
ClickHouse	нумерованные SQL-файлы `migrations/ch`	таблица `ch_schema_migrations` в PostgreSQL

Обе цепочки идемпотентны и сериализованы advisory-локом PostgreSQL, поэтому две реплики не начнут миграцию одновременно, а повторный запуск не применяет уже применённое. Журнал миграций ClickHouse намеренно живёт в PostgreSQL — это единственный источник ответа на вопрос «какая версия схемы аналитики применена».

Посмотреть фактически применённые версии:

docker compose -f docker-compose.onprem.yml --env-file .env exec -T postgres \
  psql -U pp -d actionpulse -Atc \
  "SELECT max(version_id) FROM goose_db_version WHERE is_applied"

docker compose -f docker-compose.onprem.yml --env-file .env exec -T postgres \
  psql -U pp -d actionpulse -Atc \
  "SELECT count(*), max(version) FROM ch_schema_migrations"

Если миграция не прошла

Провалившийся мигратор — это остановленное обновление, а не сломанная установка: сервисы, обслуживающие трафик, ещё не запущены и продолжают работать на прежней версии (в Helm провал hook-задания оставляет релиз без изменений).

Прочитайте причину: docker compose -f docker-compose.onprem.yml --env-file .env logs query-api-migrate (в Kubernetes — kubectl logs job/actionpulse-migrate и kubectl describe job/actionpulse-migrate).
Не запускайте ingest-api, ch-writer и worker, пока миграции не прошли.
Устраните причину — чаще всего это недостающие права роли мигратора, нехватка места или незавершённая мутация ClickHouse — и повторите ту же самую команду. Повтор безопасен: применяется только то, что ещё не применено.

Отдельно про две базы: PostgreSQL и ClickHouse — не одна транзакция. Мигратор может успеть закоммитить часть изменений в PostgreSQL и упасть на ClickHouse. Поэтому после диагностики идут вперёд (повторный прогон) либо назад целиком (восстановление снимка на новые тома) — но не «частично назад».

Можно ли обновляться через версию

Для приложения — да, с оговоркой. Цепочки миграций накопительные: мигратор применит всё пропущенное за один прогон. Но продукт не обещает, что перепрыгнуть несколько выпусков можно не читая их: каждый промежуточный релиз мог требовать одноразового действия оператора, и это действие не выполнится само. Читайте заметки всех выпусков между вашей версией и целевой.

Для хранилищ состояния — нет. NATS и ClickHouse обновляются строго по одному шагу за раз, по проверенной последовательности:

Сервис	Проверенная последовательность
NATS	`2.10.29` → `2.11.17` → `2.12.12` → `2.14.3`
ClickHouse	`24.8.14.39` → `25.8.28.1` → `26.3.17.56`

Точные ссылки контрольных точек и per-platform digest’ы лежат в release/images.lock вашего комплекта. Маршрут заблокирован, если в этом файле нет статуса готовности контрольных точек или отсутствует digest для вашей платформы.

Каждый шаг — это отдельная процедура: свежая копия, доказанная восстановлением; изменение ровно одной из ссылок NATS_IMAGE_REF или CLICKHOUSE_IMAGE_REF; preflight.sh, config --quiet и pull до остановки чего-либо; запуск только обновляемого хранилища и проверка его готовности; проверка данных (для NATS — конфигурация потоков и потребителей, непрерывность последовательностей, повторная доставка и дедупликация на синтетическом сообщении; для ClickHouse — версия сервера, CHECK TABLE, мутации, количество строк и контрольные суммы, резервное копирование и восстановление в отдельную базу, политики строк и сквозная проверка приём → отчёт). Только после этого — следующий шаг.

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

docker compose -f docker-compose.onprem.yml --env-file .env ps
curl -fsS "https://${PP_DOMAIN}/healthz"
curl -fsS "https://${PP_DOMAIN}/api/v1/license" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Все контейнеры должны быть в состоянии running или healthy, а одноразовые query-api-nats-bootstrap и query-api-migrate — успешно завершёнными. Дальше проверяют то, что обновление могло сломать незаметно:

маршрутизацию Caddy, TLS, заголовки безопасности, поток обновлений SSE и отсутствие опубликованных портов, кроме 80 и 443;
сквозной путь события: приём → NATS → ClickHouse → ограниченный по времени отчёт, плюс повторную доставку и дедупликацию;
статус лицензии: без действующей лицензии операции записи отвечают 403, а чтение продолжает работать;
наблюдаемость: правила и API Prometheus, метрики node-exporter, трассу в Jaeger, приём журналов в Elasticsearch по TLS;
свежую резервную копию и изолированное восстановление уже после обновления — схема изменилась, значит проверять надо новую;
задачу удаления данных субъекта на синтетическом субъекте до состояния completed. Не используйте для этого настоящие персональные данные.

Подробный разбор проверок — на странице Проверка работоспособности.

Откат и когда он невозможен

Откат приложения (ingest-api, query-api, ch-writer, worker) — это возврат прежних точных ссылок на образы. Он допустим только после проверки, что прежний код совместим с уже применённой схемой и с публичными контрактами.

Старый бинарник поверх нового тома запрещён

Для NATS, ClickHouse и Prometheus запуск более старой версии на томе, который уже открывала новая версия, приводит к повреждению данных. Откат хранилища — это всегда: остановить отправителей, потребителей и запись → создать новый пустой том → запустить образ версии до шага → восстановить проверенный снимок, снятый до шага → заново проверить контрольные суммы, последовательности, дедупликацию и сквозной путь события → и только после зелёного результата переключать трафик.

Откат невозможен в трёх случаях, и об этом лучше знать до начала обновления:

Миграция изменила данные. Обратных миграций в продукте нет. Прежняя версия схемы восстанавливается только вместе с данными — из копии, снятой до обновления. Всё, что записано после снятия копии, будет потеряно.
Нет проверенного снимка, снятого до шага. Без него откат хранилища состояния заблокирован: восстанавливать нечего, а запускать старую версию поверх нового тома нельзя.
Происхождение тома неизвестно. Если нельзя доказать, какая версия открывала том последней, единственный безопасный путь — новый пустой том и восстановление.

Быстрое обновление без остановки обслуживания (ingest-api и ch-writer безсостоятельные и масштабируются горизонтально) допустимо только для выпуска, который не меняет формат хранимых данных, совместимость схемы, криптографию исторических импортов и связанные с приватностью отпечатки. Для всех остальных выпусков применяется поэтапный порядок из этой статьи.

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

Симптом	Причина	Что делать
`preflight.sh` отказывает после переноса `.env`	в новом выпуске появились обязательные поля	перенесите новые поля и точные ссылки на образы из новой `.env.example` вручную
`query-api` не стартует, `query-api-migrate` завершился с ошибкой	миграции не прошли	читайте логи мигратора, исправляйте причину, повторяйте тот же прогон
Операции записи отвечают `403` после обновления	лицензия отсутствует или истекла	проверьте статус лицензии; после истечения есть 7 дней работы только на чтение
События принимаются, но не появляются в отчётах	не запущен или отстаёт `ch-writer`	логи `ch-writer` и метрика отставания записи
ClickHouse не поднимается после смены версии	пропущен шаг обязательного маршрута	восстановите снимок на новый том и пройдите шаги по одному