Come eseguire il backup e il ripristino di un database Matrix Synapse PostgreSQL

Un ripristino affidabile di Synapse inizia con un dump di PostgreSQL leggibile, un database di destinazione pulito e i file corrispondenti del server home. Per una tipica installazione a database singolo, la guida di backup di Synapse raccomanda il formato di dump personalizzato di PostgreSQL ed esclude il contenuto di e2e_one_time_keys_json. Ripristinare in un database vuoto appena creato; non sovrapporre un dump alle tabelle lasciate da un'installazione precedente. Quindi verificare che Synapse si avvii con il database ripristinato e che siano presenti i supporti locali e le chiavi di firma.

Questa procedura guidata presuppone un host Linux, un database PostgreSQL denominato synapsee un ruolo di database denominato synapse_user. Sostituisci con il database, il ruolo, il percorso di backup, il nome del servizio e i percorsi di configurazione utilizzati dalla tua implementazione. Le implementazioni Docker Compose, Kubernetes, PostgreSQL gestito e Synapse multi-database richiedono comandi equivalenti per il loro ambiente.

Cosa protegge (e cosa non protegge) un dump del database

pg_dumpcattura un database PostgreSQL in uno snapshot coerente, in modo che PostgreSQL e Synapse possano rimanere online durante l'esecuzione del dump. Un archivio in formato personalizzato ( -Fc) può essere ispezionato e ripristinato con pg_restore. La guida di Synapse raccomanda specificamente di escludere i dati delle tabelle con chiave monouso: il ripristino di chiavi usate più vecchie potrebbe causare la ricezione di nuove chiavi da parte dei client e può portare a errori di decrittazione dei messaggi. La definizione della tabella può comunque apparire nell'archivio; quando si controlla l'elenco dell'archivio, cercare le voci dei dati della tabella anziché presumere che una tabella elencata contenga righe.

Un semplice dump del database non costituisce un backup completo del server domestico. È necessario conservare anche homeserver.yamltutti i file a cui fa riferimento, la chiave di firma del server e la directory di archiviazione dei supporti. La guida al backup di Synapse identifica i supporti caricati localmente come importanti, poiché il server domestico potrebbe contenere l'unica copia. Se la configurazione utilizza più di una voce di database, è consigliabile pianificare un dump per ogni database utilizzato da Synapse.

Prima di iniziare

• Conferma il nome del database configurato, l'utente, l'host, la porta e se Synapse utilizza un singolo database o più database.
• Verifica che le utilità client di PostgreSQL pg_dump, pg_restore, createdb, e psqlsiano installate e compatibili con il tuo server PostgreSQL.
• Scegli una destinazione di backup protetta con spazio libero sufficiente. I dump possono contenere messaggi privati ​​e dati dell'account; limita l'accesso e crittografa i backup sia a riposo che in transito.
• Registra la directory di configurazione di Synapse, il percorso della chiave di firma e media_store_path. Esegui il backup dei segreti senza esporli nella cronologia della shell, nella chat o nei log.
• Decidete come testare il ripristino. Un ripristino di prova su un host isolato o su un database di staging fornisce una prova più solida rispetto al solo successo di un comando di dump.

Crea e verifica il backup di PostgreSQL

1. Confermare il database di destinazione e il ruolo

Su un host PostgreSQL autogestito, connettiti come amministratore PostgreSQL e controlla l'elenco dei database e le relative relazioni. Non fare affidamento su un nome fittizio copiato da una configurazione di esempio. Se il tuo server domestico utilizza un database remoto o gestito, usa il metodo di connessione approvato e verifica che l'account di dump disponga dei permessi di lettura necessari.

2. Creare un dump in formato personalizzato

Crea una directory che solo l'account di backup o gli amministratori possano leggere. L'esempio seguente viene eseguito pg_dumpcon l'account locale del sistema operativo PostgreSQL e scrive in un percorso protetto. Modifica il percorso con uno esistente e scrivibile nella tua configurazione.

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

Se il database è remoto, fornire le impostazioni di connessione utilizzando il metodo approvato nel proprio ambiente, ad esempio un .pgpassfile protetto o le variabili d'ambiente di libpq. Evitare di inserire la password direttamente nella riga di comando. Mantenere l'opzione di esclusione a meno che non si disponga di un motivo specifico e documentato per gestire la tabella delle chiavi monouso in modo diverso.

3. Controllare l'archivio e conservare un checksum

Verifica che il file di dump esista, che non contenga zero dati e che sia leggibile come archivio PostgreSQL. Un elenco completo dei file è un primo controllo utile, ma non garantisce che il ripristino venga completato o che l'intero homeserver sia in grado di servire gli utenti.

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

Archivia il checksum accanto al record di backup, quindi copia il dump su un sistema o servizio di backup separato. Ricalcola il checksum dopo la copia e confronta i valori. Per gli obiettivi di ripristino in ambiente di produzione, pianifica backup regolari, conserva più generazioni, crittografale ed esegui periodicamente simulazioni di ripristino.

Ripristina in un database pulito

4. Arresta Synapse e prepara una destinazione vuota

Per un ripristino, arrestare prima Synapse in modo che non possa riconnettersi mentre il database viene sostituito o testato. Il nome del servizio riportato di seguito è comune in alcune installazioni di pacchetti, ma può variare; gli utenti Docker devono arrestare il servizio Synapse tramite il loro progetto Compose, mentre le distribuzioni orchestrate devono utilizzare la normale procedura di manutenzione. Non è necessario arrestare PostgreSQL.

Utilizza un nuovo database vuoto per il ripristino. Non sovrascrivere un database Synapse esistente o uno che contenga già delle tabelle. Se devi conservare il database corrente per un eventuale rollback, lascialo intatto e ripristinalo con un nome di database temporaneo, quindi convalidalo prima di modificare la configurazione di Synapse.

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

Il proprietario del database e le impostazioni locali devono corrispondere ai requisiti della configurazione di Synapse. Se il nome di destinazione esiste già, interrompere l'operazione e confermare quale database si intende utilizzare; non dare per scontato che l'eliminazione sia sicura. Creare prima tutti i ruoli PostgreSQL necessari. Un singolo database pg_dumpnon include ruoli a livello di cluster, quindi un amministratore che passa a un nuovo cluster PostgreSQL potrebbe aver bisogno anche di un backup globale protetto separatamente, creato con pg_dumpall --globals-only.

5. Ripristinare l'archivio e gestire le chiavi monouso

Carica l'archivio personalizzato in quella destinazione vuota. L'opzione di errore esplicito fa sì che il ripristino si interrompa in caso di errore, anziché continuare e lasciare un risultato incompleto che è facile non notare.

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

Se il dump non ha escluso e2e_one_time_keys_json, connettiti al database ripristinato e tronca quella tabella prima di avviare Synapse. Questa è la misura di sicurezza per il ripristino documentata da Synapse per i backup che includono quelle righe. Non eseguire il comando su un database attivo in modo casuale: rimuove tutte le righe in quella tabella.

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

Se hai utilizzato l'esclusione consigliata, il ripristino non contiene vecchie righe con chiave monouso e questo passaggio di troncamento non è necessario. Una voce di tabella pg_restore --listpuò rappresentare una definizione di tabella senza i relativi dati. Verifica la presenza TABLE DATAdi voci durante la revisione del contenuto dell'archivio; il record operativo più sicuro è il comando di dump esatto utilizzato.

Riavvia Synapse e verifica il ripristino.

6. Ripristina i file associati e avvia Synapse

Prima di riavviare, assicurarsi che la configurazione ripristinata punti al database previsto e che la chiave di firma e l'archivio multimediale previsti siano disponibili per il processo Synapse. Se il ripristino è stato eseguito con un nome di database temporaneo, aggiornare le impostazioni del database in modo sicuro, convalidare il file e utilizzare la normale procedura di distribuzione per attivarlo. Mantenere disponibili il vecchio database e la configurazione precedente finché la nuova istanza non supera i controlli.

Avvia il servizio utilizzando il comando appropriato per la tua implementazione. Su un host systemd, controlla lo stato del servizio e i log recenti. Nei container, controlla lo stato di salute del container e i relativi log. Un processo in esecuzione è un segnale iniziale, non una prova che gli utenti possano leggere le stanze, inviare messaggi o scaricare allegati.

7. Funzioni di test da cui dipendono gli utenti

• Conferma che Synapse si avvii senza errori di migrazione del database, di autorizzazione, di localizzazione o di connessione.
• Accedi con un account di prova e visualizza le stanze esistenti; invia un messaggio di prova se il tuo piano di manutenzione lo consente.
• Verifica il comportamento della federazione e dei servizi applicativi se queste funzionalità sono incluse nella tua implementazione.
• Apri un allegato o un avatar caricato localmente e di cui conosci la funzione di caricamento, per verificare che l'archivio multimediale corrisponda al database ripristinato.
• Controlla i log di Synapse e i log di PostgreSQL per individuare eventuali errori ricorrenti dopo l'avvio, non solo dopo il primo controllo di integrità andato a buon fine.

Un ripristino può avere esito positivo dal punto di vista tecnico anche in presenza di file multimediali, configurazioni di riferimento o ruoli mancanti. Se gli utenti riscontrano allegati mancanti, verificare l'archivio multimediale configurato e ripristinare il backup multimediale locale corrispondente. Se Synapse non riesce a connettersi, confrontare il proprietario del database ripristinato, le credenziali, l'host, il nome del database, le impostazioni locali e il file di configurazione attivo.

Segnali di guasto comuni e quando cambiare metodo

I dump logici sono portatili e semplici da gestire per molte implementazioni di piccole e medie dimensioni, ma il ripristino può richiedere tempo man mano che il database cresce. Per un servizio di grandi dimensioni o ad alta disponibilità, consultare la documentazione di backup aggiornata di PostgreSQL e pianificare un backup fisico testato o un piano di ripristino a un punto specifico nel tempo. Conservare un dump logico indipendente se risponde a esigenze specifiche di portabilità o di audit. Nessuno dei due metodi protegge i file archiviati al di fuori di PostgreSQL, a meno che non vengano sottoposti a backup separatamente.

Lista di controllo per il recupero

• Il dump è leggibile pg_restore --liste il suo checksum corrisponde alla copia off-host.
• Il ripristino è stato eseguito su un nuovo database vuoto con la codifica, le impostazioni locali, il proprietario e i ruoli previsti.
• Le righe con chiave monouso sono state escluse oppure la tabella è stata troncata prima del riavvio di Synapse.
• I file di configurazione, la chiave di firma e i supporti locali necessari sono stati ripristinati da backup compatibili.
• I log di Synapse sono sufficientemente puliti per il servizio e i controlli a livello client per le stanze e i contenuti multimediali hanno esito positivo.
• Un'esercitazione di ripristino ha confermato le fasi di recupero documentate e ha misurato il tempo effettivo di ripristino.

Riferimenti ufficiali

• Guida al backup di Synapse : consigli specifici per il database, gestione delle chiavi monouso, configurazione, chiavi di firma e archivio multimediale.
• Synapse: Utilizzo di PostgreSQL — dettagli di configurazione e impostazione del database.
• PostgreSQL: pg_dump , pg_restore e backup e ripristino di PostgreSQL : opzioni di archiviazione e strategie di backup più ampie.

Documentazione verificata il 6 ottobre 2026. I nomi dei comandi e la gestione dei servizi variano a seconda del sistema operativo, dell'immagine del container, della versione di PostgreSQL e della distribuzione di Synapse. Verificare le istruzioni confrontandole con la documentazione relativa alle versioni e al metodo di packaging in uso.