Хранение файлов в S3 для каналов

Данная статья описывает режим сохранения и выдачи файлов чатов через S3-совместимое хранилище. Режим включается на уровне аккаунта и поддерживает как каналы, принимающие вложения, так и каналы, в которых отправка файлов невозможна (в этом случае пользователю доставляется защищенная ссылка на скачивание).

Назначение и область применения

При включении режима S3:

• новые файлы посетителей и операторов сохраняются в S3-бакет

• ссылки на файлы формируются как пресайнд-URL с ограниченным сроком жизни

• ранее загруженные файлы (до включения S3) продолжают открываться из файловой системы без миграции

Если S3 недоступно, операции с файлами (загрузка, предпросмотр, скачивание, доставка в каналы) недоступны до восстановления соединения с S3.

N.B.

Пресайнд-URL (Presigned URL) — это временная ссылка, по которой можно получить доступ к приватному файлу в хранилище.

Включение режима

1. Создайте конфигурационный файл S3 на сервере:

   /etc/webim/s3.json
   

   Пример содержимого:

   {
     "config": {
       "default_connection": "default"
     },
     "connections": {
       "default": {
         "access_key": "КЛЮЧ_ДОСТУПА",
         "secret_key": "СЕКРЕТ",
         "host": "https://s3.ru-1.storage.selcloud.ru",
         "region": "ru-1",
         "bucket_name": "НАЗВАНИЕ_БАКЕТА",
         "connect_timeout": 5,
         "read_timeout": 5,
         "max_retries": 3
       }
     }
   }
   

2. Включите параметр аккаунта:

3. use_s3_storage = true См. раздел «Параметры настроек сервера» и таблицу параметров.

4. Перезапустите сервисы, обслуживающие чат и файлы.

Правила формирования ключей объектов

Для новых файлов используется многоуровневая структура ключа в бакете:

<YYYY>/<MMDD>/<G1>/<G2>/<GUID>.<ext>

где:

• YYYY — год загрузки,

• MMDD — месяц и день (без разделителя),

• G1 — первые 2 символа GUID,

• G2 — следующие 2 символа GUID,

• GUID — идентификатор файла.

Для файлов, загруженных до включения S3, поддерживается прежний формат ключей с двумя уровнями префиксов по GUID (обратная совместимость чтения).

Срок жизни ссылок

Срок действия пресайнд-URL соответствует тайм-аутам для ссылок на файлы, задаваемым в конфигурации аккаунта. Подробности см. в разделе «Список тайм-аутов» — параметр file_url_expiring_timeout и сопутствующие параметры для интерфейсов и каналов.

Поведение в каналах

• Каналы, поддерживающие вложения. Отправка/получение файлов оператором и посетителем выполняется штатно. Файлы сохраняются в S3. Для изображений доступны уменьшенные версии (превью). Для некоторых каналов предпросмотр отправляется вместе с вложением (например, Apple Messages for Business).
• Каналы, не поддерживающие вложения. При отправке оператором файла в диалог вместо вложения посетителю доставляется защищенная ссылка на объект в S3 с ограниченным временем жизни.

Совместимость и миграция

• Перенос существующих файлов в S3 не выполняется автоматически. Старые файлы продолжают открываться из файловой системы.

• Режим можно безопасно включать и выключать. При выключенном use_s3_storage все операции возвращаются к файловой системе.

Требования и сеть

• Необходим доступ с серверов Webim к S3-эндпоинту по HTTPS.

• Время на серверах должно быть синхронизировано (NTP), иначе пресайнд-URL могут считаться недействительными.

• Бакет должен существовать заранее; минимальная версия ACL/политик — приватный доступ, внешняя публикация объектов не требуется (используются пресайнд-URL).

---

Последнее обновление страницы: 30 января 2026 г.