Si Matrix Synapse en CasaOS muestra «container is unhealthy», empieza por revisar los registros del contenedor y el archivo homeserver.yaml generado en lugar de reinstalarlo a ciegas. Synapse tiene una imagen oficial de Docker, pero un homeserver de producción también necesita configuración y datos persistentes, un nombre de servidor adecuado, PostgreSQL y una planificación correcta de HTTPS y la federación.
SQLite es aceptable para realizar pruebas, pero la documentación actual de Synapse recomienda PostgreSQL para casi todas las instalaciones reales. Un contenedor puede iniciarse y aun así permanecer en estado no saludable cuando falla su configuración, la base de datos, los permisos o una migración durante el inicio.
Usa la imagen oficial de Synapse
La guía de instalación de Synapse actual documenta ghcr.io/element-hq/synapse como imagen oficial del contenedor.
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 Matrix que piensas conservar.
Comprueba por qué el contenedor no está saludable
docker ps -a | grep synapse
docker inspect synapse --format '{{json .State.Health}}'
docker logs --tail 200 synapseBusca errores de YAML, archivos faltantes, fallos de permisos, errores de conexión con la base de datos o migraciones que no terminan.
Usa PostgreSQL en producción
La guía de PostgreSQL de Synapse actual explica la configuración compatible de la base de datos. Mantén persistentes los datos de Postgres y haz copias de seguridad junto con el estado de Synapse.
No cambies server_name después sin planificarlo
Los identificadores de Matrix se derivan del nombre del servidor, como @user:example.com. Elige el dominio definitivo antes de invitar a usuarios.
HTTPS es necesario para un uso práctico
Normalmente, Synapse escucha internamente mediante HTTP (habitualmente 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 procesar del contenedor.
La federación añade más requisitos de DNS y del proxy
Si quieres comunicarte con otros servidores Matrix, configura correctamente el nombre público del servidor, HTTPS y el descubrimiento de la federación. Una prueba solo local puede ser mucho más sencilla.
Haz copias 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 de PostgreSQL. Volver a descargar la imagen no restaura la identidad de un homeserver.
La guía de resolución de problemas de Docker ofrece 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 permisos 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 que espera la imagen. Evita hacer que todo el árbol de datos de CasaOS tenga permisos de escritura para cualquier usuario.
Espera a que terminen las migraciones de la base de datos antes de evaluar el estado
Después de una actualización o de la primera conexión con PostgreSQL, Synapse puede necesitar tiempo para ejecutar las migraciones del esquema. Observa los registros en lugar de reiniciar repetidamente el contenedor, ya que las migraciones interrumpidas pueden dificultar el diagnóstico.
Prueba la API local antes del proxy inverso
Confirma que el endpoint HTTP interno de Synapse responde desde el host de CasaOS antes de añadir HTTPS, DNS o la federación. Si la API local no está saludable, un proxy inverso no puede solucionarlo.
Preguntas frecuentes
¿Por qué Synapse no está saludable?
Revisa los registros y el estado de salud en busca de errores de configuración, permisos, base de datos o migraciones; el hilo de origen no proporcionó una causa única verificada.
¿Puedo usar SQLite?
Para realizar 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 homeserver; Element es un posible cliente o interfaz web.
