> ## 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.

# S3 (совместимые хранилища)

> Загрузка файлов из любого хранилища с S3 API, включая Yandex Object Storage и MinIO

## Как это работает

Коннектор «S3 (совместимые хранилища)» подключается к любому объектному хранилищу с S3 API — как к управляемому облаку
(Yandex Object Storage, VK Cloud, Selectel, Cloud.ru, Timeweb Cloud), так и к собственному серверу (MinIO, Ceph,
SeaweedFS). В отличие от коннекторов AWS S3, Cloudflare R2, Google Storage и Oracle Storage,
у которых адрес сервера зашит заранее, здесь вы указываете его сами.

Коннектор только читает хранилище: получает список объектов и скачивает их. Он ничего не меняет и не удаляет в бакете.

Один коннектор индексирует один бакет и, необязательно, один префикс (путь внутри бакета).
Для нескольких бакетов или нескольких непересекающихся префиксов нужно несколько коннекторов.
Индексируются файлы под указанным префиксом; ключи, которые оканчиваются на `/` («папки» в интерфейсе хранилища),
пропускаются.

Коннектор разбирает текстовые файлы и документы — PDF, DOCX, TXT и другие. Таблицы в формате XLSX разбираются по листам,
а CSV и TSV — как обычный текст.

Картинки индексируются, только если в [Настройках индекса](/admins/advanced_configs/search_configs)
включено **«Извлечение и описание изображений»**. Для этого нужна vision-модель, и её вызовы расходуют деньги.
Если настройка выключена, картинки пропускаются без предупреждения.

> [!NOTE]
>
> Файлы крупнее **20 МБ** не индексируются. Интерфейс об этом не сообщает — такой файл просто не попадает в индекс,
> а предупреждение остаётся только в логе.

Документ получает дату последнего изменения файла в хранилище — по ней чат отвечает на вопросы вроде «когда загрузили
этот файл». В ответах чата источник подписан «S3 (совместимые хранилища)», а ссылка ведёт на сам объект в хранилище,
в формате `{адрес хранилища}/{бакет}/{ключ}`. Если бакет закрытый,
такая ссылка в браузере откроет отказ в доступе — это поведение самого хранилища, а не коннектора.

Синхронизации прав по отдельным объектам нет.
Доступ к документам этого коннектора определяется только его настройкой доступа (приватный, публичный или по группам),
как у любого другого коннектора.

## Настройка

### Авторизация у провайдера

**1. Создайте сервисный ключ только на чтение**

В консоли своего провайдера создайте ключ доступа (Access Key ID и Secret Access Key) с правами только на чтение:
список объектов бакета и чтение объектов. Если провайдер разделяет пользователей и сервисные аккаунты,
заведите для коннектора отдельный сервисный аккаунт — это упростит отзыв доступа в будущем.

Официальная документация по созданию ключей:

* [Yandex Object Storage](https://yandex.cloud/ru/docs/iam/operations/authentication/manage-access-keys)
* [VK Cloud](https://cloud.vk.com/docs/ru/storage/s3/instructions/access-management/access-keys)
* [Selectel](https://docs.selectel.ru/s3/manage/manage-access/)
* [Cloud.ru](https://cloud.ru/docs/s3e/ug/topics/api__api-key)
* [Timeweb Cloud](https://timeweb.cloud/docs/s3-storage/manage-storage/s3-guide)

Для собственного сервера (MinIO, Ceph, SeaweedFS и другие) создайте ключ по документации вашего дистрибутива.

> [!NOTE]
>
> Для остальных провайдеров ориентируйтесь на их официальную документацию:
> названия пунктов в консоли провайдера могут отличаться от описанных здесь.

### Индексирование

**1. Откройте коннектор «S3 (совместимые хранилища)»**

Откройте панель администратора и выберите коннектор **S3 (совместимые хранилища)**.

**2. Создайте учётные данные**

Укажите:

* **S3 (совместимые хранилища) Access Key ID**: идентификатор ключа, созданного на предыдущем шаге.
* **S3 (совместимые хранилища) Secret Access Key**: секретный ключ.

**3. Настройте сведения о коннекторе**

Укажите **API-endpoint** (обязательно) — адрес API вашего хранилища:

| Провайдер | API-endpoint |
| - | - |
| Yandex Object Storage | `https://storage.yandexcloud.net` |
| VK Cloud | `https://hb.ru-msk.vkcloud-storage.ru` |
| Selectel | `https://s3.ru-1.storage.selcloud.ru` (или `ru-7`, `gis-1` — в зависимости от пула бакета) |
| Cloud.ru | `https://s3.cloud.ru` |
| Timeweb Cloud | `https://s3.twcstorage.ru` |
| Собственный сервер (MinIO и другие) | адрес вашего сервера |

Также укажите:

* **Название бакета** (обязательно): имя бакета для индексации.
* **Регион** (необязательно): регион хранилища, например `ru-central1` у Yandex Object Storage
  или `ru-1` у Timeweb Cloud. У большинства собственных серверов поле не нужно.
* **Префикс** (необязательно): путь внутри бакета, если нужно индексировать не весь бакет.

**4. Запустите проверки**

Нажмите **«Запустить проверки»**: Yahont подключится к хранилищу и подтвердит доступ к бакету,
прежде чем разрешит создать коннектор.

**5. Создайте коннектор**

После успешных проверок создайте коннектор. Индексация начнётся автоматически.

Коннектор опрашивает бакет каждые **30 минут** (поле **«Обновлять каждые»**).
Поле **«Индексировать документы после»** ограничивает глубину истории по дате изменения файла.
Поле **«Очищать каждые»** (по умолчанию 168 часов, то есть 7 дней) убирает из индекса файлы,
которых больше нет в бакете.

> [!WARNING]
>
> Для этого коннектора очистка — не лёгкая проверка, а полный проход:
> Yahont заново скачивает и разбирает каждый файл бакета, чтобы понять, какие из них удалены.
> Для большого бакета не ставьте частую очистку и учитывайте плату провайдера за исходящий трафик.

### Адрес и безопасность

> [!NOTE]
>
> **В облаке Yahont** в поле **API-endpoint** допустим только публичный адрес по `https`.
> Этого достаточно для всех пяти перечисленных выше провайдеров. Собственный сервер в закрытой сети клиента (например,
> свой MinIO в офисе) из облака Yahont недоступен.
>
> **При самостоятельном размещении** собственный сервер в закрытой сети становится доступен,
> только если администратор включит в **Панели администратора → Организация → Безопасность и защита**,
> раздел [«Защита от SSRF»](/admins/advanced_configs/security_hardening#ssrf-protection),
> вариант **«Разрешить частную сеть»** или строже не требуется. Тогда допустим и адрес по `http`.
> Адрес облачных метаданных заблокирован всегда; адрес `127.0.0.1` разрешён только при значении **«Отключено»**.

### Поле «Адресация бакета»

В расширенных настройках коннектора есть поле **«Адресация бакета»** со значениями `auto`, `path` и `virtual`.
По умолчанию `auto` — этого достаточно, например, для Timeweb Cloud.
Если проверка подключения падает с ошибкой адреса или подписи, попробуйте сначала `path`, затем `virtual`.
Это общая рекомендация, а не гарантия для каждого провайдера: подходящее значение зависит от того,
как провайдер формирует адрес бакета.

## Ограничения

* Один коннектор индексирует один бакет.
* Файлы крупнее 20 МБ не индексируются.
* Удалённый из бакета файл пропадает из поиска только после очистки — по умолчанию до 7 дней.
* Очистка скачивает и разбирает все файлы бакета заново (см. предупреждение выше).
* Синхронизации прав по отдельным объектам нет: доступ определяется только настройкой доступа коннектора.
* Ссылка на объект в закрытом бакете не откроется в браузере.
* Картинки индексируются только при включённом извлечении и описании изображений, с расходом на вызовы vision-модели.
* В Yahont Cloud проиндексированные файлы расходуют квоту фрагментов документов тарифа.


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