#Обновление

Этот документ содержит инструкции по обновлению Alauda Hyperflux до более новой версии.

#Стандартные шаги обновления

Для большинства обновлений версий (за исключением v1.2.0 → v1.2.1 и v1.3.x → v1.4.x) вы можете просто выполнить следующие шаги в консоли ACP:

1. Загрузите новый version пакета плагина в ACP Marketplace. Загрузите пакет тем же способом, что и при первоначальной установке. После завершения загрузки подождите примерно 10–15 минут, пока платформа автоматически синхронизирует информацию о новой версии.
2. Проверьте, что новая версия доступна в Marketplace. Перейдите в Administrator / Marketplace / Upload Packages. Переключитесь на вкладку Cluster Plugin и убедитесь, что для плагина Hyperflux отображается новый номер версии.
3. Выполните операцию обновления на кластере. Перейдите в Administrator / Clusters / Clusters. Найдите кластер, в котором установлен плагин Hyperflux; в записи кластера будет отображаться значок обновления. Нажмите, чтобы открыть сведения о кластере, и переключитесь на вкладку Features. В карточке плагина Hyperflux нажмите кнопку Upgrade и подтвердите операцию.
4. Проверьте результат обновления. После завершения обновления убедитесь, что номер версии обновлен на вкладке Features. Проверьте нормальную работу через мониторинг состояния плагина или журналы.

#Обновление с v1.3.x до v1.4.x (Переход на другую embedding model)

ВАЖНО: в v1.4.0 поставляется новая embedding model (gte-multilingual-base, заменяющая paraphrase-multilingual-mpnet-base-v2). Векторные пространства несовместимы, поэтому system knowledge base необходимо повторно встроить. Chart выполняет это автоматически во время обновления — но перед применением обязательно прочитайте этот раздел, особенно если вы создали custom knowledge base.

#Что обновление выполняет автоматически

Когда новый chart разворачивается, init container сканирует docvec_sys_kb на наличие любой устаревшей mpnet collection, которая соответствует правилу в smartdoc.acpKbUpgradeRules (по умолчанию: ACP 4.1 и ACP 4.2 mpnet collections), затем:

1. Получает PostgreSQL advisory lock с ключом acpKbDataVersion, чтобы init второго replica завершился корректно.
2. Записывает выполняемую замену в строку kb_swap_state (чтобы можно было восстановиться, если pod будет завершён в процессе swap).
3. Удаляет таблицы langchain_pg_embedding и langchain_pg_collection в docvec_sys_kb.
4. Выполняет pg_restore нового gte dump из /workspace-smart-doc/dumps/ (предупреждения о уже существующих extensions/ schemas допускаются, критические ошибки прерывают процесс).
5. Проверяет, что новое имя collection было создано (SELECT count(*) ... = 1); в противном случае процесс прерывается.
6. Переименовывает новую collection обратно в старое имя collection, чтобы работающий сервер продолжал выполнять запросы к тому же имени. Вам не нужно изменять pgconnect.pgCollectionName.
7. Пересоздает ParadeDB BM25 index, если в новом dump он не был включен (в последних gte dump он уже есть).
8. Помечает schema_migrations записью 003_data_swap_<old_collection>_<acpKbDataVersion> и очищает выполняющуюся строку kb_swap_state.
9. После возврата блока swap безусловный цикл миграций повторно применяет doc_id btree (001_add_doc_id_index) и URL-backfill (002_backfill_doc_id_from_url) к только что восстановленной таблице — блок swap сбрасывает их отметки, чтобы цикл считал их "не примененными" и запускал их.

Swap является:

• Идемпотентным — повторный rollout chart без изменения acpKbDataVersion не выполняет никаких действий.
• Устойчивым к сбоям — завершение pod между DROP и RESTORE можно восстановить при следующем запуске.
• Безопасным для нескольких replica — PostgreSQL advisory lock с ключом acpKbDataVersion сериализует swap.

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

При swap старая collection удаляется и заменяется новыми данными; старые mpnet vectors не сохраняются. Хотя поставляемые вместе dump воспроизводимы, перед обновлением создайте резервную копию docvec_sys_kb и docvec_user_kb, чтобы можно было откатиться, если что-то пойдет не так:

# Get the PostgreSQL pod name (if using the built-in database)
kubectl -n cpaas-system get pod | grep postgre-vec

# Dump both knowledge-base databases. The default password for the built-in PostgreSQL
# instance is `alauda-test`; pg_dump will prompt for it. To suppress the prompt, prefix
# with `PGPASSWORD=alauda-test ` inside the exec.
kubectl -n cpaas-system exec -it <postgre-vec-xxx> -- pg_dump -U postgres -W -Fc \
  -d docvec_sys_kb -f /tmp/docvec_sys_kb.backup.dump
kubectl -n cpaas-system exec -it <postgre-vec-xxx> -- pg_dump -U postgres -W -Fc \
  -d docvec_user_kb -f /tmp/docvec_user_kb.backup.dump

# Copy them to your local machine
kubectl -n cpaas-system cp <postgre-vec-xxx>:/tmp/docvec_sys_kb.backup.dump ./docvec_sys_kb.backup.dump
kubectl -n cpaas-system cp <postgre-vec-xxx>:/tmp/docvec_user_kb.backup.dump ./docvec_user_kb.backup.dump

docvec_user_kb и база данных истории чата не затрагиваются этим swap — однако резервная копия не будет лишней.

#Выполнение обновления

Выполните указанные выше Стандартные шаги обновления. Init container автоматически выполнит swap при первом перезапуске smart-doc pod в новой версии.

#Проверка обновления

Просматривайте журнал init container и убедитесь, что swap завершился успешно:

kubectl -n cpaas-system logs -l app=smart-doc -c init-database | grep '\[upgrade\]'

При успешном swap выводятся строки вида:

[upgrade] swap docvec_mpnet_acp_4_1_1215 (in docvec_sys_kb) -> dump docvec_gte_acp_4_1_20260508.dump; final name=docvec_gte_acp_4_3_20260508
[upgrade] 003_data_swap_docvec_mpnet_acp_4_1_1215_20260508-gte-acp-4-x applied.

Повторный rollout после завершения swap выводит вообще ни одной строки [upgrade] — сканирование rules не находит подходящей collection (старое имя было переименовано в pgconnect.pgCollectionName на шаге 6), и блок swap завершается без вывода. Отсутствие строки журнала при последующих rollout — это ожидаемое состояние после swap.

Строка [upgrade] ... already applied, skipping. зарезервирована для сценария восстановления: в kb_swap_state существует запись для stamp, который уже был применен (например, pod был завершен после записи stamp, но до очистки inflight-строки). Это не обычный вывод при идемпотентном повторном rollout.

После того как smart-doc pod перейдет в состояние Ready, выполните в chat UI типовой вопрос, чтобы убедиться, что ответы основаны на новом corpus.

#Особый случай: вы поддерживаете custom knowledge base

Если ранее вы следовали инструкции Создание custom knowledge base на модели v1.3.x mpnet, vectors в вашей custom collection несовместимы с сервером v1.4.0. Вам необходимо:

1. Перед обновлением: перестроить вашу custom KB с gte-multilingual-base (см. связанную инструкцию).
2. Заменить встроенные acpKbUpgradeRules на одно правило для вашей custom collection:

   smartdoc:
     acpKbDataVersion: "20260512-custom-gte"  # bump to re-arm the swap
     acpKbUpgradeRules: |
       <your_mpnet_collection_name>  <your-gte-collection-name>.dump  <your-gte-collection-name>
   Встроенные ACP rules здесь не применяются — развертывание с custom KB уже заменило эти collections в v1.3.x, поэтому встроенные OLD имена не совпадут. Оставлять их в списке rules безвредно, но это загромождает конфигурацию.
3. Применить обновление.

ПРИМЕЧАНИЕ: Init container обрабатывает только первое правило, для которого найдена OLD collection, в docvec_sys_kb за один запуск, а затем выходит из блока swap. DROP и восстановление очищают всю таблицу langchain_pg_collection, поэтому chart поддерживает только одну system-KB collection одновременно. Если вам нужно сохранить и custom corpus, и встроенный ACP corpus, загрузите их в одном запуске prepare (см. раздел Caveats в инструкции build-custom-kb) и поставьте один объединенный dump.

Если вы пропустите шаг 1, chart все равно обновится, но retrieval по устаревшей custom collection будет возвращать ноль результатов, а ответы будут сводиться к "I don't have enough information".

#Обновление с v1.2.0 до v1.2.1 (Особый случай)

ВАЖНО: Обновление с v1.2.0 до v1.2.1 приведет к повторной инициализации knowledge base. Вы обязаны вручную создать резервную копию и восстановить вашу базу данных, чтобы предотвратить потерю данных.

#Шаг 1: Резервное копирование Knowledge Base

Перед выполнением обновления выполните следующие команды:

# Get the PostgreSQL pod name (if using the built-in database)
kubectl -n cpaas-system get pod | grep postgre-vec

# Dump the database to a file
kubectl -n cpaas-system exec -it <postgre-vec-xxx> -- pg_dump -U postgres -d <your-database-name> -F c -f /tmp/hyperflux_backup.dump

# Copy the dump file to your local machine
kubectl -n cpaas-system cp <postgre-vec-xxx>:/tmp/hyperflux_backup.dump ./hyperflux_backup.dump

#Шаг 2: Выполнение обновления

Выполните описанные выше Стандартные шаги обновления, чтобы обновить версию плагина через консоль ACP.

#Шаг 3: Восстановление Knowledge Base

После завершения обновления восстановите ваши данные:

# Get the new PostgreSQL pod name
kubectl -n cpaas-system get pod | grep postgre-vec

# Copy the backup dump file back to the pod
kubectl -n cpaas-system cp ./hyperflux_backup.dump <postgre-vec-xxx>:/tmp/hyperflux_backup.dump

# Restore the database from the dump file
kubectl -n cpaas-system exec -it <postgre-vec-xxx> -- pg_restore -U postgres -d <your-database-name> /tmp/hyperflux_backup.dump

# (Optional) Update configuration if your database/collection name changed
kubectl -n cpaas-system edit configmap smart-doc-config
# Update `PG_CONN_DB` and `PG_COLLECTION_NAME` fields if necessary.
# (Env-var rename: `PG_CONN_DB` was split into `PG_SYS_KB_DB` / `PG_HISTORY_DB` /
#  `PG_USER_KB_DB` in later versions. For a v1.4.x upgrade, see the embedding-switch
#  section above instead — the chart handles the data swap automatically.)

Дождитесь перезапуска pod Alauda Hyperflux и убедитесь, что knowledge base успешно восстановлена.