Haga que su servidor Matrix Synapse sea accesible para la federación.

Para que un servidor doméstico Matrix Synapse se federe, asegúrese de que su nombre de servidor sea visible y accesible desde internet mediante HTTPS, y luego redirija las solicitudes de servidor a servidor de Matrix a Synapse. En una configuración común, un proxy inverso gestiona TLS en el puerto 443 y un /.well-known/matrix/serverarchivo apunta su dominio Matrix a dicho proxy. Si Synapse ya responde en el dominio de su servidor en el puerto 8448, es posible que no necesite delegación.

Este tutorial utiliza example.comcomo nombre permanente del servidor Matrix y matrix.example.comcomo punto final de la máquina o proxy. Reemplace ambos con sus propios nombres. Un servidor principal almacena las cuentas y salas de Matrix; la federación permite que los servidores principales se comuniquen entre sí. El DNS, las reglas del firewall, la sintaxis del proxy, la red de contenedores y los certificados dependen de su host.

Antes de cambiar la configuración

Decida si los ID de Matrix de los usuarios deben tener el formato @name:example.como @name:matrix.example.com. El valor de server_nameen homeserver.yamlpasa a formar parte de los ID de Matrix y las direcciones de sala. La documentación de instalación de Synapse indica que debe elegirse antes de la instalación, ya que no se puede modificar posteriormente sin consecuencias. Si Synapse ya está en uso, no lo modifique solo para que coincida con una dirección web; utilice la delegación para conservar los ID existentes.

Un editor YAML muestra server_name: example.com y un recordatorio para elegir el valor antes de la instalación.
El nombre del servidor forma parte de los ID de Matrix, así que confírmelo antes de continuar.

Antes de editar, asegúrese de tener acceso a Synapse, al proxy y al DNS público, y de contar con un certificado TLS válido para el punto final de la federación. Realice una copia de seguridad homeserver.yamlde la clave de firma, que establece la identidad del servidor principal. Guarde esta clave en un lugar seguro; la configuración habitual de la federación no requiere su regeneración.

Establecer la ruta pública

1. Confirmar el oyente HTTP de Synapse

Synapse suele escuchar el tráfico HTTP en un puerto 8008detrás de un proxy inverso. En el oyente que acepta el tráfico del proxy, configure la opción para que Synapse pueda usar la dirección IP y el esquema del cliente reenviados por el proxy. El proxy debe configurar los encabezados x_forwarded: trueadecuados , en lugar de pasar valores arbitrarios proporcionados por clientes externos.X-Forwarded-ForX-Forwarded-Proto

Un extracto del oyente YAML muestra Synapse en el puerto HTTP 8008 con x_forwarded habilitado y una dirección de enlace de bucle invertido.
El receptor acepta HTTP desde un proxy local y habilita el manejo de encabezados reenviados de Synapse.

La vinculación 127.0.0.1es adecuada cuando el proxy se ejecuta en el mismo host. No es adecuada cuando el proxy se encuentra en otro contenedor o máquina, a menos que dicha dirección sea accesible desde el proxy. En una implementación de contenedor, utilice la dirección de red o el nombre del servicio al que el proxy puede acceder y restrinja el acceso a través de la red o el firewall del contenedor. Mantenga la estructura del listener existente y edite los valores correspondientes; no copie un fragmento sin más sobre el resto de la configuración.

2. Rutas de la matriz de enrutamiento a través del proxy

Configure el host virtual HTTPS del proxy para que reenvíe ambas rutas /_matrixal /_synapse/clientoyente HTTP de Synapse. La primera ruta contiene las API de Matrix, incluida la federación; la segunda se utiliza para los puntos finales del cliente Synapse. Siga el ejemplo oficial de su software proxy, conserve la ruta de la solicitud y envíe los encabezados reenviados que Synapse espera. No normalice, decodifique ni reescriba las rutas URI: las firmas de solicitud de Matrix pueden fallar si un proxy modifica la ruta codificada.

Un editor de configuración de proxy inverso muestra las rutas de la API de Matrix y del cliente Synapse enrutadas al puerto 8008 de localhost con encabezados reenviados.
El proxy debe pasar ambas rutas de la API de Matrix a Synapse sin reescribir la URI.

La configuración exacta varía según Nginx, Caddy, Apache, balanceadores de carga y servicios de alojamiento gestionado. Utilice la sintaxis actual del proveedor y la documentación del proxy inverso de Synapse como referencia. Una regla de proxy que atienda al cliente web pero omita la ruta de la API de federación no es suficiente.

3. Asegúrese de que DNS, HTTPS y el puerto elegido coincidan.

Por ejemplo, matrix.example.comdebe resolverse al proxy o balanceador de carga, y el puerto 443debe ser accesible desde el exterior. El proxy necesita un certificado válido para matrix.example.com. Si en cambio sirve la federación directamente en example.com:8448, publique esa ruta y certificado y abra el puerto 8448. Use el puerto directo 8448, el predeterminado convencional, o la delegación a otro host y puerto como el 443.

Confirme las reglas de DNS, firewall o grupo de seguridad en la nube, y el certificado desde fuera de su red privada. Si hay una CDN o un túnel delante, la compatibilidad con el tráfico Matrix requerido depende de la configuración actual de dicho servicio; consulte su documentación y pruebe la ruta real en lugar de dar por sentada la compatibilidad.

Publicar el descubrimiento de la federación cuando sea necesario.

4. Agregar delegación de servidor para un punto final separado.

Si el dominio Matrix ID es example.compero Synapse es accesible en matrix.example.com:443, sirva este JSON a través de HTTPS en https://example.com/.well-known/matrix/server:

{
  "m.server": "matrix.example.com:443"
}
Una vista JSON de estilo navegador en example.com/.well-known/matrix/server contiene el valor m.server matrix.example.com:443.
Este registro de descubrimiento de federación delega example.com al punto final HTTPS en matrix.example.com en el puerto 443.

El puerto 443 es explícito en este ejemplo; si omite un puerto, el descubrimiento de Matrix usa por defecto el 8448. No confunda este archivo con /.well-known/matrix/client, que ayuda a los clientes a encontrar la API cliente-servidor y es independiente de la federación de servidor a servidor. Synapse puede servir un archivo conocido del servidor cuando el dominio del nombre del servidor se enruta directamente a Synapse, pero con un punto final separado, normalmente se publica el archivo en el servidor web del dominio del nombre del servidor.

El descubrimiento de la federación está especificado por Matrix y documentado por Synapse. La especificación de Matrix permite el descubrimiento a través de /.well-known/matrix/server; consulte las instrucciones de delegación de Synapse antes de elegir un método diferente, como un registro SRV, que también afecta a las expectativas de TLS.

Prueba desde fuera del servidor

5. Verifique el registro y luego ejecute una comprobación de federación.

Solicite la URL de descubrimiento desde una máquina fuera de la red privada del servidor. Debería devolver el objeto JSON anterior a través de HTTPS sin página de inicio de sesión, redirección HTML, advertencia de certificado ni sitio web no relacionado. A continuación, compruebe que el nombre de host delegado se resuelve, que su certificado es válido y que su puerto anunciado llega a Synapse. Utilice el verificador de configuración y el procedimiento de recarga de su proxy antes de realizar la prueba.

Finalmente, ingrese el nombre de su servidor (por ejemplo, example.com, no el nombre de host delegado a menos que sea su server_name) en el Probador de federación oficial de Matrix . La guía de federación de Synapse también sugiere realizar pruebas uniéndose a una sala pública como #synapse:matrix.org. Una verificación exitosa confirma que las comprobaciones comunes de descubrimiento y accesibilidad se superaron; no garantiza que todos los servidores remotos o todas las operaciones de la sala funcionen, ya que las políticas remotas y las condiciones de la red varían.

Si el probador informa que no se puede acceder a su servidor, verifique el dominio y el puerto que intentó usar, el DNS, las reglas del firewall, el nombre del certificado, las rutas del proxy, los encabezados reenviados y si una redirección modificó la solicitud. La documentación actual de federación de Synapse advierte específicamente que los servidores de federación de Synapse podrían no seguir las redirecciones HTTP 308 en algunos casos. Evite depender de una redirección 308 para el punto final de federación y vuelva a realizar la prueba después de corregirla. Consulte la documentación correspondiente a su versión de Synapse instalada para obtener información sobre el comportamiento específico de la versión.

La federación requiere que los servidores remotos descubran y accedan a la API de federación. No es posible determinar si esto funciona para todos los servidores remotos basándose únicamente en la configuración. Confirme la ruta con el probador y una conexión real a la sala; luego, investigue el punto final o error específico que está fallando.

Estos paneles de interfaz son ejemplos esquemáticos de configuración y datos de detección, no capturas de pantalla de un servidor en funcionamiento. La documentación se consultó el 10 de octubre de 2026.

Dejar un comentario

Solucionar errores de permisos de administrador de sala de matriz mediante una acción

Rastrea el evento M_FORBIDDEN hasta los niveles de energía de la sala, la membresía o el acceso de administrador del servidor Synapse, y luego restaura solo el permiso que necesita la acción bloqueada.

Haga que su servidor Matrix Synapse sea accesible para la federación.

Haga que su servidor Matrix Synapse sea accesible para la federación.

Configure la detección de Synapse, HTTPS y el enrutamiento proxy para que otros servidores domésticos de Matrix puedan encontrar y contactar con su servidor.

Conectar Element Web con Keycloak a través de Synapse OIDC

Configure un cliente OIDC de Keycloak y un proveedor Synapse para que los usuarios de Element Web puedan iniciar sesión a través de su servidor de identidad sin exponer las credenciales de cliente.

Configure de forma segura la copia de seguridad de claves de elementos y la firma cruzada.

Configure de forma segura la copia de seguridad de claves de elementos y la firma cruzada.

Guarda una clave de recuperación, verifica tus sesiones de Element y comprueba que las claves de mensajes cifrados se puedan restaurar sin confundir la copia de seguridad con la contraseña de tu cuenta.

Evitar fallos de memoria de Matrix Synapse durante la sincronización del cliente

Diagnostica los fallos de falta de memoria de Synapse durante la sincronización, ajusta el almacenamiento en caché de forma segura, identifica las colas de solicitudes y verifica el uso estable de la memoria.

Solucionar errores de certificado TLS de Synapse Federation

Rastrea los fallos del certificado de federación de Matrix hasta el servidor correcto, repara la cadena TLS o la confianza de la CA y verifica la solución sin deshabilitar las comprobaciones de seguridad.

Coloca un servidor Synapse Matrix detrás de Cloudflare de forma segura.

Coloca un servidor Synapse Matrix detrás de Cloudflare de forma segura.

Los clientes de Route Matrix y la federación a través de Cloudflare en HTTPS 443 preservan el descubrimiento de Synapse y evitan el almacenamiento en caché del tráfico de la API o la interrupción de las cargas de medios.

Restaura Matrix Synapse de forma segura con un volcado de PostgreSQL.

Realice una copia de seguridad de Synapse con pg_dump, proteja su clave de firma y el medio de almacenamiento, y restáurela en una base de datos PostgreSQL limpia sin reutilizar claves obsoletas de un solo uso.

Ejecuta Mjölnir como un bot de moderación de salas Matrix con Docker.

Ejecuta Mjölnir como un bot de moderación de salas Matrix con Docker.

Configura Mjölnir con una cuenta Matrix dedicada, una sala de administración cifrada, Docker Compose, una lista de políticas y comprobaciones de permisos.

Habilita la sincronización nativa de la matriz deslizante para una carga más rápida en dispositivos móviles.

Habilita la sincronización nativa de la matriz deslizante para una carga más rápida en dispositivos móviles.

Omita el proxy obsoleto y configure la sincronización deslizante integrada de Synapse. Verifique la detección de clientes y luego mida la carga de la lista de salas y el comportamiento de reconexión en un teléfono compatible.