Home
» Come fare
»
Rendi il tuo server Matrix Synapse raggiungibile per la federazione
Rendi il tuo server Matrix Synapse raggiungibile per la federazione
Per federare un homeserver Matrix Synapse, è necessario rendere il suo nome server individuabile e raggiungibile da Internet pubblico tramite HTTPS, quindi instradare le richieste da server a server Matrix verso Synapse. In una configurazione comune, un reverse proxy gestisce il TLS sulla porta 443 e un /.well-known/matrix/serverfile di configurazione punta il dominio Matrix a tale proxy. Se Synapse risponde già sul dominio del nome server sulla porta 8448, potrebbe non essere necessaria la delega.
Questa procedura guidata utilizza example.comcome nome permanente del server Matrix e matrix.example.comcome endpoint della macchina o del proxy. Sostituiscili entrambi con i tuoi nomi. Un homeserver memorizza gli account e le stanze Matrix; la federazione consente agli homeserver di comunicare. DNS, regole del firewall, sintassi del proxy, rete dei container e certificati dipendono dal tuo host.
Prima di modificare la configurazione
Decidete se gli ID Matrix degli utenti devono avere il formato @name:example.como @name:matrix.example.com. Il valore di server_namein homeserver.yamldiventa parte degli ID Matrix e degli indirizzi delle stanze. La documentazione di installazione di Synapse consiglia di sceglierlo prima dell'installazione perché non può essere modificato in seguito senza conseguenze. Se Synapse è già in uso, non modificatelo solo per farlo corrispondere a un indirizzo web; utilizzate la delega per mantenere gli ID esistenti.
Il nome del server fa parte degli ID Matrix, quindi confermalo prima di continuare.
Prima di apportare modifiche, assicurati di poter accedere a Synapse, al proxy e al DNS pubblico e di disporre di un certificato TLS valido per l'endpoint di federazione. Esegui un backup homeserver.yamldella chiave di firma, che stabilisce l'identità del server principale. Conserva questa chiave in un luogo sicuro; la configurazione di routine della federazione non richiede la sua rigenerazione.
Stabilire il percorso pubblico
1. Conferma il listener HTTP di Synapse
Synapse solitamente si mette in ascolto per il traffico HTTP sulla porta 8008dietro un reverse proxy. Nel listener che accetta il traffico proxy, impostare x_forwarded: truein modo che Synapse possa utilizzare l'indirizzo client e lo schema inoltrati dal proxy. Il proxy deve impostare le intestazioni appropriate X-Forwarded-For, X-Forwarded-Protoanziché passare valori arbitrari forniti da client esterni.
Il listener accetta richieste HTTP da un proxy locale e abilita la gestione delle intestazioni inoltrate da parte di Synapse.
Il binding 127.0.0.1è appropriato quando il proxy è in esecuzione sullo stesso host. Non è appropriato quando il proxy si trova in un altro container o macchina, a meno che tale indirizzo non sia raggiungibile dal proxy. In una distribuzione in container, utilizzare l'indirizzo di rete o il nome del servizio raggiungibile dal proxy e limitare l'accesso tramite la rete del container o il firewall. Mantenere la struttura del listener esistente e modificare i valori pertinenti; non incollare un frammento alla cieca sul resto della configurazione.
2. Percorsi della matrice di instradamento attraverso il proxy
Configura l'host virtuale HTTPS del proxy per inoltrare entrambi /_matrixi percorsi /_synapse/cliental listener HTTP di Synapse. Il primo percorso trasporta le API di Matrix, inclusa la federazione; il secondo viene utilizzato per gli endpoint client di Synapse. Segui l'esempio ufficiale del tuo software proxy, mantieni il percorso della richiesta e invia le intestazioni inoltrate previste da Synapse. Non normalizzare, decodificare o riscrivere i percorsi URI: le firme delle richieste Matrix potrebbero non funzionare se un proxy modifica il percorso codificato.
Il proxy deve passare entrambi i percorsi API di Matrix a Synapse senza riscrivere l'URI.
La configurazione esatta varia a seconda di Nginx, Caddy, Apache, bilanciatori di carico e hosting gestito. Utilizzare la sintassi corrente del fornitore e la documentazione del reverse proxy di Synapse come riferimento. Una regola proxy che serve il client web ma omette il percorso dell'API di federazione non è sufficiente.
3. Assicurarsi che DNS, HTTPS e la porta scelta siano compatibili.
Ad esempio, matrix.example.comdeve risolversi nel proxy o nel bilanciatore di carico e la porta 443deve essere raggiungibile dall'esterno. Il proxy necessita di un certificato valido per matrix.example.com. Se invece si esegue la federazione direttamente su example.com:8448, pubblicare quella rotta e il certificato e aprire la porta 8448. Utilizzare la porta diretta 8448, la porta predefinita convenzionale, oppure la delega a un altro host e porta, ad esempio 443.
Verifica le regole DNS, del firewall o del gruppo di sicurezza cloud e il certificato dall'esterno della tua rete privata. Se è presente una CDN o un tunnel, il supporto per il traffico Matrix richiesto dipende dalla configurazione attuale del servizio; consulta la relativa documentazione e testa il percorso effettivo anziché dare per scontata la compatibilità.
Pubblicare i risultati della federazione quando necessario
4. Aggiungere la delega del server per un endpoint separato
Se il dominio Matrix ID è example.comma Synapse è raggiungibile all'indirizzo matrix.example.com:443, servire questo JSON tramite HTTPS all'indirizzo https://example.com/.well-known/matrix/server:
{
"m.server": "matrix.example.com:443"
}
Questo record di individuazione della federazione delega example.com all'endpoint HTTPS all'indirizzo matrix.example.com sulla porta 443.
In questo esempio la porta 443 è specificata esplicitamente; se si omette una porta, il rilevamento di Matrix utilizza per impostazione predefinita la porta 8448. Non confondere questo file con /.well-known/matrix/client, che aiuta i client a trovare l'API client-server ed è separato dalla federazione server-to-server. Synapse può servire direttamente un file noto al server quando il dominio server-name è instradato direttamente a Synapse, ma con un endpoint separato si pubblica normalmente il file sul server web del dominio server-name.
Il rilevamento della federazione è specificato da Matrix e documentato da Synapse. La specifica Matrix consente il rilevamento tramite /.well-known/matrix/server; verificare le istruzioni di delega di Synapse prima di scegliere un metodo diverso, come un record SRV, che influisce anche sulle aspettative TLS.
Eseguire il test dall'esterno del server.
5. Verifica il record, quindi esegui un controllo di federazione.
Richiedi l'URL di rilevamento da una macchina esterna alla rete privata del server. Dovrebbe restituire l'oggetto JSON sopra indicato tramite HTTPS, senza pagina di login, reindirizzamento HTML, avviso sul certificato o sito web non correlato. Verifica quindi che il nome host delegato sia risolvibile, che il relativo certificato sia valido e che la porta pubblicizzata raggiunga Synapse. Utilizza lo strumento di verifica della configurazione del tuo proxy e la procedura di ricaricamento prima di eseguire il test.
Infine, inserisci il nome del tuo server (ad esempio, example.com, non il nome host delegato a meno che non sia il tuo server_name) nel Matrix Federation Tester ufficiale . La guida alla federazione di Synapse suggerisce anche di eseguire il test unendosi a una stanza pubblica come #synapse:matrix.org. Un controllo positivo conferma che i controlli comuni di rilevamento e raggiungibilità sono stati superati; non garantisce che ogni server remoto o ogni operazione di stanza funzionerà, poiché le policy remote e le condizioni di rete variano.
Se il tester segnala che il server non è raggiungibile, verificare il dominio e la porta utilizzati, il DNS, le regole del firewall, il nome del certificato, i percorsi del proxy, le intestazioni inoltrate e se un reindirizzamento ha modificato la richiesta. La documentazione attuale sulla federazione di Synapse avverte specificamente che i server di federazione di Synapse potrebbero non seguire i reindirizzamenti HTTP 308 in alcuni casi. Evitare di fare affidamento su un reindirizzamento 308 per l'endpoint di federazione e ripetere il test dopo averlo corretto. Consultare la documentazione relativa alla versione di Synapse installata per informazioni specifiche sul comportamento della versione.
La federazione richiede che i server domestici remoti scoprano e raggiungano la tua API di federazione. Non è possibile sapere, basandosi solo sulla configurazione, se ciò funzioni per ogni server remoto. Conferma il percorso con il tester e partecipa a una sessione di gioco reale, quindi analizza l'endpoint o l'errore specifico che non funziona.
Questi pannelli di interfaccia sono esempi schematici di dati di configurazione e rilevamento, non schermate di un server in funzione. Riferimenti alla documentazione verificati il 10 ottobre 2026.