Cum să configurați aliasuri personalizate pentru camerele Matrix pe domeniul dvs.

Un alias de cameră Matrix oferă unei camere o adresă lizibilă de către om, cum ar fi #support:example.org. Partea de după două puncte este numele serverului homeserver , domeniul care deține spațiul de nume alias. Nu este o etichetă de domeniu arbitrară care poate fi modificată prin adăugarea unei înregistrări DNS. Pentru a utiliza propriul domeniu, homeserverul trebuie să fie configurat cu acel domeniu ca nume de server; federația poate fi apoi delegată unei gazde separate.

Acest ghid folosește example.orgca domeniu, matrix.example.orgca gazdă Synapse și #support:example.orgca alias țintă. Înlocuiți acești substituenți cu propriile valori. Se concentrează pe Synapse auto-găzduit. Dacă utilizați un furnizor Matrix găzduit, verificați dacă acesta vă permite să utilizați un nume de server personalizat; multe conturi găzduite pot crea aliasuri doar sub domeniul furnizorului.

Ce face un alias de cameră Matrix

Un server de acasă este serverul Matrix care stochează datele camerelor utilizatorilor și se conectează la alte servere. Un ID de cameră , cum ar fi !opaqueid:example.org, identifică o cameră din punct de vedere tehnic. Un alias de cameră , cum ar fi #support:example.org, este o intrare de director lizibilă care se rezolvă într-un ID de cameră și o listă de servere care pot ajuta un utilizator să se alăture.

Un alias nu redenumește camera, nu îi modifică confidențialitatea și nu garantează că aceasta apare într-un director public al camerei. Acestea sunt setări separate ale camerei. Camera poate avea mai multe aliasuri. Un alias canonic este adresa preferată afișată sau partajată de clienți; este publicată ca stare a camerei, în timp ce serverul principal menține maparea alias-cameră. Specificația Matrix avertizează că mapările aliasurilor se pot schimba, așadar rezolvați o adresă înainte de a vă baza pe ea.

Înainte de a începe

• Controlează domeniul pe care dorești să îl utilizezi, cum ar fi example.org, inclusiv posibilitatea de a servi conținut HTTPS pe domeniul respectiv.
• Rulați un server de acasă, cum ar fi Synapse, cu Matricea sa server_namesetată la example.org. Această valoare este aleasă la configurarea serverului și nu ar trebui modificată ulterior: ID-urile de utilizator și aliasurile o folosesc ca spațiu de nume.
• Să aveți un certificat TLS funcțional și o rută de federație. Gazda Matrix delegată, cum ar fi matrix.example.org, trebuie să prezinte un certificat valid.
• Fiți alăturați camerei și aveți permisiunea necesară pentru a-i schimba adresele. Synapse are, de asemenea, reguli pe server care pot permite sau refuza crearea de aliasuri.

Dacă serverul rulează deja cu un nume de server diferit, de exemplu provider.net, crearea #support:example.orgnu este o comandă rapidă pentru maparea domeniului. Întrebați furnizorul despre suportul pentru domenii personalizate sau planificați o implementare și o migrare separată a serverului de domiciliu. Matrix nu definește un proces pentru ca un server de domiciliu să creeze aliasuri în spațiul de nume al altui server.

Pasul 1: Alegeți numele serverului și ruta de federație

Decideți ce nume va apărea după două puncte înainte de a configura serverul de domiciliu. În acest exemplu, Synapse folosește example.orgca nume de server, în timp ce serviciile sale client și de federație rulează la matrix.example.org. O înregistrare DNS trimite trafic matrix.example.orgcătre gazdă sau proxy invers. Înregistrarea DNS în sine nu stabilește spațiul de nume alias; numele serverului Synapse o face.

Când serverul de domiciliu nu este accesibil direct pe example.orgportul implicit de federație 8448, Matrix are nevoie de o modalitate de a descoperi punctul său final de federație. O metodă comună este delegarea .well-known : un mic răspuns JSON HTTPS la nivelul domeniului numelui serverului direcționează traficul de federație către gazda Matrix reală. Serviți acest lucru la https://example.org/.well-known/matrix/server:

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

Asigurați-vă că răspunsul este un JSON valid, servit prin HTTPS și că gazda țintă are un certificat valid și direcționează cererile de federație către Synapse. Portul poate fi omis atunci când endpoint-ul de federație utilizează 8448; în acest exemplu, portul 443 este explicit. Dacă Synapse deservește deja federația pe domeniul numelui serverului la portul 8448, delegarea poate să nu fie necesară. /.well-known/matrix/clientFișierul orientat către client este un mecanism de descoperire diferit și nu înlocuiește delegarea serverului.

Documentația de configurare actuală a Synapse include serve_server_wellknownopțiunea pentru cazurile în care cererile către domeniul numelui serverului pe portul 443 sunt direcționate către Synapse. Folosiți această opțiune numai dacă proxy-ul și rutarea domeniului corespund cerințelor documentate. În caz contrar, configurați răspunsul JSON la serverul web sau la proxy.

Pasul 2: Verificați politicile de alias ale Synapse

Synapse poate restricționa cine poate crea aliasuri și ce adrese de cameră sunt permise. În homeserver.yaml, inspectează alias_creation_rulesdacă o cerere de creare a unui alias este respinsă. Synapse evaluează regulile configurate în ordine; prima regulă potrivită decide cererea, iar dacă nicio regulă nu se potrivește, cererea este respinsă. O listă goală respinge toate cererile de creare a unui alias. O listă nulă sau omisă permite crearea de aliasuri în mod implicit, sub rezerva altor verificări.

Bifați și require_membership_for_aliases, care implicit impune prezența utilizatorului în cameră. Dacă modificați configurația Synapse, urmați procesul normal de validare și repornire al implementării și evitați să relaxați politica mai mult decât este necesar. Nivelurile de putere ale unei camere și controalele disponibile ale clientului pot afecta, de asemenea, dacă un membru obișnuit poate seta aliasul preferat.

Pasul 3: Creați un alias pentru cameră

Alătură-te camerei dorite într-un client Matrix și deschide setările acesteia. Caută o secțiune de adresă sau alias; textul și aspectul clientului pot varia în funcție de versiune. Introdu adresa completă, inclusiv adresa principală #și domeniul serverului principal, de exemplu #support:example.org. Adaugă-o ca adresă de cameră și, dacă clientul oferă opțiunea, setează-o ca alias canonic sau preferat. Salvează modificarea.

Dacă clientul dvs. nu furnizează un control alias, o solicitare API client-server poate crea maparea. PUT /_matrix/client/v3/directory/room/{roomAlias}Punctul final autentificat necesită un ID de cameră în corpul solicitării. De exemplu, un membru autorizat al camerei sau un cont de server poate trimite o solicitare către serverul principal care deține example.org:

curl -X PUT \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org" \
  -H "Authorization: Bearer $MATRIX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"room_id":"!yourRoomId:example.org"}'

Înlocuiți ID-ul camerei eșantion cu ID-ul exact al camerei și utilizați un token de acces valid cu autorizația necesară. Tratați token-ul ca pe o parolă: nu-l publicați, nu-l lipiți într-o postare de asistență și nu-l trimiteți către controlul sursei. Procentul este afișat ca escape în codificarea URL #și :pentru calea HTTP. Un răspuns reușit indică faptul că maparea a fost creată. Un răspuns „există deja” înseamnă că numele este ocupat; confirmați cine îl deține înainte de a modifica sau elimina ceva.

Pasul 4: Verificați adresa și distribuiți-o

Rezolvați aliasul folosind API-ul public client-server. Această căutare nu necesită autentificare:

curl -i \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org"

Un răspuns reușit ar trebui să conțină valoarea așteptată room_idși o serverslistă. Comparați ID-ul camerei returnat cu camera dorită. O eroare 404 înseamnă că aliasul nu are nicio mapare pe serverul care gestionează acel spațiu de nume. O eroare 400 indică o adresă formatată invalid. Apoi, testați aliasul complet într-un al doilea cont sau client Matrix pentru a confirma că se rezolvă camera și că aceasta poate fi alăturată conform regulilor sale de alăturare.

Dacă setezi un alias canonic, verifică din nou detaliile camerei și confirmă că adresa preferată este cea pe care intenționezi să o publici. Partajează aliasul sau un permalink Matrix numai după ce confirmi că acesta duce la camera corectă. Reține că un alias public nu face publică o cameră privată; un utilizator are nevoie în continuare de permisiune pentru a se alătura.

Probleme comune de evitat

• Utilizarea unui domeniu pe care serverul de domiciliu nu îl deține: Numele serverului dintr-un alias trebuie să corespundă cu spațiul de nume al serverului de domiciliu care îl creează. Un CNAME DNS nu poate autoriza singur domeniul altui server.
• Amestecarea domeniului și a gazdei: example.org poate fi spațiul de nume alias în timp ce matrix.example.orgeste gazda serviciului. Setați numele serverului Synapse și delegarea în mod deliberat.
• Plasarea fișierului de descoperire a clientului în locul greșit: Delegarea federației utilizează [numele /.well-known/matrix/serverfișierului]. Fișierul de descoperire a clientului are o cale și un scop diferit.
• Presupunând că un alias publică o cameră: Rezolvarea aliasului și publicarea directoarelor de camere publice sunt operațiuni separate, guvernate de politici separate.
• Schimbarea numelui serverului pe o implementare stabilită: ID-urile Matrix existente depind de acel spațiu de nume. Tratați o modificare de domeniu ca o migrare arhitecturală, nu ca o setare rapidă de alias.
• Partajare fără verificarea mapării: Rezolvați aliasul și comparați ID-ul camerei returnat înainte de a-l publica. O adresă lizibilă este convenabilă, dar maparea serverului este cea care determină unde duce.

Pentru detalii despre protocol, consultați formatul identificatorului și aliasului Matrix și API-ul aliasului de cameră Matrix . Pentru configurarea Synapse, consultați ghidul de delegare a federației și manualul de configurare Element . Opțiunile Synapse și ecranele clientului se pot schimba între versiuni; verificați documentația pentru versiunea pe care o utilizați.