Início
» Como fazer
»
Torne seu servidor Matrix Synapse acessível para federação.
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.
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
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.
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"
}
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.