Cómo configurar un servidor Matrix detrás de un proxy de Cloudflare

Un servidor Matrix puede estar detrás de Cloudflare, pero la configuración depende de cómo lo descubran los clientes y otros servidores domésticos. El proxy HTTP estándar de Cloudflare admite HTTPS en el puerto 443; la federación de Synapse suele usar por defecto el puerto 8448, que no está en la lista de puertos proxy estándar de Cloudflare. Una solución fiable consiste en exponer Synapse a través de un proxy inverso en el puerto 443 y publicar registros conocidos de Matrix que dirijan el tráfico de clientes y de federación a ese nombre de host. Como alternativa, se puede mantener la federación en el puerto 8448 y configurar ese registro DNS como de solo DNS.

Esta guía utiliza Synapse, la implementación oficial del servidor doméstico Matrix, con los ID de Matrix @alice:example.comy el punto final del cliente de ejemplo matrix.example.com. Reemplace estos nombres y direcciones con los suyos. Las instrucciones asumen que Synapse y un proxy inverso HTTPS ya están instalados. No se aplican sin cambios a todas las implementaciones de servidor doméstico. Verificado con la documentación actual de Cloudflare y Element Synapse el 6 de octubre de 2026.

Elija el diseño de red adecuado

El proxy orange-cloud de Cloudflare es un proxy inverso HTTP/HTTPS. Se sitúa entre los clientes y el servidor de origen para las solicitudes web que utilizan el proxy; no gestiona todos los puertos TCP. Sus puertos HTTPS estándar incluyen el 443 y el 8443, pero no el puerto de federación 8448, de uso común en Synapse. Consulte los puertos de red compatibles y las limitaciones de proxy de Cloudflare .

A continuación se muestra el primer diseño. Un registro DNS con proxy no configura por sí solo el descubrimiento de Matrix, el proxy inverso, TLS ni la política del firewall.

1. Decida el nombre del servidor Matrix antes de configurar el DNS.

El nombre del servidor Matrix es la parte que aparece después de los dos puntos en un ID de usuario. En este ejemplo es example.com, por lo que los usuarios tienen ID como @alice:example.com. El nombre de host del cliente técnico es matrix.example.com. Esta separación permite que el dominio utilizado en los ID de usuario se mantenga estable mientras el tráfico se delega a otro nombre de host. Si Synapse ya está inicializado, no lo cambie server_namesin motivo: forma parte de la identidad del usuario y de la sala, y cambiarlo es una migración, no un ajuste del proxy.

Plan para servir dos pequeños documentos de descubrimiento JSON desde el dominio del nombre del servidor:

• https://example.com/.well-known/matrix/clientindica a los clientes compatibles que utilicen https://matrix.example.com.
• https://example.com/.well-known/matrix/serverindica a otros servidores domésticos que alcancen la federación en matrix.example.com:443.

El documento del cliente necesita un Access-Control-Allow-Origin: *encabezado de respuesta. La guía de delegación de Synapse incluye ejemplos de estos registros y su estructura esperada: Delegación de federación de Synapse .

2. Crea los registros DNS de Cloudflare.

En Cloudflare DNS, crea un Aregistro matrixque apunte a la dirección IPv4 pública del servidor. Agrega un AAAAregistro solo si el origen tiene conectividad IPv6 activa y un firewall configurado para IPv6. Establece el estado del proxy del nombre de host web en Proxyed (nube naranja). Si el dominio raíz también apunta a este servidor y servirá los archivos conocidos, configura también su registro web como proxy.

Mantenga los registros no relacionados, incluidos los registros de correo, en su configuración DNS-only apropiada. Los registros MX y TXT no se procesan mediante proxy. Cloudflare explica que un registro A, AAAA o CNAME procesado mediante proxy enruta las solicitudes HTTP/HTTPS a través de Cloudflare, mientras que DNS-only devuelve la dirección de origen directamente: Comportamiento del estado del proxy de Cloudflare .

Permita el tráfico HTTPS entrante desde Cloudflare al origen. Para una mayor protección, restrinja el firewall de origen a los rangos de IP publicados por Cloudflare y manténgalos actualizados. Si la IP del servidor estaba expuesta antes de que la zona se activara, el proxy DNS no invalida esa dirección antigua; considere cambiar la IP de origen después de la activación. No asuma que la nube naranja por sí sola impide el acceso directo al origen.

3. Configura HTTPS entre Cloudflare y el origen.

En la configuración SSL/TLS de Cloudflare, utilice el modo Completo (estricto) cuando el origen presente un certificado válido para el nombre de host, como un certificado de confianza pública o un certificado de CA de origen de Cloudflare. El modo Completo (estricto) cifra la conexión entre Cloudflare y el origen y valida el certificado de origen; el modo Flexible no proporciona la misma ruta TLS de extremo a extremo. Consulte la documentación de Cloudflare sobre el modo Completo (estricto) .

Instale el certificado y la clave privada en el proxy inverso, no necesariamente en Synapse. El proxy inverso debe escuchar en el puerto público 443 y reenviar las solicitudes de Matrix internamente al oyente HTTP de Synapse, generalmente en el puerto 8008. No exponga públicamente el oyente de Synapse si el proxy inverso va a ser el único punto de entrada.

4. Indíquele a Synapse que se encuentra detrás de un proxy inverso de confianza.

En el oyente HTTP correspondiente homeserver.yaml, habilite el manejo de encabezados reenviados. Un ejemplo simplificado para un servidor no en contenedores es:

listeners:
  - port: 8008
    type: http
    tls: false
    x_forwarded: true
    bind_addresses: ['127.0.0.1']
    resources:
      - names: [client, federation]
        compress: false

Integra estos ajustes en el listener existente en lugar de reemplazar toda la configuración. La documentación actualizada de Synapse recomienda x_forwarded: trueusar un proxy inverso y sugiere vincularlo a localhost cuando el proxy se ejecuta en el mismo host. Para una implementación en contenedores, vincular Synapse a la interfaz loopback del contenedor puede impedir que el proxy del host lo alcance; en su lugar, usa la dirección de red del contenedor o servicio y bloquea esa ruta con un firewall. Consulta la guía actual de Synapse sobre proxy inverso antes de modificar la configuración del listener.

Los encabezados reenviados solo son confiables cuando Synapse acepta tráfico desde su proxy controlado. Si Cloudflare es la única ruta de acceso a internet, impida el acceso público directo al origen y configure el proxy para que envíe la dirección del cliente correcta. $remote_addrDe lo contrario, la dirección de Nginx será una dirección de Cloudflare porque Cloudflare se conecta a Nginx. Configure el módulo real-IP de Nginx para que solo confíe en los rangos de origen publicados por Cloudflare antes de usar CF-Connecting-IP; nunca confíe en ese encabezado de clientes de internet arbitrarios. Mantenga la API de administración de Synapse privada a menos que tenga una razón específica para exponerla.

5. Rutas de la matriz de enrutamiento sin reescribirlas.

Configure su proxy inverso para que envíe ambos /_matrixa /_synapse/clientSynapse. Conserve la URI de la solicitud tal cual. Las firmas de las solicitudes de federación de Synapse pueden fallar si un proxy decodifica o normaliza los segmentos de ruta codificados.

Aquí tienes un ejemplo compacto de Nginx para matrix.example.com. Se supone que tus directivas de certificado TLS ya están configuradas para este bloque de servidor y que el proxy inverso y Synapse se ejecutan en el mismo host:

server {
    listen 443 ssl;
    server_name matrix.example.com;

    location ~ ^(/_matrix|/_synapse/client) {
        proxy_pass http://127.0.0.1:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $host;
        proxy_http_version 1.1;
        client_max_body_size 50M;
    }
}

No añada un sufijo URI a la ubicación de esta expresión regular proxy_pass. La documentación del proxy de Synapse indica que la canonicalización de URI puede causar errores en la firma de federación. Además, ajuste el valor client_max_body_sizepara que coincida con el límite de carga de Synapse y cualquier límite del plan de Cloudflare aplicable a su zona. El 50Mvalor anterior es solo un ejemplo, no una recomendación universal.

Cloudflare admite WebSockets en sus planes, y los clientes de Matrix pueden usar conexiones de larga duración. Confirme que su proxy permite la actualización y que las reglas de WAF o de limitación de velocidad no rechazan las solicitudes legítimas de Matrix. La documentación de WebSockets de Cloudflare describe cómo gestiona las conexiones actualizadas.

6. Publicar las respuestas más conocidas.

Envía las siguientes dos respuestas a example.comtravés de HTTPS. Puedes devolverlas desde tu servidor web, un host estático o un host virtual independiente. Mantén los documentos del cliente y de la federación separados:

GET /.well-known/matrix/client
HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: *

{"m.homeserver":{"base_url":"https://matrix.example.com"}}

GET /.well-known/matrix/server
HTTP/1.1 200 OK
Content-Type: application/json

{"m.server":"matrix.example.com:443"}

No utilice una redirección a un host no relacionado como sustituto sin antes verificar los requisitos de detección de Matrix y el comportamiento del cliente. Asegúrese de que el host del servidor esté cubierto por un certificado HTTPS válido y de que Cloudflare no almacene en caché respuestas de detección obsoletas mientras las modifica.

7. Mantenga el tráfico de la API dinámico y las cargas dentro de los límites.

No almacene en caché las respuestas autenticadas de la API de Matrix. Agregue una regla de caché de Cloudflare para omitir el almacenamiento en caché de las rutas de la API de Matrix, incluidas /_matrix/*y /_synapse/client/*, a menos que tenga una razón cuidadosamente probada para manejar una respuesta pública específica de manera diferente. Evite reglas amplias de WAF o de bots que desafíen o bloqueen los puntos finales de federación; las solicitudes de federación provienen de muchos servidores independientes. Si es necesaria una regla de seguridad, pruébela con el inicio de sesión del cliente, la sincronización, la carga de medios y la federación antes de aplicarla de forma general.

Las cargas tienen varios límites independientes: el cliente, la configuración de carga del plan o zona de Cloudflare, el límite de tamaño del cuerpo del proxy inverso y el de Synapse max_upload_size. Un error 413 significa que uno de esos límites rechazó la solicitud. Cloudflare publica límites de carga que dependen del plan e indica que estos ajustes se pueden modificar dentro de las restricciones documentadas: página de solución de problemas 413 de Cloudflare . Aumente solo los límites necesarios y pruebe con un archivo más pequeño que el límite configurado antes de aumentarlos aún más.

8. Verificar el acceso, la detección y la federación del cliente.

Ejecute estas comprobaciones desde una máquina fuera de la red de su servidor. Reemplace los nombres de host de ejemplo:

curl -i https://example.com/.well-known/matrix/client
curl -i https://example.com/.well-known/matrix/server
curl -i https://matrix.example.com/_matrix/client/versions
curl -i https://matrix.example.com/health

Las dos primeras solicitudes deben devolver HTTP 200, contenido JSON y los valores esperados. El documento del cliente debe incluir el encabezado CORS. El punto final de versiones del cliente debe devolver JSON desde Synapse a través de Cloudflare. El punto final de estado de Synapse devuelve HTTP 200 cuando se accede a él mediante un oyente configurado, pero no sustituye la comprobación de inicio de sesión o federación.

Luego, inicia sesión con un cliente Matrix usando una ID que termine en :example.com, únete a una sala alojada en otro lugar y confirma que los mensajes y las actualizaciones de membresía se sincronicen. Usa un probador de federación de Matrix o un segundo servidor principal para validar el descubrimiento del servidor y la federación. Una solicitud exitosa a /_matrix/client/versionssolo demuestra que la ruta orientada al cliente funciona; no demuestra que el descubrimiento de la federación, la firma o la federación saliente sean correctos.

Qué significa el éxito y cuándo cambiar el diseño.

• Los clientes se conectan a través de Cloudflare: el DNS se resuelve a direcciones de Cloudflare, HTTPS utiliza el certificado previsto y la API del cliente Matrix devuelve una respuesta.
• El descubrimiento es correcto: ambas URL conocidas devuelven el JSON correcto y el documento del cliente supera las comprobaciones de origen cruzado.
• La federación funciona: un servidor remoto descubre el punto final anunciado y puede intercambiar el estado de la sala. Si la delegación 443 falla, pero la directa 8448 funciona, revise el registro conocido, el enrutamiento de la ruta proxy y las reglas del WAF.
• Las cargas funcionan correctamente con el tamaño esperado: prueba con una carga representativa. Si los archivos pequeños se cargan correctamente, pero los archivos más grandes devuelven un error 413, compara los cuatro límites de tamaño en lugar de modificar solo Synapse.
• El origen no es una ruta pública alternativa: las solicitudes directas al origen deben bloquearse o limitarse según lo previsto. Si aún así llegan al servicio Matrix, corrija la configuración del firewall y del proxy de confianza.

Utilice la federación solo DNS en el puerto 8448 si sus requisitos o implementación no permiten la federación en el puerto 443, pero tenga en cuenta que esto expone la dirección de origen y elimina la protección de proxy HTTP de Cloudflare para ese nombre de host. Spectrum es otra opción para puertos no estándar, sujeta a la disponibilidad del producto y las restricciones del plan. El proxy de Cloudflare también implica que TLS finaliza en Cloudflare antes de una segunda conexión TLS a su origen; el cifrado de extremo a extremo de Matrix protege el contenido del mensaje cifrado, pero no oculta los metadatos de conexión ni el contenido que no está cifrado de extremo a extremo a los servicios que gestionan la solicitud HTTP. Elija la topología según sus requisitos de privacidad, federación y disponibilidad, y vuelva a realizar pruebas después de cambios en DNS, certificados, Synapse o reglas de Cloudflare.