Wenn Matrix Synapse unter CasaOS „container is unhealthy“ anzeigt, beginnen Sie mit den Containerprotokollen und der generierten homeserver.yaml, statt blind neu zu installieren. Synapse verfügt über ein offizielles Docker-Image, aber ein produktiver Homeserver benötigt außerdem eine persistente Konfiguration und Datenspeicherung, einen passenden Servernamen, PostgreSQL sowie eine Planung für HTTPS und Föderation.
SQLite ist für Tests akzeptabel, aber die aktuelle Synapse-Dokumentation empfiehlt PostgreSQL für fast alle echten Installationen. Ein Container kann zwar starten, aber trotzdem fehlerhaft bleiben, wenn seine Konfiguration, Datenbank oder Berechtigungen nicht stimmen oder eine Startmigration fehlschlägt.
Das offizielle Synapse-Image verwenden
Der aktuelle Synapse-Installationsleitfaden führt ghcr.io/element-hq/synapse als offizielles Container-Image auf.
Die anfängliche Konfiguration generieren
Erstellen Sie ein persistentes Verzeichnis und generieren Sie die Konfiguration einmal vor dem normalen Start:
mkdir -p /DATA/AppData/synapse
docker run --rm -it -v /DATA/AppData/synapse:/data -e SYNAPSE_SERVER_NAME=matrix.example.com -e SYNAPSE_REPORT_STATS=no ghcr.io/element-hq/synapse:latest generateErsetzen Sie die Beispieldomain durch den Matrix-Servernamen, den Sie dauerhaft verwenden möchten.
Prüfen, warum der Container fehlerhaft ist
docker ps -a | grep synapse
docker inspect synapse --format '{{json .State.Health}}'
docker logs --tail 200 synapseAchten Sie auf YAML-Fehler, fehlende Dateien, Berechtigungsfehler, Datenbankverbindungsfehler oder Migrationen, die nicht abgeschlossen werden.
PostgreSQL für den produktiven Betrieb verwenden
Der aktuelle Synapse-Leitfaden für PostgreSQL erläutert die unterstützte Datenbankkonfiguration. Speichern Sie die PostgreSQL-Daten dauerhaft und sichern Sie sie gemeinsam mit dem Synapse-Zustand.
server_name später nicht ohne Planung ändern
Ihre Matrix-IDs werden aus dem Servernamen abgeleitet, zum Beispiel @user:example.com. Legen Sie die langfristig verwendete Domain fest, bevor Sie Benutzer einladen.
HTTPS ist für die praktische Nutzung erforderlich
Synapse lauscht intern normalerweise auf HTTP (häufig auf Port 8008). Verwenden Sie für Clients und Föderation einen Reverse-Proxy mit HTTPS, anstatt den unveränderten Container-Port öffentlich bereitzustellen.
Die Föderation bringt zusätzliche DNS- und Proxy-Anforderungen mit sich
Wenn Sie mit anderen Matrix-Servern kommunizieren möchten, konfigurieren Sie den öffentlichen Servernamen, HTTPS und die Föderationserkennung korrekt. Ein lokaler Test kann deutlich einfacher sein.
Mehr als nur den Container sichern
Bewahren Sie homeserver.yaml, Signaturschlüssel, hochgeladene Medien und die PostgreSQL-Datenbank auf. Das erneute Herunterladen des Images stellt die Identität eines Homeservers nicht wieder her.
Der Docker-Leitfaden zur Fehlerbehebung beschreibt das allgemeine Modell zur Container-Diagnose.
Besitzrechte im persistenten Datenordner prüfen
Wenn das Containerprotokoll beim Lesen von homeserver.yaml, Signaturschlüsseln oder Medien „permission denied“ meldet, korrigieren Sie die Besitzrechte des eingebundenen Synapse-Datenverzeichnisses auf die von dem Image erwartete UID/GID. Vermeiden Sie es, den gesamten CasaOS-Datenbaum für alle Benutzer beschreibbar zu machen.
Vor der Bewertung des Gesundheitsstatus Datenbankmigrationen abwarten
Nach einem Upgrade oder der ersten PostgreSQL-Verbindung benötigt Synapse möglicherweise Zeit für Schema-Migrationen. Beobachten Sie die Protokolle, statt den Container wiederholt neu zu starten, da unterbrochene Migrationen die Diagnose erschweren können.
Die lokale API vor dem Reverse-Proxy testen
Stellen Sie sicher, dass der interne Synapse-HTTP-Endpunkt vom CasaOS-Host aus antwortet, bevor Sie HTTPS, DNS oder Föderation hinzufügen. Wenn die lokale API fehlerhaft ist, kann ein Reverse-Proxy das Problem nicht beheben.
FAQ
Warum ist Synapse fehlerhaft?
Prüfen Sie Protokolle und Gesundheitsstatus auf Konfigurations-, Berechtigungs-, Datenbank- oder Migrationsfehler; der Ausgangsbeitrag nannte keine verifizierte einzelne Ursache.
Kann ich SQLite verwenden?
Für Tests ja. Die aktuelle Synapse-Dokumentation empfiehlt PostgreSQL für fast alle produktiven Installationen.
Welchen Port verwendet Synapse intern?
Übliche Docker-Konfigurationen stellen die Client-/Server-API hinter einem Reverse-Proxy auf Port 8008 bereit.
Benötige ich Element?
Nein. Synapse ist der Homeserver; Element ist ein möglicher Client bzw. ein mögliches Web-Frontend.
