Wie man eine Matrix Synapse PostgreSQL-Datenbank sichert und wiederherstellt

Eine zuverlässige Synapse-Wiederherstellung beginnt mit einem lesbaren PostgreSQL-Dump, einer leeren Zieldatenbank und den zugehörigen Homeserver-Dateien. Für eine typische Einzeldatenbankinstallation empfiehlt Synapses Backup-Anleitung das benutzerdefinierte PostgreSQL-Dump-Format und schließt den Inhalt von `/etc/postgresql` aus e2e_one_time_keys_json. Stellen Sie die Daten in einer neu erstellten, leeren Datenbank wieder her; überschreiben Sie keine Tabellen, die von einer früheren Installation vorhanden waren. Überprüfen Sie anschließend, ob Synapse mit der wiederhergestellten Datenbank startet und ob lokale Medien und Signaturschlüssel vorhanden sind.

Diese Anleitung setzt einen Linux-Host, eine PostgreSQL-Datenbank namens `<Datenbankname>` synapseund eine Datenbankrolle namens `<Datenbankrolle>` voraus synapse_user. Ersetzen Sie `<Datenbankname>`, `<Rolle>`, `Backup-Pfad`, `Servicename` und `Konfigurationspfad` durch die in Ihrer Umgebung verwendeten Angaben. Für Docker Compose, Kubernetes, verwaltete PostgreSQL-Datenbanken und Synapse-Bereitstellungen mit mehreren Datenbanken benötigen Sie entsprechende Befehle.

Was ein Datenbank-Dump schützt – und was nicht.

pg_dumpEs wird eine PostgreSQL-Datenbank in einem konsistenten Snapshot erfasst, sodass PostgreSQL und Synapse während des Dump-Vorgangs online bleiben können. Ein Archiv im benutzerdefinierten Format ( -Fc) kann mit untersucht und wiederhergestellt werden pg_restore. Die Synapse-Anleitung empfiehlt ausdrücklich, Daten von Tabellen mit Einmalschlüsseln auszuschließen: Die Wiederherstellung älterer, verwendeter Schlüssel kann dazu führen, dass Clients die Schlüssel erneut erhalten und Nachrichten entschlüsselt werden müssen. Die Tabellendefinition kann weiterhin im Archiv enthalten sein. Suchen Sie beim Überprüfen der Archivliste nach Tabellendateneinträgen und gehen Sie nicht davon aus, dass eine aufgeführte Tabelle Zeilen enthält.

Ein Datenbank-Dump allein reicht für eine vollständige Homeserver-Sicherung nicht aus. Bewahren Sie zusätzlich homeserver.yamlalle darin referenzierten Dateien, den Server-Signaturschlüssel und das Medienverzeichnis auf. Synapses Sicherungsleitfaden weist darauf hin, dass lokal hochgeladene Medien wichtig sind, da sich möglicherweise die einzige Kopie auf dem Homeserver befindet. Wenn Ihre Konfiguration mehrere Datenbankeinträge verwendet, erstellen Sie für jede von Synapse genutzte Datenbank einen Dump.

Bevor Sie beginnen

• Bitte überprüfen Sie den konfigurierten Datenbanknamen, Benutzer, Host, Port und ob Synapse eine oder mehrere Datenbanken verwendet.
• Prüfen Sie, ob die PostgreSQL-Client-Dienstprogramme pg_dump, pg_restore, createdbund psqlinstalliert und mit Ihrem PostgreSQL-Server kompatibel sind.
• Wählen Sie ein geschütztes Backup-Ziel mit ausreichend freiem Speicherplatz. Backups können private Nachrichten und Kontodaten enthalten; beschränken Sie daher den Zugriff und verschlüsseln Sie die Backups sowohl im Ruhezustand als auch während der Übertragung.
• Notieren Sie das Synapse-Konfigurationsverzeichnis, den Pfad zum Signaturschlüssel und media_store_path. Sichern Sie Geheimnisse, ohne sie in der Shell-Historie, im Chat oder in Protokollen preiszugeben.
• Entscheiden Sie, wie Sie die Wiederherstellung testen. Eine Testwiederherstellung auf einem isolierten Host oder einer Staging-Datenbank ist ein aussagekräftigerer Beweis als ein erfolgreicher Dump-Befehl allein.

PostgreSQL-Backup erstellen und überprüfen

1. Bestätigen Sie die Zieldatenbank und die Rolle.

Melden Sie sich auf einem selbstverwalteten PostgreSQL-Host als PostgreSQL-Administrator an und überprüfen Sie die Datenbankliste und die Beziehungen. Verwenden Sie dabei nicht einfach einen angenommenen Namen aus einer Beispielkonfiguration. Wenn Ihr Homeserver eine Remote- oder verwaltete Datenbank nutzt, verwenden Sie die dafür vorgesehene Verbindungsmethode und stellen Sie sicher, dass das Dump-Konto über die erforderlichen Leserechte verfügt.

2. Erstellen Sie einen benutzerdefinierten Datenspeicherabbild.

Erstellen Sie ein Verzeichnis, auf das nur das Backup-Konto oder Administratoren Zugriff haben. Das folgende Beispiel wird pg_dumpals lokales PostgreSQL-Betriebssystemkonto ausgeführt und schreibt in einen geschützten Pfad. Ändern Sie den Pfad in einen Pfad, der in Ihrer Umgebung existiert und beschreibbar ist.

sudo -u postgres pg_dump -Fc \
  --exclude-table-data e2e_one_time_keys_json \
  synapse -f /var/backups/synapse/synapse.dump

Bei entfernten Datenbanken verwenden Sie für die Verbindungseinstellungen die in Ihrer Umgebung übliche Methode, z. B. eine geschützte .pgpassDatei oder libpq-Umgebungsvariablen. Geben Sie Passwörter nicht direkt in der Befehlszeile an. Verwenden Sie die Ausschlussoption nur, wenn Sie einen triftigen, dokumentierten Grund haben, die Einmalschlüsseltabelle anders zu behandeln.

3. Überprüfen Sie das Archiv und speichern Sie eine Prüfsumme.

Prüfen Sie, ob die Dump-Datei existiert, einen Wert ungleich null enthält und als PostgreSQL-Archiv lesbar ist. Eine erfolgreiche Auflistung ist ein nützlicher erster Test, beweist aber weder, dass die Wiederherstellung abgeschlossen wird, noch dass der gesamte Homeserver betriebsbereit ist.

sudo -u postgres pg_restore --list /var/backups/synapse/synapse.dump
sha256sum /var/backups/synapse/synapse.dump

Speichern Sie die Prüfsumme neben dem Sicherungsdatensatz und kopieren Sie den Dump anschließend auf ein separates System oder einen Sicherungsdienst. Berechnen Sie die Prüfsumme nach dem Kopieren neu und vergleichen Sie die Werte. Für die Wiederherstellung im Produktivbetrieb sollten Sie regelmäßige Sicherungen planen, mehrere Generationen aufbewahren, diese verschlüsseln und regelmäßig Wiederherstellungsübungen durchführen.

Wiederherstellung in einer sauberen Datenbank

4. Synapse stoppen und ein leeres Ziel vorbereiten.

Für eine Wiederherstellung muss Synapse zuerst gestoppt werden, damit keine Verbindung hergestellt werden kann, während die Datenbank ersetzt oder getestet wird. Der unten stehende Dienstname ist bei einigen Paketinstallationen üblich, kann aber variieren. Docker-Benutzer sollten den Synapse-Dienst über ihr Compose-Projekt stoppen, und orchestrierte Bereitstellungen sollten ihr normales Wartungsverfahren verwenden. PostgreSQL selbst muss nicht gestoppt werden.

Verwenden Sie für die Wiederherstellung eine neue, leere Datenbank. Stellen Sie keine bestehende Synapse-Datenbank oder eine Datenbank mit bereits vorhandenen Tabellen wieder her. Wenn Sie die aktuelle Datenbank für ein Rollback benötigen, lassen Sie sie unverändert und stellen Sie die Datenbank unter einem temporären Datenbanknamen wieder her. Überprüfen Sie die Datenbank anschließend, bevor Sie die Synapse-Konfiguration ändern.

sudo -u postgres createdb \
  --encoding=UTF8 --locale=C --template=template0 \
  --owner=synapse_user synapse

Der Datenbankbesitzer und das Gebietsschema müssen den Anforderungen Ihrer Synapse-Konfiguration entsprechen. Falls der Zielname bereits existiert, prüfen Sie, welche Datenbank Sie verwenden möchten; gehen Sie nicht davon aus, dass das Löschen der Datenbank unbedenklich ist. Erstellen Sie zunächst alle erforderlichen PostgreSQL-Rollen. Eine einzelne Datenbank pg_dumpumfasst keine clusterweiten Rollen. Daher benötigt ein Administrator, der zu einem neuen PostgreSQL-Cluster wechselt, möglicherweise auch eine separat geschützte Sicherung der globalen Variablen pg_dumpall --globals-only.

5. Archiv wiederherstellen und Einmalschlüssel verwalten

Laden Sie das benutzerdefinierte Archiv in das leere Zielverzeichnis. Die Option „Explizite Fehlerbehandlung“ bewirkt, dass die Wiederherstellung bei einem Fehler abgebrochen wird, anstatt fortzufahren und ein unvollständiges Ergebnis zu hinterlassen, das leicht übersehen werden kann.

sudo -u postgres pg_restore --exit-on-error \
  --dbname=synapse /var/backups/synapse/synapse.dump

Falls Ihr Backup die Tabelle nicht ausschloss e2e_one_time_keys_json, stellen Sie eine Verbindung zur wiederhergestellten Datenbank her und leeren Sie diese Tabelle, bevor Sie Synapse starten. Dies ist die von Synapse dokumentierte Sicherheitsmaßnahme für Backups, die diese Zeilen enthalten. Führen Sie diesen Befehl nicht ohne Weiteres auf einer aktiven Datenbank aus: Er löscht alle Zeilen in dieser Tabelle.

sudo -u postgres psql -d synapse \
  -c 'TRUNCATE e2e_one_time_keys_json;'

Wenn Sie den empfohlenen Ausschluss verwendet haben, enthält die Wiederherstellung keine alten Einmalschlüsselzeilen mehr, und dieser Kürzungsschritt ist überflüssig. Ein Tabelleneintrag pg_restore --listkann eine Tabellendefinition ohne die zugehörigen Daten darstellen. Prüfen Sie TABLE DATAbeim Durchsehen der Archivinhalte auf solche Einträge; der sicherste Betriebsdatensatz ist der exakt verwendete Dump-Befehl.

Synapse wiederherstellen und die Wiederherstellung überprüfen.

6. Begleitdateien wiederherstellen und Synapse starten

Stellen Sie vor dem Neustart sicher, dass die wiederhergestellte Konfiguration auf die vorgesehene Datenbank verweist und der erwartete Signaturschlüssel sowie der Medienspeicher für den Synapse-Prozess verfügbar sind. Wenn Sie die Wiederherstellung unter einem temporären Datenbanknamen durchgeführt haben, aktualisieren Sie die Datenbankeinstellungen sicher, validieren Sie die Datei und aktivieren Sie sie anschließend mit Ihrem üblichen Bereitstellungsprozess. Bewahren Sie die alte Datenbank und die vorherige Konfiguration so lange auf, bis die neue Instanz die Prüfungen bestanden hat.

Starten Sie den Dienst mit dem für Ihre Bereitstellung geeigneten Befehl. Überprüfen Sie auf einem Systemd-Host den Dienststatus und die aktuellen Protokolle. Überprüfen Sie in Containern den Containerzustand und die Protokolle. Ein laufender Prozess ist ein erstes Signal, aber kein Beweis dafür, dass Benutzer Räume lesen, Nachrichten senden oder Anhänge abrufen können.

7. Testfunktionen, auf die die Benutzer angewiesen sind

• Prüfen Sie, ob Synapse ohne Datenbankmigrations-, Berechtigungs-, Gebietsschema- oder Verbindungsfehler startet.
• Melden Sie sich mit einem Testkonto an und lesen Sie die vorhandenen Räume; senden Sie eine Testnachricht, sofern Ihr Wartungsvertrag dies zulässt.
• Prüfen Sie das Verhalten von Verbunddiensten und Anwendungsdiensten, falls diese Funktionen Teil Ihrer Bereitstellung sind.
• Öffnen Sie einen bekannten, lokal hochgeladenen Anhang oder Avatar, um zu testen, ob der Medienspeicher mit der wiederhergestellten Datenbank übereinstimmt.
• Prüfen Sie nach dem Start die Synapse- und PostgreSQL-Protokolle auf wiederholte Fehler, nicht nur auf den ersten erfolgreichen Integritätscheck.

Eine Wiederherstellung kann technisch erfolgreich sein, auch wenn Mediendateien, referenzierte Konfigurationen oder Rollen fehlen. Falls Benutzer fehlende Anhänge feststellen, überprüfen Sie den konfigurierten Medienspeicher und stellen Sie die entsprechende lokale Mediensicherung wieder her. Kann Synapse keine Verbindung herstellen, vergleichen Sie den wiederhergestellten Datenbankbesitzer, die Anmeldeinformationen, den Host, den Datenbanknamen, das Gebietsschema und die aktive Konfigurationsdatei.

Häufige Fehlersignale und wann die Methode geändert werden sollte

Logische Backups sind portabel und für viele kleine und mittlere Installationen unkompliziert, ihre Wiederherstellung kann jedoch mit zunehmender Datenbankgröße zeitaufwendig sein. Für große oder hochverfügbare Dienste sollten Sie die aktuelle Backup-Dokumentation von PostgreSQL konsultieren und ein getestetes physisches Backup oder eine Wiederherstellung zu einem bestimmten Zeitpunkt planen. Erstellen Sie ein separates logisches Backup, wenn dieses einem separaten Portabilitäts- oder Audit-Zweck dient. Beide Methoden schützen keine Dateien, die außerhalb von PostgreSQL gespeichert sind, es sei denn, diese werden separat gesichert.

Checkliste zur Wiederherstellung

• Der Dump ist lesbar pg_restore --listund seine Prüfsumme stimmt mit der externen Kopie überein.
• Die Wiederherstellung erfolgte in einer neuen, leeren Datenbank mit der erwarteten Kodierung, dem Gebietsschema, dem Eigentümer und den Rollen.
• Einmalige Schlüsselzeilen wurden ausgeschlossen oder die Tabelle wurde vor dem Neustart von Synapse gekürzt.
• Konfigurationsdateien, Signaturschlüssel und die erforderlichen lokalen Medien wurden aus kompatiblen Backups wiederhergestellt.
• Die Synapse-Protokolle sind für den Dienst ausreichend sauber, und die Prüfungen auf Clientebene für Räume und Medien sind erfolgreich.
• Eine Wiederherstellungsübung hat die dokumentierten Wiederherstellungsschritte bestätigt und die tatsächliche Wiederherstellungszeit gemessen.

Offizielle Referenzen

• Synapse-Backup-Leitfaden – datenbankspezifische Hinweise, Umgang mit Einmalschlüsseln, Konfiguration, Signaturschlüssel und Medienspeicher.
• Synapse: Verwendung von PostgreSQL – Datenbankeinrichtung und Konfigurationsdetails.
• PostgreSQL: pg_dump , pg_restore und PostgreSQL-Backup und -Wiederherstellung – Archivierungsoptionen und umfassendere Backup-Strategien.

Die Dokumentation wurde am 6. Oktober 2026 geprüft. Befehlsnamen und Dienstverwaltung variieren je nach Betriebssystem, Container-Image, PostgreSQL-Version und Synapse-Bereitstellung. Vergleichen Sie die Anweisungen mit der Dokumentation für die von Ihnen verwendete Version und Paketierungsmethode.