Matrix Synapseで古いメッセージ履歴とメディアを削除する方法

シナリオ例（説明のみ）：架空の非営利団体であるNorthstar CommunityがMatrix Synapseホームサーバーを運用しています。データベースとメディアストアが肥大化しており、管理者は古いルーム履歴と不要なメディアを削除しつつ、現在のディスカッションやプロフィール画像を誤って削除しないようにしたいと考えています。この例は、実際の導入事例やテスト結果を報告するものではありません。

重要なのは、メッセージ履歴とメディアを別々のクリーンアップ作業として扱うことです。Synapseにはルーム履歴の削除APIと個別のメディアクリーンアップツールが用意されています。また、メディア保持設定によって、参照しているMatrixイベントを保持したままファイルを削除することも可能です。まず、保持しておくべきものを決定し、次にデータベースとメディアストアをバックアップし、適切な方法を選択して、バックアップ後に両方のストレージ領域を確認してください。

サーバーにとって「古い」とはどういう意味かを決めましょう。

設定を変更したり、破壊的なエンドポイントを呼び出す前に、保持ルールを書き留めてください。Northstarの例では、取締役会が通常の会議室履歴を180日間保持し、ローカルアップロードも同様のポリシーで保持し、リモートメディアは必要に応じて再度取得できるキャッシュとして扱うことを承認したとします。組織によっては、法的、運用上、またはコミュニティ上の理由から、数年間の保持が必要になる場合があります。これらの期間はあくまで例であり、普遍的な推奨事項ではありません。

データを2つのカテゴリに分類します。

• ルームイベント： Synapseのデータベースに保存されるメッセージやその他のイベント。イベントを削除すると、ユーザーがルーム内で閲覧できる過去の履歴の範囲が変わります。
• メディア：アップロードされたファイル、サムネイル、および他のホームサーバーからのファイルのキャッシュコピー。これらはメディアリポジトリ、または設定済みの外部リポジトリに保存されます。

Synapse の公式ドキュメントでは、イベントとメディアのクリーンアップに関する保持ポリシーを個別に説明しています。ルーム履歴の削除だけではメディアストアがクリーンアップされたとは証明されず、メディアファイルを削除しても、それにリンクされたイベントは消去されません。まず、データベースサイズ、メディアストアサイズ、影響を受けるルーム、および意図するカットオフを記録してください。Synapse設定マニュアルを参照してください。

削除する前にバックアップを取っておく

ご使用のデータベースエンジンに推奨されている手順に従ってデータベースのバックアップを作成し、メディアリポジトリまたは外部メディアストアもバックアップしてください。データベースのバックアップだけではアップロードされたファイルは保持されません。メディアのバックアップだけではルームイベントは復元されません。作業を進める前に、バックアップが読み取り可能であり、復元方法を理解していることを確認してください。Synapseがコンテナ内で実行されている場合、または個別のワーカーを使用している場合は、関連する構成とストレージボリュームをメンテナンスプランに含めてください。

Northstarの仮想サーバーの場合、管理者は共有ルームを操作する前に、データベースとメディアストアのサイズを記録し、最新の復元ポイントを確認します。これは、「クリーンアップ」が成功するためには、必要なコンテンツを復元可能な状態で残しつつ、意図したデータのみを削除する必要があるためです。

継続的なクリーンアップには、スケジュールされた保持を選択してください。

Synapseにポリシーを継続的に適用させたい場合は、ホームサーバーの設定でイベント保持期間とメディア保持期間を個別に設定してください。たとえば、管理者は、ルーム履歴とローカルメディアの保持期間が180日間、リモートメディアのキャッシュ期間が30日間という承認済みポリシーを持つサーバー向けに、このサンプルを適応させることができます。

retention:
  enabled: true
  default_policy:
    max_lifetime: 180d

media_retention:
  local_media_lifetime: 180d
  remote_media_lifetime: 30d

これは構成例であり、すべてのサーバーに適用できるポリシーではありません。Synapse では、イベント保持機能はデフォルトで無効になっていると説明されています。これは状態イベントdefault_policyのないルームに適用されますm.room.retention。ルーム管理者はルームポリシーを設定できますが、サーバー管理者はドキュメントに記載されている allow-lifetime 設定を使用してポリシーの有効期間を制限できます。一貫した上限が必要な場合は、デフォルト設定がすべてのルームをカバーしていると想定するのではなく、これらのコントロールと既に使用されているルームポリシーを確認してください。

メディアの有効期間は、メディアアイテムが最後にアクセスされてからの時間に基づきます。アイテムが一度もアクセスされていない場合、Synapse はその作成時間を使用します。この設定はオリジナルとサムネイルに適用されます。有効期間が設定されていないか、null の場合は、そのメディアカテゴリは削除されません。リモートでキャッシュされたアイテムは、削除された後でも、そのオリジンから再度要求される可能性があります。隔離されたメディアとローカルで保護されたメディアは例外であり、これらの保持設定では削除されません。メディアのクリーンアップは、enable_media_repo有効になっている Synapse プロセスまたはワーカーで実行されます。現在の保持と media_retention のリファレンスを確認してから、通常の再起動またはデプロイ手順に従って、インストール環境に合わせて設定を適用してください。

サンプルを採用する前に、その動作をニーズと比較してください。ルームメッセージが添付ファイル付きで180日間閲覧可能な状態を維持する必要がある場合は、ローカルに保存されているファイルよりもメッセージの方が長く残る可能性があることを許容しない限り、メディアの有効期間を短く設定しないでください。メディアがSynapse自体に保存されているか、外部メディアリポジトリに保存されているかを確認してください。Synapseのローカルメディア削除APIは、外部リポジトリに保存されているメディアを削除しません。

古いルームイベントをオンデマンドで削除する

一度限りのクリーンアップには、Synapse Purge History Admin API を使用してください。これにはサーバー管理者アクセストークンが必要です。個々のルームの管理者であることと、同じ権限を持つことはできません。Synapse では、Admin API を一般公開せず、通常はサーバーまたは信頼できる管理ホストからこれらのリクエストを行うことを推奨しています。ライブアクセストークンを共有シェル履歴、チケット、またはログに貼り付けないでください。

リクエストでは、イベントIDまたはミリ秒単位のUnixタイムスタンプを使用してカットオフを指定する必要があります。以下のシェルスクリプトの例は参考用です。ホームサーバー、ルームID、トークン変数、およびサンプルカットオフを、ご自身で確認した値に置き換えてください。この例では、ローカルユーザーのメッセージイベントの削除も明示的に要求しています。

export SYNAPSE_ADMIN_TOKEN='replace-with-a-server-admin-token'
PURGE_CUTOFF_MS=1760000000000  # replace with the approved UTC cutoff

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $SYNAPSE_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  --data "{\"purge_up_to_ts\": $PURGE_CUTOFF_MS, \"delete_local_events\": true}" \
  "https://matrix.example.org/_synapse/admin/v1/purge_history/!room:example.org"

がない場合はdelete_local_events: true、Synapse はデフォルトでローカル ユーザーが送信したイベントを保持します。リモートから送信されたイベントは削除できます。メンバーシップやトピックの状態などのルームの状態は保持されます。Synapse は各ルームに少なくとも 1 つのメッセージを保持します。この操作には数分以上かかる場合があり、実行中は削除対象の部分をページ送りしてさらに遡ることはできません。API はすぐにパージ ID を返します。/_synapse/admin/v1/purge_history_status/<purge_id>ステータスが になるまでポーリングするcompleteか、 の場合はエラーを調査してくださいfailed。カットオフを選択する前に、パージ履歴 API のドキュメントを参照してください。特に、ローカル イベントの削除がルームに適しているかどうかを確認してください。

ローカルメディアとリモートキャッシュを個別にクリーンアップします。

定期的なクリーンアップには、media_retentionユーザーに約束する可用性に見合った有効期間を選択してください。一度限りのクリーンアップには、Synapse が提供する個別のエンドポイントを使用できます。

• ローカルメディア： POST /_synapse/admin/v1/media/delete?before_ts=<timestamp_ms>最終使用時間に基づいて、対象となるローカルメディアを削除します。APIはサイズしきい値も受け付けます。プロフィールとルームアバターのメディアはデフォルトで保持されます。意図的に影響を検討しない限り、この保護機能を無効にしないでください。
• キャッシュされたリモートメディア： POST /_synapse/admin/v1/purge_media_cache?before_ts=<timestamp_ms>最終アクセスが期限前だったキャッシュされたリモートメディアを削除します。ユーザーが後で削除されたリモートファイルを要求した場合、Synapse は元のホームサーバーから再度ファイルを要求できます。

どちらのエンドポイントも、ミリ秒単位の正のUnixタイムスタンプを使用し、メディアの削除タイミングはアップロード日や作成日ではなく、最終アクセス日に基づいています。ローカルメディア削除APIは、リモートファイルのローカルキャッシュコピーを含むSynapse独自のストレージからファイルとサムネイルを削除します。外部メディアリポジトリは削除しません。レスポンスには、削除されたアイテム数が報告されます。リクエストを実行する前に、Synapseメディア管理APIで現在のパラメータとエンドポイントの詳細を確認してください。

Northstarの例では、管理者はまず承認済みのポリシーに対してカットオフをテストし、エンドポイントから返されるIDまたはカウントが期待値と一致するかどうかを確認します。リモートキャッシュが唯一の増加要因である場合、ローカルアップロードを削除するのは誤った操作です。ローカルアップロードを常に利用可能にしておく必要がある場合は、ローカルの有効期間を長く設定するか、ローカルメディア削除エンドポイントの使用を避けてください。

結果を測定し、必要に応じて方針を変更する。

各ジョブの実行後、パージが正常に完了したことを確認し、API応答数をチェックし、代表的なルームに想定される履歴境界が表示されていることを確認し、データベースとメディアストアの使用状況を個別に比較してください。データベース行数の減少が、オペレーティングシステムのディスク使用量の同等の減少としてすぐに反映されるとは限りません。データベース領域の解放は、データベースエンジンとそのメンテナンス手順に依存します。データベースファイルを手動で削除するのではなく、データベースベンダーのガイダンスに従ってください。

データベースが縮小してもメディアストアが縮小しない場合は、メディア保持、メディアワーカーenable_media_repo、隔離または保護状態、およびファイルが外部に保存されているかどうかを確認してください。メディアの使用量が減少しても古いメッセージが残っている場合は、メディアのみが削除されたため、これは想定される動作です。イベントが予期せず残っている場合は、保持が有効になっているか、ルームに独自の保持状態があるか、ローカルイベントが意図的に保存されているか、および削除状態が完了しているかを確認してください。

Northstarにとっての成功基準は、単に「ディスク容量が小さくなった」ということではありません。承認された古い履歴の境界が明確に表示され、必要な最新のメッセージと添付ファイルが正常に機能し、意図したメディアカテゴリがクリーンアップされ、両方のバックアップが引き続き利用可能であることです。これらのチェックが失敗した場合は、それ以上のパージを停止し、クリーンアップの範囲を広げる前に、ルームポリシー、API応答、ワーカー構成、およびストレージバックエンドを検査してください。

留意すべき制限事項

保持ポリシーは、組織の法的レビューや記録保持レビューの代わりとなるものではありません。フェデレーションとは、他のホームサーバーがイベントやメディアのコピーを独自に保持する可能性があることを意味し、Synapseはそれらのサーバーからの削除を保証できません。リモートメディアの削除は、このサーバーのキャッシュを削除するだけで、元のホームサーバー上のソースファイルを削除するわけではありません。同様に、Synapseからローカルのイベントやメディアオブジェクトを削除しても、他の参加者が既にダウンロードしたコピーは復元されません。

繰り返し適用可能なポリシーが必要な場合は、スケジュールされた保持機能を使用してください。レビュー済みの対象を絞ったクリーンアップには、管理APIを使用してください。これらの2つの操作は成功シグナルと効果が異なるため、変更記録では分けて記録してください。