Solucionar un problema con el repositorio multimedia Matrix Synapse que está ocupando demasiado espacio en disco.

Un repositorio multimedia de Matrix Synapse puede consumir espacio en disco más rápido que la base de datos del servidor principal, ya que almacena diferentes tipos de archivos: contenido multimedia subido por usuarios locales, miniaturas, contenido multimedia en caché obtenido de servidores remotos y recursos utilizados para previsualizaciones de URL. La solución adecuada no es eliminar archivos al azar del directorio multimedia. Primero, identifique qué archivos están aumentando de tamaño y, a continuación, utilice la API de administración de Synapse o los controles de retención para que los metadatos de la base de datos y los archivos en disco se mantengan consistentes.

A fecha de octubre de 2026, la versión actual de Synapse es la 1.162, y la documentación oficial de gestión de medios incluye API para consultar medios, eliminar medios locales, purgar medios remotos almacenados en caché y configurar la retención automática. Si su instalación es muy antigua, consulte las versiones oficiales de Synapse , ya que el comportamiento de los puntos finales y las opciones de configuración pueden variar entre versiones.

Lista de verificación de triaje rápido

1. Confirme que el problema de espacio en disco reside en el repositorio de medios.

Comience con el sistema de archivos, no con Synapse. Ejecute:

df -h
du -sh /path/to/media_store

La ruta depende de la instalación. media_store_pathLa configuración de Synapse define el directorio que se usa para las imágenes y los archivos adjuntos cargados, y su valor predeterminado documentado es media_storerelativo al directorio de datos de Synapse. Los paquetes de distribución y las implementaciones de contenedores suelen establecer una ruta explícita, así que revise su configuración real en lugar de asumir una ubicación.

Leyenda: Compare el uso del sistema de archivos con el tamaño del almacén de medios Synapse configurado antes de decidir que la limpieza de medios es la solución correcta.

Si el disco está casi lleno, evite ejecutar operaciones recursivas extensas que creen archivos temporales o copias de seguridad de gran tamaño en el mismo sistema de archivos. Si existe un riesgo inminente de quedarse sin espacio, primero detenga las tareas que realicen escrituras intensivas no relacionadas o añada capacidad temporal; a continuación, realice una limpieza controlada.

2. Verifique la configuración de medios activos e identifique qué está creciendo.

Abra el activo homeserver.yamly busque media_store_path. Revise también max_upload_size, cualquier media_storage_providers, y cualquier bloque existente . El manual de configuraciónmedia_retention oficial de Synapse documenta estas opciones.

Leyenda: Confirme que el media_store_pathalmacenamiento esté activo antes de medir o cambiar. La ruta que se muestra aquí es un ejemplo de configuración.

A continuación, mida los subdirectorios de primer nivel:

du -sh /path/to/media_store/* 2>/dev/null | sort -h

La documentación del repositorio de medios de Synapse describe las categorías importantes en disco. Las cargas locales se almacenan debajo de local_content, las miniaturas locales debajo de local_thumbnails, los archivos remotos en caché debajo de remote_content, las miniaturas remotas debajo de remote_thumbnaily los datos de vista previa de URL debajo de url_cachey url_cache_thumbnails.

Leyenda: Un desglose del tamaño a nivel de directorio ayuda a distinguir la caché remota recuperable de las cargas de usuario locales que pueden ser la única copia almacenada por su servidor doméstico.

No utilice rm -rfestos directorios como método de limpieza habitual. Synapse también realiza un seguimiento de los archivos multimedia en su base de datos. Si se omiten las rutas de limpieza compatibles, es posible que queden metadatos que hagan referencia a archivos que ya no existen o que se elimine contenido que los usuarios aún esperan recuperar.

3. Recupere primero la caché de medios remotos cuando sea el consumidor principal.

El almacenamiento en caché de medios remotos suele ser la opción de menor riesgo para recuperar espacio. Synapse guarda copias de los medios alojados originalmente en otros servidores domésticos. La API oficial de eliminación de medios remotos borra los medios remotos almacenados en caché cuyo último acceso se produjo antes de una fecha y hora específicas. Si un usuario vuelve a solicitar esos medios, Synapse los solicitará nuevamente al servidor doméstico de origen.

La API de administración requiere un token de acceso de administrador del servidor. Synapse recomienda mantenerla /_synapse/admin/...oculta al acceso público y, por lo general, llamarla localmente. Consulte la guía oficial de la API de administración .

Por ejemplo, calcule un límite de 30 días en el pasado y elimine la caché remota anterior a ese período:

export SYNAPSE_ADMIN_TOKEN='your-admin-token'
CUTOFF_MS=$(( $(date -d '30 days ago' +%s) * 1000 ))

curl -sS -X POST   -H "Authorization: Bearer $SYNAPSE_ADMIN_TOKEN"   "http://127.0.0.1:8008/_synapse/admin/v1/purge_media_cache?before_ts=$CUTOFF_MS"

La respuesta incluye un deletedrecuento. El límite se basa en el último acceso, no simplemente en la fecha de modificación del archivo. Elija un período que se ajuste al historial de navegación habitual de los usuarios. El contenido remoto eliminado solo se puede recuperar si el servidor de origen aún lo mantiene disponible.

4. Trate los medios locales como datos permanentes a menos que tenga una política de retención.

Los archivos multimedia locales son diferentes. Se subieron a tu servidor doméstico, por lo que eliminarlos puede dañar permanentemente archivos adjuntos, imágenes u otras referencias MXC. Antes de eliminar archivos multimedia locales de forma masiva, inspecciona los elementos representativos o los archivos multimedia de los usuarios a través de la API de administración.

Para consultar un elemento multimedia específico:

curl -sS   -H "Authorization: Bearer $SYNAPSE_ADMIN_TOKEN"   "http://127.0.0.1:8008/_synapse/admin/v1/media/example.org/MEDIA_ID"

La respuesta puede incluir media_length, created_ts, last_access_ts, tipo MIME y estado de cuarentena. La documentación oficial de la API de administración de medios define estos campos y las operaciones de eliminación admitidas.

Leyenda: Consultar los metadatos de los archivos multimedia antes de aplicar las reglas de eliminación para que las decisiones sobre antigüedad y tamaño se basen en los registros de Synapse en lugar de en las marcas de tiempo del sistema de archivos.

Synapse puede eliminar archivos multimedia locales por fecha de último acceso y, opcionalmente, por tamaño:

CUTOFF_MS=$(( $(date -d '180 days ago' +%s) * 1000 ))

curl -sS -X POST   -H "Authorization: Bearer $SYNAPSE_ADMIN_TOKEN"   "http://127.0.0.1:8008/_synapse/admin/v1/media/delete?before_ts=$CUTOFF_MS&size_gt=0&keep_profiles=true"

before_tses una marca de tiempo Unix en milisegundos y se refiere al último acceso. size_gtes un umbral de bytes; su valor predeterminado es cero. keep_profiles=truees el valor predeterminado y conserva los medios que aún se utilizan como imágenes de perfil o de sala. Mantenga esa protección a menos que tenga una razón específica para eliminar esas imágenes.

También puedes listar o eliminar archivos multimedia subidos por un usuario local específico /_synapse/admin/v1/users/<user_id>/media. Esto resulta útil cuando una cuenta genera un crecimiento inusual. Consulta la documentación de la API de administración de usuarios antes de usar la función de eliminación, especialmente sus parámetros de ordenación y límite.

5. Evitar que el almacenamiento de medios vuelva a llenar el disco.

Habilitar la retención automática de medios

Para un control continuo, Synapse proporciona media_retention. Un ejemplo basado en el formato de configuración oficial es:

media_retention:
  local_media_lifetime: 180d
  remote_media_lifetime: 30d

Un archivo multimedia se puede eliminar si no se ha accedido a él durante el tiempo de vida útil configurado. Si nunca se ha accedido, Synapse utiliza su fecha de creación. Se eliminan tanto el archivo original como las miniaturas. Si se omite o se establece como nulo el tiempo de vida útil, esa categoría no se elimina automáticamente.

Elija el valor local con precaución: a diferencia de la caché remota, los archivos multimedia locales eliminados no se pueden reconstruir simplemente solicitando el original a otro servidor. Los archivos multimedia en cuarentena no se eliminan mediante la retención automática, y los archivos multimedia locales protegidos también se excluyen según la documentación de configuración.

Utilice controles de carga para el crecimiento futuro.

max_upload_sizeLimita cada carga individual; no limita el tamaño total del repositorio. La versión actual de Synapse también permite media_upload_limitslimitar la cantidad de archivos que un usuario puede subir durante periodos de tiempo definidos. Estos controles reducen el crecimiento, pero no reemplazan la retención ni la monitorización de la capacidad.

Considere un proveedor de almacenamiento cuando el sistema de archivos local sea el cuello de botella.

Synapse admite la migración media_storage_providers, incluyendo un proveedor de sistema de archivos que permite ubicar los archivos multimedia en otro directorio. Esto puede ser útil si se dispone de un volumen o nivel de almacenamiento dedicado. Se trata de un cambio en la arquitectura de almacenamiento, no de una solución de emergencia, por lo que se recomienda probar las copias de seguridad, los permisos, el acceso de los trabajadores y el comportamiento de recuperación antes de migrar los archivos multimedia de producción.

Verificación después de la limpieza

Tras cualquier purga, verifique tanto la capacidad como el comportamiento de la aplicación:

df -h
du -sh /path/to/media_store
du -sh /path/to/media_store/* 2>/dev/null | sort -h

• Abra un archivo adjunto subido recientemente a su dispositivo en un cliente Matrix.
• Abra un archivo adjunto remoto antiguo y confirme que se puede recuperar de nuevo.
• Compruebe los registros de Synapse en busca de errores relacionados con el sistema de archivos o el procesador de medios.
• Si utiliza trabajadores de medios dedicados, confirme que las solicitudes de la API de administración se enrutan a un trabajador del repositorio de medios. La documentación del trabajador de Synapse enumera los puntos finales de administración específicos de los medios que deben gestionarse allí.
• Registre el tamaño del almacenamiento de medios después de la limpieza y compárelo nuevamente después de varios días para medir la tasa de crecimiento real.

Referencia rápida para la toma de decisiones

En resumen

Cuando un repositorio de medios de Matrix Synapse llena un disco, primero hay que determinar qué tipo de medio es el responsable. La caché remota suele ser la opción más segura, ya que Synapse cuenta con una API de purga específica y normalmente puede recuperar ese contenido. Los medios locales requieren una política mucho más estricta, puesto que puede ser la única copia en el servidor de un archivo adjunto. Una vez recuperado el espacio disponible, configure media_retentiony supervise la tasa de crecimiento del almacenamiento de medios para que la limpieza se convierta en un mantenimiento predecible en lugar de una emergencia.