Cum se configurează un server matricial pe Raspberry Pi 4 cu Conduit

Un Raspberry Pi 4 poate fi folosit ca un server de acasă Matrix de dimensiuni reduse și practice pentru o gospodărie, un grup privat sau un laborator, iar Conduit este conceput având în vedere hardware-ul ușor. Matrix este un protocol deschis pentru comunicarea descentralizată: utilizatorii se conectează la un server de acasă , care le stochează conturile și datele camerei, în timp ce federația permite serverului de acasă să facă schimb de evenimente cu alte servere Matrix.

Acest ghid folosește Conduit în Docker, cu NGINX în față pentru HTTPS. Aceasta menține serviciul Matrix izolat pe Pi, expunând doar porturile web publice. Instrucțiunile au fost verificate în raport cu documentația Conduit, Matrix, Raspberry Pi, Docker și NGINX disponibilă în octombrie 2026. O limitare importantă este prima: Conduit se descrie încă ca fiind beta , deci este cel mai potrivit pentru utilizatorii care acceptă că unele caracteristici Matrix și versiuni mai vechi de cameră pot să nu funcționeze exact așa cum o fac pe o implementare Synapse matură. Verificați proiectul oficial Conduit înainte de a-l utiliza pentru un serviciu critic.

1. Înțelegeți configurarea înainte de a instala orice

Calea finală este simplă: un client Matrix, cum ar fi Element, se conectează la https://matrix.example.com; NGINX termină TLS și transmite cererea către Conduit pe Pi; Conduit își stochează baza de date într-un spațiu de stocare persistent Docker. Dacă federația este activată, alte servere de acasă ajung la același punct final public HTTPS.

Veți avea nevoie de un Raspberry Pi 4, o sursă de alimentare fiabilă, un card microSD sau SSD și un sistem de operare pe 64 de biți. Un SSD este preferabil pentru un server pe care intenționați să îl păstrați mult timp, deoarece Matrix scrie continuu date din baza de date și media. De asemenea, veți avea nevoie de un nume de domeniu dacă serverul trebuie să fie accesibil de pe internetul public.

Începând cu 15 septembrie 2026, versiunea actuală a Raspberry Pi OS pe 64 de biți se bazează pe Debian 13 „Trixie”, iar Raspberry Pi OS Lite este disponibil pentru Pi 4. Consultați pagina oficială de descărcare a Raspberry Pi OS . Pentru acest server, Lite este o alegere bună, deoarece evită un mediu desktop inutil.

Alegeți cu atenție numele serverului Matrix

În acest ghid, numele serverului este matrix.example.com. Un ID de utilizator Matrix rezultat arată astfel @alice:matrix.example.com. Tratați acest nume ca o alegere de identitate pe termen lung. ID-urile Matrix și referințele de federație includ numele serverului, deci schimbarea ulterioară a acestuia nu este echivalentă cu simpla redenumire a unei gazde web.

2. Instalați sistemul de operare Raspberry Pi și actualizați Pi-ul

Scrieți versiunea Raspberry Pi OS Lite pe 64 de biți pe placă sau SSD cu Raspberry Pi Imager, activați SSH în timpul imagisticii dacă doriți o instalare headless și porniți Pi. Confirmați că sunteți pe un sistem ARM pe 64 de biți:

uname -m
cat /etc/os-release

uname -mar trebui să raporteze în mod normal aarch64. Apoi instalați actualizările curente:

sudo apt update
sudo apt full-upgrade -y
sudo reboot

3. Instalați motorul Docker și Compose

Documentația Docker precizează că utilizatorii sistemului de operare Raspberry Pi pe 64 de biți ar trebui să utilizeze pachetele Debian ARM64 acceptate, în loc de calea mai veche pe 32 de biți a sistemului de operare Raspberry Pi. Procedura autoritativă se află pe pagina Docker Engine pentru Debian . Următoarea configurare a repozitoriului respectă această abordare:

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg   -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io   docker-buildx-plugin docker-compose-plugin

sudo docker run --rm hello-world

Dacă comanda finală afișează confirmarea hello-world a lui Docker, runtime-ul containerului funcționează. Puteți continua să utilizați comanda sudo dockerpentru restul ghidului. Adăugarea contului dvs. la dockergrup este opțională, dar rețineți că apartenența la grupul Docker oferă efectiv control la nivel de root asupra gazdei.

4. Creați o configurație Conduit

Conduit poate fi configurat cu un fișier TOML sau cu variabile de mediu. Referința oficială de configurare Conduit listează server_name, database_backend, și database_pathca câmpuri obligatorii și recomandă RocksDB.

Creați un director de lucru:

sudo mkdir -p /opt/conduit
sudo chown "$USER":"$USER" /opt/conduit
cd /opt/conduit
nano conduit.toml

Folosește această configurație inițială și înlocuiește numele de gazdă și token-ul de înregistrare:

[global]
server_name = "matrix.example.com"
database_backend = "rocksdb"
database_path = "/var/lib/matrix-conduit/"
address = "0.0.0.0"
port = 6167

allow_registration = true
registration_token = "replace-with-a-long-random-secret"
allow_federation = true
trusted_servers = ["matrix.org"]

De ce 0.0.0.0aici? În interiorul unui container, Conduit trebuie să asculte interfața containerului pentru ca Docker să îl poată accesa. Portul de pe partea gazdă va fi în continuare legat doar la 127.0.0.1, deci portul 6167 nu este expus direct la internet.

5. Rulați Conduit cu Docker Compose

Creați /opt/conduit/docker-compose.yml:

services:
  conduit:
    image: registry.gitlab.com/famedly/conduit/matrix-conduit:latest
    container_name: matrix-conduit
    restart: unless-stopped
    ports:
      - "127.0.0.1:6167:6167"
    volumes:
      - ./conduit.toml:/etc/conduit.toml:ro
      - conduit-data:/var/lib/matrix-conduit/
    environment:
      CONDUIT_CONFIG: /etc/conduit.toml

volumes:
  conduit-data:

Imaginea stabilă a registrului GitLab este imaginea recomandată de documentația oficială Conduit Docker . Evitați copierea unei etichete de imagine veche dintr-un tutorial aleatoriu; utilizați registrul oficial și consultați notele de lansare înainte de actualizări.

Porniți serviciul și verificați-l:

cd /opt/conduit
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=100 conduit

Doriți ca containerul să rămână într-o Upstare de funcționare sau în stare de funcționare, fără bucle de repornire repetate. Înainte de a configura NGINX, verificați API-ul local:

curl http://127.0.0.1:6167/_matrix/client/versions

6. Îndreptați DNS-ul către Pi și puneți NGINX în fața Conduit-ului

Creați o Aînregistrare care să matrix.example.comindice către adresa dvs. publică IPv4. Dacă publicați o AAAAînregistrare, asigurați-vă că IPv6 ajunge efectiv la Pi; o înregistrare IPv6 spartă poate face ca clienții să eșueze chiar și atunci când IPv4 funcționează.

Pe un router obișnuit de acasă, redirecționați porturile TCP 80 și 443 către Raspberry Pi. Dacă furnizorul dvs. de servicii de internet utilizează NAT de nivel operator (CGNAT), redirecționarea porturilor de intrare obișnuite s-ar putea să nu funcționeze; în acest caz, aveți nevoie de o adresă publică, un design VPS/tunel invers sau un alt aranjament de găzduire.

Instalați NGINX:

sudo apt install -y nginx

Creați /etc/nginx/sites-available/matrix:

server {
    listen 80;
    server_name matrix.example.com;

    client_max_body_size 20M;

    location / {
        proxy_pass http://127.0.0.1:6167;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Documentele oficiale de ghid pentru reverse proxy ale NGINX proxy_passși anteturile redirecționate utilizate aici.

sudo ln -s /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/matrix
sudo nginx -t
sudo systemctl reload nginx

7. Activați HTTPS și descoperirea prin matrice

Matrix necesită HTTPS valid pentru o implementare publică normală. Obțineți un certificat numai după ce DNS se rezolvă la Pi și portul 80 este accesibil. Debian Trixie oferă pachete Certbot, în timp ce proiectul Certbot publică, de asemenea, instrucțiuni specifice platformei la certbot.eff.org .

O rută comună Debian/NGINX este:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d matrix.example.com

După ce Certbot actualizează gazda virtuală NGINX, testați din nou configurația:

sudo nginx -t
sudo systemctl reload nginx

Deoarece acest ghid folosește același nume de gazdă pentru numele serverului Matrix și endpoint-ul public, Conduit poate răspunde la /.well-knowncăile de descoperire Matrix prin proxy-ul invers. Specificația Matrix definește aceste endpoint-uri, astfel încât clienții și alte servere să poată descoperi adresa URL corectă a serverului de domiciliu. Consultați specificația Matrix Client-Server .

8. Creați primul cont, apoi verificați serverul

Documentația Docker a Conduit spune că primul cont creat pe un nou server de acasă devine administrator. Deschideți un client Matrix care acceptă token-uri de înregistrare, alegeți un server de acasă personalizat și introduceți:

https://matrix.example.com

Înregistrați primul cont folosind token-ul de la conduit.toml. Faceți acest lucru la scurt timp după ce puneți serviciul online. Dacă nu doriți alte înregistrări, editați configurația pentru a seta allow_registration = falseși reporniți containerul:

cd /opt/conduit
sudo docker compose restart conduit

Acum executați trei verificări de pe orice mașină care poate ajunge la domeniu:

curl https://matrix.example.com/_matrix/client/versions

curl https://matrix.example.com/.well-known/matrix/client

curl https://matrix.example.com/.well-known/matrix/server

Prima solicitare ar trebui să returneze un JSON care să descrie versiunile API client Matrix acceptate. Solicitările cunoscute ar trebui să returneze informații valide de descoperire JSON. Pentru federație, utilizați și Matrix Federation Tester și încercați să vă alăturați unei camere federate din noul cont.

Greșeli frecvente care împiedică funcționarea unui server Raspberry Pi Matrix

• Utilizarea inutilă a unui sistem de operare pe 32 de biți: pentru un Pi 4, utilizați sistemul de operare Raspberry Pi pe 64 de biți și pachetele Debian ARM64 acceptate de Docker.
• Expunerea directă a Conduit-ului: păstrați portul 6167 legat 127.0.0.1la gazdă și expuneți HTTPS prin NGINX.
• Lăsarea înregistrării deschise fără protecție: utilizați un token de înregistrare puternic în timpul configurării inițiale, apoi dezactivați înregistrarea dacă nu aveți nevoie de ea.
• Publicarea unui DNS incorect: atât înregistrările IPv4, cât și cele IPv6 trebuie să ducă la un punct final funcțional dacă le publicați pe amândouă.
• Uitarea regulilor routerului sau firewall-ului: un container corect nu poate compensa blocarea TCP 80/443 de intrare.
• Presupunând că mesageria și apelurile vocale sunt identice: mesageria matricială poate funcționa chiar și în timp ce apelurile eșuează. Documentația Conduit precizează că comunicarea vocală necesită un server TURN, cum ar fi Coturn.
• Omiterea copiilor de rezervă: Întrebările frecvente despre Conduit recomandă oprirea Conduit înainte de a face o copie normală a bazei de date a sistemului de fișiere, cu excepția cazului în care utilizați o instantanee adecvată a sistemului de fișiere. Faceți o copie de rezervă a volumului Docker și a configurației înainte de actualizări.

Cum arată o instalare reușită

Ați terminat când toate acestea sunt adevărate: containerul Conduit rămâne în funcțiune după o repornire; https://matrix.example.com/_matrix/client/versionsreturnează JSON; un client Matrix se poate înregistra sau conecta la serverul dvs. de domiciliu personalizat; contul poate crea o cameră și poate trimite un mesaj; și, dacă federația este activată, testerul de federație poate ajunge la server, iar utilizatorul poate comunica cu conturi de pe un alt server de domiciliu.

Pentru o implementare Raspberry Pi de dimensiuni reduse, aceasta este o bază curată, nu sfârșitul administrării. Monitorizați spațiul de stocare liber, mențineți actualizate Raspberry Pi OS și Docker, faceți copii de rezervă ale bazei de date și citiți documentația oficială Conduit înainte de a activa funcții suplimentare. Conduit rămâne o opțiune ușoară și atractivă pentru hardware-ul din clasa Pi, dar statutul său beta este o considerație operațională reală, mai degrabă decât o obiecție.