Настройка хранилища файлов

В разделе описана настройка хранилища файлов в SuiteCRM версий 8.9.0+

1. Введение

Новый механизм хранения файлов для загрузки и выгрузки данных использует достаточно гибкую систему хранения. Настройка управляется переменными окружения (см. файлы .env и .env.local), что позволяет легко переключаться между локальным и удалёнными хранилищами (AWS S3 и Azure Blob).

2. Обзор хранилища файлов

2.1. Используемые пакеты Symfony

  • VichUploaderBundle: обрабатывает загрузку файлов и сопоставление файлов с сущностями Doctrine.

  • LeagueFlysystemBundle: Интегрирует абстракцию файловой системы Flysystem, поддерживая различные системы хранения (локальные, S3, Azure и т. д.).

  • DoctrineBundle: Управляет взаимодействием с базой данных для мультимедийных метаданных.

  • ApiPlatform: Предоставляет медиаобъекты как ресурсы API.

2.2. Типы хранилищ

Предлагается несколько типов хранилищ, каждый из которых соответствует определённому варианту использования:

archived.documents.storage

Хранение архивированных документов, как правило, для долгосрочного хранения или соблюдения нормативных требований.
Используется: ArchivedDocumentMediaObject

private.documents.storage

Хранение личных документов. Доступ ограничен авторизованными пользователями.
Используется: PrivateDocumentMediaObject

private.images.storage

Хранение личных изображений, доступно только авторизованным пользователям.
Используется: PrivateImageMediaObject

public.images.storage

Хранение изображений, предназначенных для публичного доступа (например, аватары пользователей, публичные галереи).
Используется: PublicImageMediaObject

public.documents.storage

Хранение документов, к которым возможен публичный доступ (например, загружаемые ресурсы).
Используется: PublicDocumentMediaObject

Хранилища (локальное, AWS S3, Azure Blob) настраиваются через переменные окружения.

Каждое хранилище настраивается через переменную окружения MEDIA_FLY_SYSTEM_STORAGES как JSON-объект с указанием адаптера (local, aws, azure) и параметров (например, бакет или контейнер).

2.3. Замечания по настройке

  • При использовании секретов в JSON всегда заключайте ссылку в двойные кавычки.

  • Настройки хранилища установлены в оптимальные значения по умолчанию, поэтому изменяйте их только в том случае, если вы уверены в своих действиях.

  • Сопоставление между классами сущностей и хранилищами определяется в YAML-файлах сопоставления VichUploader в каталоге config/vich_uploader/.

  • Подробнее см. примеры настроек в разделах .env и .env.local, а также файлы настроек пакетов в каталоге config/packages/.

3. Стандартные настройки

3.1. Настройка Flysystem

Файл config/packages/flysystem.php объединяет хранилища по умолчанию и хранилища, заданные в переменных окружения:

  • Хранилища по умолчанию используют адаптер local и хранят файлы в каталогах проекта.

  • Пользовательские хранилища можно определить через переменную MEDIA_FLY_SYSTEM_STORAGES для использования с AWS S3 или Azure Blob.

  • Эти настройки передаются в расширение flysystem.

3.2. Настройка VichUploader

Файл config/packages/vich_uploader.php:

  • Читает определения клиентов AWS и Azure из переменных окружения.

  • Создает определения сервисов для каждого клиента.

  • Задает сопоставления для каждого типа медиаобъекта, например:

    • archived_documents_media_object → archived.documents.storage

    • private_documents_media_object → private.documents.storage

    • private_images_media_object → private.images.storage

    • public_images_media_object → public.images.storage

    • public_documents_media_object → public.documents.storage

  • Для каждого сопоставления указываются префикс URI, целевой каталог для загрузки, настройки именования файлов и настройки именования каталогов.

4. Переменные окружения хранилища

4.1. MEDIA_FLY_SYSTEM_STORAGES

Назначение

Определяет серверные части хранилища для Flysystem, сопоставляя логические имена хранилищ с адаптерами (локальными, AWS S3, Azure Blob и т. д.).

Настройка

Задаётся как строка JSON, сопоставляющая ключи хранилища с настройками адаптеров.

По умолчанию:

{
  "private.documents.storage": {
    "adapter": "local",
    "options": {
      "directory": "%kernel.project_dir%/uploads/documents"
    }
  },
  "archived.documents.storage": {
    "adapter": "local",
    "options": {
      "directory": "%kernel.project_dir%/uploads/archived"
    }
  },
  "private.images.storage": {
    "adapter": "local",
    "options": {
      "directory": "%kernel.project_dir%/uploads/images"
    }
  },
  "public.images.storage": {
    "adapter": "local",
    "options": {
      "directory": "%kernel.project_dir%/public/media-upload/images"
    }
  },
  "public.documents.storage": {
    "adapter": "local",
    "options": {
      "directory": "%kernel.project_dir%/public/media-upload/documents"
    }
  }
}

Пример:

MEDIA_FLY_SYSTEM_STORAGES='{
  "private.documents.storage": {
    "adapter": "aws",
    "options": {
      "client": "aws.s3.client.main",
      "bucket": "your-bucket"
    }
  },
  "private.images.storage": {
    "adapter": "azure",
    "options": {
      "client": "azure.blob.client.main",
      "container": "your-blob-container"
    }
  }
}'

4.2. MEDIA_UPLOADER_MAPPINGS

Назначение

Определяет правила сопоставления для VichUploader, которые связывают поля сущностей с хранилищами и стратегиями именования.

Настройка

Задаётся в виде строки JSON, которая сопоставляет имена с объектами настройки.

По умолчанию:

{
  "archived_documents_media_object": {
    "uri_prefix": "/media/archived",
    "upload_destination": "archived.documents.storage",
    "namer": "App\\MediaObjects\\Services\\UuidMediaObjectFileNamer",
    "directory_namer": {
      "service": "Vich\\UploaderBundle\\Naming\\CurrentDateTimeDirectoryNamer",
      "options": {
        "date_time_format": "Y/m",
        "date_time_property": "dateEntered"
      }
    }
  },
  "private_documents_media_object": {
    "uri_prefix": "/media/documents",
    "upload_destination": "private.documents.storage",
    "namer": "App\\MediaObjects\\Services\\UuidMediaObjectFileNamer",
    "directory_namer": {
      "service": "Vich\\UploaderBundle\\Naming\\CurrentDateTimeDirectoryNamer",
      "options": {
        "date_time_format": "Y/m",
        "date_time_property": "dateEntered"
      }
    }
  },
  "private_images_media_object": {
    "uri_prefix": "/media/images",
    "upload_destination": "private.images.storage",
    "namer": "App\\MediaObjects\\Services\\UuidMediaObjectFileNamer",
    "directory_namer": {
      "service": "Vich\\UploaderBundle\\Naming\\CurrentDateTimeDirectoryNamer",
      "options": {
        "date_time_format": "Y/m",
        "date_time_property": "dateEntered"
      }
    }
  },
  "public_images_media_object": {
    "uri_prefix": "/media-upload/images",
    "upload_destination": "public.images.storage",
    "namer": "Vich\\UploaderBundle\\Naming\\SmartUniqueNamer",
    "directory_namer": {
      "service": "Vich\\UploaderBundle\\Naming\\CurrentDateTimeDirectoryNamer",
      "options": {
        "date_time_format": "Y/m",
        "date_time_property": "dateEntered"
      }
    }
  },
  "public_documents_media_object": {
    "uri_prefix": "/media-upload/documents",
    "upload_destination": "public.documents.storage",
    "namer": "Vich\\UploaderBundle\\Naming\\SmartUniqueNamer",
    "directory_namer": {
      "service": "Vich\\UploaderBundle\\Naming\\CurrentDateTimeDirectoryNamer",
      "options": {
        "date_time_format": "Y/m",
        "date_time_property": "dateEntered"
      }
    }
  }
}

Пример:

MEDIA_UPLOADER_MAPPINGS='{
  "private_documents_media_object": {
    "uri_prefix": "/media/documents",
    "upload_destination": "private.documents.storage",
    "namer": "App\\MediaObjects\\Services\\UuidMediaObjectFileNamer"
  }
}'

4.3. AWS_S3_INSTANCES

Назначение

Настраивает клиентские экземпляры AWS S3 для использования в качестве серверных частей хранилищ.

Настройка

Задаётся как строка JSON, сопоставляющая имена экземпляров с учётными данными AWS и регионом.

По умолчанию:

{}

Пример:

AWS_S3_INSTANCES='{
  "main": {
    "region": "eu-west-1",
    "access_key": "%env(AWS_S3_ACCESS_KEY)%",
    "access_secret": "%env(AWS_S3_ACCESS_SECRET)%"
  }
}'

4.4. AZURE_BLOB_INSTANCES

Назначение

Настраивает клиентские экземпляры хранилища Azure Blob Storage для использования в качестве серверных частей хранилища.

Настройка

Задаётся как строка JSON, сопоставляющая имена экземпляров со строками подключения.

По умолчанию:

{}

Пример:

AZURE_BLOB_INSTANCES='{
  "main": {
    "connection_string": "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net"
  }
}'

4.5. Использование секретов Symfony

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

Пример использования секретов:

AWS_S3_INSTANCES='{
  "main": {
    "region": "eu-west-1",
    "access_key": "%env(AWS_S3_ACCESS_KEY)%",
    "access_secret": "%env(AWS_S3_ACCESS_SECRET)%"
  }
}'

Для установки секрета выполните следующие команды:

php bin/console secrets:set AWS_S3_ACCESS_KEY
php bin/console secrets:set AWS_S3_ACCESS_SECRET

Затем обратитесь к секрету в JSON-настройках, используя %env(SECRET_NAME)%.

При использовании секретов в JSON всегда заключайте ссылку в двойные кавычки.

Content is available under GNU Free Documentation License 1.3 or later unless otherwise noted.