如何在 Matrix Synapse 中清除舊的訊息歷史記錄和媒體文件

範例場景（僅供參考）：假設非營利組織 Northstar Community 運行著 Matrix Synapse 家庭伺服器。其資料庫和媒體庫不斷增長，管理員希望刪除舊的聊天記錄和過時的媒體文件，同時避免誤刪當前的討論或個人資料圖片。此範例並非實際部署或測試結果的報表。

關鍵在於將郵件歷史記錄和媒體檔案視為獨立的清理任務。 Synapse 提供了房間歷史記錄清除 API 和獨立的媒體文件清理工具；媒體文件保留設定也可以刪除文件，但引用這些文件的 Matrix 事件仍然保留。首先確定哪些內容必須保留，然後備份資料庫和媒體文件存儲，選擇合適的備份方法，並在備份完成後驗證這兩個儲存區域。

確定你的伺服器中「舊」的定義。

在變更配置或呼叫破壞性端點之前，請先制定保留規則。以 Northstar 為例，假設董事會批准將普通會議室歷史記錄保留 180 天，本地上傳內容也採用類似策略，並將遠端媒體視為緩存，以便在需要時再次取得。其他組織可能出於法律、營運或社區原因需要保留數年。這些時間段僅供參考，並非普遍適用的建議。

將數據分為兩類：

房間事件：儲存在 Synapse 資料庫中的消息和其他事件。清除事件會改變使用者可以瀏覽房間記錄的時間範圍。
媒體檔案：上傳的檔案、縮圖以及來自其他伺服器的檔案快取副本。這些檔案儲存在媒體庫或已配置的外部儲存庫中。

Synapse 的官方文件分別描述了事件和媒體清理的保留策略。房間歷史記錄的清除本身並不能證明媒體儲存已被清理，刪除媒體檔案也不會刪除與其關聯的事件。首先，請記錄資料庫大小、媒體儲存大小、受影響的房間以及預期的截止時間。請參閱Synapse 設定手冊。

清除之前請先備份

請使用資料庫引擎建議的步驟備份資料庫，並同時備份媒體庫或外部媒體儲存。僅備份資料庫無法保留已上傳的檔案；僅備份媒體庫無法還原房間事件。在繼續操作之前，請確認備份檔案可讀，並且您知道如何還原它們。如果 Synapse 運行在容器中或使用獨立的 worker，請將相關的設定和儲存磁碟區包含在您的維護計畫中。

對於 Northstar 的假設伺服器，管理員會在操作共享房間之前記錄資料庫和媒體儲存的大小，並確認最近的還原點。這樣做很有用，因為只有在刪除目標資料的同時保留所需內容可恢復的情況下，「清理」才算成功。

選擇定期保留策略以進行持續清理。

如果您希望 Synapse 持續套用策略，請在 homeserver 設定中分別設定事件保留和媒體保留。例如，管理員可以針對已批准的策略調整此範例，該策略規定會議室歷史記錄和本地媒體保留 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狀態事件的房間；房間管理員可以設定房間策略，而伺服器管理員可以使用文件中規定的允許生存期設定來限制策略的生存期。如果您需要一致的上限，請檢查這些控制項以及已使用的房間策略，而不是假設預設設定涵蓋所有房間。

媒體文件的生命週期是基於媒體項目上次被訪問至今的時間。如果某個媒體項目從未被訪問過，Synapse 將使用其建立時間。此設定適用於原始檔案和縮圖；未設定或為空生命週期的檔案不會清除該媒體類別。遠端快取的媒體項目在清除後仍可從其來源檔案再次要求。隔離的媒體和本地保護的媒體是例外，不受這些保留設定的影響。媒體清理操作在已enable_media_repo啟用此功能的 Synapse 進程或工作進程上執行。請查看目前的保留策略和 media_retention 參考文檔，然後使用適用於您安裝的常規重新啟動或部署流程套用設定。

在採用範例之前，請將其行為與您的需求進行比較。如果房間訊息及其附件必須保持可讀狀態 180 天，除非您接受訊息的保存期限可能超過本機檔案的保存期限，否則請勿選擇更短的媒體保存期限。請檢查您的媒體是儲存在 Synapse 本身還是外部媒體儲存庫中；Synapse 的本機媒體刪除 API 不會刪除儲存在外部儲存庫中的媒體。

按需清除舊的房間事件

一次清理作業請使用 Synapse 的「清除歷史記錄」管理 API。此操作需要伺服器管理員存取權杖；擁有單一房間的管理員權限與此不同。 Synapse 建議將管理 API 對公眾隱藏，並通常從伺服器或受信任的管理主機發出這些請求。請勿將有效的存取權杖貼到共用的 shell 歷史記錄、工單或日誌中。

請求必須使用事件 ID 或以毫秒為單位的 Unix 時間戳記指定截止時間。以下 shell 範例僅供參考。請將 homeserver、房間 ID、token 變數和範例截止時間替換為您已審核過的值。此範例也明確要求刪除本機用戶訊息事件：

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 也會在每個房間中保留至少一則訊息。此操作可能需要幾分鐘或更長時間，並且在操作進行期間，使用者無法翻閱正在清除的部分。 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。請在變更記錄中將這兩種操作分開，因為它們的成功訊號和效果不同。