Torne seu servidor Matrix Synapse acessível para federação.

Para federar um servidor doméstico Matrix Synapse, torne o nome do servidor detectável e acessível pela internet pública via HTTPS e, em seguida, direcione as solicitações de servidor para servidor do Matrix para o Synapse. Em uma configuração comum, um proxy reverso lida com TLS na porta 443 e um /.well-known/matrix/serverarquivo aponta seu domínio Matrix para esse proxy. Se o Synapse já responder no seu domínio de nome de servidor na porta 8448, você pode não precisar de delegação.

Este guia usa example.com`<nome_do_servidor>` como nome permanente do servidor Matrix e `< matrix.example.comendereço_do_servidor>` como o endpoint da máquina ou proxy. Substitua ambos pelos seus próprios nomes. Um servidor doméstico armazena contas e salas do Matrix; a federação permite que servidores domésticos se comuniquem. DNS, regras de firewall, sintaxe de proxy, rede de contêineres e certificados dependem do seu host.

Antes de alterar a configuração

Decida se os IDs do Matrix dos usuários devem ter o formato `<nome_do_usuário> @name:example.com` ou `< nome_do_usuário> @name:matrix.example.com`. O valor de server_name`< homeserver.yamlnome_do_usuário>` passa a fazer parte dos IDs do Matrix e dos endereços das salas. A documentação de instalação do Synapse recomenda escolher esse valor antes da instalação, pois não poderá ser alterado posteriormente sem consequências. Se o Synapse já estiver em uso, não o altere apenas para corresponder a um endereço web; use a delegação para manter os IDs existentes.

Um editor YAML exibe server_name: example.com e um lembrete para escolher o valor antes da instalação.
O nome do servidor faz parte dos IDs da Matrix, portanto, confirme-o antes de continuar.

Antes de editar, certifique-se de que você tem acesso ao Synapse, ao proxy e ao DNS público, e que possui um certificado TLS válido para o endpoint de federação. Faça backup homeserver.yamlda chave de assinatura, que estabelece a identidade do servidor principal. Guarde essa chave em segurança; a configuração de federação de rotina não exige a sua regeneração.

Estabelecer a rota pública

1. Confirme o ouvinte HTTP do Synapse.

Normalmente, o Synapse escuta conexões HTTP na porta 8080 8008por trás de um proxy reverso. No listener que aceita o tráfego do proxy, configure o Synapse para que ele possa usar o endereço e o esquema do cliente encaminhados pelo proxy. O proxy deve definir os cabeçalhos `HttpClient` e `HttpRequest` x_forwarded: trueapropriados , em vez de passar valores arbitrários fornecidos por clientes externos.X-Forwarded-ForX-Forwarded-Proto

Um trecho de um listener YAML mostra o Synapse na porta HTTP 8008 com x_forwarded habilitado e um endereço de loopback configurado.
O ouvinte aceita HTTP de um proxy local e habilita o tratamento de cabeçalhos encaminhados do Synapse.

A vinculação 127.0.0.1é adequada quando o proxy é executado no mesmo host. Não é adequada quando o proxy está em outro contêiner ou máquina, a menos que esse endereço seja acessível a partir do proxy. Em uma implantação de contêiner, use o endereço de rede ou o nome do serviço que o proxy possa alcançar e restrinja o acesso por meio da rede ou firewall do contêiner. Mantenha a estrutura de ouvinte existente e edite os valores relevantes; não copie e cole um fragmento cegamente sobre o restante da sua configuração.

2. Rotas da matriz através do proxy

Configure o host virtual HTTPS do proxy para encaminhar ambos /_matrixos /_synapse/clientcaminhos para o listener HTTP do Synapse. O primeiro caminho transporta as APIs do Matrix, incluindo a federação; o segundo é usado para os endpoints do cliente Synapse. Siga o exemplo oficial do seu software de proxy, preserve o caminho da requisição e envie os cabeçalhos encaminhados que o Synapse espera. Não normalize, decodifique ou reescreva os caminhos URI: as assinaturas de requisição do Matrix podem falhar se um proxy alterar o caminho codificado.

Um editor de configuração de proxy reverso mostra os caminhos da API Matrix e do cliente Synapse roteados para a porta 8008 do localhost com cabeçalhos encaminhados.
O proxy deve passar ambos os caminhos da API Matrix para o Synapse sem reescrever o URI.

A configuração exata varia entre Nginx, Caddy, Apache, balanceadores de carga e hospedagem gerenciada. Use a sintaxe atual do fornecedor e a documentação do proxy reverso Synapse como referência. Uma regra de proxy que atenda o cliente web, mas omita o caminho da API de federação, não é suficiente.

3. Certifique-se de que o DNS, o HTTPS e a porta escolhida estejam configurados corretamente.

Por exemplo, o matrix.example.comendereço deve ser resolvido para o proxy ou balanceador de carga, e a porta 443deve ser acessível externamente. O proxy precisa de um certificado válido para o endereço matrix.example.com. Se, em vez disso, você disponibilizar a federação diretamente em example.com:8448, publique essa rota e o certificado e abra a porta 8448. Use a porta direta 8448, o padrão convencional, ou delegue para outro host e porta, como a 443.

Confirme as regras de DNS, firewall ou grupo de segurança na nuvem, e o certificado de fora da sua rede privada. Se houver uma CDN ou túnel intermediário, o suporte ao tráfego Matrix necessário dependerá da configuração atual desse serviço; consulte a documentação e teste a rota real em vez de presumir compatibilidade.

Publicar descoberta de federação quando necessário

4. Adicione delegação de servidor para um endpoint separado.

Se o domínio do ID da Matriz for `<domain>`, example.commas o Synapse estiver acessível em ` matrix.example.com:443<domain>`, forneça este JSON via HTTPS em https://example.com/.well-known/matrix/server: ` <domain>`

{
  "m.server": "matrix.example.com:443"
}
Uma visualização JSON no estilo de navegador em example.com/.well-known/matrix/server contém o valor m.server matrix.example.com:443.
Este registro de descoberta de federação delega example.com ao endpoint HTTPS em matrix.example.com na porta 443.

A porta 443 é explícita neste exemplo; se você omitir uma porta, a descoberta do Matrix usará a porta 8448 por padrão. Não confunda este arquivo com o arquivo `server.xml` /.well-known/matrix/client, que ajuda os clientes a encontrar a API cliente-servidor e é separado da federação servidor-servidor. O Synapse pode servir um arquivo `server.xml` conhecido pelo servidor quando o domínio do nome do servidor é roteado diretamente para o Synapse, mas com um endpoint separado, você normalmente publica o arquivo no servidor web do domínio do nome do servidor.

A descoberta de federação é especificada pela Matrix e documentada pela Synapse. A especificação da Matrix permite a descoberta por meio de registros SRV /.well-known/matrix/server; verifique as instruções de delegação da Synapse antes de escolher um método diferente, como um registro SRV, que também afeta as expectativas do TLS.

Teste a partir de fora do servidor

5. Verifique o registro e, em seguida, execute uma verificação de federação.

Solicite a URL de descoberta a partir de uma máquina fora da rede privada do servidor. Ela deve retornar o objeto JSON acima via HTTPS, sem página de login, redirecionamento HTML, aviso de certificado ou site irrelevante. Em seguida, verifique se o nome do host delegado é resolvido, se o certificado é válido e se a porta anunciada alcança o Synapse. Use a ferramenta de verificação de configuração e o procedimento de recarregamento do seu proxy antes de testar.

Por fim, insira o nome do seu servidor (por exemplo, ` example.com<nome_do_servidor>`, e não o nome de host delegado, a menos que esse seja o seu `<nome_do_servidor> server_name`) no Testador de Federação Matrix oficial . O guia de federação do Synapse também sugere testar entrando em uma sala pública, como ` #synapse:matrix.org<nome_da_sala>`. Uma verificação bem-sucedida confirma que as verificações comuns de descoberta e acessibilidade foram aprovadas; isso não garante que todos os servidores remotos ou todas as operações em salas funcionarão, pois as políticas remotas e as condições de rede variam.

Se o testador reportar que seu servidor está inacessível, verifique o domínio e a porta que ele tentou acessar, o DNS, as regras do firewall, o nome do certificado, os caminhos do proxy, os cabeçalhos encaminhados e se um redirecionamento alterou a requisição. A documentação atual de federação do Synapse alerta especificamente que os servidores de federação do Synapse podem não seguir redirecionamentos HTTP 308 em alguns casos. Evite depender de um redirecionamento 308 para o endpoint de federação e teste novamente após corrigir o problema. Consulte a documentação correspondente à sua versão do Synapse para obter informações específicas sobre o comportamento da versão.

A federação exige que os servidores remotos descubram e acessem sua API de federação. Não é possível saber apenas pela configuração se isso funcionará para todos os servidores remotos. Confirme a rota com o testador e com a entrada em uma sala real e, em seguida, investigue o endpoint ou erro específico que está apresentando falhas.

Esses painéis de interface são exemplos esquemáticos de dados de configuração e descoberta, não capturas de tela de um servidor em produção. Referências da documentação verificadas em 10 de outubro de 2026.

Deixar um comentário

Resolver erros de permissão de administrador de salas Matrix por meio de ação

Rastreie a variável de ambiente M_FORBIDDEN até os níveis de poder da sala, a associação ou o acesso de administrador do servidor Synapse e, em seguida, restaure apenas a permissão necessária para a ação bloqueada.

Torne seu servidor Matrix Synapse acessível para federação.

Torne seu servidor Matrix Synapse acessível para federação.

Configure a descoberta do Synapse, o HTTPS e o roteamento de proxy para que outros servidores domésticos Matrix possam encontrar e contatar o seu servidor.

Conecte o Element Web ao Keycloak por meio do OIDC do Synapse.

Configure um cliente OIDC Keycloak e um provedor Synapse para que os usuários do Element Web possam fazer login por meio do seu servidor de identidade sem expor segredos do cliente.

Configure o backup e a assinatura cruzada da chave do elemento com segurança.

Configure o backup e a assinatura cruzada da chave do elemento com segurança.

Salve uma chave de recuperação, verifique suas sessões do Element e certifique-se de que as chaves de mensagens criptografadas possam ser restauradas sem confundir o backup com a senha da sua conta.

Pare as falhas de memória do Matrix Synapse durante a sincronização do cliente.

Diagnosticar falhas de falta de memória do Synapse durante a sincronização, ajustar o cache com segurança, identificar atrasos nas solicitações e verificar o uso estável da memória.

Resolver erros de certificado TLS da Synapse Federation

Rastreie falhas de certificado de federação do Trace Matrix para o servidor correto, repare a cadeia TLS ou a confiança da CA e verifique a correção sem desativar as verificações de segurança.

Coloque um servidor Synapse Matrix atrás do Cloudflare com segurança.

Coloque um servidor Synapse Matrix atrás do Cloudflare com segurança.

Os clientes do Route Matrix e a federação através do Cloudflare em HTTPS 443 preservam a descoberta do Synapse e evitam o armazenamento em cache do tráfego da API ou a interrupção de uploads de mídia.

Restaure o Matrix Synapse com segurança usando um dump do PostgreSQL.

Faça backup do Synapse com pg_dump, proteja sua chave de assinatura e mídia e restaure-o em um banco de dados PostgreSQL limpo, sem reutilizar chaves de uso único obsoletas.

Execute o Mjölnir como um bot de moderação de salas Matrix com Docker.

Execute o Mjölnir como um bot de moderação de salas Matrix com Docker.

Configure o Mjölnir com uma conta Matrix dedicada, sala de gerenciamento criptografada, Docker Compose, lista de políticas e verificações de permissão.

Ative a sincronização deslizante nativa da matriz para um carregamento mais rápido em dispositivos móveis.

Ative a sincronização deslizante nativa da matriz para um carregamento mais rápido em dispositivos móveis.

Ignore o proxy descontinuado e configure a Sincronização Deslizante integrada do Synapse. Verifique a descoberta de clientes e, em seguida, meça o carregamento da lista de salas e o comportamento de reconexão em um telefone compatível.