S3 File System
Proporciona un sistema de archivos remoto basado en Amazon S3 para Drupal, permitiendo almacenar y servir archivos desde S3 o cualquier servicio de almacenamiento compatible con S3.
s3fs
Install
composer require 'drupal/s3fs:8.x-3.9'
composer require 'drupal/s3fs:8.x-3.7'
Overview
S3 File System (s3fs) proporciona un sistema de archivos adicional a tu sitio Drupal, junto con los sistemas de archivos públicos y privados, que almacena archivos en Amazon Simple Storage Service (S3) o cualquier servicio de almacenamiento compatible con S3. Puedes configurar tu sitio para usar S3 File System como predeterminado, o usarlo solo para campos individuales.
Esta funcionalidad está diseñada para sitios con balanceo de carga entre múltiples servidores, ya que el mecanismo utilizado por los sistemas de archivos predeterminados de Drupal no es viable bajo dicha configuración. El módulo utiliza una caché de metadatos que rastrea cada archivo almacenado en S3, lo que acelera significativamente las operaciones del sistema de archivos.
S3fs utiliza una arquitectura modular con submódulos separados para la creación del cliente S3, configuración de buckets, provisión de stream wrapper y optimización de CSS/JS. Esto permite una configuración flexible de múltiples buckets S3 con diferentes ajustes y credenciales.
Features
- Almacena y sirve archivos desde Amazon S3 o cualquier almacenamiento compatible con S3 (MinIO, DigitalOcean Spaces, Backblaze B2, etc.)
- Soporte para configuración de múltiples buckets con credenciales y ajustes separados por bucket
- Toma el control de los sistemas de archivos public:// y/o private:// para almacenar todos los archivos en S3
- Creación de stream wrapper personalizado para múltiples esquemas de archivos respaldados por S3
- Caché de metadatos de archivos en la base de datos de Drupal para mejorar el rendimiento
- Soporte de URLs prefirmadas para acceso temporal a archivos privados
- Soporte de CNAME/CDN para servir archivos desde dominios personalizados
- Soporte de cifrado del lado del servidor (AES256 y AWS KMS)
- Reescritura de enlaces CSS/JS para recursos almacenados en S3
- Generación de derivados de estilos de imagen con almacenamiento en S3
- Integración con Key module para gestión segura de credenciales
- Soporte de caché de credenciales AWS usando Doctrine Cache
- Comandos Drush para actualización de caché y gestión de buckets
- Soporte de migración desde instalaciones S3FS de Drupal 7
- Soporte para buckets versionados y acceso a archivos de versiones específicas
Use Cases
Despliegue Multi-servidor con Balanceo de Carga
Para sitios Drupal ejecutándose en múltiples servidores web detrás de un balanceador de carga, s3fs resuelve el problema de sincronización de archivos almacenando todos los archivos en un bucket S3 central. Todos los servidores acceden a los mismos archivos sin necesidad de montajes NFS compartidos o soluciones rsync.
Integración con CDN
Configure s3fs con un CNAME apuntando a una distribución CloudFront u otro CDN. Los archivos se sirven desde ubicaciones de borde en todo el mundo, reduciendo la latencia y la carga del servidor. Use la configuración de dominio personalizado y los encabezados Cache-Control para un almacenamiento en caché CDN óptimo.
Acceso a Archivos Privados con URLs Prefirmadas
Almacene archivos sensibles en S3 con ACL privada y use URLs prefirmadas para otorgar acceso de tiempo limitado. Configure patrones de URL prefirmadas para generar automáticamente enlaces de acceso temporal para rutas de archivos específicas.
Servicios de Almacenamiento Compatibles con S3
Use s3fs con cualquier servicio de almacenamiento compatible con S3 como MinIO, DigitalOcean Spaces, Backblaze B2 o Wasabi. Configure endpoints personalizados y URLs de estilo de ruta según sea necesario para su proveedor.
Configuración de Múltiples Buckets
Configure múltiples buckets S3 con diferentes credenciales y configuraciones. Por ejemplo, use un bucket para archivos multimedia públicos con acceso CDN y otro bucket privado para documentos sensibles con cifrado.
Cumplimiento de Almacenamiento Cifrado
Habilite el cifrado del lado del servidor (AES256 o AWS KMS) para requisitos de cumplimiento. Use los hooks de cifrado para implementar claves de cifrado administradas por el cliente (SSE-C) para rutas de archivos específicas.
Tips
- Siempre almacene su directorio php_storage/twig localmente cuando use la toma de control de public://. Los archivos Twig en S3 representan riesgos de seguridad y rendimiento.
- Use el módulo Key para la gestión de credenciales en lugar de almacenar credenciales en settings.php para mayor seguridad.
- Limpie la caché de Drupal después de habilitar o deshabilitar la toma de control del stream wrapper public:// o private://.
- Para endpoints personalizados (MinIO, etc.), habilite 'Use path-style endpoint' si su proveedor no soporta URLs de estilo virtual-hosted.
- Configure encabezados Cache-Control apropiados (por ejemplo, 'public, max-age=31536000') para assets estáticos para maximizar el almacenamiento en caché del CDN y del navegador.
- Use URLs prefirmadas para archivos privados que necesitan acceso público temporal en lugar de hacer público todo el bucket.
- Al migrar desde almacenamiento local, use 'drush s3fs:copy-local' para copiar archivos mientras mantiene la caché de metadatos.
- Pruebe su configuración usando el botón de validación en la página de acciones del bucket antes de desplegar a producción.
Technical Details
Admin Pages 7
/admin/config/s3
Sección principal de configuración de S3 que contiene enlaces a S3 Buckets, StreamWrappers y configuración de CSS/JS.
/admin/config/s3/s3-bucket
Lista de conexiones de bucket S3 configuradas. Gestiona las configuraciones de bucket incluyendo credenciales, endpoints y ajustes de almacenamiento.
/admin/config/s3/s3-bucket/add
Crear una nueva configuración de bucket S3 con credenciales y ajustes de conexión.
/admin/config/s3/s3-bucket/{s3fs_bucket}/actions
Realizar acciones administrativas en el bucket S3 como actualizar la caché de metadatos.
/admin/config/s3/streamwrapper
Lista de stream wrappers S3 configurados. Cada stream wrapper define un esquema URI personalizado para acceder a archivos en S3.
/admin/config/s3/streamwrapper/add
Crear una nueva configuración de stream wrapper que mapea un esquema URI a un bucket S3.
/admin/config/s3/cssjs
Configurar cómo se reescriben las URLs dentro de archivos CSS y JavaScript cuando se almacenan en S3.
Permissions 3
Hooks 6
hook_s3fs_url_settings_alter
Modifica el formato y las opciones utilizadas al crear una URL externa. Permite la modificación de la configuración de URL prefirmadas, tiempos de espera y argumentos GET personalizados.
hook_s3fs_stream_open_params_alter
Modifica los parámetros del archivo S3 cuando se abre un flujo. Útil para agregar parámetros de cifrado del lado del servidor.
hook_s3fs_upload_params_alter
Modifica los parámetros del archivo S3 al subir un objeto. Permite la modificación de ACL, cifrado y otros parámetros de carga.
hook_s3fs_copy_params_alter
Modifica los parámetros de S3 al copiar o renombrar archivos. Útil para manejar archivos de origen y destino cifrados.
hook_s3fs_command_params_alter
Modifica los parámetros de S3 devueltos por getCommandParams(). Afecta llamadas como la obtención de metadatos (HeadObject).
hook_s3fs_bucket_command_params_alter
Modifica los parámetros de S3 a nivel de plugin de bucket. Similar a hook_s3fs_command_params_alter pero con contexto adicional incluyendo bucket_id.
Drush Commands 2
drush s3fs:list-buckets
Lista todas las entidades de bucket S3 configuradas con su estado.
drush s3fs:refresh-cache
Actualiza la caché de metadatos del Sistema de Archivos S3 para un bucket específico.
Troubleshooting 7
Ejecute la actualización de caché de metadatos a través de Drush (drush s3fs:refresh-cache --bucket=BUCKET_NAME) o a través de la interfaz de administración en /admin/config/s3/s3-bucket/BUCKET_NAME/actions. S3fs requiere su caché de metadatos para conocer los archivos.
Esto ocurre cuando existe un objeto tanto en '/path/to/object' como en '/path/to/object/another_object' en el bucket. Elimine/renombre el objeto raíz o elimine/renombre todos los objetos con el mismo prefijo de ruta.
Si usa BlockPublicAcls en su bucket, habilite la opción 'Upload all files as private in S3'. También asegúrese de que los permisos IAM incluyan todas las acciones requeridas y que la política CORS del bucket permita solicitudes GET.
Para servidores Nginx, agregue el bloque location: location ~ ^/s3/styles/ { try_files $uri @rewrite; } a la configuración de su servidor.
Asegúrese de que el módulo s3fs_cssjs esté habilitado cuando use la toma de control de public://. Configure CORS en su bucket S3 para permitir solicitudes GET desde el dominio de su sitio.
Habilite el almacenamiento en caché de credenciales instalando doctrine/cache (composer require 'doctrine/cache:~1.4') y configurando la opción 'Cached Credentials Directory'.
S3fs tiene un límite de 255 caracteres en los URIs de archivos debido a las limitaciones de índices de MySQL. Acorte los nombres de archivos o reduzca la profundidad de anidamiento de directorios.
Security Notes 6
- Las credenciales de S3 deben almacenarse fuera de la raíz web. Use el módulo Key, variables de entorno o roles IAM en lugar de settings.php cuando sea posible.
- Cuando el almacenamiento en caché de credenciales está habilitado, las credenciales se almacenan en texto plano en el sistema de archivos. Asegúrese de que el directorio de caché esté fuera del docroot y debidamente asegurado.
- Deshabilitar la verificación SSL/TLS es un riesgo de seguridad y solo debe usarse para desarrollo con certificados autofirmados.
- Los archivos almacenados con ACL público son accesibles para cualquiera con la URL. Use 'upload_as_private' para contenido sensible y URLs prefirmadas para acceso controlado.
- La opción 'Ignore file metadata cache' hace que todas las solicitudes lleguen directamente a S3, lo que podría exponer su bucket a llamadas API excesivas y potencial DDoS.
- Cuando use la toma de control de public://, asegúrese de que la política CORS de su bucket solo permita solicitudes desde su dominio, no orígenes con comodín.