AI Platform Docs

Канонический механизм

Agent Registry и Activity используют разные хранилища и механизмы миграции. Разделы до «Миграция Activity в ClickHouse» относятся к PostgreSQL Agent Registry. Их команды Alembic не создают и не понижают схему ClickHouse.

Alembic — единственный поддерживаемый способ создания и изменения схемы PostgreSQL Agent Registry. Приложение не вызывает SQLModel.metadata.create_all при запуске.

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

Low-code Runtime не имеет собственной изменяемой базы данных. База рабочих версий Low-code IDE принадлежит проекту-владельцу и должна иметь отдельный версионированный план миграции; ее нельзя изменять миграциями Agent Registry.

Последовательность версий

Порядок	Версия	Изменение	Риск понижения
1	`e298f58dfdac`	Создает каталог R1, наблюдения, протокольные проекции, аудит, транзакционную очередь и задания поиска	Удаляет всю схему R1 и все ее данные
2	`b41f876a08c2`	Добавляет `reindex_job.retired_generations` для учета прежних поколений OpenSearch	Удаляет поле и сохраненные в нем сведения
3	`d3f62e716ad4`	Добавляет `exposure` и `authorization` в `invocation_route_projection_state` и заполняет их для принятых маршрутов	Удаляет поля и их сохраненные значения
4	`f62a9b7c4d11`	Удаляет одноразовую схему R1 и создает каталог публикаций R2: `catalog_agent`, версии, навыки, интерфейсы, состояния наблюдений и проекций, outbox событий, аудит	Понижение не поддерживается — `downgrade()` вызывает `RuntimeError`; восстановление только из резервной копии до R2

Опубликованные исходные файлы:

Отдельные up.sql и down.sql не публикуются. Функции upgrade() и downgrade() находятся в одном версионированном исходном файле Alembic. Ручной SQL рядом создал бы второй источник истины.

Подготовка

Зафиксируйте текущую версию Alembic, идентификатор образа приложения и версию конфигурации.
Подтвердите свежую резервную копию PostgreSQL и возможность восстановления на отдельном экземпляре.
Проверьте свободное место, длительность блокировок и окно изменения.
Выполните alembic check на исходных файлах выпуска.
Примените миграции к базе той же основной версии PostgreSQL и сопоставимого объема данных.
Проверьте параллельный запуск двух заданий миграции.
На одноразовой копии проверьте сценарий ошибки и понижение обратимой части цепочки: f62a9b7c4d11 необратима, поэтому проверьте возврат до d3f62e716ad4 (и дальше при необходимости) и восстановление из резервной копии до R2.
Убедитесь, что образ, совместимый с фактической схемой, доступен для возврата, так как после f62a9b7c4d11 прежний образ не совместим со схемой R2 и откат только через резервную копию.
Сохраните очищенный отчет без строки подключения и учетных данных.

Применение

Штатно миграцию запускает Garden. Для проверки на изолированной одноразовой базе допустимы команды:

uv run alembic upgrade head uv run alembic current uv run alembic check

Ожидаемая текущая версия — f62a9b7c4d11.

После применения проверьте:

наличие ожидаемых таблиц, ограничений и индексов;
одновременную фиксацию изменения каталога и записи транзакционной очереди;
отсутствие частично примененной схемы;
готовность API и Kubernetes Reconciler;
публикацию и обработку контрольного события;
создание нового задания пересчета поиска;
на одноразовой базе успешный возврат совместимого образа (для f62a9b7c4d11 — через восстановление резервной копии до R2).

Ошибка миграции

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

Понижение версии

Миграция f62a9b7c4d11 необратима: ее downgrade() вызывает RuntimeError. Вернуться ниже f62a9b7c4d11 можно только восстановлением базы из резервной копии, сделанной до применения R2.

Команда для снятия только третьей миграции:

uv run alembic downgrade b41f876a08c2

Она удаляет поля exposure и authorization таблицы invocation_route_projection_state и их сохраненные значения.

Команда для снятия только второй миграции:

uv run alembic downgrade e298f58dfdac

Она удаляет retired_generations и его содержимое. До выполнения сохраните сведения о прежних поколениях OpenSearch, которые еще нужны для возврата.

Переход ниже e298f58dfdac удаляет всю схему R1 и не является обычным откатом приложения. Для общей или промышленной среды он требует явного разрешения человека, проверенной резервной копии, плана восстановления и окна недоступности.

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

Подтвердите:

соответствие версии Alembic выбранному образу;
чтение канонических данных;
свежесть наблюдения Kubernetes;
правильную работу отношений SpiceDB;
сокращение транзакционной очереди;
сходимость активного поколения OpenSearch;
ответы защищенного API при разрешенном, запрещенном и недоступном SpiceDB;
отсутствие ручных изменений производных хранилищ.

Миграция Activity в ClickHouse

Activity использует таблицу activity.otel_logs в ClickHouse 26.8.10.6. Текущая версия схемы — activity-storage/v2. Схемой владеет продуктовый мигратор control_plane.activity_schema; установщик общего провайдера создаёт базу и учётные записи, но не подменяет миграцию приложения.

Переход	Изменение	Совместимость возврата
Новая установка → `v2`	Создание таблицы и вычисляемых колонок, проверка схемы и установка маркера готовности	Нужен читатель `v2`
`v1` → `v2`	Добавление и заполнение типизированных `MATERIALIZED`-колонок `e_*`, `EventValid`, `EventFingerprint` в существующей таблице	Исходные данные сохраняются; прежний читатель `v1` отклоняет маркер `v2`
Готовая `v2` → `v2`	Проверка фактических колонок, выражений, движка, сортировки, TTL и маркера	Повторное заполнение готовой схемы не запускается

Вычисляемые колонки ускоряют чтение и проверку события. Это та же таблица исходных фактов, а не новая витрина агрегатов. Версия схемы хранения и профиль нормализации agentgateway-1.5-conservative/v2 различаются: миграция не может восстановить сведения о токенах, потерянные источником до записи.

Подготовка Activity

Зафиксируйте образы CP, ClickHouse и Collector, профиль нормализации и текущую версию схемы. Проверьте доступность образа CP, совместимого с v2, для возврата.
Подтвердите резервную копию и восстановление на отдельном экземпляре. Копия на временной файловой системе проверки не является постоянным хранилищем резервных копий.
Оцените место на томе ClickHouse и время заполнения колонок на сопоставимой истории. Итоговая нагрузочная квалификация AU-I05 ещё не завершена; успешная миграция небольшой таблицы не задаёт длительность для любой нагрузки.
Сохраните исходный PVC очереди Collector и её конфигурацию. Возврат приложения не должен удалять очередь или менять идентификатор её хранилища.
Предоставьте только миграционному заданию учётную запись migrator. Пользователи reader и collector не получают DDL-права.

Применение Activity

При activity.delivery.enabled=true продуктовый чарт создаёт конечное задание после установки или обновления Helm. Оно запускает поставляемую команду:

python -m control_plane.activity_schema --schema /activity/ddl.sql

Это команда внутри задания, с доставленными конфигурацией и Secret; вручную копировать пароль в командную строку не требуется. В основной композиции dev-local задание поставляет действие agent-platform-activity-schema (релиз aip-activity-schema в инфраструктурном пространстве имён). Штатный запуск из каталога deploy:

python3 scripts/dev_local_garden.py deploy agent-platform --yes

Мигратор добавляет недостающие колонки и дожидается заполнения существующих частей таблицы через MATERIALIZE COLUMN. Только после успешного завершения публикуется маркер activity-storage/v2. Ожидание заполнения ограничено 600 секундами, задание Helm — 900 секундами. Пока схема не готова, новый API возвращает activity_unavailable; работа инференса не зависит от чтения DDL.

После обновления проверьте:

успешное завершение миграционного задания и точное соответствие схеме v2;
повторный штатный запуск мигратора без повторного заполнения готовой v2;
запись нового контрольного события и чтение его через публичный API CP;
видимость старой истории в пределах 30 дней и применение текущих прав;
отсутствие DDL-прав у процессов чтения и доставки;
сохранение наблюдаемых ошибок и пропусков доставки при восстановлении.

Ошибка и совместимый возврат Activity

Если заполнение прервано или вышло за время ожидания, остановите продвижение релиза, сохраните очищенную диагностику задания и проверьте состояние мутаций ClickHouse. Не меняйте маркер готовности вручную. Штатный повторный запуск незавершённого перехода безопасно повторяет детерминированное заполнение.

Схема v2 не понижается при возврате образа CP. Оставьте совместимого читателя v2 либо временно отключите чтение Activity. Старый читатель v1 с маркером v2 несовместим, даже если исходные колонки сохранены. Не удаляйте вычисляемые колонки и не запускайте старую версию ClickHouse поверх нового каталога данных как способ возврата.

При отключении всего потока сначала отключите источники событий на обоих шлюзах и подтвердите применение их управляемой конфигурации. Затем дождитесь доставки принятых событий, сохраняя Collector, его PVC и совместимый ClickHouse. Нулевое значение одной метрики очереди само по себе не доказывает полноту доставки. Порядок проверки, сроки хранения и восстановление описаны в руководстве оператора.

План миграции данных платформы