Comment sauvegarder et restaurer une base de données PostgreSQL Matrix Synapse

Une restauration Synapse fiable commence par une sauvegarde PostgreSQL lisible, une base de données de destination propre et les fichiers du serveur d'installation correspondants. Pour une installation classique à base de données unique, le guide de sauvegarde de Synapse recommande le format de sauvegarde personnalisé de PostgreSQL et exclut le contenu du répertoire `/etc/postgresql/`. e2e_one_time_keys_jsonRestaurez les données dans une base de données vide nouvellement créée ; ne superposez pas une sauvegarde aux tables restantes d'une installation précédente. Vérifiez ensuite que Synapse démarre correctement sur la base de données restaurée et que les supports d'installation locaux et les clés de signature sont présents.

Ce guide suppose un système Linux, une base de données PostgreSQL nommée `<nom_de_la_base_de_données>` synapseet un rôle de base de données nommé `< synapse_usernom_du_rôle_de_base_de_données>`. Remplacez ces éléments par la base de données, le rôle, le chemin de sauvegarde, le nom du service et les chemins de configuration utilisés par votre déploiement. Les déploiements Docker Compose, Kubernetes, PostgreSQL managé et Synapse multi-bases de données nécessitent des commandes équivalentes adaptées à leur environnement.

Ce qu'une sauvegarde de base de données protège (et ne protège pas)

pg_dumpCette commande capture une base de données PostgreSQL dans un instantané cohérent, permettant ainsi à PostgreSQL et Synapse de rester en ligne pendant la sauvegarde. Une archive au format personnalisé -Fcpeut être inspectée et restaurée pg_restore. Le guide Synapse recommande d'exclure les données des tables à clés uniques : la restauration d'anciennes clés utilisées peut entraîner la réception de nouvelles clés par les clients et provoquer des erreurs de déchiffrement des messages. La définition de la table peut encore apparaître dans l'archive ; lors de la consultation de la liste des archives, recherchez les entrées de données de table plutôt que de supposer qu'une table listée contient des lignes.

Une simple sauvegarde de la base de données ne constitue pas une sauvegarde complète de votre serveur domestique. Il est également nécessaire de conserver homeserver.yamlles fichiers référencés, la clé de signature du serveur et le répertoire du stockage multimédia. Le guide de sauvegarde de Synapse souligne l'importance des fichiers multimédias téléchargés localement, car le serveur domestique peut en contenir l'unique copie. Si votre configuration utilise plusieurs entrées de base de données, prévoyez une sauvegarde pour chacune d'elles.

Avant de commencer

• Veuillez confirmer le nom de la base de données configurée, l'utilisateur, l'hôte, le port et indiquer si Synapse utilise une seule base de données ou plusieurs.
• Vérifiez que les utilitaires clients PostgreSQL pg_dump, pg_restore, createdb, et psqlsont installés et compatibles avec votre serveur PostgreSQL.
• Choisissez un emplacement de sauvegarde sécurisé disposant d'un espace libre suffisant. Les sauvegardes peuvent contenir des messages privés et des données de compte ; limitez l'accès et chiffrez les sauvegardes au repos et en transit.
• Enregistrez le répertoire de configuration de Synapse, le chemin de la clé de signature et media_store_pathsauvegardez les informations confidentielles sans les exposer dans l'historique du shell, le chat ou les journaux.
• Déterminez comment vous allez tester la récupération. Un test de restauration sur un hôte isolé ou une base de données de test constitue une preuve plus convaincante qu'une simple commande de sauvegarde réussie.

Créez et vérifiez la sauvegarde PostgreSQL

1. Confirmez la base de données cible et le rôle

Sur un serveur PostgreSQL autogéré, connectez-vous en tant qu'administrateur PostgreSQL et examinez la liste des bases de données et leurs relations. N'utilisez pas un nom d'utilisateur copié d'une configuration d'exemple. Si votre serveur utilise une base de données distante ou gérée, utilisez sa méthode de connexion recommandée et vérifiez que le compte de sauvegarde dispose des droits de lecture nécessaires.

2. Créez une sauvegarde au format personnalisé

Créez un répertoire accessible en lecture uniquement par le compte de sauvegarde ou les administrateurs. L'exemple ci-dessous s'exécute pg_dumpavec le compte système local de PostgreSQL et écrit dans un répertoire protégé. Modifiez ce répertoire pour qu'il existe et soit accessible en écriture dans votre configuration.

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

Si votre base de données est distante, fournissez les paramètres de connexion selon la méthode approuvée dans votre environnement, par exemple un .pgpassfichier protégé ou les variables d'environnement libpq. Évitez de saisir le mot de passe directement dans la ligne de commande. Conservez l'option d'exclusion, sauf si vous avez une raison valable et documentée de traiter différemment la table des clés à usage unique.

3. Vérifiez l'archive et conservez une somme de contrôle

Vérifiez que le fichier de sauvegarde existe, qu'il n'est pas nul et qu'il est lisible comme une archive PostgreSQL. Un affichage correct est une première vérification utile, mais ne garantit pas la réussite de la restauration ni la disponibilité du serveur d'accueil pour les utilisateurs.

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

Stockez la somme de contrôle à côté de l'enregistrement de sauvegarde, puis copiez la sauvegarde sur un système ou un service de sauvegarde distinct. Recalculez la somme de contrôle après la copie et comparez les valeurs. Pour une reprise après exploitation optimale, planifiez des sauvegardes régulières, conservez plusieurs générations, chiffrez-les et effectuez des exercices de restauration périodiques.

Restaurer dans une base de données propre

4. Arrêtez Synapse et préparez une destination vide

Pour une restauration, arrêtez d'abord Synapse afin qu'il ne puisse pas se reconnecter pendant le remplacement ou le test de la base de données. Le nom du service ci-dessous est courant dans certaines installations de paquets, mais il peut varier ; les utilisateurs de Docker doivent arrêter le service Synapse via leur projet Compose, et les déploiements orchestrés doivent suivre leur procédure de maintenance habituelle. Il n'est pas nécessaire d'arrêter PostgreSQL lui-même.

Utilisez une base de données vierge pour la restauration. Ne restaurez pas par-dessus une base de données Synapse existante ou contenant déjà des tables. Si vous devez conserver la base de données actuelle pour la restauration, laissez-la intacte et restaurez-la sous un nom de base de données temporaire, puis validez avant de modifier la configuration de Synapse.

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

Le propriétaire et les paramètres régionaux de la base de données doivent correspondre aux exigences de votre configuration Synapse. Si le nom cible existe déjà, arrêtez-vous et vérifiez quelle base de données vous souhaitez utiliser ; ne présumez pas que sa suppression est sans risque. Créez d’abord les rôles PostgreSQL nécessaires. Une base de données unique pg_dumpn’inclut pas les rôles à l’échelle du cluster ; par conséquent, un administrateur migrant vers un nouveau cluster PostgreSQL peut également avoir besoin d’une sauvegarde des variables globales protégée séparément pg_dumpall --globals-only.

5. Restaurez l'archive et gérez les clés à usage unique.

Chargez l'archive personnalisée dans ce répertoire vide. L'option de gestion explicite des erreurs permet d'interrompre la restauration en cas d'erreur, évitant ainsi qu'elle ne se poursuive et ne laisse un résultat incomplet, facilement négligeable.

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

Si votre sauvegarde n'a pas exclu certaines lignes e2e_one_time_keys_json, connectez-vous à la base de données restaurée et tronquez la table correspondante avant de lancer Synapse. Il s'agit de la procédure de récupération recommandée par Synapse pour les sauvegardes contenant ces lignes. N'exécutez pas cette commande sur une base de données en production : elle supprimerait toutes les lignes de la table.

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

Si vous avez utilisé l'exclusion recommandée, la restauration ne contient aucune ligne contenant d'anciennes clés à usage unique et cette étape de troncature est inutile. Une entrée de table pg_restore --listpeut représenter la définition d'une table sans ses données. Vérifiez la présence TABLE DATAd'entrées lors de l'examen du contenu de l'archive ; l'enregistrement opérationnel le plus sûr est la commande de sauvegarde exacte utilisée.

Réinitialisez Synapse et vérifiez la récupération.

6. Restaurez les fichiers associés et démarrez Synapse.

Avant de redémarrer, assurez-vous que la configuration restaurée pointe vers la base de données prévue et que la clé de signature et le magasin de médias attendus sont accessibles au processus Synapse. Si vous avez effectué la restauration sous un nom de base de données temporaire, mettez à jour les paramètres de la base de données de manière sécurisée, validez le fichier et utilisez votre procédure de déploiement habituelle pour l'activer. Conservez l'ancienne base de données et la configuration précédente jusqu'à ce que la nouvelle instance réussisse les vérifications.

Démarrez le service à l'aide de la commande appropriée à votre déploiement. Sur un hôte systemd, consultez l'état du service et les journaux récents. Dans les conteneurs, vérifiez l'état et les journaux du conteneur. Un processus en cours d'exécution est un premier signe, mais ne garantit pas que les utilisateurs peuvent lire les salons, envoyer des messages ou récupérer les pièces jointes.

7. Tester les fonctions dont les utilisateurs dépendent

• Vérifiez que Synapse démarre sans erreur de migration de base de données, d'autorisation, de paramètres régionaux ou de connexion.
• Connectez-vous avec un compte de test et consultez les salles existantes ; envoyez un message de test si votre contrat de maintenance le permet.
• Vérifiez le comportement de la fédération et des services applicatifs si ces fonctionnalités font partie de votre déploiement.
• Ouvrez une pièce jointe ou un avatar téléchargé localement et dont vous connaissez la provenance pour vérifier que le magasin de médias correspond à la base de données restaurée.
• Vérifiez les journaux Synapse et PostgreSQL pour détecter les erreurs répétées après le démarrage, et pas seulement après le premier contrôle d'intégrité réussi.

Une restauration peut réussir techniquement même si des fichiers multimédias, une configuration référencée ou des rôles sont manquants. Si des pièces jointes sont manquantes, vérifiez le magasin de médias configuré et restaurez la sauvegarde locale correspondante. Si Synapse ne parvient pas à se connecter, comparez le propriétaire de la base de données restaurée, les informations d'identification, l'hôte, le nom de la base de données, les paramètres régionaux et le fichier de configuration actif.

Signaux d'erreur courants et quand changer de méthode

Les sauvegardes logiques sont portables et simples d'utilisation pour de nombreuses petites et moyennes bases de données, mais leur restauration peut s'avérer longue à mesure que la base de données s'agrandit. Pour un service de grande envergure ou à haute disponibilité, consultez la documentation de sauvegarde de PostgreSQL et planifiez une sauvegarde physique testée ou une restauration à un point précis dans le temps. Conservez une sauvegarde logique indépendante si elle répond à un besoin de portabilité ou d'audit spécifique. Aucune de ces méthodes ne protège les fichiers stockés en dehors de PostgreSQL, sauf s'ils sont sauvegardés séparément.

Liste de contrôle de récupération

• Le fichier de vidage est lisible pg_restore --listet sa somme de contrôle correspond à la copie hors hôte.
• La restauration a été effectuée dans une nouvelle base de données vide, avec l'encodage, les paramètres régionaux, le propriétaire et les rôles attendus.
• Les lignes contenant une clé unique ont été exclues, ou la table a été tronquée avant le redémarrage de Synapse.
• Les fichiers de configuration, la clé de signature et les supports locaux requis ont été restaurés à partir de sauvegardes compatibles.
• Les journaux Synapse sont suffisamment propres pour le service, et les vérifications au niveau client sont concluantes pour les salles et les médias.
• Un exercice de restauration a confirmé les étapes de récupération documentées et a mesuré le temps de restauration réel.

Références officielles

• Guide de sauvegarde Synapse — conseils spécifiques à la base de données, gestion des clés à usage unique, configuration, clés de signature et stockage des médias.
• Synapse : Utilisation de PostgreSQL — détails de configuration et d’installation de la base de données.
• PostgreSQL : pg_dump , pg_restore , et sauvegarde et restauration PostgreSQL — options d’archivage et stratégies de sauvegarde plus générales.

Documentation vérifiée le 6 octobre 2026. Les noms de commandes et la gestion des services varient selon le système d'exploitation, l'image du conteneur, la version de PostgreSQL et le déploiement de Synapse. Veuillez comparer les instructions avec la documentation correspondant à votre version et à la méthode de packaging utilisée.