Come configurare un server Matrix dietro un proxy Cloudflare

Un server Matrix può trovarsi dietro Cloudflare, ma la configurazione dipende da come i client e gli altri server domestici lo rilevano. Il proxy HTTP standard di Cloudflare supporta HTTPS sulla porta 443; la federazione Synapse utilizza solitamente la porta 8448 come predefinita, che non è presente nell'elenco standard delle porte proxy di Cloudflare. Una soluzione affidabile consiste nell'esporre Synapse tramite un reverse proxy sulla porta 443 e pubblicare record DNS noti di Matrix che indirizzino i client e il traffico di federazione a tale hostname. In alternativa, è possibile mantenere la federazione sulla porta 8448 e impostare il record DNS corrispondente come solo DNS.

Questa guida utilizza Synapse, l'implementazione ufficiale di Matrix per i server domestici, con gli ID Matrix @alice:example.come l'endpoint client di esempio matrix.example.com. Sostituisci questi nomi e indirizzi con i tuoi. Le istruzioni presuppongono che Synapse e un proxy inverso HTTPS siano già installati. Non si applicano senza modifiche a tutte le implementazioni di server domestici. Verificato rispetto alla documentazione aggiornata di Cloudflare ed Element Synapse il 6 ottobre 2026.

Scegliere la configurazione di rete corretta

Il proxy orange-cloud di Cloudflare è un proxy inverso HTTP/HTTPS. Si interpone tra i client e il server di origine per le richieste web inoltrate; non funge da proxy per tutte le porte TCP. Le sue porte HTTPS standard includono la 443 e la 8443, ma non la porta di federazione 8448, comunemente utilizzata da Synapse. Consulta l' elenco delle porte di rete supportate da Cloudflare e le limitazioni del proxy .

Il primo layout viene utilizzato di seguito. Un record DNS con proxy non configura di per sé il rilevamento Matrix, il reverse proxying, TLS o le policy del firewall.

1. Decidere il nome del server Matrix prima di configurare il DNS

Il nome del server Matrix è la parte che segue i due punti nell'ID utente. In questo esempio è example.com, quindi gli utenti hanno ID come @alice:example.com. Il nome host tecnico del client è matrix.example.com. Questa separazione consente al dominio utilizzato negli ID utente di rimanere stabile mentre il traffico viene delegato a un altro nome host. Se Synapse è già inizializzato, non modificarlo server_namecasualmente: fa parte dell'identità dell'utente e della stanza e la sua modifica è una migrazione, non una regolazione del proxy.

Prevedi di servire due piccoli documenti di individuazione JSON dal dominio del nome server:

• https://example.com/.well-known/matrix/clientdice ai client compatibili di usare https://matrix.example.com.
• https://example.com/.well-known/matrix/serverdice agli altri homeserver di raggiungere la federazione a matrix.example.com:443.

Il documento client necessita di Access-Control-Allow-Origin: *un'intestazione di risposta. La guida alla delega di Synapse include esempi di questi record e della loro struttura prevista: Delega di federazione Synapse .

2. Crea i record DNS di Cloudflare

In Cloudflare DNS, crea un Arecord con un nome matrixche punti all'indirizzo IPv4 pubblico del server. Aggiungi un AAAArecord solo se l'origine ha una connettività IPv6 funzionante e un firewall configurato per IPv6. Imposta lo stato del proxy del nome host web su Proxied (nuvola arancione). Se anche il dominio radice punta a questo server e servirà i file noti, configura come proxy anche il suo record web.

Mantieni i record non correlati, inclusi i record di posta elettronica, con le impostazioni DNS-only appropriate. I record MX e TXT non vengono inoltrati tramite proxy. Cloudflare spiega che un record A, AAAA o CNAME inoltrato tramite proxy instrada le richieste HTTP/HTTPS attraverso Cloudflare, mentre il DNS-only restituisce direttamente l'indirizzo di origine: Comportamento dello stato del proxy di Cloudflare .

Consenti il ​​traffico HTTPS in entrata da Cloudflare verso l'origine. Per una maggiore protezione, limita il firewall di origine agli intervalli IP pubblicati da Cloudflare e mantieni tali intervalli aggiornati. Se l'indirizzo IP del server era esposto prima dell'attivazione della zona, il proxying DNS non invalida il vecchio indirizzo; valuta la possibilità di modificare l'indirizzo IP di origine dopo l'attivazione. Non dare per scontato che la sola nuvola arancione impedisca l'accesso diretto all'origine.

3. Configurare HTTPS tra Cloudflare e l'origine

Nelle impostazioni SSL/TLS di Cloudflare, utilizzare la modalità Completa (rigorosa) quando l'origine presenta un certificato valido per il nome host, ad esempio un certificato pubblicamente attendibile o un certificato CA di origine di Cloudflare. La modalità Completa (rigorosa) crittografa la connessione da Cloudflare all'origine e convalida il certificato di origine; la modalità Flessibile non fornisce lo stesso percorso TLS end-to-end. Consultare la documentazione di Cloudflare relativa alla modalità Completa (rigorosa) .

Installare il certificato e la chiave privata sul reverse proxy, non necessariamente in Synapse. Il reverse proxy deve rimanere in ascolto sulla porta pubblica 443 e inoltrare internamente le richieste Matrix al listener HTTP di Synapse, solitamente sulla porta 8008. Non esporre pubblicamente il listener di Synapse se il reverse proxy è destinato a essere l'unico punto di accesso.

4. Indica a Synapse che si trova dietro un proxy inverso affidabile.

Nel listener HTTP pertinente in homeserver.yaml, abilita la gestione dell'intestazione inoltrata. Un esempio semplificato per un server non containerizzato è:

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

Integra queste impostazioni nel listener esistente anziché sostituire l'intera configurazione. La documentazione di Synapse raccomanda x_forwarded: truedi utilizzare un reverse proxy e suggerisce di associare il listener a localhost quando il proxy è in esecuzione sullo stesso host. In caso di implementazione in container, associare Synapse all'interfaccia di loopback del container può impedire al proxy dell'host di raggiungerlo; in tal caso, utilizza l'indirizzo di rete del container o del servizio e proteggi tale percorso con un firewall. Consulta la guida aggiornata di Synapse per il reverse proxy prima di modificare le impostazioni del listener.

Le intestazioni inoltrate sono attendibili solo quando Synapse accetta traffico dal proxy controllato. Se Cloudflare è l'unico percorso accessibile da Internet, impedisci l'accesso pubblico diretto all'origine e configura il proxy in modo che trasmetta l'indirizzo client corretto. $remote_addrAltrimenti, l'indirizzo IP di Nginx sarà un indirizzo Cloudflare perché Cloudflare è connesso a Nginx. Configura il modulo real-IP di Nginx in modo che si fidi solo degli intervalli di indirizzi IP pubblicati da Cloudflare prima di utilizzarlo CF-Connecting-IP; non fidarti mai di quell'intestazione proveniente da client Internet arbitrari. Mantieni privata l'API di amministrazione di Synapse a meno che tu non abbia un motivo specifico per esporla.

5. Percorsi della matrice di instradamento senza riscriverli

Configura il tuo reverse proxy per inviare entrambi /_matrixi parametri /_synapse/clienta Synapse. Mantieni l'URI della richiesta esattamente come è scritto. Le firme delle richieste di federazione di Synapse potrebbero non funzionare se un proxy decodifica o normalizza i segmenti di percorso codificati.

Ecco un esempio compatto di Nginx matrix.example.com. Si presume che le direttive del certificato TLS siano già configurate per questo blocco di server e che il reverse proxy e Synapse siano in esecuzione sullo stesso 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;
    }
}

Non aggiungere un suffisso URI alla posizione di questa espressione regolare proxy_pass. La documentazione proxy di Synapse indica la canonizzazione dell'URI come causa di errori nella firma di federazione. Regola inoltre il valore client_max_body_sizein modo che corrisponda al limite di caricamento di Synapse e a qualsiasi limite del piano Cloudflare applicabile alla tua zona. Il 50Mvalore sopra riportato è solo un esempio, non una raccomandazione universale.

Cloudflare supporta i WebSocket nei suoi piani e i client Matrix possono utilizzare connessioni a lunga durata. Verifica che il tuo proxy consenta l'aggiornamento e che eventuali WAF o regole di limitazione della frequenza non rifiutino le richieste Matrix legittime. La documentazione di Cloudflare sui WebSocket descrive la gestione delle connessioni aggiornate.

6. Pubblicare le risposte più note

Invia le seguenti due risposte tramite example.comHTTPS. Puoi restituirle dal tuo server web, da un host statico o da un host virtuale separato. Mantieni distinti i documenti del client e della federazione:

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

Non utilizzare un reindirizzamento a un host non correlato come alternativa senza prima aver verificato i requisiti di rilevamento di Matrix e il comportamento del client. Assicurati che l'host server-name sia coperto da un certificato HTTPS valido e che Cloudflare non memorizzi nella cache risposte di rilevamento obsolete durante la modifica.

7. Mantenere il traffico API dinamico e i caricamenti entro i limiti

Non memorizzare nella cache le risposte autenticate dell'API Matrix. Aggiungi una regola di cache di Cloudflare per ignorare la memorizzazione nella cache per i percorsi dell'API Matrix, inclusi /_matrix/*e /_synapse/client/*, a meno che tu non abbia un motivo ben testato per gestire una specifica risposta pubblica in modo diverso. Evita regole WAF o per bot generiche che sfidano o bloccano gli endpoint di federazione; le richieste di federazione provengono da molti homeserver indipendenti. Se è necessaria una regola di sicurezza, testala rispetto all'accesso client, alla sincronizzazione, al caricamento multimediale e alla federazione prima di applicarla in generale.

I caricamenti hanno diversi limiti indipendenti: quello del client, quello del piano o della zona di Cloudflare per il caricamento dei file, quello del proxy inverso per la dimensione del corpo del file e quello di Synapse max_upload_size. Un errore 413 significa che uno di questi limiti ha rifiutato la richiesta. Cloudflare pubblica i limiti di caricamento dipendenti dal piano e precisa che queste impostazioni possono essere modificate entro i limiti documentati: pagina di Cloudflare per la risoluzione dei problemi relativi all'errore 413. Aumenta solo i limiti necessari ed effettua un test con un file di dimensioni inferiori al limite configurato prima di incrementarli ulteriormente.

8. Verificare l'accesso, il rilevamento e la federazione dei client.

Esegui questi controlli da una macchina esterna alla rete del tuo server. Sostituisci i nomi host di esempio:

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

Le prime due richieste dovrebbero restituire HTTP 200, contenuto JSON e i valori previsti. Il documento client dovrebbe includere l'intestazione CORS. L'endpoint delle versioni client dovrebbe restituire JSON da Synapse tramite Cloudflare. L'endpoint di integrità di Synapse restituisce HTTP 200 quando viene raggiunto tramite un listener configurato, ma non sostituisce la verifica dell'accesso o della federazione.

Quindi accedi con un client Matrix utilizzando un ID che termina con :example.com, unisciti a una stanza ospitata altrove e verifica che i messaggi e gli aggiornamenti dell'appartenenza siano sincronizzati. Utilizza un tester di federazione Matrix o un secondo homeserver per convalidare il rilevamento del server e la federazione. Una richiesta riuscita a /_matrix/client/versionsdimostra solo che il percorso rivolto al client funziona; non dimostra che il rilevamento della federazione, la firma o la federazione in uscita siano corretti.

Che aspetto ha il successo e quando è il momento di cambiare il progetto.

• I client si connettono tramite Cloudflare: il DNS si risolve negli indirizzi Cloudflare, HTTPS utilizza il certificato previsto e l'API client di Matrix restituisce una risposta.
• Discovery è corretto: entrambi gli URL noti restituiscono il JSON corretto e il documento client supera i controlli di origine incrociata.
• La federazione funziona: un server remoto rileva l'endpoint pubblicizzato e può scambiare lo stato della stanza. Se la delega sulla porta 443 fallisce ma la delega diretta sulla porta 8448 funziona, verificare il record noto, il routing del percorso proxy e le regole WAF.
• Il caricamento funziona correttamente con le dimensioni previste: esegui un test con un file rappresentativo. Se i file di piccole dimensioni vengono caricati correttamente ma quelli di dimensioni maggiori restituiscono un errore 413, confronta tutti e quattro i limiti di dimensione anziché modificare solo Synapse.
• L'origine non rappresenta un percorso pubblico alternativo: le richieste dirette all'origine devono essere bloccate o limitate come previsto. Se, nonostante ciò, raggiungono comunque il servizio Matrix, correggere la configurazione del firewall e del proxy attendibile.

Se i requisiti o l'implementazione non consentono l'instradamento della federazione sulla porta 443, è possibile utilizzare la federazione solo DNS sulla porta 8448, tenendo presente che ciò espone l'indirizzo di origine e rimuove la protezione proxy HTTP di Cloudflare per tale hostname. Spectrum rappresenta un'altra opzione per le porte non standard, soggetta alla disponibilità del prodotto e ai vincoli del piano. L'utilizzo del proxy Cloudflare implica inoltre che la connessione TLS termini presso Cloudflare prima di una seconda connessione TLS verso l'origine; la crittografia end-to-end Matrix protegge il contenuto dei messaggi crittografati, ma non nasconde i metadati di connessione o il contenuto non crittografato end-to-end ai servizi che gestiscono la richiesta HTTP. Scegliere la topologia in base ai requisiti di privacy, federazione e disponibilità, quindi eseguire nuovamente il test dopo aver apportato modifiche a DNS, certificati, Synapse o regole Cloudflare.