Jak skonfigurować serwer Matrix na Raspberry Pi 4 za pomocą Conduit

Raspberry Pi 4 może służyć jako praktyczny, mały serwer domowy Matrix dla gospodarstwa domowego, grupy osób prywatnych lub laboratorium, a Conduit został zaprojektowany z myślą o lekkim sprzęcie. Matrix to otwarty protokół do zdecentralizowanej komunikacji: użytkownicy łączą się z serwerem domowym , który przechowuje ich konta i dane dotyczące pomieszczeń, a federacja umożliwia wymianę zdarzeń między serwerem domowym a innymi serwerami Matrix.

W tym przewodniku wykorzystano Conduit w Dockerze, z NGINX dla HTTPS. Dzięki temu usługa Matrix jest izolowana na Raspberry Pi, a jednocześnie udostępniane są tylko publiczne porty internetowe. Instrukcje zostały sprawdzone pod kątem dokumentacji Conduit, Matrix, Raspberry Pi, Dockera i NGINX, która będzie dostępna w październiku 2026 roku. Na pierwszy plan wysuwa się jedno ważne ograniczenie: Conduit nadal określa się jako beta , więc najlepiej nadaje się dla użytkowników, którzy akceptują fakt, że niektóre funkcje Matrix i starsze wersje pokojów mogą nie działać dokładnie tak samo, jak w dojrzałym wdrożeniu Synapse. Przed użyciem Conduit w krytycznej usłudze należy sprawdzić oficjalny projekt Conduit .

1. Przed zainstalowaniem czegokolwiek zapoznaj się z konfiguracją

Gotowa ścieżka jest prosta: klient Matrix, taki jak Element, łączy się z https://matrix.example.com; NGINX kończy TLS i przekazuje żądanie do Conduit na Raspberry Pi; Conduit przechowuje swoją bazę danych w trwałej pamięci masowej Docker. Jeśli federacja jest włączona, inne serwery domowe docierają do tego samego publicznego punktu końcowego HTTPS.

Będziesz potrzebować Raspberry Pi 4, niezawodnego zasilacza, karty microSD lub dysku SSD oraz 64-bitowego systemu operacyjnego. Dysk SSD będzie lepszy w przypadku serwera, który będzie używany przez długi czas, ponieważ Matrix stale zapisuje dane z bazy danych i multimediów. Będziesz również potrzebować nazwy domeny, jeśli serwer ma być dostępny z publicznego internetu.

Od 15 września 2026 roku aktualna wersja 64-bitowego systemu operacyjnego Raspberry Pi OS jest oparta na Debianie 13 „Trixie”, a system Raspberry Pi OS Lite jest dostępny dla Raspberry Pi 4. Zobacz oficjalną stronę pobierania systemu Raspberry Pi OS . Wersja Lite jest dobrym wyborem dla tego serwera, ponieważ eliminuje niepotrzebne środowisko graficzne.

Wybierz ostrożnie nazwę serwera Matrix

W tym przewodniku nazwa serwera to matrix.example.com. Wynikowy identyfikator użytkownika Matrix wygląda następująco @alice:matrix.example.com. Traktuj tę nazwę jako długoterminowy wybór tożsamości. Identyfikatory Matrix i odwołania do federacji zawierają nazwę serwera, więc jej późniejsza zmiana nie jest równoznaczna ze zmianą nazwy hosta internetowego.

2. Zainstaluj system operacyjny Raspberry Pi i zaktualizuj Raspberry Pi

Zapisz system operacyjny Raspberry Pi OS Lite 64-bit na karcie lub dysku SSD za pomocą Raspberry Pi Imager, włącz SSH podczas tworzenia obrazu, jeśli chcesz przeprowadzić instalację bez monitora, i uruchom Raspberry Pi. Upewnij się, że korzystasz z 64-bitowego systemu ARM:

uname -m
cat /etc/os-release

uname -mPowinien normalnie zgłosić aarch64. Następnie zainstaluj bieżące aktualizacje:

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

3. Zainstaluj Docker Engine i Compose

Dokumentacja Dockera mówi, że użytkownicy 64-bitowego systemu Raspberry Pi OS powinni korzystać z obsługiwanych pakietów Debian ARM64, a nie ze starszej ścieżki 32-bitowego systemu Raspberry Pi OS. Autorytatywna procedura znajduje się na stronie Docker Engine dla Debiana . Poniższa konfiguracja repozytorium opiera się na tym podejściu:

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

Jeśli ostatnie polecenie wyświetli potwierdzenie „hello-world” Dockera, środowisko wykonawcze kontenera działa. Możesz kontynuować korzystanie z niego, aby zapoznać się sudo dockerz dalszą częścią tego przewodnika. Dodanie konta do dockergrupy jest opcjonalne, ale pamiętaj, że członkostwo w grupie Dockera skutecznie przyznaje kontrolę nad hostem na poziomie roota.

4. Utwórz konfigurację Conduit

Conduit można skonfigurować za pomocą pliku TOML lub zmiennych środowiskowych. Oficjalny podręcznik konfiguracji Conduit wymienia pola server_name, database_backend, i database_pathjako pola wymagane i zaleca RocksDB.

Utwórz katalog roboczy:

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

Użyj tej konfiguracji początkowej i zastąp nazwę hosta oraz token rejestracyjny:

[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"]

Dlaczego 0.0.0.0w tym przypadku? Wewnątrz kontenera Conduit musi nasłuchiwać na interfejsie kontenera, aby Docker mógł się z nim połączyć. Port po stronie hosta nadal będzie powiązany tylko z 127.0.0.1, więc port 6167 nie będzie bezpośrednio dostępny w Internecie.

5. Uruchom Conduit z Docker Compose

Tworzyć /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:

Stabilny obraz GitLab Registry to obraz zalecany przez oficjalną dokumentację Conduit Docker . Unikaj kopiowania starego tagu obrazu z przypadkowego samouczka; korzystaj z oficjalnego rejestru i zapoznaj się z informacjami o wydaniu przed aktualizacją.

Uruchom usługę i sprawdź ją:

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

Chcesz, aby kontener pozostawał w Upstanie „lub” bez powtarzających się pętli restartu. Przed skonfigurowaniem NGINX zweryfikuj lokalne API:

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

6. Skieruj DNS do Raspberry Pi i umieść NGINX przed Conduit

Utwórz Arekord matrix.example.comwskazujący na Twój publiczny adres IPv4. Jeśli publikujesz AAAArekord, upewnij się, że IPv6 faktycznie dociera do Raspberry Pi. Uszkodzony rekord IPv6 może spowodować awarię klientów, nawet gdy IPv4 działa.

Na typowym routerze domowym przekieruj porty TCP 80 i 443 do Raspberry Pi. Jeśli Twój dostawca usług internetowych korzysta z NAT klasy operatorskiej (CGNAT), zwykłe przekierowywanie portów przychodzących może nie działać; w takim przypadku potrzebujesz adresu publicznego, VPS/odwrotnego tunelu lub innego rozwiązania hostingowego.

Zainstaluj NGINX:

sudo apt install -y nginx

Tworzyć /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;
    }
}

Oficjalne dokumenty podręcznika dotyczącego odwrotnego serwera proxy NGINX proxy_passi przekazane nagłówki używane w tym miejscu.

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

7. Włącz HTTPS i wykrywanie macierzy

Matrix wymaga prawidłowego protokołu HTTPS do standardowego wdrożenia publicznego. Certyfikat należy uzyskać dopiero po rozwiązaniu DNS na Raspberry Pi i osiągnięciu portu 80. Debian Trixie udostępnia pakiety Certbot, a projekt Certbot publikuje również aktualne instrukcje dla poszczególnych platform na stronie certbot.eff.org .

Typowa ścieżka dla Debian/NGINX wygląda następująco:

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

Po zaktualizowaniu wirtualnego hosta NGINX przez Certbot należy ponownie przetestować konfigurację:

sudo nginx -t
sudo systemctl reload nginx

Ponieważ ten przewodnik używa tej samej nazwy hosta dla nazwy serwera Matrix i publicznego punktu końcowego, Conduit może odpowiadać na /.well-knownścieżki wykrywania Matrix poprzez odwrotny serwer proxy. Specyfikacja Matrix definiuje te punkty końcowe, aby klienci i inne serwery mogły znaleźć prawidłowy adres URL serwera domowego. Zobacz specyfikację klienta-serwera Matrix .

8. Utwórz pierwsze konto, a następnie zweryfikuj serwer

Dokumentacja Conduit Dockera podaje, że pierwsze konto utworzone na nowym serwerze domowym staje się kontem administratora. Otwórz klienta Matrix obsługującego tokeny rejestracyjne, wybierz niestandardowy serwer domowy i wprowadź:

https://matrix.example.com

Zarejestruj pierwsze konto za pomocą tokena z conduit.toml. Zrób to wkrótce po uruchomieniu usługi. Jeśli nie chcesz dalszych rejestracji, edytuj konfigurację, aby ją ustawić allow_registration = falsei ponownie uruchomić kontener:

cd /opt/conduit
sudo docker compose restart conduit

Teraz uruchom trzy sprawdzenia na dowolnym komputerze, który ma dostęp do domeny:

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

Pierwsze żądanie powinno zwrócić JSON opisujący obsługiwane wersje API klienta Matrix. Znane żądania powinny zwracać prawidłowe informacje o odkryciu JSON. W przypadku federacji należy również użyć narzędzia Matrix Federation Tester i spróbować dołączyć do pokoju federacyjnego z nowego konta.

Typowe błędy uniemożliwiające działanie serwera Raspberry Pi Matrix

• Korzystanie z 32-bitowego systemu operacyjnego bez potrzeby: w przypadku Raspberry Pi 4 należy użyć 64-bitowego systemu operacyjnego Raspberry Pi oraz pakietów Debian ARM64 obsługiwanych przez Dockera.
• Bezpośrednie udostępnianie Conduit: utrzymanie portu 6167 powiązanego 127.0.0.1z hostem i udostępnianie protokołu HTTPS przez NGINX.
• Pozostawienie rejestracji otwartej bez zabezpieczenia: podczas początkowej konfiguracji użyj silnego tokena rejestracyjnego, a następnie wyłącz rejestrację, jeśli jej nie potrzebujesz.
• Publikowanie nieprawidłowych rekordów DNS: jeśli publikujesz oba, zarówno rekordy IPv4, jak i IPv6 muszą prowadzić do działającego punktu końcowego.
• Zapomnienie reguł routera lub zapory sieciowej: poprawny kontener nie jest w stanie zrekompensować zablokowanego ruchu przychodzącego TCP 80/443.
• Zakładając, że wiadomości i połączenia głosowe są takie same: wiadomości Matrix mogą działać, nawet gdy połączenia się nie powiodą. Dokumentacja Conduit stwierdza, że ​​komunikacja głosowa wymaga serwera TURN, takiego jak Coturn.
• Pomijanie kopii zapasowych: FAQ Conduit zaleca zatrzymanie Conduit przed wykonaniem normalnej kopii systemu plików jego bazy danych, chyba że używasz odpowiedniej migawki systemu plików. Przed uaktualnieniem wykonaj kopię zapasową woluminu Docker i konfiguracji.

Jak wygląda udana instalacja

Zakończysz, gdy wszystkie poniższe warunki zostaną spełnione: kontener Conduit pozostanie uruchomiony po ponownym uruchomieniu, https://matrix.example.com/_matrix/client/versionszwraca JSON, klient Matrix będzie mógł zarejestrować się lub zalogować na Twoim niestandardowym serwerze domowym, konto będzie mogło utworzyć pokój i wysłać wiadomość, a jeśli federacja jest włączona, tester federacji będzie mógł połączyć się z serwerem, a użytkownik będzie mógł komunikować się z kontami na innym serwerze domowym.

W przypadku małego wdrożenia Raspberry Pi stanowi to czystą bazę, a nie koniec administracji. Monitoruj dostępną przestrzeń dyskową, dbaj o poprawność systemu operacyjnego Raspberry Pi i Dockera, twórz kopię zapasową bazy danych i zapoznaj się z oficjalną dokumentacją Conduit przed włączeniem dodatkowych funkcji. Conduit pozostaje lekką i atrakcyjną opcją dla sprzętu klasy Pi, ale jego status beta jest realnym czynnikiem operacyjnym, a nie przypisem.