Cum se instalează serverul Synapse Matrix cu Docker Compose

Exemplu ilustrativ: Imaginați-vă un mic grup de voluntari care își dorește propriul server Matrix la chat.example.com. Aceasta este o configurație ipotetică, nu un raport al unui server testat. Aceiași pași pot fi adaptați la un domeniu real, dar alegeți cu atenție numele serverului Matrix: Synapse îl folosește în ID-urile de utilizator și nu poate fi modificat ulterior.

Acest ghid creează un serviciu Synapse și o bază de date PostgreSQL cu Docker Compose. Imaginea oficială Docker a Synapse începe în mod implicit cu SQLite, ceea ce este convenabil pentru o versiune de probă de unică folosință; documentația Docker a Synapse recomandă PostgreSQL pentru producție. Prin urmare, exemplul generează mai întâi configurația Synapse, modifică setările bazei de date la PostgreSQL și apoi pornește ambele containere. Imaginea oficială este ghcr.io/element-hq/synapse. Instrucțiunile și detaliile imaginii au fost verificate în raport cu documentația oficială actuală pe 6 octombrie 2026; etichetele imaginii și versiunile de software acceptate se pot modifica, așadar consultați documentația legată înainte de o implementare pe termen lung.

Ce aveți nevoie înainte de instalare

• Un server Linux sau o altă gazdă compatibilă cu Docker, cu Docker Engine și pluginul Docker Compose instalate. Confirmați că Compose este disponibil cu [numele aplicației] docker compose version. Urmați instrucțiunile oficiale de instalare ale Docker pentru sistemul dvs. de operare.
• Un domeniu sau subdomeniu care indică serverul. În acest exemplu, chat.example.comeste numele serverului Synapse, deci ID-urile utilizatorilor locali vor arăta astfel @alex:chat.example.com. Înlocuiți-l cu un domeniu pe care îl controlați înainte de a genera configurația.
• Un proxy invers sau o altă metodă de terminare TLS pentru uz public. Ascultătorul HTTP implicit al Synapse pe port 8008nu este un endpoint HTTPS conectat la internet. Acest exemplu Compose leagă acel port de interfața loopback a gazdei, astfel încât un proxy invers de pe aceeași mașină să îl poată accesa.

Numele din [numele de utilizator] SYNAPSE_SERVER_NAMEnu este neapărat adresa URL a fiecărei conexiuni client. Dacă doriți ID-uri mai scurte, cum ar fi @alex:example.comatunci când serviți clienți de la [ chat.example.comnumele utilizatorului], aceasta necesită o configurație deliberată a domeniului și a descoperirii. Decideți acest lucru înainte de a crea conturi.

1. Creați un director de lucru și o parolă pentru baza de date

Pe server, creați un director pentru proiectul Compose și fișierele persistente Synapse:

mkdir -p ~/matrix-synapse/data
cd ~/matrix-synapse

Creați un fișier local .envpe care Docker Compose îl va citi. Generați o parolă aleatorie lungă folosind un manager de parole sau un generator local securizat și plasați-o după POSTGRES_PASSWORD=. Folosiți litere și cifre pentru acest exemplu pentru a evita problemele de citare YAML ulterioare. Nu trimiteți acest fișier într-un depozit public și restricționați-i permisiunile:

umask 077
nano .env

Fișierul ar trebui să conțină o linie, de exemplu POSTGRES_PASSWORD=replace-with-a-long-random-value. Textul este un provizoriu, nu o parolă de reutilizat. Păstrați parola disponibilă pentru configurarea bazei de date Synapse la pasul 3.

2. Definiți serviciile Synapse și PostgreSQL

Creați compose.yamlîn directorul proiectului:

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=C"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  synapse:
    image: ghcr.io/element-hq/synapse:latest
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      SYNAPSE_SERVER_NAME: chat.example.com
      SYNAPSE_REPORT_STATS: "no"
    volumes:
      - ./data:/data
    ports:
      - "127.0.0.1:8008:8008"

volumes:
  postgres_data:

Înlocuiți chat.example.comcu numele final al serverului ales. Verificarea stării de funcționare PostgreSQL permite companiei Compose să aștepte ca baza de date să raporteze că este pregătită înainte de a porni Synapse. Volumul bazei de date numit și ./datadirectorul montat pe gazdă supraviețuiesc înlocuirii containerului; eliminarea containerelor în sine nu le șterge. Evitați acest lucru, docker compose down -vcu excepția cazului în care doriți intenționat să ștergeți volumul bazei de date.

Exemplul folosește metoda :latestpentru a simplifica prima extragere. Pentru un server întreținut, selectați și înregistrați o anumită etichetă de lansare Synapse sau un rezumat de imagine, apoi actualizați-o printr-un proces de actualizare planificată după ce ați citit notele de lansare. Nu presupuneți că latesteticheta modificabilă va păstra aceeași versiune.

3. Generați configurația Synapse și direcționați-o către PostgreSQL

Rulați imaginea oficială o singură dată în modul de generare a configurației. Deoarece Compose se montează ./datala /data, configurația generată și cheia de semnare rămân pe gazdă:

docker compose run --rm synapse generate

Această comandă folosește numele serverului și statisticile anonime alese din mediul Compose. Synapse creează și o cheie de semnare; păstrați-o în directorul de date și includeți-o în copiile de rezervă protejate. Nu o regenerați și nu o eliminați în timpul unei actualizări obișnuite a containerului.

Deschideți data/homeserver.yamlși înlocuiți secțiunea generată database:cu următoarele setări. Folosiți parola exactă din .envsecțiunea inițială în locul substituentului:

database:
  name: psycopg2
  args:
    user: synapse
    password: 'replace-with-the-same-random-value'
    dbname: synapse
    host: postgres
    port: 5432
    cp_min: 5
    cp_max: 10

Păstrați indentarea YAML din jur și asigurați-vă că există o singură database:secțiune activă. Numele gazdei postgreseste numele serviciului Compose, pe care containerele îl pot rezolva în rețeaua lor implicită partajată. Configurația folosește numele motorului PostgreSQL documentat al Synapse, psycopg2, și numele argumentelor bazei de date, inclusiv dbname.

Pentru acest mic exemplu, parola bazei de date apare atât în ​​configurația Synapse, cât și în .envfișierul protejat. Tratați ambele fișiere ca secrete, limitați accesul gazdei și utilizați o abordare dedicată gestionării secretelor, dacă mediul de implementare necesită una. Nu lipiți parola reală în jurnale, capturi de ecran sau solicitări de asistență.

4. Porniți Synapse cu Docker Compose

Porniți stiva în fundal:

docker compose up -d

Verificați starea serviciului și citiți jurnalele de pornire:

docker compose ps
docker compose logs --tail=100 synapse

Așteptați ca Synapse să finalizeze configurarea bazei de date pentru prima pornire. Un container care rulează înseamnă doar că procesul său este activ; verificați jurnalele pentru erori de configurare, bază de date sau permisiuni înainte de a continua. Pentru a urmări jurnalele pe măsură ce sosesc, utilizați docker compose logs -f synapseși apăsați Ctrl+Cpentru a opri urmărirea lor fără a opri containerul.

5. Verificați API-ul local și configurați accesul public

De la gazda Docker, solicitați endpoint-ul versiunilor API-ului clientului Synapse:

curl -fsS http://127.0.0.1:8008/_matrix/client/versions

Un răspuns reușit este un JSON care descrie versiunile API-ului clientului Matrix acceptate. Aceasta confirmă faptul că listener-ul HTTP răspunde local; nu dovedește că DNS, HTTPS sau federația sunt configurate corect.

Configurați proxy-ul invers al gazdei pentru a redirecționa cererile pentru domeniul ales http://127.0.0.1:8008și a obține un certificat TLS valid. Păstrați calea cererii Matrix la proxy. Apoi verificați endpoint-ul public:

curl -fsS https://chat.example.com/_matrix/client/versions

Înlocuiți numele de gazdă exemplu cu cel real. Dacă clienții trebuie să descopere serverul de acasă dintr-un domeniu separat de ID utilizator, publicați înregistrările de descoperire cunoscute Matrix corespunzătoare pentru acel design. Federarea necesită, de asemenea, rutare publică și DNS corecte; deschiderea portului local 8008nu oferă o implementare publică completă. Consultați instrucțiunile Synapse privind reverse-proxy-ul și federația înainte de a expune serviciul.

6. Creați primul cont de administrator

Synapse dezactivează înregistrarea publică în mod implicit. Pentru un server privat, păstrați această valoare implicită și creați conturi din linia de comandă. Adăugați temporar o registration_shared_secretvaloare puternică la data/homeserver.yaml, apoi reporniți Synapse astfel încât să citească modificarea:

docker compose restart synapse

Rulați instrumentul de înregistrare în interiorul containerului. Acesta solicită un nume de utilizator și o parolă; setarea --admincreează primul administrator:

docker compose exec synapse register_new_matrix_user \
  http://localhost:8008 \
  -c /data/homeserver.yaml \
  --admin

După ce contul este creat, eliminați-l registration_shared_secretdin configurație și reporniți Synapse. Dacă lăsați secretul configurat, oricine îl obține poate înregistra conturi standard sau de administrator prin interfața de înregistrare. Conectați-vă printr-un client Matrix care acceptă servere de acasă personalizate, utilizând adresa URL a serverului furnizată de proxy-ul invers.

Copii de rezervă, actualizări și remedieri comune

• Faceți o copie de rezervă a datelor corecte: opriți sau faceți o instantanee constantă a datelor PostgreSQL și faceți o copie de rezervă a ./data, inclusiv a configurației, a suportului media și a cheii de semnare. O copie a compose.yamlnu poate restaura serverul de bază. Stocați copiile de rezervă undeva separat de server și confirmați periodic că le puteți citi.
• Sinapsa nu poate scrie pe /data: inspectați proprietatea și permisiunile gazdei pe ./data. Utilizatorul oficial al imaginii de execuție are nevoie de permisiunea de a citi configurația și de a scrie date. Ajustați cu atenție proprietatea gazdei, în loc să faceți directorul accesibil tuturor.
• Conexiunea la baza de date eșuează: verificați dacă configurația bazei de date folosește host: postgres, dacă parola se potrivește .envși dacă docker compose logs postgresindică o bază de date sănătoasă. depends_onCondiția de pregătire a programului Compose reduce concurența la pornire, dar nu repară acreditările incorecte.
• API-ul local funcționează, dar clienții nu se pot conecta: verificați înregistrarea DNS, certificatul TLS, înregistrările reverse-proxy upstream și discovery pentru aranjamentul de domeniu ales. Maparea porturilor loopback-only este intenționată pentru un proxy de aceeași gazdă; un proxy dintr-un alt container necesită o rețea Docker partajată și un design de rutare diferit.
• Actualizare: faceți mai întâi o copie de rezervă, consultați notele de lansare Synapse, actualizați eticheta imaginii fixate și recreați serviciul cu [ docker compose pullurmăriți], urmat de [urmăriți] docker compose up -d. Păstrați același director de date, volum al bazei de date, nume de server și cheie de semnare.

În configurația ilustrativă a grupului de voluntari, instalarea este finalizată numai atunci când endpoint-ul versiunilor locale răspunde, endpoint-ul HTTPS răspunde prin proxy și administratorul se poate conecta utilizând domeniul Matrix ID dorit. Aceste verificări sunt indicatori practici ai unei prime implementări funcționale; ele nu înlocuiesc revizuirea cerințelor de securitate, copii de rezervă, federație și operaționale înainte de a invita o comunitate mai largă.

Referințe oficiale

• Instrucțiuni de instalare Synapse și îndrumări privind numele serverului
• Imagine oficială Synapse Docker README
• Referință de configurare a sinapselor
• Ghidare pentru proxy invers sinapsă
• Instalarea motorului Docker
• Ordinea de pornire și verificările de sănătate ale Docker Compose