> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yahont.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Миграция объектного хранилища

> Перенос файлов из встроенного MinIO в объектное хранилище SeaweedFS

## Обзор

Yahont с самостоятельным размещением поставляет S3-совместимое хранилище для файлов, которые он держит вне PostgreSQL.
До сих пор таким хранилищем был MinIO. MinIO заархивировал свою community-редакцию и удалил публичные образы,
поэтому Yahont заменяет его на [SeaweedFS](https://github.com/seaweedfs/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](https://docs.yahont.ai/deployment/local/yahont_cli.md)
сами переключают приложение на объектное хранилище и оставляют MinIO как запасной вариант.

Следите за копированием командой:

```bash theme={null}
docker compose logs -f object-store-copy
```

Он пишет в лог прогресс по страницам объектов и завершается строкой `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`,
это подходит только для чистой установки.

> [!NOTE]
>
> То же относится к случаю, когда CLI обновляет установку, в `.env` которой встроенный MinIO доступен по любому адресу,
> кроме `http://minio:9000`: CLI этот endpoint не трогает, поэтому внесите оба изменения сами,
> задав в `S3_LEGACY_ENDPOINT_URL` адрес, который использовал ваш `.env`.

### Helm

Чарт `0.9.0` добавляет [раздел `objectStore`](https://docs.yahont.ai/deployment/local/object_store)
и задание `<fullname>-legacy-minio-copy-<hash>`, где `<fullname>` — имя релиза, если оно содержит `onyx`,
и `<release>-onyx` в остальных случаях. Субчарт MinIO получает только аннотацию keep на свой PVC,
поэтому его под не перезапускается.

Следите за копированием командой:

```bash theme={null}
kubectl logs -f -n <namespace> -l app=legacy-minio-copy
```

Это обычное задание (Job), а не хук Helm, поэтому `helm upgrade` возвращается, не дожидаясь его.
Работают `--reuse-values`, ArgoCD, Flux и отрендеренные манифесты. Если задание завершилось с ошибкой,
устраните причину, удалите его и выполните обновление снова, чтобы запустить заново.
Повторный запуск пропускает уже скопированные объекты.

Перед обновлением проверьте, что новый PVC `<fullname>-object-store` вместит все данные MinIO.
Он берёт размер и класс хранилища из `minio.persistence`, пока вы не задали `objectStore.persistence`.
`MIGRATION.md` чарта описывает реестры без доступа в интернет, безопасность подов и OpenShift.

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

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

| Хранилище | Копирование | Сообщение о завершении |
| - | - | - |
| 22 000 файлов, 4,8 ГБ (копия реальной установки) | менее 3 минут | около 13 минут |
| 1 000 000 файлов, 174 ГБ | 80 минут | около 2 часов |

Оба хранилища содержат все файлы, пока вы не выведете MinIO из работы. См.
[размер](https://docs.yahont.ai/deployment/local/object_store.md#sizing).

> [!NOTE]
>
> Копирование можно безопасно прервать. Если копировщик, 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. Понизьте схему базы данных**

> [!WARNING]
>
> Понижение удаляет данные, которые хранит только `v5.0.0`, например дочерние сессии чата, гранты и токены OAuth,
> выданные Yahont, и личные настройки инструментов MCP и OpenAPI.

В Compose выполните команду из каталога с файлами Compose.
В prod-установке добавьте `-f docker-compose.prod.yml` после `docker compose`.
Если `docker compose ls` показывает имя проекта, отличное от `onyx`, добавьте `-p <project>`.

```bash theme={null}
IMAGE_TAG=<v5 version> docker compose run --rm --no-deps api_server alembic downgrade 25053020dd5a
```

В Helm:

```bash theme={null}
kubectl exec -n <namespace> deploy/<fullname>-api-server -- alembic downgrade 25053020dd5a
```

`25053020dd5a` — последняя миграция `v4.9`.
Для другого выпуска получите её командой `docker run --rm onyxdotapp/onyx-backend:<version> alembic heads`.

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

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

```bash theme={null}
# Compose
onyx-cli deploy upgrade --tag <older version> --allow-downgrade
# Helm
helm rollback -n <namespace> <release> <revision>
```

Если вы откатили выпуск раньше, более старый API-сервер перезапускается в цикле. Выполните команду понижения из шага 2.
В Helm `kubectl exec` выбирает готовый под, который всё ещё работает на `v5.0.0`.

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

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

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

В Compose:

```bash theme={null}
docker compose exec object-store-copy python -m onyx.file_store.legacy_copy --retire
```

В Helm, из пода API-сервера:

```bash theme={null}
kubectl exec -n <namespace> deploy/<fullname>-api-server -- \
  python -m onyx.file_store.legacy_copy --retire
```

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

**2. Остановите MinIO**

В Compose задайте `MINIO_REPLICAS=0` в `.env`, затем остановите MinIO и `object-store-copy`,
не перезапуская приложение:

```bash theme={null}
docker compose up -d --no-deps minio object-store-copy
```

Том `minio_data` остаётся, пока вы его не удалите.

В Helm сначала убедитесь, что у PVC MinIO есть аннотация keep,
так как обновление с `--reuse-values` может пропустить ту, которую добавляет чарт:

```bash theme={null}
kubectl annotate pvc -n <namespace> <release>-minio helm.sh/resource-policy=keep --overwrite
```

Затем задайте `minio.enabled: false` и `objectStore.enabled: true` и выполните обновление. PVC MinIO остаётся,
пока вы его не удалите.

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

Более поздний выпуск полностью уберёт MinIO из встроенного развёртывания.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.