Matrix Synapse PostgreSQLデータベースのバックアップと復元方法

信頼性の高い Synapse リカバリは、読み取り可能な PostgreSQL ダンプ、クリーンな宛先データベース、および対応するホームサーバー ファイルから始まります。一般的な単一データベースのインストールの場合、Synapse のバックアップ ガイドでは PostgreSQL のカスタム ダンプ フォーマットを推奨し、 の内容を除外していますe2e_one_time_keys_json。新しく作成された空のデータベースにリストアします。以前のインストールで残されたテーブルの上にダンプを重ねないでください。次に、リストアされたデータベースに対して Synapse が起動し、ローカル メディアと署名キーが存在することを確認します。

このチュートリアルでは、Linux ホスト、という名前の PostgreSQL データベースsynapse、およびという名前のデータベース ロールを前提としていますsynapse_user。ご使用のデプロイメントで使用されているデータベース、ロール、バックアップ パス、サービス名、および構成パスに置き換えてください。Docker Compose、Kubernetes、マネージド PostgreSQL、およびマルチデータベース Synapse デプロイメントでは、それぞれの環境に対応した同等のコマンドが必要です。

データベースダンプが保護するものと保護しないもの

pg_dumpは 1 つの PostgreSQL データベースを一貫性のあるスナップショットとしてキャプチャするため、ダンプの実行中も PostgreSQL と Synapse はオンラインのままにしておくことができます。カスタム形式のアーカイブ ( -Fc) は で検査および復元できますpg_restore。Synapse ガイドでは、ワンタイムキーのテーブルデータを除外することを特に推奨しています。古い使用済みキーを復元すると、クライアントがキーを再度受信し、メッセージの復号化エラーにつながる可能性があります。テーブル定義はアーカイブに表示される場合があります。アーカイブ リストを確認する際は、リストされたテーブルに行が含まれていると想定するのではなく、テーブルデータのエントリを探してください。

データベースのダンプだけでは、ホームサーバーの完全なバックアップにはなりません。homeserver.yaml参照するファイル、サーバー署名キー、メディアストアディレクトリも保持してください。Synapseのバックアップガイドでは、ローカルにアップロードされたメディアはホームサーバーに唯一のコピーが保存されている可能性があるため、重要であるとされています。構成で複数のデータベースエントリを使用している場合は、Synapseが使用するすべてのデータベースのダンプを計画してください。

始める前に

• 設定されているデータベース名、ユーザー、ホスト、ポート、およびSynapseが単一のデータベースを使用するか複数のデータベースを使用するかを確認してください。
• PostgreSQLクライアントユーティリティpg_dump、、、pg_restoreおよびcreatedbがpsqlインストールされており、PostgreSQLサーバーと互換性があることを確認してください。
• 十分な空き容量のある、保護されたバックアップ先を選択してください。ダンプファイルにはプライベートメッセージやアカウントデータが含まれる可能性があるため、アクセスを制限し、保存時および転送時のバックアップを暗号化してください。
• Synapse の設定ディレクトリ、署名キーのパス、および を記録しますmedia_store_path。シェル履歴、チャット、ログに秘密情報を公開せずにバックアップします。
• 復旧テストの方法を決定します。隔離されたホストまたはステージングデータベースでのリストアテストは、ダンプコマンドの成功のみよりも強力な証拠となります。

PostgreSQLのバックアップを作成して確認する

1. 対象データベースと役割を確認する

自己管理型のPostgreSQLホストでは、PostgreSQL管理者として接続し、データベース一覧とリレーションを確認してください。サンプル構成からコピーした仮名に頼らないでください。ホームサーバーがリモートデータベースまたは管理対象データベースを使用している場合は、承認済みの接続方法を使用し、ダンプアカウントに必要な読み取りアクセス権があることを確認してください。

2. カスタム形式のダンプを作成する

バックアップアカウントまたは管理者のみが読み取り可能なディレクトリを作成します。以下の例では、pg_dumpローカルのPostgreSQLオペレーティングシステムアカウントとして実行され、保護されたパスに書き込みます。ご使用の環境で存在し、書き込み可能なパスに変更してください。

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

データベースがリモートにある場合は、保護されたファイルやlibpq環境変数など、環境で承認されている方法で接続設定を指定してください.pgpass。コマンドラインにパスワードを直接入力することは避けてください。ワンタイムキーテーブルを別の方法で処理する明確な理由がない限り、除外オプションを有効にしてください。

3. アーカイブをチェックし、チェックサムを保存する

ダンプファイルが存在し、値がゼロ以外であり、PostgreSQLアーカイブとして読み取り可能であることを確認してください。正常にリスト化できることは有用な最初の確認事項ですが、リストアが完了することや、ホームサーバー全体がユーザーにサービスを提供できることを保証するものではありません。

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

チェックサムをバックアップレコードの横に保存し、ダンプを別のシステムまたはバックアップサービスにコピーします。コピー後にチェックサムを再計算し、値を比較します。本番環境の復旧を目的として、定期的なバックアップをスケジュールし、複数世代のデータを保持し、暗号化し、定期的にリストア訓練を実行します。

クリーンなデータベースに復元する

4. Synapseを停止し、空の宛先を準備します。

リストアを行うには、データベースの置換またはテスト中にSynapseが再接続できないように、まずSynapseを停止してください。以下のサービス名は一部のパッケージインストールで共通していますが、環境によって異なります。DockerユーザーはComposeプロジェクトを通じてSynapseサービスを停止し、オーケストレーションされたデプロイメントの場合は通常のメンテナンス手順に従ってください。PostgreSQL自体を停止する必要はありません。

リストアには、新しい空のデータベースを使用してください。既存の Synapse データベースや、既にテーブルが含まれているデータベースに上書きしてリストアしないでください。ロールバックのために現在のデータベースを保持する必要がある場合は、データベースをそのままにして、一時的なデータベース名でリストアし、Synapse の設定を変更する前に検証を行ってください。

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

データベースの所有者とロケールは、Synapse の設定要件と一致する必要があります。ターゲット名が既に存在する場合は、停止して使用するデータベースを確認してください。削除しても安全だと考えないでください。必要な PostgreSQL ロールを最初に作成します。単一データベースにはpg_dumpクラスタ全体のロールは含まれないため、新しい PostgreSQL クラスタに移行する管理者は、で作成された個別に保護されたグローバル バックアップも必要になる場合がありますpg_dumpall --globals-only。

5. アーカイブを復元し、ワンタイムキーを処理する

カスタムアーカイブをその空の保存先にロードします。明示的なエラーオプションを指定すると、エラーが発生した際に復元処理が中断され、処理が続行されて見落としやすい不完全な結果が残るのを防ぎます。

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

ダンプで除外されなかった行がある場合はe2e_one_time_keys_json、復元されたデータベースに接続し、Synapse を起動する前にそのテーブルを切り捨ててください。これは、これらの行を含むバックアップに対して Synapse が文書化している復旧時の安全対策です。このコマンドをライブデータベースに対して安易に実行しないでください。そのテーブル内のすべての行が削除されます。

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

推奨される除外設定を使用した場合、復元データには古いワンタイムキー行は含まれないため、この切り捨て処理は不要です。テーブルエントリは、pg_restore --listデータを含まないテーブル定義を表す場合があります。アーカイブの内容を確認する際は、エントリに注意してくださいTABLE DATA。最も安全な運用記録は、使用したダンプコマンドそのものです。

Synapseを復元して、回復を確認する

6. コンパニオンファイルを復元し、Synapseを起動します。

再起動する前に、復元された構成が目的のデータベースを指していること、および想定される署名キーとメディアストアがSynapseプロセスから利用可能であることを確認してください。一時的なデータベース名で復元した場合は、データベース設定を安全に更新し、ファイルを検証してから、通常のデプロイプロセスを使用してアクティブ化してください。新しいインスタンスがチェックに合格するまで、古いデータベースと以前の構成は保持しておいてください。

デプロイメントに適したコマンドを使用してサービスを開始してください。systemdホストでは、サービスの状態と最新のログを確認してください。コンテナでは、コンテナの健全性とログを確認してください。実行中のプロセスは初期シグナルであり、ユーザーがルームを閲覧したり、メッセージを送信したり、添付ファイルを取得したりできることの証明ではありません。

7. ユーザーが依存するテスト機能

• Synapseがデータベース移行、権限、ロケール、接続エラーなしで起動することを確認してください。
• テストアカウントでログインして既存の部屋情報を閲覧し、メンテナンスプランで許可されている場合はテストメッセージを送信してください。
• デプロイメントにフェデレーション機能とアプリケーションサービス機能が含まれている場合は、それらの動作を確認してください。
• ローカルにアップロードされた既知の添付ファイルまたはアバターを開いて、メディアストアが復元されたデータベースと一致するかどうかをテストします。
• 起動後、最初のヘルスチェックが成功した時だけでなく、その後も繰り返し発生するエラーがないか、SynapseログとPostgreSQLログを確認してください。

メディアファイル、参照されている構成、またはロールが欠落している場合でも、復元は技術的には成功する可能性があります。ユーザーが添付ファイルの欠落を確認した場合は、構成済みのメディアストアを確認し、対応するローカルメディアバックアップを復元してください。Synapseが接続できない場合は、復元されたデータベースの所有者、認証情報、ホスト、データベース名、ロケール、およびアクティブな構成ファイルを比較してください。

一般的な故障の兆候と、方法を変更するタイミング

論理ダンプは、多くの中小規模のシステム環境において移植性と容易性を兼ね備えていますが、データベースの規模が大きくなるにつれて復元に時間がかかる場合があります。大規模システムや高可用性サービスの場合は、PostgreSQLの最新のバックアップに関するドキュメントを参照し、テスト済みの物理バックアップまたは特定時点への復旧設計を計画してください。移植性や監査上の特別なニーズがある場合は、独立した論理ダンプを保持してください。どちらの方法も、PostgreSQL外部に保存されているファイルを個別にバックアップしない限り、それらのファイルを保護しません。

回復チェックリスト

• ダンプファイルは読み取り可能でありpg_restore --list、そのチェックサムはオフホストのコピーと一致します。
• 復元処理は、想定どおりのエンコード、ロケール、所有者、および役割を持つ、新しい空のデータベースに対して実行されました。
• ワンタイムキーの行が除外されたか、Synapseが再起動される前にテーブルが切り詰められた。
• 設定ファイル、署名キー、および必要なローカルメディアは、互換性のあるバックアップから復元されました。
• Synapseのログはサービス提供に十分なほどクリーンであり、ルームとメディアに関するクライアントレベルのチェックも合格している。
• 復旧訓練を実施し、文書化された復旧手順を確認するとともに、実際の復旧時間を測定した。

公式資料

• Synapseバックアップガイド― データベース固有のアドバイス、ワンタイムキーの取り扱い、設定、署名キー、およびメディアストア。
• Synapse: PostgreSQL の使用方法— データベースのセットアップと構成の詳細。
• PostgreSQL: pg_dump、pg_restore、およびPostgreSQLのバックアップと復元- アーカイブオプションとより広範なバックアップ戦略。

ドキュメントは2026年10月6日に確認済みです。コマンド名とサービス管理は、オペレーティングシステム、コンテナイメージ、PostgreSQLのバージョン、およびSynapseのデプロイ方法によって異なります。ご使用のバージョンとパッケージング方法に対応するドキュメントを参照して、手順をご確認ください。