Stage File Proxy
Obtiene automáticamente archivos de un servidor de producción bajo demanda para entornos de desarrollo, eliminando la necesidad de sincronizar directorios de archivos grandes.
stage_file_proxy
Install
composer require 'drupal/stage_file_proxy:^3.1'
Overview
Stage File Proxy es una herramienta de desarrollo esencial que resuelve un problema común en los flujos de trabajo de desarrollo de Drupal: la necesidad de tener archivos de producción disponibles en entornos de desarrollo sin copiar manualmente contenido subido por usuarios que puede ocupar gigabytes.
Cuando se solicita un archivo que no existe localmente, Stage File Proxy intercepta la solicitud y descarga el archivo del servidor de origen configurado (típicamente producción) en tiempo real. El archivo se guarda localmente para solicitudes posteriores, creando un sistema eficiente de sincronización de archivos bajo demanda.
El módulo es particularmente inteligente con los estilos de imagen: cuando está configurado, obtiene la imagen original en lugar de las versiones procesadas, permitiendo que el sistema de imágenes de Drupal genere el estilo apropiado localmente. Este enfoque acelera las solicitudes futuras de otros estilos de la misma imagen.
Para escenarios donde el almacenamiento local no es necesario, Stage File Proxy puede operar en modo "hotlink", simplemente redirigiendo las solicitudes al servidor de producción mediante respuestas HTTP 301.
Features
- Obtención de archivos bajo demanda desde un servidor de producción remoto cuando los archivos faltan localmente
- Descarga automática y almacenamiento en caché local de archivos remotos para solicitudes posteriores
- Manejo inteligente de estilos de imagen que obtiene las imágenes originales y permite que el sitio local genere las versiones derivadas
- Modo hotlink para servir archivos directamente desde el servidor de origen mediante redirecciones 301
- Control de verificación de certificados SSL para conexiones HTTPS
- Soporte para credenciales de HTTP Basic Authentication integradas en la URL de origen
- Directorio de origen configurable para instalaciones multisitio con diferentes rutas
- Exclusión de extensiones de archivo para omitir ciertos tipos de archivos del proxy
- Soporte de encabezados HTTP personalizados para solicitudes al servidor de origen
- Comando Drush para descarga masiva de todos los archivos gestionados desde el origen
- Sistema de eventos que permite a otros módulos excluir rutas específicas del proxy
- Mecanismo de reintentos para la generación de estilos de imagen durante solicitudes paralelas
- Protección contra el proxy de archivos de agregación CSS/JS
- Prevención de ataques de traversal de directorios
Use Cases
Desarrollo local sin sincronización de archivos
El caso de uso principal: los desarrolladores que trabajan localmente pueden acceder a todos los archivos de producción sin descargar gigabytes de contenido de usuarios. Simplemente configure la URL de producción como origen, y los archivos se obtienen bajo demanda a medida que se visualizan las páginas. Esto reduce significativamente el tiempo de configuración del entorno local y el uso de espacio en disco.
Acceso a archivos en entorno de staging
Los entornos de staging que necesitan acceso a archivos de producción pero no deben almacenar duplicados pueden usar Stage File Proxy para obtener archivos según sea necesario, manteniendo los entornos de staging ligeros mientras siguen siendo funcionales para pruebas.
Modo hotlink para almacenamiento limitado
Cuando el almacenamiento local es severamente limitado o los archivos solo se necesitan temporalmente, habilite el modo hotlink para redirigir todas las solicitudes de archivos a producción. No se almacenan archivos localmente; el servidor de producción maneja todo el servicio de archivos. Nota: esto aumenta la carga en el servidor de producción.
Desarrollo multisitio
Para instalaciones multisitio donde cada sitio tiene diferentes rutas de archivos (ej. sites/site1/files vs sites/site2/files), configure origin_dir para que coincida con la ruta de archivos del sitio de producción, permitiendo el proxy adecuado de archivos independientemente de las diferencias en las rutas locales.
Sincronización masiva de archivos
Cuando necesite todos los archivos localmente (ej. antes de quedarse sin conexión), use el comando Drush 'drush stage_file_proxy:dl' para descargar todos los archivos gestionados de una vez, en lugar de esperar la obtención bajo demanda.
Exclusión de archivos multimedia grandes
Si su sitio tiene archivos de video o audio grandes que no desea pasar por proxy, configure excluded_extensions con 'mp4,mp3,ogg,webm' para omitir estos archivos mientras sigue obteniendo imágenes y documentos.
Tips
- Siempre configure Stage File Proxy en settings.php o settings.local.php en lugar de a través de la interfaz para evitar que la configuración se sincronice a producción
- Use el módulo Configuration Split si necesita configuración por interfaz y sincronización de configuración juntas
- Para una configuración inicial más rápida, ejecute 'drush stage_file_proxy:dl' para descargar todos los archivos de una vez en lugar de esperar la obtención bajo demanda
- Habilite 'Raíz de estilos de imagen' para descargar las imágenes originales una vez y dejar que su sitio local genere todos los derivados necesarios
- Monitoree los logs de Drupal para errores de Stage File Proxy al depurar problemas de obtención de archivos
- Recuerde actualizar la configuración de NGINX si no está usando Apache - la configuración predeterminada de NGINX para Drupal omite PHP para los errores 404 de archivos
Technical Details
Admin Pages 1
/admin/config/system/stage_file_proxy
Configura la conexión al servidor de origen y controla cómo se obtienen y manejan los archivos. Esta página permite a los administradores configurar la URL del servidor de producción, controlar la verificación SSL, configurar el manejo de estilos de imagen y gestionar las exclusiones de archivos.
Permissions 1
Drush Commands 1
drush stage_file_proxy:dl
Descarga todos los archivos gestionados del servidor de origen que no existen localmente. Consulta la tabla file_managed e intenta descargar cada archivo público faltante.
Troubleshooting 6
Verifique que la URL de origen sea correcta y accesible. Compruebe que el origen no tenga una barra diagonal final. Asegúrese de que el servidor de origen permita solicitudes desde la IP de su entorno de desarrollo. Revise los logs de Drupal para mensajes de error específicos de Stage File Proxy.
Actualice la configuración de NGINX para enrutar todas las solicitudes de archivos a través de Drupal. Cambie 'location ~ ^/sites/.*/files/styles/' a 'location ~ ^/sites/.*/files/' y asegúrese de que use 'try_files $uri @rewrite;'.
Si el origen tiene un certificado SSL válido, asegúrese de que los certificados CA de su servidor estén actualizados. Para desarrollo con certificados autofirmados, deshabilite la verificación SSL estableciendo 'verify' en FALSE (no recomendado para entornos similares a producción).
Asegúrese de que 'Raíz de estilos de imagen' esté habilitado para que Stage File Proxy obtenga las imágenes originales en lugar de los derivados. Limpie las cachés y verifique que el módulo Image funcione correctamente. Revise los permisos de archivo en el directorio de estilos.
Asegúrese de que las credenciales estén codificadas en URL en la URL de origen. Los caracteres especiales como & deben codificarse (ej. %26). Formato: 'http://usuario:contraseña@ejemplo.com'.
Stage File Proxy incluye lógica de reintentos para la generación de estilos de imagen, pero cargas concurrentes pesadas aún pueden causar problemas. Considere usar un proxy inverso o CDN para combinar solicitudes duplicadas, o precaliente las cachés usando el comando de descarga de Drush.
Security Notes 6
- Este módulo NUNCA debe habilitarse en entornos de producción - crea una dependencia de un servidor externo y podría exponer rutas internas de archivos
- La URL de origen puede contener credenciales de autenticación - asegúrese de que settings.php tenga los permisos de archivo apropiados y no esté expuesto a través del control de versiones
- Si usa HTTP Basic Auth en la URL de origen, las credenciales se almacenan en texto plano en la configuración
- Verificar SSL debe permanecer habilitado en entornos de staging para asegurar la autenticidad del servidor de origen
- El módulo incluye protección contra ataques de traversal de directorios rechazando rutas que contengan '..'
- Sea cauteloso con el modo hotlink ya que expone la estructura de URL de su servidor de producción a los usuarios finales