Бэкенды хранения (Storage Backends)
Бэкенды хранения хранят исходные файлы, изображения из разбора и экспортируемые артефакты. В одном пространстве можно зарегистрировать несколько экземпляров, назначить экземпляр по умолчанию и отдельно выбрать место хранения для базы знаний.
Многоэкземплярное хранилище подходит для следующих сценариев:
- хранить материалы разных команд или проектов в отдельных бакетах, раздельно управляя использованием и правами;
- выбирать регион расположения бакета согласно требованиям к размещению данных;
- при миграции в облачное объектное хранилище позволять новым базам знаний использовать новый бэкенд, а существующим — продолжать обращаться к исходным файлам.
Регистрация и выбор бэкенда хранения
Admin пространства может регистрировать экземпляры и управлять ими в «Настройки → Хранилище»:
- Создайте бэкенд, выберите provider (
local/minio/cos/tos/s3/oss/ks3/obs, совпадает с provider хранилища в конвейере добавления документов), заполните параметры подключения (см. таблицу ниже). Список доступных значений ограничен переменной окруженияSTORAGE_ALLOW_LIST; пустое значение означает, что доступны все; - Проверить подключение: проверка реально читает и записывает в хранилище, проверяя эндпоинт, бакет и учётные данные;
- Назначьте экземпляр используемым по умолчанию в пространстве. Когда при создании базы знаний экземпляр не указан, используется это значение по умолчанию;
- Если нужно указать отдельно, выберите экземпляр на вкладке «Хранилище» в диалоге редактирования базы знаний.
Пока база знаний пуста, можно изменить бэкенд хранения; при наличии файлов интерфейс запрещает выбор и предлагает миграцию. Пути к файлам зависят от бэкенда на момент добавления, и прямая замена повлияет на доступ к исходным файлам. Если замена необходима, следует создать новую базу знаний и перенести содержимое.
Параметры подключения
Разные provider используют общий набор полей конфигурации; access_key_id / secret_access_key сохраняются в зашифрованном виде и в ответах интерфейса показываются замаскированными.
| Название | Тип | По умолчанию | Описание |
|---|---|---|---|
endpoint | string | пусто | Адрес сервиса. Обязателен для minio (mode=remote), tos, s3, oss, ks3, obs; для cos не требуется. При сохранении выполняется проверка SSRF; адреса внутренней сети нужно добавить в SSRF_WHITELIST |
region | string | пусто | Регион. Обязателен для cos, tos, s3, oss, ks3, obs |
access_key_id / secret_access_key | string | пусто | Ключ доступа; для COS соответствуют SecretId / SecretKey. Не требуются для local и MinIO в режиме mode=docker |
bucket_name | string | пусто | Бакет, обязателен для всех, кроме local |
path_prefix | string | пусто | Префикс ключа объекта, должен быть относительным путём, не может начинаться с / или содержать .. |
mode | string | remote | Только MinIO: docker использует MinIO из состава развёртывания (адрес и ключ берутся из переменных окружения вроде MINIO_ENDPOINT), remote подключается к внешнему MinIO |
use_ssl | bool | false | Использовать ли HTTPS для MinIO, S3, OBS |
force_path_style | bool | false | Только S3: использовать path-style адресацию; для большинства S3-совместимых сервисов её нужно включить |
app_id | string | пусто | Только COS: AppID облачного вендора |
temp_bucket_name / temp_region | string | пусто | Только COS, TOS, OSS: бакет и регион для временных файлов; для OSS дополнительно требуется use_temp_bucket=true |
- OBS: когда endpoint — домен, используется адресация через виртуальный хост (
<bucket>.<endpoint>); Huawei Cloud с 2023-12-30 отклоняет path-style запросы к endpoint-домену; когда endpoint — IP, по-прежнему используется path-style. Если домен прокси не настроен, URL файла имеет вид<scheme>://<bucket>.<endpoint-host>/<key>. - Таймаут передачи: для одиночной загрузки/скачивания в S3, COS, KS3, OBS, OSS больше нет общего ограничения в 30 секунд — вместо этого одна передача может длиться до 30 минут; установка соединения, TLS-рукопожатие и ожидание заголовков ответа по-прежнему имеют собственные таймауты, и при потере связи с противоположной стороной сбой происходит достаточно быстро.
- Редиректы KS3: при следовании редиректам на каждом переходе выполняется проверка SSRF, и подпись запроса больше не пересылается на хост-цель редиректа.
Отличия от векторного хранилища
Файловое и векторное хранилища управляют соответственно исходными файлами и индексом поиска:
| Бэкенд хранения (Storage Backend) | Векторное хранилище (Vector Store) | |
|---|---|---|
| Что хранит | Исходные файлы, изображения, экспортируемые артефакты | Векторы и индекс поиска |
| Где настраивается | «Настройки → Хранилище» | «Настройки → Векторное хранилище» |
| Поле базы знаний | storage_backend_id | vector_store_id |
| Связанный раздел | Этот документ | Движки поиска и векторное хранилище |
Справочник по интерфейсам
| Метод | Путь | Права |
|---|---|---|
| GET | /storage-backends/types | Viewer+, возвращает список имён provider, разрешённых в STORAGE_ALLOW_LIST |
| GET | /storage-backends, /storage-backends/:id | Viewer+ |
| POST | /storage-backends | Admin+ |
| PUT / DELETE | /storage-backends/:id | Admin+ |
| POST | /storage-backends/test | Admin+, пробное подключение с несохранёнными параметрами |
| POST | /storage-backends/:id/test | Admin+, проверка сохранённого экземпляра |
| PUT | /storage-backends/:id/default | Admin+, назначить используемым по умолчанию в пространстве |
API Key требует возможности manage_storage_backends или full-access.
Модель данных и правила совместимости
Ключевые поля таблицы storage_backends (изоляция по tenant_id, мягкое удаление):
| Поле | Описание |
|---|---|
name | Уникально в пространстве (частичный уникальный индекс с учётом мягкого удаления) |
provider | Тип хранилища |
config | JSONB, содержит зашифрованные ключи |
source | user (регистрация через интерфейс или API) / env (создано конфигурацией переменных окружения) |
status | active / disabled |
legacy_alias | см. ниже |
legacy_alias служит для совместимости с историческими хранилищами, заданными через переменные окружения. При обновлении создаётся запись-псевдоним, чтобы существующие пути к файлам продолжали разрешаться без переноса данных. В одном пространстве для одного provider допускается только одна запись-псевдоним; зарегистрированные вручную экземпляры хранятся отдельно.