Si Matrix Synapse en CasaOS muestra “container is unhealthy”, empieza por los registros del contenedor y el homeserver.yaml generado, en lugar de reinstalar a ciegas. Synapse tiene una imagen Docker oficial, pero un homeserver de producción también necesita configuración y datos persistentes, un nombre de servidor adecuado, PostgreSQL y planificación de HTTPS y la federación.
SQLite es aceptable para pruebas, pero la documentación actual de Synapse recomienda PostgreSQL para casi todas las instalaciones reales. Un contenedor puede iniciarse y, aun así, no estar en buen estado si falla su configuración, la base de datos, los permisos o la migración de inicio.
Usa la imagen oficial de Synapse
La guía de instalación actual de Synapse documenta ghcr.io/element-hq/synapse como imagen de contenedor oficial.
Genera la configuración inicial
Crea un directorio persistente y genera la configuración una vez antes del inicio normal:
mkdir -p /DATA/AppData/synapse
docker run --rm -it -v /DATA/AppData/synapse:/data -e SYNAPSE_SERVER_NAME=matrix.example.com -e SYNAPSE_REPORT_STATS=no ghcr.io/element-hq/synapse:latest generateSustituye el dominio de ejemplo por el nombre del servidor de Matrix que quieras conservar.
Comprueba por qué el contenedor no está en buen estado
docker ps -a | grep synapse
docker inspect synapse --format '{{json .State.Health}}'
docker logs --tail 200 synapseBusca errores de YAML, archivos faltantes, problemas de permisos, errores de conexión con la base de datos o migraciones que nunca se completan.
Usa PostgreSQL en producción
La guía actual de PostgreSQL para Synapse explica la configuración de base de datos compatible. Mantén persistentes los datos de Postgres y haz copias de seguridad junto con el estado de Synapse.
No cambies server_name más adelante sin planificarlo
Tus ID de Matrix se derivan del nombre del servidor, por ejemplo, @user:example.com. Elige el dominio definitivo antes de invitar a usuarios.
Se requiere HTTPS para un uso práctico
Synapse suele escuchar internamente a través de HTTP (normalmente en el puerto 8008). Usa un proxy inverso con HTTPS para los clientes y la federación, en lugar de exponer públicamente el puerto sin protección del contenedor.
La federación añade más requisitos de DNS y proxy
Si quieres comunicarte con otros servidores Matrix, configura correctamente el nombre público del servidor, HTTPS y la detección de federación. Una prueba solo local puede ser mucho más sencilla.
Haz una copia de seguridad de algo más que el contenedor
Conserva homeserver.yaml, las claves de firma, los archivos multimedia subidos y la base de datos PostgreSQL. Volver a descargar la imagen no restaura la identidad del servidor doméstico.
La guía de resolución de problemas de Docker presenta el modelo general para depurar contenedores.
Comprueba la propiedad de los archivos en la carpeta de datos persistentes
Si el registro del contenedor informa de un error de permiso denegado al leer homeserver.yaml, las claves de firma o los archivos multimedia, corrige la propiedad del directorio de datos de Synapse montado para que coincida con el UID/GID esperado por la imagen. Evita que todos los archivos del árbol de datos de CasaOS tengan permisos de escritura para cualquier usuario.
Espera a que terminen las migraciones de la base de datos antes de evaluar el estado de salud
Después de una actualización o de la primera conexión a PostgreSQL, es posible que Synapse necesite tiempo para ejecutar las migraciones del esquema. Vigila los registros en lugar de reiniciar el contenedor repetidamente, ya que interrumpir las migraciones puede dificultar el diagnóstico.
Prueba la API local antes del proxy inverso
Comprueba que el endpoint HTTP interno de Synapse responda desde el host de CasaOS antes de añadir HTTPS, DNS o federación. Si la API local no funciona correctamente, un proxy inverso no puede solucionarlo.
Preguntas frecuentes
¿Por qué Synapse no está en buen estado?
Revisa los registros y el estado de salud para detectar errores de configuración, permisos, base de datos o migración; el hilo original no proporcionó una causa única verificada.
¿Puedo usar SQLite?
Para hacer pruebas, sí. La documentación actual de Synapse recomienda PostgreSQL para casi todas las instalaciones de producción.
¿Qué puerto usa Synapse internamente?
Las configuraciones habituales de Docker exponen la API de cliente/servidor en el puerto 8008, detrás de un proxy inverso.
¿Necesito Element?
No. Synapse es el servidor doméstico; Element es un posible cliente o interfaz web.
