Настройка S3-совместимого хранилища для 1С-Битрикс
Диск на сервере заканчивается. Или нужно разнести несколько серверов и синхронизировать загруженные файлы между ними. Перенос /upload/ в S3-совместимое хранилище (MinIO, Selectel, VK Cloud, Cloudflare R2) решает обе задачи — но только если настроить правильно, иначе Битрикс начнёт записывать пути к файлам некорректно.
Модуль main.cloudstorages
Битрикс поддерживает облачные хранилища через модуль main.cloudstorages. Он абстрагирует работу с файлами через провайдеры. Для S3-совместимых хранилищ используется провайдер amazon (совместимость на уровне API S3).
Настройка провайдера производится в /bitrix/admin/main_cloud_storage.php. Параметры для S3-совместимого хранилища:
-
Endpoint URL — URL сервиса (для MinIO:
http://minio:9000, для Selectel:https://s3.selectel.ru) - Key — Access Key ID
- Secret — Secret Access Key
- Bucket — имя бакета
-
Region — регион (для кастомных S3 часто
us-east-1)
Конфигурация в коде (для автоматизации настройки):
\Bitrix\Main\Config\Option::set('main', 'cloud_storage_active', 'Y');
\Bitrix\Main\Config\Option::set('main', 'cloud_storage_provider', 'amazon');
\Bitrix\Main\Config\Option::set('main', 'cloud_storage_endpoint', 'https://s3.example.com');
\Bitrix\Main\Config\Option::set('main', 'cloud_storage_access_key', 'ACCESS_KEY');
\Bitrix\Main\Config\Option::set('main', 'cloud_storage_secret_key', 'SECRET_KEY');
\Bitrix\Main\Config\Option::set('main', 'cloud_storage_bucket', 'bitrix-uploads');
\Bitrix\Main\Config\Option::set('main', 'cloud_storage_path', 'upload/');
Path style vs virtual hosted style
Самая частая проблема при подключении не-AWS S3 — неверная адресация бакета. AWS использует virtual hosted style: https://bucket.s3.amazonaws.com/key. Большинство S3-совместимых сервисов поддерживают path style: https://s3.example.com/bucket/key.
Стандартный модуль Битрикса использует virtual hosted style. Для сервисов, которые не поддерживают его (например, MinIO в локальной сети без wildcard DNS), нужно патчить класс провайдера /bitrix/modules/main/lib/cloudstorages/amazon.php — добавить параметр use_path_style_endpoint: true при инициализации AWS SDK:
$s3Client = new \Aws\S3\S3Client([
'version' => 'latest',
'region' => $region,
'endpoint' => $endpoint,
'use_path_style_endpoint' => true,
'credentials' => [
'key' => $accessKey,
'secret' => $secretKey,
],
]);
Синхронизация существующих файлов
После подключения хранилища Битрикс начинает загружать новые файлы в S3, но старые остаются локально. Для миграции используется встроенная утилита: /bitrix/admin/main_cloud_copy.php. Она запускает агент, который пакетами переносит файлы из /upload/ в хранилище и обновляет пути в b_file.
При переносе важно: поле SUBDIR в b_file хранит относительный путь файла. После миграции в S3 пути становятся URL-адресами бакета. Если миграция прервётся на середине, часть файлов будет в S3, часть — локально. Битрикс определяет источник файла по полю EXTERNAL_ID в b_file — если оно заполнено, файл считается облачным.
Публичный доступ и CDN
Файлы в S3 должны быть публично доступны для прямых ссылок на изображения. Настройка политики бакета (bucket policy) для публичного чтения:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": "*",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::bitrix-uploads/*"
}]
}
Для подключения CDN перед бакетом (CloudFront, Cloudflare) в настройках модуля указывается параметр CDN_URL — Битрикс будет формировать публичные URL через CDN, а запись в S3 будет идти напрямую.
Кэш и временные файлы
Директорию /bitrix/cache/ переносить в S3 нельзя — это деградирует производительность. Кэш должен оставаться локальным или на быстром сетевом хранилище (NFS, Redis для управляемого кэша). В S3 переносится только /upload/ — пользовательский контент.