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.

Un editor YAML visualizza server_name: example.com e un promemoria per scegliere il valore prima dell'installazione.
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.

Un estratto del listener YAML mostra Synapse sulla porta HTTP 8008 con x_forwarded abilitato e un indirizzo di binding di loopback.
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.

Un editor di configurazione del proxy inverso mostra i percorsi dell'API Matrix e del client Synapse instradati alla porta 8008 di localhost con intestazioni inoltrate.
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"
}
Una vista JSON in stile browser all'indirizzo example.com/.well-known/matrix/server contiene il valore 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.

Lascia un commento

Risolvi gli errori di autorizzazione amministrativa della stanza Matrix tramite azione

Individuare la causa di M_FORBIDDEN, che può essere ricondotta ai livelli di alimentazione della stanza, all'iscrizione dei membri o all'accesso di amministratore al server Synapse, quindi ripristinare solo l'autorizzazione necessaria per l'azione bloccata.

Rendi il tuo server Matrix Synapse raggiungibile per la federazione

Rendi il tuo server Matrix Synapse raggiungibile per la federazione

Configura il rilevamento Synapse, HTTPS e il routing proxy in modo che gli altri homeserver Matrix possano trovare e contattare il tuo server.

Connetti Element Web a Keycloak tramite Synapse OIDC

Configura un client OIDC Keycloak e un provider Synapse in modo che gli utenti di Element Web possano accedere tramite il tuo server di identità senza esporre le credenziali del client.

Configura in modo sicuro il backup e la firma incrociata delle chiavi Element.

Configura in modo sicuro il backup e la firma incrociata delle chiavi Element.

Salva una chiave di ripristino, verifica le tue sessioni Element e controlla che le chiavi dei messaggi crittografati possano essere ripristinate senza confondere il backup con la password del tuo account.

Rimuovi i crash di memoria di Matrix Synapse durante la sincronizzazione del client

Diagnostica gli errori di memoria insufficiente di Synapse durante la sincronizzazione, regola la cache in modo sicuro, identifica i ritardi nelle richieste e verifica un utilizzo stabile della memoria.

Risolvere gli errori del certificato TLS di Synapse Federation

Individuare gli errori del certificato di federazione Matrix sul server corretto, riparare la catena TLS o la relazione di fiducia con la CA e verificare la correzione senza disabilitare i controlli di sicurezza.

Posizionare un server Synapse Matrix dietro Cloudflare in modo sicuro

Posizionare un server Synapse Matrix dietro Cloudflare in modo sicuro

Instrada i client Matrix e la federazione tramite Cloudflare su HTTPS 443, preserva il rilevamento di Synapse ed evita la memorizzazione nella cache del traffico API o l'interruzione del caricamento dei file multimediali.

Ripristinare Matrix Synapse in modo sicuro con un dump di PostgreSQL

Esegui il backup di Synapse con pg_dump, proteggi la chiave di firma e i supporti di memorizzazione e ripristina il tutto in un database PostgreSQL pulito senza riutilizzare chiavi monouso obsolete.

Esegui Mjölnir come bot di moderazione per le stanze Matrix con Docker

Esegui Mjölnir come bot di moderazione per le stanze Matrix con Docker

Configura Mjölnir con un account Matrix dedicato, una sala di gestione crittografata, Docker Compose, un elenco di policy e controlli di autorizzazione.

Attiva la sincronizzazione nativa dello scorrimento della matrice per un caricamento più rapido sui dispositivi mobili.

Attiva la sincronizzazione nativa dello scorrimento della matrice per un caricamento più rapido sui dispositivi mobili.

Ignora il proxy obsoleto e configura Sliding Sync, la funzione integrata di Synapse. Verifica il rilevamento dei client, quindi misura il caricamento dell'elenco delle stanze e il comportamento di riconnessione su un telefono compatibile.