PostgreSQLダンプを使用してMatrix Synapseを安全に復元する
pg_dumpを使用してSynapseをバックアップし、署名キーとメディアを保護し、古いワンタイムキーを再利用せずにクリーンなPostgreSQLデータベースに復元します。
SynapseデータベースのバックアップにはPostgreSQLのカスタムダンプ形式を使用し、ワンタイムキーテーブルを除外して、新しく作成した空のデータベースに復元してください。データベースダンプだけでは完全なホームサーバーのバックアップにはなりません。Synapseの設定、署名キー、ローカルメディアも保存してください。2026年10月10日に確認されたSynapseの公式バックアップガイダンスでは、既存のテーブルへの上書き復元や、古いエンドツーエンド暗号化ワンタイムキーの復元は避けるよう特に警告しています。
検証済み: pg_dump PostgreSQL がオンラインのままで一貫性のあるスナップショットを作成します。ダンプの実行中に Synapse を停止する必要はありません。データベースのみのダンプには、Synapse のメディア ストアのファイル、homeserver.yaml参照される構成ファイル、またはサーバーの署名キーは含まれません。これらは別の保護されたバックアップ セットに保管してください。Synapse は、ローカルにアップロードされたコンテンツと、動的サムネイルが無効になっている場合はローカル サムネイルを保持対象データとして識別します。リモート メディアと URL プレビュー キャッシュは、通常フェッチまたは再構築できます。
対策:復旧計画を作成する前に、アクティブなデータベース名、PostgreSQLの役割、Synapse構成ディレクトリ、署名キーパス、およびメディアストアパスを特定してください。サーバーに設定されているパスを使用してください。これらのパスは、パッケージ、コンテナ、およびデプロイメントによって異なります。
よくある誤解: SQLダンプが正常に完了したからといって、ホームサーバー全体を復旧できるとは限りません。対策:データベース、設定、署名キー、および必要なローカルメディアをバックアップし、定期的にそれらをまとめて復元するテストを実施してください。
以下のコマンドは、PostgreSQLコマンドラインツールがインストールされたLinuxホスト、という名前のデータベースsynapse、およびオペレーティングシステムアカウントとしてPostgreSQLコマンドを実行する権限があることを前提としていますpostgres。データベース名とパスは、ご使用の環境に合わせて変更してください。ダンプファイルは、十分な空き容量のある保護されたストレージに保存してください。ダンプファイルには、プライベートメッセージやアカウントデータが含まれる可能性があります。
Synapseが古いバックアップから再生してはならないと指定しているテーブルの内容を除外して、ダンプを作成します。
sudo -u postgres pg_dump -Fc --exclude-table-data=e2e_one_time_keys_json synapse > /secure-backups/synapse.dump-FcPostgreSQL独自のアーカイブ形式を選択します。この形式は、pg_restore通常のSQLよりも適しており、多くの場合サイズも小さくなります。除外設定はテーブルデータに影響しますが、テーブル定義自体は削除されません。
ファイルが存在し、かつ空でないことを確認し、アーカイブの目次を表示します。
ls -lh /secure-backups/synapse.dump
sudo -u postgres pg_restore --list /secure-backups/synapse.dumpリスト表示によってPostgreSQLがアーカイブ構造を読み取れることは確認できますが、すべての行が復元可能であることや他のバックアップファイルが完全であることは証明されません。より確実な検証を行うには、ダンプファイルを別のバックアップストレージにコピーし、転送後にチェックサムを確認してください。
よくある誤解:すべてのスナップショット作成にSynapseの停止が必要であるpg_dump。公式のSynapseページによると、通常のpg_dumpスナップショットはSynapseやPostgreSQLを停止しなくても整合性が保たれる。対処法:この論理バックアップのためにはサービスをオンラインのままにしておくが、完全なリストアのためにメンテナンスウィンドウを計画しておく。
復元は置換操作です。まず、SynapseおよびSynapseワーカーを停止し、復元中にターゲットへの接続や書き込みが行われないようにしてください。データベースを変更するコマンドを発行する前に、ターゲットデータベース名とダンプファイルを確認してください。
Synapseの設定で使用されている所有者とUTF-8エンコーディングを使用して、新しいデータベースを作成します。以下では、例としてロールを使用しますsynapse_user。
sudo -u postgres createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse_user synapseデータベース名が既に存在する場合は、安易に復元しないでください。古いデータベースの内容を確認し、復元可能なバックアップが別途用意されていることを確認した上で、復元手順に従って古いデータベースを保持または削除してください。
アーカイブを空のデータベースにロードします。
sudo -u postgres pg_restore --dbname=synapse /secure-backups/synapse.dumpコマンドの終了ステータスとPostgreSQLの出力を確認してください。Synapseを起動する前にエラーを調査してください。--cleanデータが格納されている本番データベースに上書き復元するためのショートカットとして、などのオプションは使用しないでください。Synapseは、既存のテーブルがエラーや微妙な不整合を引き起こす可能性があると警告します。
ダンプにワンタイムキーデータが除外されていない場合は、起動前にそれをクリアしてください。復元されたデータベースに接続し、以下を実行します。
sudo -u postgres psql --dbname=synapse -c 'TRUNCATE e2e_one_time_keys_json;'Synapseはこの例外を文書化しています。これは、古いワンタイムキーを復元すると、クライアントが既に消費されたキーを再利用してしまう可能性があり、メッセージの復号化に問題が生じる可能性があるためです。ワンタイムキーをクリアすると、クライアントは新しいキーをアップロードするように促されます。推奨される除外設定に従っていれば、テーブルには復元された行はなく、この余分な切り捨ては不要です。
よくある誤解:すべてのデータベーステーブルを安全にまとめてロールバックできる。対処法:バックアップ時に除外するe2e_one_time_keys_jsonか、リストア後に切り捨てる。そして、これらの操作はSynapseプロセスを開始する前に行う。
可能な限り、同じ復元ポイントから、一致する構成、署名キー、および必要なローカルメディアファイルを復元してください。元の署名キーは保持してください。Synapse は、イベントとフェデレーション要求に署名するためにこのキーを使用します。どうしても交換する必要がある場合は、Synapse の署名キーに関するガイダンスに従い、古い公開キーを古い署名キーとして構成してください。異なる時点から復元されたデータベース、メディア、および構成は、同じ状態を表していない可能性があるため、復元計画の一貫性を確認してください。
復元とワンタイムキーの処理が完了してから、Synapseとそのワーカーを起動してください。サービスログを確認し、データベース接続エラー、スキーマの欠落または権限エラー、バックグラウンド更新の問題がないか確認してください。次に、テストアカウントでサインインし、既知のルームの最近の履歴を調べ、ローカルにアップロードされた添付ファイルを開きます。デプロイメントがフェデレーションサービスとアプリケーションサービスに依存している場合は、それらも確認してください。これらのチェックは、実用的な動作確認テストであり、すべてのルームまたはメディアオブジェクトが復元されたことを保証するものではありません。
デプロイメントによって異なります。コマンド パス、サービス名、データベース ロール、コンテナ オーケストレーション、バックアップ保持期間はインストール固有のものです。この手順では、論理的な PostgreSQL ダンプとリストアについて説明します。ポイント イン タイム リカバリ、PostgreSQL クラスタ全体のロール、または高可用性フェイルオーバー設計については説明していません。本番システムの場合は、 PostgreSQL のバージョンとリカバリの目的に合った方法について、 Synapse バックアップのドキュメントとPostgreSQL バックアップおよびリストアのドキュメントを参照してください。リストア テストの日付、ソフトウェア バージョン、および結果を記録してください。テストされていないアーカイブがリカバリ可能なバックアップであると想定しないでください。
pg_dumpを使用してSynapseをバックアップし、署名キーとメディアを保護し、古いワンタイムキーを再利用せずにクリーンなPostgreSQLデータベースに復元します。
Mjölnirを、専用のMatrixアカウント、暗号化された管理ルーム、Docker Compose、ポリシーリスト、および権限チェックとともにセットアップします。
廃止されたプロキシはスキップし、Synapseに組み込まれているスライディング同期を設定してください。クライアント検出機能をチェックした後、互換性のあるスマートフォンでルームリストの読み込みと再接続の動作を測定します。
Element Webを静的サイトとしてデプロイし、Matrixホームサーバーに接続し、HTTPSを追加し、Nginxを設定して古いファイルなしで更新を配信します。
64ビット版Raspberry Pi 4に、永続データ、HTTPSフェデレーション、保護された登録、および動作中のホームサーバーのチェック機能を備えたConduitをセットアップします。
ElementまたはMatrix APIを使用して、権限、Synapse命名規則、およびフェデレーションのチェックを行いながら、ドメイン上の共有しやすいMatrixルームのアドレスを設定できます。
coturnとSynapseを一致するTURN認証情報で設定し、必要なリレーポートを開き、Matrixクライアントがリレー候補を取得できることを確認します。
Docker Compose、PostgreSQL、プライベート設定、およびHTTPS経由で公開する前にチェックを行う機能を備えた、永続的なSynapseホームサーバーをセットアップします。
Element Web デプロイメント用にブランド名、カスタムカラー、ログインアセットを設定すると同時に、どの部分が Element ブランドのままになるかを理解してください。
Synapseがプロセスごとのオープンファイル数の上限に達したかどうかを診断し、適切なサービスまたはワーカーに対してsystemdのドロップインを設定し、実際の制限を確認します。