Cum se configurează federația pe Matrix Synapse: Un ghid pas cu pas

Federația matricială permite unui server de acasă Synapse să facă schimb de evenimente de cameră cu alte servere de acasă, astfel încât persoanele care utilizează servere diferite să poată participa în aceeași cameră. Pentru a o configura, faceți API-ul de federație al Synapse accesibil prin HTTPS, publicați informațiile corecte de descoperire a serverului, permiteți traficul de rețea necesar și testați endpoint-ul public. Simpla pornire a Synapse sau deschiderea portului 8448 nu este suficientă dacă rutarea DNS, TLS sau proxy este greșită.

Acest ghid utilizează o implementare tipică de tip reverse-proxy: domeniul de identitate Matrix este example.org, Synapse rulează la matrix.example.org, iar proxy-ul gestionează TLS pe ​​portul 443. Înlocuiți ambele domenii exemplu cu ale dvs. Dacă Synapse este deja accesibil prin HTTPS pe example.org:8448, de obicei nu aveți nevoie de delegare. Comenzile și căile de fișiere depind de instalarea Synapse dintr-un pachet, dintr-un mediu virtual sau dintr-un container.

Ce trebuie să fie adevărat înainte ca federația să poată funcționa?

• Serverul tău Synapse are un nume public stabil server_name. Acest nume apare în ID-urile Matrix, cum ar fi @alex:example.org; schimbarea ulterioară a acestuia nu este o modificare obișnuită a numelui de gazdă.
• Alte servere de acasă pot accesa API-ul de federație prin HTTPS și pot valida certificatul TLS.
• Descoperirea serverelor conduce serverele de acasă la distanță către gazda și portul corect. Portul standard de federație este 8448; delegarea poate indica HTTPS pe 443.
• Regulile firewall-ului permit traficul de intrare pe endpoint-ul de federație ales și conexiunile de federație de ieșire.

Federația se referă la comunicarea de la server la server. Nu face automat publice camerele private și nu invită alți utilizatori. Utilizatorii trebuie în continuare să se alăture sau să fie invitați în camere, iar apartenența la cameră și setările camerei determină cine poate participa. Începeți prin a decide cum ar trebui să arate ID-urile Matrix, apoi utilizați același domeniu ca și cel al Synapse server_name.

Pasul 1: Verificați numele serverului Synapse și implementarea

Deschideți fișierul activ homeserver.yamlși confirmați că acesta server_nameeste domeniul pe care intenționați să îl păstrați. Un aranjament comun este:

server_name: "example.org"
public_baseurl: "https://matrix.example.org/"

server_namedetermină domeniul din ID-urile Matrice ale utilizatorilor. public_baseurleste adresa URL publică orientată către client, cum ar fi adresa URL pe care oamenii o introduc într-un client; în spatele unui proxy invers ar trebui să denumească adresa URL a proxy-ului. Acestea servesc unor scopuri diferite, așa că nu înlocuiți numele serverului cu un nume de container backend și nu îl modificați doar pentru a se potrivi cu un subdomeniu. Dacă serverul este deja utilizat, faceți o copie de rezervă a configurației și a bazei de date înainte de a modifica setările de rețea.

Verificați cum este instalat și gestionat Synapse. Un serviciu systemd, o stivă Docker Compose, o implementare Kubernetes și un produs de găzduire gestionat utilizează proceduri diferite de repornire și de conectare la rețea. Aplicați exemplele de mai jos la fișierul de configurare corect și păstrați orice listener-uri și setări personalizate existente.

Pasul 2: Alegeți federația directă pe 8448 sau delegarea către 443

Există două rute comune pentru federația de intrare:

• Folosește portul implicit 8448: direcționează DNS-ul domeniului server_namecătre server, expune HTTPS pe portul 8448 și prezintă un certificat valid pentru domeniul respectiv. Dacă API-urile sunt disponibile la domeniul numit de server_namepe portul 8448, documentația Synapse precizează că delegarea nu este necesară.
• Folosește portul 443 cu delegare: servește https://example.org/.well-known/matrix/servercu JSON direcționând alte servere către endpoint-ul real, de exemplu {"m.server":"matrix.example.org:443"}. Numele de gazdă delegat trebuie să fie rezolvat public și să prezinte un certificat valid pentru matrix.example.org.

Portul 8448 nu este obligatoriu în fiecare implementare. Dacă utilizați delegarea la 443, federația de intrare poate utiliza 443 în schimb. Dacă conexiunile de ieșire sunt restricționate de un firewall de ieșire, permiteți atât 443, cât și 8448, deoarece serverele la distanță pot utiliza oricare dintre ele. Alegeți o rută de intrare și asigurați-vă că înregistrarea DNS, certificatul TLS, proxy-ul invers și firewall-ul sunt în concordanță cu aceasta.

Pasul 3: Dirijați API-ul de federație al Synapse prin proxy-ul invers

Synapse ascultă de obicei pe portul HTTP 8008 în spatele unui proxy invers. Proxy-ul termină HTTPS și transmite punctele finale Matrix către Synapse. În homeserver.yamllistener-ul relevant, asigurați-vă că listener-ul HTTP include atât resursele clientului, cât și pe cele ale federației și are încredere în anteturile proxy:

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

Acesta este un exemplu de ascultător, nu un înlocuitor drop-in pentru configurația completă a fiecărei instalări. Dacă Synapse rulează într-un container, legarea în 127.0.0.1interiorul containerului poate împiedica containerul proxy să îl acceseze; utilizați în schimb rețeaua de servicii și o adresă de legare adecvată. Păstrați ascultătorul backend privat și expuneți doar proxy-ul așa cum a fost prevăzut.

Configurați proxy-ul pentru a redirecționa cererile către /_matrixși /_synapse/clientcătre portul 8008, setând X-Forwarded-Forși X-Forwarded-Proto. Pentru NGINX, locația esențială poate arăta astfel:

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

Folosește adresa corectă în amonte pentru gazda sau rețeaua containerului. Nu adaugă o cale rescrisă la proxy_pass; instrucțiunile proxy ale Synapse avertizează că normalizarea căilor de solicitare codificate poate cauza erori de verificare a semnăturii federației. Aliniază limita de dimensiune a încărcării proxy-ului cu setarea de încărcare media Synapse dacă utilizatorii trebuie să încarce fișiere mai mari.

Pasul 4: Configurați TLS și DNS

Obțineți un certificat TLS de încredere publică pentru numele de gazdă care deservește federația. Cu configurația reverse-proxy de mai sus, aceasta se întâmplă matrix.example.orgatunci când utilizați delegarea către gazda respectivă. Confirmați că proxy-ul deservește întregul lanț de certificate, reînnoiește certificatele automat și prezintă certificatul corect pe portul pe care serverele la distanță îl vor contacta. Un certificat autosemnat sau un certificat pentru un nume de gazdă greșit va eșua validarea pe alte servere de acasă.

Creați o înregistrare publică A și, dacă utilizați IPv6, o înregistrare AAAA pentru matrix.example.orga indica proxy-ul. Verificați dacă ambele înregistrări ajung la serviciul dorit; o înregistrare AAAA incorectă poate cauza erori pentru serverele la distanță compatibile cu IPv6, chiar și atunci când IPv4 funcționează. Dacă utilizați direct portul 8448, DNS-ul pentru example.orgtrebuie să conducă la listener, iar certificatul său trebuie să se potrivească cu example.org.

Pasul 5: Publicați informațiile despre descoperirea serverului

Pentru exemplul delegat, faceți ca URL-ul HTTPS de mai jos să returneze starea 200 și JSON cu endpoint-ul exact:

https://example.org/.well-known/matrix/server

{
  "m.server": "matrix.example.org:443"
}

Serviți-l ca application/json. Verificați dacă este lizibil public fără autentificare, că nu redirecționează într-o buclă și că numele de gazdă și portul corespund cu proxy-ul TLS. Nu publicați matrix.example.orgîn fișier dacă proxy-ul direcționează de fapt federația în altă parte.

Synapse poate servi acest fișier singur serve_server_wellknown: truedoar atunci când cererile către https://<server_name>/sunt rutate corespunzător către Synapse. Dacă numele serverului dvs. este , example.orgdar Synapse este găzduit la matrix.example.org, un server web static sau un proxy invers pe example.orgeste adesea locul mai potrivit pentru a servi răspunsul de delegare.

O eroare frecventă este tratarea /.well-known/matrix/clientși /.well-known/matrix/serverca fiind interschimbabile. Fișierul serverului ajută alte servere de domiciliu să descopere federația primită. Fișierul client promovează o adresă URL a serverului de domiciliu orientată către client și este opțional pentru federație. Configurați-l separat numai dacă doriți ca clienții compatibili să descopere adresa URL a clientului din ID-urile Matrice ale utilizatorilor.

Pasul 6: Deschideți căile de firewall necesare

Pentru federația directă de intrare, permiteți portul TCP 8448 de intrare către listener-ul sau proxy-ul TLS. Pentru exemplul delegat, permiteți portul TCP 443 de intrare către proxy. Conexiunile client utilizează în mod normal și HTTPS pe 443. Dacă accesul la rețea de ieșire este restricționat, permiteți Synapse să se conecteze la servere de domiciliu la distanță prin TCP 443 și 8448. Nu deschideți portul backend 8008 Synapse către internetul public atunci când proxy-ul invers este destinat să fie punctul de intrare public.

Dacă serverul se află în spatele unui firewall în cloud, al unui router, al unei rețele de containere și al unui firewall gazdă, verificați fiecare nivel. O solicitare locală reușită către portul 8008 dovedește doar că Synapse răspunde local; nu dovedește că un server Matrix la distanță poate rezolva domeniul dvs., valida TLS sau ajunge la listener-ul public.

Pasul 7: Reporniți în siguranță și verificați endpoint-urile publice

Validați YAML-ul înainte de a reporni, utilizând comanda de validare acceptată de metoda de instalare. Apoi, reporniți serviciul sau implementarea Synapse și verificați jurnalele acestuia pentru erori de configurare sau de ascultare. De pe o mașină din afara rețelei private, solicitați fișierul de descoperire și endpoint-ul versiunii de federație:

curl -i https://example.org/.well-known/matrix/server
curl -i https://matrix.example.org/_matrix/federation/v1/version

Pentru prima comandă, așteptați-vă la un răspuns HTTPS cu un corp JSON care conține codul corect m.server. Pentru a doua, așteptați-vă la un răspuns HTTPS de succes de la Synapse, mai degrabă decât la o eroare de proxy, un avertisment de certificat sau o expirare a conexiunii. Corpul exact al răspunsului poate varia în funcție de versiunea Synapse.

Apoi, introduceți Matricea server_name(de exemplu, example.org, nu neapărat numele de gazdă proxy) în Testerul de federație Matrix . Remediați orice erori DNS, de delegare, certificat sau endpoint raportate și rulați din nou testul. În cele din urmă, invitați un utilizator de pe un alt server de acasă într-o cameră de testare sau alăturați-vă unei camere găzduite în altă parte. Un rezultat pozitiv al testerului este o verificare utilă a conectivității publice, dar nu garantează că fiecare server la distanță, politică de cameră, firewall sau configurație client se va comporta identic.

Concepții greșite care duc la configurații defectuoase sau neașteptate

• „Trebuie să expun întotdeauna portul 8448.” Nu. Implicit este 8448, dar delegarea serverului poate direcționa federația primită către 443. Deschideți portul pe care îl utilizează de fapt ruta de descoperire publicată.
• „Fișierul bine cunoscut al clientului permite federația.” Nu o face. Descoperirea federației utilizează punctul final bine cunoscut al serverului sau un rezerv DNS acceptat; punctul final al clientului servește unui alt scop.
• „Federația face publică fiecare cameră locală.” Nu. Federația permite comunicarea cu serverul. Vizibilitatea camerei și apartenența la aceasta guvernează în continuare participarea; invitați un cont la distanță într-o cameră de testare pentru a confirma cazul de utilizare de care aveți nevoie.
• „O verificare locală verde a stării de funcționare dovedește federația.” Nu. Verificările locale nu testează DNS-ul public, validarea TLS externă, NAT, regulile firewall-ului în cloud sau rutarea proxy. Testați din exterior și utilizați testerul de federație.

Documentația Synapse întreținută recomandă un proxy invers pentru terminarea TLS și explică porturile separate pentru client și federație. Consultați ghidurile oficiale pentru configurarea proxy-ului invers , delegarea federației primite , opțiunile de configurare Synapse și îndrumările privind firewall-ul și securitatea . Pentru regulile de descoperire a serverelor, consultați specificația API-ului Matrix Server-Server . Exemplele de aici presupun că Synapse standard se află în spatele unui proxy invers HTTPS; rețelele de containere, implementările gestionate și machetele de ascultare personalizate pot necesita valori diferite.