Skip to main content

Обзор

Yahont с самостоятельным размещением поставляет S3-совместимое хранилище для файлов, которые он держит вне PostgreSQL. До сих пор таким хранилищем был MinIO. MinIO заархивировал свою community-редакцию и удалил публичные образы, поэтому Yahont заменяет его на SeaweedFS, который работает как сервис под названием объектное хранилище. При обновлении существующие файлы переносятся автоматически, без простоя и с безопасным откатом. Установки, которые уже используют внешнее хранилище (AWS S3, Google Cloud Storage, Azure Blob Storage или другой S3-совместимый сервис), не затрагиваются, как и Yahont Cloud.

Что хранит объектное хранилище

В объектном хранилище лежит единственная копия содержимого каждого файла, который хранит Yahont. PostgreSQL хранит указатели на эти файлы, а OpenSearch — поисковый индекс, но сами данные находятся только здесь:
  • Файлы, прикреплённые к чатам, и изображения, сгенерированные в чатах
  • Файлы, загруженные в проекты и пользовательскую библиотеку
  • Документы, загруженные через коннектор «Загрузка файлов»
  • Снимки песочниц Craft и история кодинга
  • Ресурсы брендинга Enterprise, например логотип
  • Изображения и вложения, извлечённые из документов коннекторов во время индексации
  • Контрольные точки индексации, сформированные отчёты, история запросов и выгрузки логов
Если запустить новое хранилище пустым, сломаются все вложения в старых чатах, навсегда пропадут загруженные документы и работа в Craft, а брендинг исчезнет. Только изображения из коннекторов возвращаются при повторной индексации. Поэтому при обновлении всё копируется, а не начинается с чистого листа.

Миграция

Объектное хранилище поставляется в v5.0.0 (Helm-чарт 0.9.0), это повышение основной версии. Этот выпуск на время перехода запускает оба хранилища рядом:
  • Приложение записывает и удаляет каждый файл и в объектном хранилище, и в MinIO, поэтому при откате файл найдётся.
  • Чтение, которое не нашло файл в объектном хранилище, обращается к MinIO.
  • Задание копирования переносит из MinIO в объектное хранилище каждый файл, который отслеживает Yahont. Оно никогда не заменяет файл, записанный приложением, кроме случая, когда после отката более старый выпуск записал более новую версию, и пропускает объекты, на которые не указывает ни одна запись о файле.
Администратору ничего вводить не нужно, кроме самого обновления. Приложение сразу начинает работать, а копирование идёт рядом.

Docker Compose

Сервис object-store запускает SeaweedFS на собственном томе object_store_data, а сервис object-store-copy выполняет копирование. Обновления через Yahont CLI сами переключают приложение на объектное хранилище и оставляют MinIO как запасной вариант. Следите за копированием командой:
Он пишет в лог прогресс по страницам объектов и завершается строкой Legacy MinIO copy complete. Копирование заканчивается только после прохода, при котором ничего не скопировано, и когда с его начала прошло LEGACY_COPY_SETTLE_SECONDS (по умолчанию 600). Если какие-то объекты скопировать не удалось, он пишет их ключи в лог и повторяет попытку каждые пять минут. Приложение в это время продолжает работать с обоими хранилищами.

Обновление вручную

Если вы запускаете docker compose сами, а не через CLI, новый выпуск стартует с вашим старым .env. В установке со встроенным MinIO (S3_ENDPOINT_URL=http://minio:9000) приложение остаётся на MinIO: объектное хранилище и сервис копирования работают пустыми, а приложение продолжает писать файлы в MinIO, который удалит более поздний выпуск. Внесите эти два изменения в .env перед docker compose up. Установке на внешнем хранилище (S3, GCS, Azure) изменения не нужны.
  1. Задайте S3_ENDPOINT_URL=http://object-store:8333.
  2. Добавьте S3_LEGACY_ENDPOINT_URL=http://minio:9000.
Ничего не сломается, если вы забудете: приложение работает с MinIO, как раньше, а логи api_server и object-store-copy при запуске предупреждают, что файлы всё ещё в MinIO, и называют эти две настройки. Копирование начнётся, когда вы перезапустите с этими значениями. Держите MINIO_REPLICAS незаданным или равным 1, пока не выведете MinIO из работы. env.template задаёт 0, это подходит только для чистой установки.
То же относится к случаю, когда CLI обновляет установку, в .env которой встроенный MinIO доступен по любому адресу, кроме http://minio:9000: CLI этот endpoint не трогает, поэтому внесите оба изменения сами, задав в S3_LEGACY_ENDPOINT_URL адрес, который использовал ваш .env.

Helm

Чарт 0.9.0 добавляет раздел objectStore и задание <fullname>-legacy-minio-copy-<hash>, где <fullname> — имя релиза, если оно содержит onyx, и <release>-onyx в остальных случаях. Субчарт MinIO получает только аннотацию keep на свой PVC, поэтому его под не перезапускается. Следите за копированием командой:
Это обычное задание (Job), а не хук Helm, поэтому helm upgrade возвращается, не дожидаясь его. Работают --reuse-values, ArgoCD, Flux и отрендеренные манифесты. Если задание завершилось с ошибкой, устраните причину, удалите его и выполните обновление снова, чтобы запустить заново. Повторный запуск пропускает уже скопированные объекты. Перед обновлением проверьте, что новый PVC <fullname>-object-store вместит все данные MinIO. Он берёт размер и класс хранилища из minio.persistence, пока вы не задали objectStore.persistence. MIGRATION.md чарта описывает реестры без доступа в интернет, безопасность подов и OpenShift.

Сколько это занимает

Копирование идёт со скоростью пары сотен файлов в секунду, а для больших файлов около 165 МБ/с. Об окончании оно сообщает только после проверочного прохода, который не находит ничего нового для копирования, и когда с начала прошло десять минут. Проход занимает около 20 минут на миллион файлов. Измерения на копии реальной установки и на синтетическом хранилище из миллиона файлов: Оба хранилища содержат все файлы, пока вы не выведете MinIO из работы. См. размер.
Копирование можно безопасно прервать. Если копировщик, MinIO, объектное хранилище или PostgreSQL остановятся посреди копирования, оно остановится примерно через минуту, а следующий запуск продолжит с того же места. Ничего не теряется, потому что приложение продолжает писать в оба хранилища и читать из любого.

Откат

Откат на предыдущий выпуск снова направляет приложение в MinIO. В MinIO есть все файлы, включая загруженные после обновления, потому что переходный выпуск пишет в оба хранилища. Том объектного хранилища остаётся, и следующее обновление продолжит копирование. Yahont CLI и Helm возвращают endpoint сами. В .env, который вы ведёте вручную, снова задайте S3_ENDPOINT_URL=http://minio:9000 и очистите S3_LEGACY_ENDPOINT_URL перед запуском более старого выпуска. Откат не меняет схему базы данных. Более старый выпуск не запускается на схеме v5.0.0 с ошибкой Can't locate revision. Миграции для понижения есть только в образе v5.0.0. Выполняйте откат в таком порядке.
1

Воспроизведите записи, которые пропустил MinIO

Файл, записанный, пока MinIO был недоступен, попадает в MinIO только после повтора неудачной записи. В Compose сервис копирования повторяет её в течение пяти минут после того, как MinIO снова ответил. В Helm повтор происходит при следующем запуске копирования. Если у MinIO был сбой после завершения задания, удалите задание, выполните обновление снова и дождитесь завершения.
2

Понизьте схему базы данных

Понижение удаляет данные, которые хранит только v5.0.0, например дочерние сессии чата, гранты и токены OAuth, выданные Yahont, и личные настройки инструментов MCP и OpenAPI.
В Compose выполните команду из каталога с файлами Compose. В prod-установке добавьте -f docker-compose.prod.yml после docker compose. Если docker compose ls показывает имя проекта, отличное от onyx, добавьте -p <project>.
В Helm:
25053020dd5a — последняя миграция v4.9. Для другого выпуска получите её командой docker run --rm onyxdotapp/onyx-backend:<version> alembic heads.
3

Сразу откатите выпуск

Приложение возвращает ошибки, пока не запущен более старый выпуск. API-сервер v5.0.0, перезапустившийся до этого, снова обновит схему. Запустите onyx-cli оттуда, откуда вы обычно его запускаете, или передайте --dir <install root>. Он предупредит, что понижение не поддерживается. Продолжайте, потому что схема уже соответствует.
Если вы откатили выпуск раньше, более старый API-сервер перезапускается в цикле. Выполните команду понижения из шага 2. В Helm kubectl exec выбирает готовый под, который всё ещё работает на v5.0.0.

Вывод MinIO из работы

После завершения копирования MinIO можно остановить, не дожидаясь следующего выпуска. После этого откат на выпуск до объектного хранилища больше не увидит файлы, загруженные с этого момента.
1

Выполните команду вывода

В Compose:
В Helm, из пода API-сервера:
Команда копирует всё оставшееся, ждёт спокойную минуту и проверяет, что за это время ничего не попало только в MinIO. Если попало, значит, контейнер или под на более старом выпуске всё ещё работает, поэтому она отказывается, и MinIO остаётся в работе. Иначе она записывает метку в объектное хранилище, и в течение минуты каждый запущенный процесс перестаёт писать в MinIO. Перезапуск не нужен.
2

Остановите MinIO

В Compose задайте MINIO_REPLICAS=0 в .env, затем остановите MinIO и object-store-copy, не перезапуская приложение:
Том minio_data остаётся, пока вы его не удалите.В Helm сначала убедитесь, что у PVC MinIO есть аннотация keep, так как обновление с --reuse-values может пропустить ту, которую добавляет чарт:
Затем задайте minio.enabled: false и objectStore.enabled: true и выполните обновление. PVC MinIO остаётся, пока вы его не удалите.

Прекращение поддержки MinIO

Более поздний выпуск полностью уберёт MinIO из встроенного развёртывания.
Обновитесь через v5.0.0 и дождитесь завершения копирования, прежде чем переходить на выпуск, в котором MinIO больше не поставляется. Если пропустить этот шаг, ваши файлы останутся в томе MinIO, который новый выпуск не читает, и каждое вложение чата, загрузка, снимок Craft и ресурс брендинга будут недоступны, пока вы не вернётесь и не выполните копирование.