Como configurar um servidor Matrix por trás de um proxy Cloudflare

Um servidor Matrix pode ficar atrás do Cloudflare, mas a configuração depende de como os clientes e outros servidores domésticos o descobrem. O proxy HTTP padrão do Cloudflare suporta HTTPS na porta 443; a federação do Synapse geralmente usa a porta 8448 por padrão, que não está na lista de portas proxy padrão do Cloudflare. Uma solução confiável é expor o Synapse por meio de um proxy reverso na porta 443 e publicar registros WK (Well-Known Register) do Matrix que direcionem os clientes e o tráfego de federação para esse hostname. Como alternativa, mantenha a federação na porta 8448 e configure esse registro DNS como somente DNS.

Este guia utiliza o Synapse, a implementação oficial do Matrix para servidores domésticos, com os IDs do Matrix @alice:example.come o endpoint do cliente de exemplo matrix.example.com. Substitua esses nomes e endereços pelos seus. As instruções pressupõem que o Synapse e um proxy reverso HTTPS já estejam instalados. Elas não se aplicam integralmente a todas as implementações de servidores domésticos. Verificado com base na documentação atual do Cloudflare e do Element Synapse em 6 de outubro de 2026.

Escolha o layout de rede correto

O proxy laranja da Cloudflare é um proxy reverso HTTP/HTTPS. Ele se posiciona entre os clientes e seu servidor de origem para requisições web encaminhadas; ele não encaminha todas as portas TCP indiscriminadamente. Suas portas HTTPS padrão incluem 443 e 8443, mas não a porta 8448, comumente usada para federação pelo Synapse. Consulte a lista de portas de rede suportadas e limitações de proxy da Cloudflare .

O primeiro layout é usado abaixo. Um registro DNS proxy não configura, por si só, a descoberta do Matrix, o proxy reverso, o TLS ou a política de firewall.

1. Defina o nome do servidor Matrix antes de configurar o DNS.

O nome do servidor Matrix é a parte que vem depois dos dois pontos no ID do usuário. Neste exemplo, é `<username>` example.com, então os usuários têm IDs como `<username> @alice:example.com`. O nome técnico do host do cliente é `<username>` matrix.example.com. Essa separação permite que o domínio usado nos IDs de usuário permaneça estável enquanto o tráfego é delegado para outro nome de host. Se o Synapse já estiver inicializado, não o altere server_namesem necessidade: ele faz parte da identidade do usuário e da sala, e alterá-lo é uma migração, não um ajuste de proxy.

Planeja-se disponibilizar dois pequenos documentos JSON de descoberta a partir do domínio do nome do servidor:

• https://example.com/.well-known/matrix/clientIndica aos clientes compatíveis para usarem https://matrix.example.com.
• https://example.com/.well-known/matrix/serverinstrui outros servidores domésticos a acessarem a federação em matrix.example.com:443.

O documento do cliente precisa de um Access-Control-Allow-Origin: *cabeçalho de resposta. O guia de delegação do Synapse inclui exemplos desses registros e sua estrutura esperada: Delegação de federação do Synapse .

2. Crie os registros DNS do Cloudflare.

No DNS da Cloudflare, crie um Aregistro com o nome matrixque aponte para o endereço IPv4 público do servidor. Adicione um AAAAregistro somente se a origem tiver conectividade IPv6 funcionando e um firewall configurado para IPv6. Defina o status de proxy do nome de host da web como " Proxyed" (nuvem laranja). Se o domínio raiz também apontar para este servidor e servir os arquivos conhecidos, configure o registro web dele como proxy também.

Mantenha registros não relacionados, incluindo registros de e-mail, em suas configurações apropriadas de DNS somente. Registros MX e TXT não são encaminhados por proxy. A Cloudflare explica que um registro A, AAAA ou CNAME encaminhado por proxy direciona solicitações HTTP/HTTPS através da Cloudflare, enquanto o DNS somente retorna o endereço de origem diretamente: Comportamento do status do proxy da Cloudflare .

Permita o tráfego HTTPS de entrada do Cloudflare para a origem. Para uma proteção mais robusta, restrinja o firewall de origem aos intervalos de IP publicados pelo Cloudflare e mantenha esses intervalos atualizados. Se o IP do servidor estava exposto antes da ativação da zona, o proxy DNS não invalida esse endereço antigo; considere alterar o IP de origem após a ativação. Não presuma que a nuvem laranja, por si só, impeça o acesso direto da origem.

3. Configure o HTTPS entre o Cloudflare e a origem.

Nas configurações de SSL/TLS do Cloudflare, use a opção Completo (estrito) quando a origem apresentar um certificado válido para o nome do host, como um certificado publicamente confiável ou um certificado da Autoridade Certificadora de Origem do Cloudflare. O modo Completo (estrito) criptografa a conexão entre o Cloudflare e a origem e valida o certificado de origem; o modo Flexível não oferece esse mesmo caminho TLS de ponta a ponta. Consulte a documentação do Cloudflare sobre o modo Completo (estrito) .

Instale o certificado e a chave privada no proxy reverso, não necessariamente no Synapse. O proxy reverso deve escutar na porta pública 443 e encaminhar as requisições do Matrix internamente para o listener HTTP do Synapse, geralmente na porta 8008. Não exponha o listener do Synapse publicamente se o proxy reverso for o único ponto de entrada.

4. Informe ao Synapse que ele está atrás de um proxy reverso confiável.

No listener HTTP relevante homeserver.yaml, habilite o tratamento de cabeçalhos encaminhados. Um exemplo simplificado para um servidor não conteinerizado é:

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

Incorpore essas configurações ao listener existente em vez de substituir toda a configuração. A documentação da Synapse recomenda x_forwarded: trueo uso de um proxy reverso e sugere a vinculação ao localhost quando o proxy estiver em execução no mesmo host. Para uma implantação em contêiner, vincular o Synapse ao loopback do contêiner pode impedir que o proxy do host o alcance; use o endereço de rede do contêiner ou do serviço e configure o firewall para esse caminho. Consulte o guia atual de proxy reverso do Synapse antes de alterar as configurações do listener.

Os cabeçalhos encaminhados são confiáveis ​​somente quando o Synapse aceita tráfego do seu proxy controlado. Se o Cloudflare for a única rota voltada para a internet, impeça o acesso público direto à origem e configure o proxy para passar o endereço correto do cliente. $remote_addrCaso contrário, o endereço do Nginx será um endereço do Cloudflare, pois o Cloudflare está conectado ao Nginx. Configure o módulo real-IP do Nginx para confiar apenas nos intervalos de origem publicados pelo Cloudflare antes de usar o cabeçalho CF-Connecting-IP; nunca confie nesse cabeçalho de clientes arbitrários da internet. Mantenha a API de administração do Synapse privada, a menos que você tenha um motivo específico para expô-la.

5. Rotas em matrizes sem reescrevê-las

Configure seu proxy reverso para enviar ambos /_matrixos /_synapse/clientparâmetros para o Synapse. Preserve o URI da solicitação exatamente. As assinaturas de solicitação de federação do Synapse podem falhar se um proxy decodificar ou normalizar segmentos de caminho codificados.

Aqui está um exemplo compacto do Nginx para matrix.example.com. Ele pressupõe que suas diretivas de certificado TLS já estejam configuradas para este bloco de servidor e que o proxy reverso e o Synapse estejam sendo executados no mesmo 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;
    }
}

Não adicione um sufixo URI ao local desta expressão regular proxy_pass. A documentação do proxy do Synapse menciona a canonicalização de URIs como uma causa de erros de assinatura de federação. Ajuste também client_max_body_sizepara corresponder ao limite de upload do Synapse e a qualquer limite do plano Cloudflare aplicável à sua zona. O 50Mvalor acima é apenas um exemplo, não uma recomendação universal.

A Cloudflare oferece suporte a WebSockets em seus planos, e os clientes Matrix podem usar conexões de longa duração. Confirme se seu proxy permite a atualização e se as regras de WAF ou de limitação de taxa não rejeitam solicitações legítimas do Matrix. A documentação da Cloudflare sobre WebSockets descreve como ela lida com conexões atualizadas.

6. Publique as respostas já conhecidas.

Forneça as duas respostas a seguir via example.comHTTPS. Você pode retorná-las do seu servidor web, de um host estático ou de um host virtual separado. Mantenha os documentos do cliente e da federação distintos:

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"}

Não utilize um redirecionamento para um host não relacionado como substituto sem verificar os requisitos de descoberta do Matrix e o comportamento do cliente. Certifique-se de que o host do nome do servidor esteja coberto por um certificado HTTPS válido e que o Cloudflare não armazene em cache respostas de descoberta desatualizadas enquanto você as estiver alterando.

7. Mantenha o tráfego da API dinâmico e os uploads dentro dos limites.

Não armazene em cache as respostas autenticadas da API do Matrix. Adicione uma regra de cache do Cloudflare para ignorar o cache dos caminhos da API do Matrix, incluindo `/api/matrix` /_matrix/*e /_synapse/client/*`/api/matrix`, a menos que você tenha um motivo bem fundamentado e testado para tratar uma resposta pública específica de forma diferente. Evite regras amplas de WAF ou bots que desafiem ou bloqueiem endpoints de federação; as solicitações de federação vêm de muitos servidores domésticos independentes. Se uma regra de segurança for necessária, teste-a em relação ao login do cliente, sincronização, upload de mídia e federação antes de aplicá-la de forma geral.

Os uploads têm vários limites independentes: o do cliente, a configuração de upload do plano ou zona da Cloudflare, o limite de tamanho do corpo do arquivo do proxy reverso e o do Synapse max_upload_size. Um erro 413 significa que um desses limites rejeitou a solicitação. A Cloudflare publica os limites de upload dependentes do plano e observa que essas configurações podem ser ajustadas dentro das restrições documentadas: página de solução de problemas do erro 413 da Cloudflare . Aumente apenas os limites necessários e teste com um arquivo menor que o limite configurado antes de aumentá-los ainda mais.

8. Verificar acesso, descoberta e federação do cliente

Execute essas verificações a partir de uma máquina fora da rede do seu servidor. Substitua os nomes de host de exemplo:

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

As duas primeiras requisições devem retornar HTTP 200, conteúdo JSON e os valores esperados. O documento do cliente deve incluir o cabeçalho CORS. O endpoint de versões do cliente deve retornar JSON do Synapse por meio do Cloudflare. O endpoint de integridade do Synapse retorna HTTP 200 quando acessado por meio de um listener configurado, mas não substitui a verificação de login ou federação.

Em seguida, faça login com um cliente Matrix usando um ID que termine em :example.com, entre em uma sala hospedada em outro local e confirme se as mensagens e as atualizações de membros estão sincronizadas. Use um testador de federação Matrix ou um segundo servidor doméstico para validar a descoberta e a federação do servidor. Uma solicitação bem-sucedida para /_matrix/client/versionsprova apenas que a rota voltada para o cliente funciona; não prova que a descoberta de federação, a assinatura ou a federação de saída estejam corretas.

O que significa sucesso — e quando mudar o design.

• Os clientes se conectam através do Cloudflare: o DNS resolve para endereços do Cloudflare, o HTTPS usa o certificado pretendido e a API do cliente Matrix retorna uma resposta.
• A descoberta está correta: ambas as URLs conhecidas retornam o JSON correto e o documento do cliente passa nas verificações de origem cruzada.
• Funcionamento da federação: um servidor remoto descobre o endpoint anunciado e pode trocar informações sobre o estado da sala. Se a delegação na porta 443 falhar, mas a delegação direta na porta 8448 funcionar, verifique o registro conhecido (WAF), o roteamento do proxy e as regras do WAF.
• Os uploads funcionam no tamanho esperado: teste com um upload representativo. Se arquivos pequenos forem bem-sucedidos, mas arquivos maiores retornarem erro 413, compare todos os quatro limites de tamanho em vez de alterar apenas o Synapse.
• A origem não é um caminho público alternativo: solicitações diretas à origem devem ser bloqueadas ou limitadas conforme projetado. Se ainda assim conseguirem chegar ao serviço Matrix, corrija a configuração do firewall e do proxy confiável.

Use a federação somente por DNS na porta 8448 se seus requisitos ou implementação não permitirem o roteamento da federação na porta 443, mas esteja ciente de que isso expõe o endereço de origem e remove a proteção de proxy HTTP do Cloudflare para esse nome de host. O Spectrum é outra opção para portas não padrão, sujeito à disponibilidade do produto e às restrições do plano. O proxy do Cloudflare também significa que o TLS termina no Cloudflare antes de uma segunda conexão TLS com sua origem; a criptografia de ponta a ponta do Matrix protege o conteúdo da mensagem criptografada, mas não oculta os metadados da conexão ou o conteúdo que não está criptografado de ponta a ponta dos serviços que processam a solicitação HTTP. Escolha a topologia com base em seus requisitos de privacidade, federação e disponibilidade e, em seguida, teste novamente após alterações no DNS, certificados, Synapse ou regras do Cloudflare.