Налаштування централізованого сховища медіафайлів 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/.