Cum se configurează un server Matrix în spatele unui proxy Cloudflare

Un server Matrix poate fi amplasat în spatele Cloudflare, dar configurarea depinde de modul în care clienții și alte servere principale îl descoperă. Proxy-ul HTTP standard al Cloudflare acceptă HTTPS pe portul 443; federația Synapse se folosește de obicei implicit la portul 8448, care nu se află în lista standard de porturi proxy a Cloudflare. O soluție fiabilă este expunerea Synapse printr-un proxy invers pe portul 443 și publicarea înregistrărilor cunoscute Matrix care direcționează clienții și traficul federației către acel nume de gazdă. Alternativ, păstrați federația pe 8448 și faceți ca înregistrarea DNS să fie doar DNS.

Acest ghid folosește Synapse, implementarea oficială a serverului de acasă Matrix, cu exemplele de ID-uri Matrix @alice:example.comși endpoint-uri client matrix.example.com. Înlocuiți aceste nume și adrese cu ale dvs. Instrucțiunile presupun că Synapse și un proxy invers HTTPS sunt deja instalate. Acestea nu se aplică neschimbate fiecărei implementări de server de acasă. Verificat cu documentația actuală Cloudflare și Element Synapse la 6 octombrie 2026.

Alegeți aspectul corect al rețelei

Proxy-ul orange-cloud de la Cloudflare este un proxy invers HTTP/HTTPS. Acesta se află între clienți și originea dvs. pentru cererile web proxy; nu proxyază fiecare port TCP arbitrar. Porturile sale HTTPS standard includ 443 și 8443, dar nu și portul de federație 8448, utilizat în mod obișnuit de Synapse. Consultați porturile de rețea acceptate de Cloudflare și limitările de proxy .

Prima configurație este utilizată mai jos. O înregistrare DNS proxy nu configurează în sine politica de descoperire Matrix, proxy invers, TLS sau firewall.

1. Decideți numele serverului Matrix înainte de a configura DNS-ul

Numele serverului Matrix este partea de după două puncte dintr-un ID de utilizator. În acest exemplu este example.com, deci utilizatorii au ID-uri precum @alice:example.com. Numele de gazdă al clientului tehnic este matrix.example.com. Această separare permite domeniului utilizat în ID-urile de utilizator să rămână stabil în timp ce traficul este delegat către un alt nume de gazdă. Dacă Synapse este deja inițializat, nu îl modificați server_nameîntâmplător: face parte din identitatea utilizatorului și a camerei, iar modificarea sa este o migrare, nu o ajustare a proxy-ului.

Planificați să serviți două documente JSON mici de descoperire din domeniul numelui serverului:

• https://example.com/.well-known/matrix/clientle spune clienților compatibili să utilizeze https://matrix.example.com.
• https://example.com/.well-known/matrix/serverspune celorlalte servere de acasă să ajungă la federație la matrix.example.com:443.

Documentul clientului are nevoie de un Access-Control-Allow-Origin: *antet de răspuns. Ghidul de delegare Synapse include exemple ale acestor înregistrări și structura lor așteptată: Delegare de federație Synapse .

2. Creați înregistrările DNS Cloudflare

În Cloudflare DNS, creați o Aînregistrare numită matrixcare indică adresa IPv4 publică a serverului. Adăugați o AAAAînregistrare numai dacă originea are conectivitate IPv6 funcțională și un firewall configurat pentru IPv6. Setați starea proxy a numelui gazdei web la Proxied (cloud portocaliu). Dacă domeniul rădăcină indică, de asemenea, către acest server și va servi fișierele cunoscute, utilizați proxy și înregistrarea sa web.

Păstrați înregistrările fără legătură, inclusiv înregistrările de e-mail, la setările DNS-only corespunzătoare. Înregistrările MX și TXT nu sunt transmise prin proxy. Cloudflare explică faptul că o înregistrare A, AAAA sau CNAME transmisă prin proxy direcționează cererile HTTP/HTTPS prin Cloudflare, în timp ce DNS-only returnează direct adresa de origine: Comportamentul stării proxy-ului Cloudflare .

Permiteți HTTPS de intrare de la Cloudflare către origine. Pentru o protecție mai puternică, restricționați firewall-ul de origine la intervalele IP publicate de Cloudflare și mențineți aceste intervale actualizate. Dacă adresa IP a serverului a fost expusă înainte ca zona să devină activă, proxy-ul DNS nu invalidează vechea adresă; luați în considerare schimbarea adresei IP de origine după activare. Nu presupuneți că singurul cloud portocaliu împiedică accesul direct de la origine.

3. Configurați HTTPS între Cloudflare și origine

În setările SSL/TLS ale Cloudflare, utilizați Full (strict) atunci când originea prezintă un certificat valid pentru numele de gazdă, cum ar fi un certificat de încredere publică sau un certificat Cloudflare Origin CA. Full (strict) criptează conexiunea Cloudflare-origine și validează certificatul de origine; Modul flexibil nu oferă aceeași cale TLS end-to-end. Consultați documentația Cloudflare Full (strict) .

Instalați certificatul și cheia privată pe proxy-ul invers, nu neapărat în Synapse. Proxy-ul invers ar trebui să asculte pe portul public 443 și să transmită intern cererile Matrix către listener-ul HTTP al Synapse, de obicei portul 8008. Nu expuneți public listener-ul Synapse dacă proxy-ul invers este destinat a fi singurul punct de intrare.

4. Spuneți-i companiei Synapse că se află în spatele unui proxy invers de încredere

În listenerul HTTP relevant din homeserver.yaml, activați gestionarea antetelor redirecționate. Un exemplu simplificat pentru un server necontainerizat este:

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

Îmbinați aceste setări în listener-ul existent, în loc să înlocuiți întreaga configurație. Documentația întreținută a Synapse recomandă x_forwarded: trueutilizarea unui proxy invers și sugerează legarea la localhost atunci când proxy-ul rulează pe aceeași gazdă. Pentru o implementare de container, legarea Synapse la loopback-ul containerului poate împiedica proxy-ul gazdei să îl acceseze; utilizați în schimb adresa de rețea a containerului sau a serviciului și firewall-ul pentru a accesa acea cale. Consultați ghidul actual al proxy-ului invers Synapse înainte de a modifica setările listener-ului.

Anteturile redirecționate sunt de încredere doar atunci când Synapse acceptă trafic de la proxy-ul controlat. Dacă Cloudflare este singura rută orientată spre internet, împiedicați accesul public direct la origine și configurați proxy-ul să transmită adresa corectă a clientului. $remote_addrAltfel, adresa Nginx va fi o adresă Cloudflare deoarece Cloudflare s-a conectat la Nginx. Configurați modulul real-IP al Nginx să aibă încredere doar în intervalele de surse publicate de Cloudflare înainte de utilizare CF-Connecting-IP; nu aveți niciodată încredere în acel antet de la clienți de internet arbitrari. Păstrați API-ul de administrare Synapse privat, cu excepția cazului în care aveți un motiv specific pentru a-l expune.

5. Rutați căile matriceale fără a le rescrie

Configurați proxy-ul invers să trimită atât , /_matrixcât și /_synapse/clientcătre Synapse. Păstrați exact URI-ul cererii. Semnăturile cererilor de federație Synapse pot eșua dacă un proxy decodează sau normalizează segmentele de cale codificate.

Iată un exemplu compact Nginx pentru matrix.example.com. Presupune că directivele de certificare TLS sunt deja configurate pentru acest bloc de server și că proxy-ul invers și Synapse rulează pe aceeași gazdă:

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

Nu adăugați un sufix URI la această locație regex proxy_pass. Documentația proxy a Synapse menționează canonizarea URI ca o cauză a erorilor de semnătură a federației. De asemenea, ajustați client_max_body_sizepentru a se potrivi cu limita de încărcare Synapse și cu orice limită a planului Cloudflare care se aplică zonei dvs. Valoarea 50Mde mai sus este doar un exemplu, nu o recomandare universală.

Cloudflare acceptă WebSockets în planurile sale, iar clienții Matrix pot utiliza conexiuni de lungă durată. Confirmați că proxy-ul dvs. permite actualizarea și că orice reguli WAF sau de limită de rată nu resping solicitările legitime Matrix. Documentația WebSockets de la Cloudflare descrie modul în care gestionează conexiunile actualizate.

6. Publicați răspunsurile binecunoscute

Serviți următoarele două răspunsuri prin example.comHTTPS. Le puteți returna de la serverul web, de la o gazdă statică sau de la o gazdă virtuală separată. Păstrați documentele clientului și cele ale federației distincte:

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

Nu utilizați o redirecționare către o gazdă fără legătură ca înlocuitor fără a verifica cerințele de descoperire Matrix și comportamentul clientului. Asigurați-vă că gazda cu numele serverului este acoperită de un certificat HTTPS valid și că Cloudflare nu stochează în cache răspunsurile de descoperire învechite în timp ce le modificați.

7. Mențineți traficul API dinamic și încărcările în limite

Nu memorați în cache răspunsurile autentificate Matrix API. Adăugați o regulă de cache Cloudflare pentru a ocoli memorarea în cache pentru căile Matrix API, inclusiv /_matrix/*și /_synapse/client/*, cu excepția cazului în care aveți un motiv testat cu atenție pentru a gestiona diferit un anumit răspuns public. Evitați regulile WAF sau bot ample care contestă sau blochează endpoint-urile de federație; solicitările de federație provin de la mai multe servere de domiciliu independente. Dacă este necesară o regulă de securitate, testați-o în funcție de autentificarea clientului, sincronizare, încărcarea media și federație înainte de a o aplica în general.

Încărcările au mai multe limite independente: clientul, setarea de încărcare a planului sau zonei Cloudflare, limita de dimensiune a corpului a proxy-ului invers și limita de eroare 413 a Synapse max_upload_size. O eroare 413 înseamnă că una dintre aceste limite a respins solicitarea. Cloudflare publică limite de încărcare dependente de plan și notează că aceste setări pot fi ajustate în cadrul constrângerilor documentate: Pagina de depanare 413 a Cloudflare . Ridicați doar limitele necesare și testați cu un fișier mai mic decât limita configurată înainte de a le crește în continuare.

8. Verificați accesul clientului, descoperirea și federarea

Executați aceste verificări de pe o mașină din afara rețelei serverului dvs. Înlocuiți numele de gazdă din exemplu:

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

Primele două cereri ar trebui să returneze HTTP 200, conținut JSON și valorile așteptate. Documentul clientului ar trebui să includă antetul CORS. Punctul final al versiunilor clientului ar trebui să returneze JSON de la Synapse prin Cloudflare. Punctul final de sănătate Synapse returnează HTTP 200 atunci când este accesat printr-un listener configurat, dar nu înlocuiește verificarea autentificării sau a federației.

Apoi, conectați-vă cu un client Matrix folosind un ID care se termină în :example.com, alăturați-vă unei camere găzduite în altă parte și confirmați că mesajele și actualizările de apartenență se sincronizează. Folosiți un tester de federație Matrix sau un al doilea server de domiciliu pentru a valida descoperirea serverului și federarea. O solicitare reușită pentru /_matrix/client/versionsdovedește doar că ruta orientată spre client funcționează; nu dovedește că descoperirea federației, semnarea sau federația de ieșire sunt corecte.

Cum arată succesul - și când să schimbi designul

• Clienții se conectează prin Cloudflare: DNS-ul se rezolvă la adrese Cloudflare, HTTPS folosește certificatul dorit, iar API-ul clientului Matrix returnează un răspuns.
• Descoperirea este corectă: ambele adrese URL cunoscute returnează JSON-ul corect, iar documentul client trece verificările între origini.
• Federația funcționează: un server la distanță descoperă endpoint-ul anunțat și poate schimba starea camerei. Dacă delegarea 443 eșuează, dar direct 8448 funcționează, inspectați înregistrarea cunoscută, rutarea căii proxy și regulile WAF.
• Încărcările funcționează la dimensiunea așteptată: testați o încărcare reprezentativă. Dacă fișierele mici reușesc, dar fișierele mai mari returnează 413, comparați toate cele patru limite de dimensiune în loc să modificați doar Synapse.
• Originea nu este o cale publică alternativă: solicitările directe către origine ar trebui blocate sau limitate conform proiectării. Dacă acestea ajung în continuare la serviciul Matrix, corectați configurația firewall-ului și a proxy-ului de încredere.

Folosește federația doar DNS pe portul 8448 dacă cerințele sau implementarea ta nu pot ruta federația pe 443, dar reține că acest lucru expune adresa de origine și elimină protecția proxy HTTP Cloudflare pentru numele de gazdă respectiv. Spectrum este o altă opțiune pentru porturile non-standard, în funcție de disponibilitatea produsului și de constrângerile planului. Proxy-ul Cloudflare înseamnă, de asemenea, că TLS se termină la Cloudflare înainte de o a doua conexiune TLS la originea ta; criptarea end-to-end Matrix protejează conținutul mesajelor criptate, dar nu ascunde metadatele conexiunii sau conținutul care nu este criptat end-to-end de serviciile care gestionează solicitarea HTTP. Alege topologia în funcție de cerințele tale de confidențialitate, federație și disponibilitate, apoi testează din nou după modificările aduse DNS, certificatelor, Synapse sau regulilor Cloudflare.