Cómo resolver el error ‘error al subir el almacenamiento de objetos’ de Mastodon en S3

Las instancias de Mastodon que utilizan almacenamiento de objetos compatible con S3 para archivos multimedia pueden encontrar el error “Error al subir el almacenamiento de objetos” cuando los usuarios intentan adjuntar imágenes, videos u otros archivos a sus publicaciones. Este error suele aparecer como un banner rojo en la interfaz web o como un fallo registrado en los trabajos de Sidekiq de Mastodon. La causa raíz casi siempre es una configuración incorrecta en las variables de entorno de Mastodon que controlan el acceso a S3 o una restricción a nivel de red que bloquea la solicitud de subida. Este artículo explica los valores de configuración específicos que deben ser correctos, proporciona instrucciones paso a paso para verificar y corregir cada ajuste, y cubre patrones de fallo relacionados, como tiempos de espera y errores de permisos.

Por qué Mastodon no puede subir archivos multimedia a S3

Mastodon almacena archivos multimedia subidos por los usuarios, como fotos de perfil, imágenes de cabecera y archivos adjuntos en publicaciones. Por defecto, Mastodon guarda estos archivos en el sistema de archivos local. Cuando se habilita el almacenamiento de objetos compatible con S3, Mastodon utiliza el AWS SDK para Ruby para subir archivos a un bucket remoto. El proceso de subida implica varios pasos: el proceso web de Mastodon recibe el archivo, Sidekiq procesa el trabajo de subida y el SDK envía una solicitud PUT al endpoint de S3. Si alguna de las variables de entorno que controlan este proceso falta, es incorrecta o no está alineada con los requisitos del proveedor de S3, la subida falla.

Las causas más comunes son:

• S3_ENABLED faltante o incorrecto: Mastodon ignora toda la configuración de S3 si esta variable no está establecida en true.
• S3_PROTOCOL o S3_HOSTNAME incorrectos: Para proveedores de S3 que no son AWS, como DigitalOcean Spaces o MinIO, debe configurar estos valores con la URL del endpoint correcto.
• Permisos del bucket: El usuario de IAM o la clave de acceso deben tener permisos s3:PutObject y s3:PutObjectAcl en el bucket.
• Bloqueo de red o firewall: El servidor de Mastodon debe poder alcanzar el endpoint de S3 a través de HTTPS en el puerto 443.

Pasos para diagnosticar y corregir el error de subida a S3 en Mastodon

Siga estos pasos en orden. Pruebe después de cada cambio subiendo una imagen pequeña a cualquier publicación de Mastodon.

1. Verifique el archivo de entorno de Mastodon
   Conéctese por SSH a su servidor de Mastodon como usuario mastodon. Abra el archivo .env.production ubicado en el directorio de inicio de Mastodon, generalmente /home/mastodon/live/.env.production. Ejecute: sudo -u mastodon nano /home/mastodon/live/.env.production. Verifique que las siguientes líneas existan y no estén comentadas:
2. Confirme que S3_ENABLED esté establecido en true
   Busque la línea S3_ENABLED=true. Si falta o está establecida en false, Mastodon no utilizará S3 en absoluto e intentará guardar los archivos localmente, lo que también puede fallar si la ruta de almacenamiento local está mal configurada.
3. Verifique las credenciales de AWS
   Asegúrese de que estas líneas estén presentes:
   AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
   La clave de acceso debe tener permisos de escritura en el bucket de S3. Si no está seguro, genere un nuevo par de claves desde el panel de control de su proveedor de S3.
4. Establezca el nombre del bucket y la región correctos
   Compruebe que S3_BUCKET=your-bucket-name coincida exactamente con el bucket que creó. Para la región, use S3_REGION=us-east-1 o la región que utilice su proveedor. DigitalOcean Spaces utiliza la región nyc3 o ams3.
5. Configure el endpoint de S3 para proveedores que no son AWS
   Si utiliza un proveedor distinto de AWS, debe configurar:
   S3_PROTOCOL=https
S3_HOSTNAME=nyc3.digitaloceanspaces.com
   Reemplace el hostname con el endpoint de su proveedor. Para MinIO, use la IP o el dominio de su servidor MinIO.
6. Establezca S3_ALIAS_HOST si es necesario
   Si su bucket de S3 se accede a través de un dominio personalizado o CDN, configure S3_ALIAS_HOST=https://media.yourdomain.com. Esto le indica a Mastodon que sirva las URLs de los archivos multimedia desde ese dominio en lugar del endpoint directo de S3.
7. Reinicie los servicios de Mastodon
   Después de guardar el archivo de entorno, reinicie todos los procesos de Mastodon para que los cambios surtan efecto. Ejecute:
   sudo systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming
8. Pruebe la subida
   Inicie sesión en su instancia de Mastodon como administrador o usuario regular. Redacte una nueva publicación y adjunte un archivo de imagen de menos de 5 MB. Si la subida se realiza correctamente, el error se ha resuelto.

Si Mastodon aún muestra el error de subida después de los cambios de configuración

La configuración CORS del bucket de S3 bloquea las subidas

Incluso con la configuración correcta de Mastodon, el propio bucket de S3 puede rechazar las subidas debido a cabeceras CORS faltantes o incorrectas. Inicie sesión en el panel de control de su proveedor de S3 y añada la siguiente regla CORS al bucket:

[
  {
    "AllowedHeaders": [""],
    "AllowedMethods": ["PUT", "POST", "GET", "HEAD"],
    "AllowedOrigins": ["https://your-mastodon-instance.com"],
    "ExposeHeaders": ["ETag"]
  }
]

Reemplace el origen con el dominio de su instancia de Mastodon. Si está probando localmente, use http://localhost:3000.

La política del bucket deniega PutObject para la clave de acceso

El usuario de IAM o la clave de acceso deben tener una política que permita s3:PutObject. Una política típica se ve así:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl",
        "s3:GetObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::your-bucket-name/"
    }
  ]
}

Adjunte esta política al usuario asociado con la clave de acceso. Para DigitalOcean Spaces, use la clave de acceso de Spaces con los permisos adecuados en el panel de control de Spaces.

El firewall o DNS bloquea el endpoint de S3

Desde el servidor de Mastodon, pruebe la conectividad al endpoint de S3 usando curl. Ejecute:
curl -I https://nyc3.digitaloceanspaces.com
Si el comando se cuelga o devuelve un tiempo de espera, revise las reglas del firewall de su servidor. Asegúrese de que el tráfico HTTPS saliente al rango de IP del endpoint de S3 esté permitido. También verifique que la resolución DNS funcione para el hostname.

El tamaño del archivo excede el límite del bucket de S3 o el límite de Mastodon

Mastodon tiene un límite de tamaño de archivo predeterminado de 8 MB para archivos adjuntos. Algunos proveedores de S3 imponen un límite más bajo. Consulte la documentación de su proveedor. Puede ajustar el límite de Mastodon configurando MAX_IMAGE_SIZE y MAX_VIDEO_SIZE en el archivo de entorno, pero el proveedor de S3 debe aceptar el tamaño mayor.

Configuración de S3 en Mastodon vs. almacenamiento local: diferencias clave

Elemento	Almacenamiento de objetos S3	Sistema de archivos local
Ubicación de almacenamiento	Bucket remoto en un proveedor compatible con S3	Disco local en el servidor de Mastodon
Variable de entorno requerida	S3_ENABLED=true más credenciales y endpoint de AWS	No se necesitan variables de S3
Escalabilidad	Alta; el almacenamiento es independiente del disco del servidor	Limitada por la capacidad del disco del servidor
Estrategia de copia de seguridad	Replicación gestionada por el proveedor o bucket de respaldo separado	Copia de seguridad manual del directorio public/system
Causa del fallo de subida	Entorno mal configurado, permisos del bucket o red	Disco lleno, permisos incorrectos en directorios locales
Solución típica	Verificar S3_ENABLED, credenciales, endpoint y CORS	Liberar espacio en disco o corregir la propiedad de /home/mastodon/live/public/system

Ahora puede resolver el error “Error al subir el almacenamiento de objetos” verificando cada variable de entorno de S3 en su archivo .env.production de Mastodon, reiniciando los servicios y confirmando que las políticas CORS e IAM del bucket permitan operaciones de escritura. Si el problema persiste, pruebe la conectividad de red al endpoint de S3 y revise los registros de Sidekiq de Mastodon para obtener mensajes de error detallados usando journalctl -u mastodon-sidekiq -n 50. Para el mantenimiento continuo, supervise el uso de almacenamiento del bucket y configure políticas de ciclo de vida para eliminar archivos multimedia antiguos automáticamente.