Wenn Matrix Synapse auf CasaOS „container is unhealthy“ anzeigt, prüfe zuerst die Container-Logs und die generierte homeserver.yaml, statt blind neu zu installieren. Synapse verfügt über ein offizielles Docker-Image, aber ein produktiver Homeserver benötigt außerdem eine dauerhaft gespeicherte Konfiguration und Daten, einen korrekten Servernamen, PostgreSQL sowie eine Planung für HTTPS und Föderation.
SQLite eignet sich für Tests, aber die aktuelle Synapse-Dokumentation empfiehlt PostgreSQL für fast alle echten Installationen. Ein Container kann starten und dennoch als fehlerhaft angezeigt werden, wenn die Konfiguration, Datenbank, Berechtigungen oder Startmigration Probleme bereiten.
Das offizielle Synapse-Image verwenden
Der aktuelle Synapse-Installationsleitfaden nennt ghcr.io/element-hq/synapse als offizielles Container-Image.
Erste Konfiguration erstellen
Erstelle ein dauerhaftes Verzeichnis und generiere die Konfiguration einmalig, bevor du den normalen Start ausführst:
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 generateErsetze die Beispieldomain durch den Matrix-Servernamen, den du dauerhaft verwenden möchtest.
Prüfen, warum der Container als fehlerhaft angezeigt wird
docker ps -a | grep synapse
docker inspect synapse --format '{{json .State.Health}}'
docker logs --tail 200 synapseAchte auf YAML-Fehler, fehlende Dateien, Berechtigungsprobleme, Datenbankverbindungsfehler oder Migrationen, die nie abgeschlossen werden.
PostgreSQL für den Produktivbetrieb verwenden
Der aktuelle Synapse-Leitfaden für PostgreSQL erläutert die unterstützte Datenbankeinrichtung. Sorge dafür, dass die Postgres-Daten dauerhaft gespeichert werden, und sichere sie zusammen mit dem Synapse-Status.
Servernamen später nicht ohne Planung ändern
Deine Matrix-IDs werden vom Servernamen abgeleitet, zum Beispiel @user:example.com. Lege die langfristig verwendete Domain fest, bevor du Nutzer einlädst.
HTTPS ist für die praktische Nutzung erforderlich
Synapse lauscht intern normalerweise über HTTP (üblicherweise auf Port 8008). Verwende für Clients und Föderation einen Reverse-Proxy mit HTTPS, statt den unveränderten Container-Port öffentlich zugänglich zu machen.
Föderation bringt zusätzliche Anforderungen an DNS und Proxy mit sich
Wenn du mit anderen Matrix-Servern kommunizieren möchtest, konfiguriere den öffentlichen Servernamen, HTTPS und die Föderationssuche korrekt. Ein rein lokaler Test kann deutlich einfacher sein.
Sichere mehr als nur den Container
Sichere homeserver.yaml, Signaturschlüssel, hochgeladene Medien und die PostgreSQL-Datenbank. Ein erneutes Herunterladen des Images stellt die Homeserver-Identität nicht wieder her.
Der Docker-Leitfaden zur Fehlerbehebung erläutert das allgemeine Modell für die Container-Fehlerbehebung.
Prüfe die Dateieigentümerschaft des persistenten Datenordners
Meldet das Containerprotokoll beim Lesen von homeserver.yaml, Signaturschlüsseln oder Medien einen Berechtigungsfehler, korrigiere die Eigentümerzuordnung des eingebundenen Synapse-Datenverzeichnisses entsprechend der vom Image erwarteten UID/GID. Vermeide es, den gesamten CasaOS-Datenbaum für alle Benutzer beschreibbar zu machen.
Warte Datenbankmigrationen ab, bevor du den Gesundheitsstatus beurteilst
Nach einem Upgrade oder der ersten PostgreSQL-Verbindung benötigt Synapse möglicherweise Zeit, um Schema-Migrationen auszuführen. Beobachte die Protokolle, statt den Container wiederholt neu zu starten, da unterbrochene Migrationen die Diagnose erschweren können.
Zuerst die lokale API testen, dann den Reverse-Proxy
Prüfe, ob der interne Synapse-HTTP-Endpunkt vom CasaOS-Host aus erreichbar ist, bevor du HTTPS, DNS oder Föderation einrichtest. Ist die lokale API nicht fehlerfrei, kann ein Reverse-Proxy das nicht beheben.
FAQ
Warum ist Synapse nicht fehlerfrei?
Prüfe Protokolle und Health-Ausgabe auf Konfigurations-, Berechtigungs-, Datenbank- oder Migrationsfehler. Im Ausgangsthread wurde keine einzelne, verifizierte Ursache genannt.
Kann ich SQLite verwenden?
Zum Testen ja. Die aktuelle Synapse-Dokumentation empfiehlt PostgreSQL für fast alle Produktivinstallationen.
Welchen Port verwendet Synapse intern?
Bei gängigen Docker-Setups ist die Client-/Server-API hinter einem Reverse-Proxy über Port 8008 erreichbar.
Brauche ich Element?
Nein. Synapse ist der Homeserver; Element ist ein möglicher Client bzw. ein Web-Frontend.
