Настройка централизованного хранилища медиафайлов 1С-Битрикс

Настройка централизованного хранилища медиафайлов 1С-Битрикс

При кластерной конфигурации Битрикс или при наличии нескольких окружений (prod, staging, dev) медиафайлы из /upload/ живут локально на каждом сервере. Загруженная картинка товара есть на одной ноде, но не на других. Резервирование файлов через NFS работает, но создаёт единую точку отказа. Централизованное хранилище на базе S3-совместимого объектного хранилища — стандартное решение для этого класса задач.

Варианты объектного хранилища

• Yandex Object Storage — S3-совместимый, данные в РФ, простая интеграция
• AWS S3 — если данные можно хранить за рубежом
• MinIO — self-hosted S3, можно поднять на своих серверах
• Selectel Object Storage — российский хостинг с S3 API

Все варианты работают с одним и тем же API (S3 compatible), интеграция с Битрикс одинаковая.

Модуль Bitrix Cloud Storage

В Битрикс есть встроенный модуль bitrix.cloud для хранения файлов в облаке. Настройка: Настройки → Облачное хранилище.

Поддерживаемые провайдеры из коробки: Amazon S3, Azure Blob Storage. Для Yandex Object Storage — через кастомную точку входа (endpoint), так как он S3-совместимый:

// Конфигурация через .settings.php для S3-совместимого хранилища
// Используем прямую интеграцию через AWS SDK

Ограничение модуля bitrix.cloud: не все типы файлов переносятся корректно (редактор файлов в админке, кэш ресайза). Лучше проверять на staging.

Прямая интеграция через AWS SDK

composer require aws/aws-sdk-php

// /local/lib/Storage/S3Storage.php
namespace Local\Storage;

use Aws\S3\S3Client;

class S3Storage
{
    private static ?S3Client $client = null;

    public static function getClient(): S3Client
    {
        if (!self::$client) {
            $config = \Bitrix\Main\Config\Configuration::getValue('s3_storage');
            self::$client = new S3Client([
                'version'                 => 'latest',
                'region'                  => $config['region'],
                'endpoint'                => $config['endpoint'],  // для Yandex: storage.yandexcloud.net
                'use_path_style_endpoint' => true,
                'credentials'             => [
                    'key'    => $config['access_key'],
                    'secret' => $config['secret_key'],
                ],
            ]);
        }
        return self::$client;
    }

    public static function upload(string $localPath, string $s3Key): string
    {
        $bucket = \Bitrix\Main\Config\Configuration::getValue('s3_storage')['bucket'];
        self::getClient()->putObject([
            'Bucket'      => $bucket,
            'Key'         => $s3Key,
            'SourceFile'  => $localPath,
            'ACL'         => 'public-read',
            'ContentType' => mime_content_type($localPath),
        ]);
        return 'https://' . $bucket . '.storage.yandexcloud.net/' . $s3Key;
    }
}

Конфигурация в /bitrix/.settings.php:

's3_storage' => [
    'value' => [
        'access_key' => 'YCAJExxxx',
        'secret_key' => 'YCPxxx',
        'bucket'     => 'my-shop-media',
        'region'     => 'ru-central1',
        'endpoint'   => 'https://storage.yandexcloud.net',
    ],
],

Перехват загрузки файлов в Битрикс

Битрикс сохраняет файлы через CFile::SaveFile(). Чтобы файлы уходили в S3 вместо локального диска, перехватываем через хук:

// Альтернатива: переопределяем поведение через обработчик после сохранения
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'main',
    'OnAfterFileSave',
    function (\Bitrix\Main\Event $event) {
        $file = $event->getParameter('FILE');
        $localPath = $_SERVER['DOCUMENT_ROOT'] . $file['SRC'];

        if (file_exists($localPath)) {
            $s3Key = ltrim($file['SRC'], '/');
            \Local\Storage\S3Storage::upload($localPath, $s3Key);

            // Опционально: удаляем локальную копию после загрузки в S3
            // unlink($localPath);
        }
    }
);

Для отдачи файлов — настраиваем nginx на проксирование запросов к /upload/ через S3 CDN:

location /upload/ {
    proxy_pass https://my-shop-media.storage.yandexcloud.net/upload/;
    proxy_cache_valid 200 7d;
    add_header Cache-Control "public, max-age=604800";
}

Миграция существующих файлов

Перенос текущего /upload/ в S3 — отдельная операция:

# Синхронизация локального upload/ в S3 через AWS CLI
aws s3 sync /var/www/bitrix/upload/ s3://my-shop-media/upload/ \
    --endpoint-url https://storage.yandexcloud.net \
    --acl public-read \
    --no-progress

# Проверяем количество файлов
aws s3 ls s3://my-shop-media/upload/ --recursive --endpoint-url https://storage.yandexcloud.net | wc -l

Миграцию делаем с возможностью откатиться: локальные файлы не удаляем до подтверждения корректной работы.

Сроки настройки

Настройка S3-хранилища, интеграция с Битрикс через SDK, конфиг nginx для проксирования, миграция существующих файлов — 2–4 рабочих дня в зависимости от объёма существующего upload/.