清理舊的 Synapse 訊息和媒體檔案而不遺失數據

為了安全地刪除舊的 Matrix Synapse 數據,請將房間歷史記錄和媒體檔案作為單獨的任務處理。使用「清除歷史記錄管理 API」清除舊的房間事件,使用媒體文件刪除 API 清除本機媒體文件,使用遠端媒體快取 API 清除從其他主伺服器下載的文件。對於定期清理,請為訊息和媒體檔案配置保留策略。清除資料庫行並不總是會立即縮小磁碟上的資料庫檔案大小。

選擇符合您目標的清理方式

什麼東西佔據了空間?使用重要限制
舊消息和其他房間事件清除歷史記錄管理 API 或自動訊息保留歷史記錄清除是針對特定房間的。房間狀態會被保留;Synapse 會在每個房間中至少保留一則訊息。
您的家庭伺服器儲存的媒體刪除本機媒體 API 或本機媒體保留個人資料和房間頭像中使用的媒體預設受日期/大小端點保護。
從其他伺服器快取的媒體清除遠端媒體 API 或遠端媒體保留如果再次請求,Synapse 會再次從來源伺服器取得該檔案。

這些控制選項會影響 Synapse 本身的資料庫和媒體庫。如果您使用外部媒體庫(例如 Matrix Media Repository),Synapse 的本機媒體刪除端點不會刪除儲存在其中的檔案。刪除資料前,請務必查看該媒體庫的文件和備份策略。

清洗前做好準備

  1. 確認哪個 Synapse 執行個體負責處理媒體。在工作進程部署中,媒體清理會在工作進程上運行enable_media_repo: true;這可能是主進程。在診斷清理程序似乎未執行的問題之前,請先確認您的路由和設定。
  2. 備份資料庫和媒體儲存。在進行不可逆清除作業之前,請先製作一個可還原的最新備份。記錄房間 ID 和截止時間,並使用伺服器管理員存取令牌。請勿將令牌貼到共用 shell 歷史記錄中或將其發佈到日誌中。
  3. 仔細規劃截止時間。清除端點接受以 Unix 毫秒為單位的時間戳記。使用基於 UTC 的截止時間,並在發送請求之前驗證該時間值。截止時間並非預覽:它可能會永久刪除符合條件的資料。

在下列範例中,請將 `<your homeserver_client_base_URL>` 替換https://matrix.example.com為您的 homeserver 的用戶端基本 URL,設定有效的房間 ID,並在 `<your homeserver_client_base_URL>` 中匯出管理員代幣ADMIN_TOKEN。請將 bearer token 保密。

刪除房間內的舊訊息記錄

清除歷史記錄 API 會從 Synapse 資料庫中刪除指定時間點之前的事件。它不會編輯其他伺服器的訊息,也不同於刪除房間。默认情况下,Synapse 会删除远程用户发送的事件,但保留本地用户的事件;只有当您也想删除本地用户的事件时才delete_local_events需要进行设置true。房間狀態(例如會員資格和主題)會被保留。

例如,要在 Linux 主機上設定當前時間前 180 天的截止時間,請計算毫秒時間戳,檢查該時間戳,然後提交單一房間的請求:

export SYNAPSE_URL='https://matrix.example.com'
export ROOM_ID='!roomid:example.com'
export ADMIN_TOKEN='replace-with-a-server-admin-token'
PURGE_BEFORE_MS=$(python3 -c 'import time; print(int((time.time() - 180*86400) * 1000))')
printf 'Cutoff (Unix milliseconds): %s\n' "$PURGE_BEFORE_MS"

curl -sS -X POST "$SYNAPSE_URL/_synapse/admin/v1/purge_history/$ROOM_ID" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"purge_up_to_ts\":$PURGE_BEFORE_MS,\"delete_local_events\":true}"

如果希望使用 Synapse 的預設行為,請省略delete_local_events或將其設為 false false。如果 API 傳回purge_id,則表示清除作業已開始,但不一定已完成。輪詢狀態端點,直到其報告complete或檢查其error狀態(如果狀態為 )failed:

curl -sS "$SYNAPSE_URL/_synapse/admin/v1/purge_history_status/$PURGE_ID" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

大規模清除操作可能需要幾分鐘甚至更長時間。操作期間,使用者可能無法從被清除的位置繼續翻閱該房間的記錄。 Synapse 會在每個房間中保留至少一則訊息,因此此 API 不會將房間的時間軸完全清空。

刪除舊媒體檔案和快取的遠端文件

若要一次清理截止日期前最後使用的本機媒體文件,請使用目前本機媒體端點。該端點before_ts是一個以毫秒為單位的 Unix 時間戳,並且還可以指定size_gt要清理的檔案大小超過指定的位元組閾值。預設情況下,該端點會保留仍用於個人資料或房間頭像的媒體檔案;keep_profiles=false除非您有意要刪除這些文件,否則請勿設定此參數。

curl -sS -X POST "$SYNAPSE_URL/_synapse/admin/v1/media/delete?before_ts=$PURGE_BEFORE_MS" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

請檢查回應total和已刪除的媒體 ID。此端點會刪除本機原始檔案和縮圖。請避免使用包含 `;` 的舊路徑/media/<server_name>/delete;Synapse 文件已將該路徑標記為自 v1.78.0 起已棄用。目前的本機媒體端點不支援單獨的外部媒體儲存庫。

快取的遠端媒體屬於單獨的類別。若要刪除快取中上次存取時間早於同一截止時間的遠端媒體,請使用:

curl -sS -X POST "$SYNAPSE_URL/_synapse/admin/v1/purge_media_cache?before_ts=$PURGE_BEFORE_MS" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

此回應報告了已刪除的快取項目數量。如果使用者稍後要求這些文件,Synapse 可能會從來源伺服器重新下載它們,因此此操作以本地磁碟使用量為代價,換取了可能的網路流量和檢索延遲。

設定定期保留策略,而不是重複手動清除。

Synapse 訊息保留功能預設為停用狀態。若要為沒有獨立保留狀態的聊天室強制執行伺服器範圍的預設設置,請在配置中新增策略並啟用它。以下範例設定最長保留期限為一年:

retention:
  enabled: true
  default_policy:
    max_lifetime: 1y

使用 Synapse 支援的持續時間單位,例如d天和y年。房間管理員和版主還可以設定房間的m.room.retention狀態事件,而伺服器管理員可以使用 `--max-lifetime-time` 和 `--max-lifetime-time` 設定允許的最大生命週期allowed_lifetime_min。allowed_lifetime_max啟用策略前,請仔細閱讀完整內容:符合條件的事件會被背景清除作業永久刪除。 Synapse 會在事件過期後立即對用戶端隱藏過期事件,但資料庫清除作業會定期執行,因此某些行可能會一直保留到清除作業運行為止。狀態事件不受訊息保留策略的保護。

對於媒體,新增media_retention生命週期,例如:

media_retention:
  local_media_lifetime: 90d
  remote_media_lifetime: 14d

這些生命週期指的是非活動期,而不僅僅是上傳時間限制:如果檔案已被訪問,Synapse 會使用其最後一次訪問時間;對於從未被訪問過的媒體,則使用其建立時間。原始文件和縮圖將被刪除。隔離的媒體和受隔離保護的本機媒體不會被此清理操作刪除。請在託管媒體庫的進程上設定媒體保留策略,然後根據您執行的 Synapse 版本的設定手冊驗證此設定。

在進行任何變更之前,請先閱讀官方的「清除歷史記錄 API」、「媒體管理 API」、「Synapse 設定手冊」和「郵件保留策略」文件。此處所述的 API 行為反映了 2026 年 10 月 10 日核實的官方文件;請根據您已安裝的版本確認端點和配置。

確認儲存空間已回收。

  • 輪詢歷史記錄清除狀態,直到顯示「已清除」complete;將清除 ID 和回應儲存到維護日誌中。
  • 檢查本機媒體和遠端快取回應的已刪除計數,然後在清理後檢查 Synapse 日誌和檔案系統使用情況。
  • 不要以為資料庫行數減少就代表資料庫檔案變小。 Synapse 的文檔指出,PostgreSQL 可能會重複使用已釋放的空間,而不會將其回饋給作業系統。對於 PostgreSQL,VACUUM FULL可以使用 VACUUM 操作回收磁碟空間,但這需要獨佔鎖定;因此,在安排此操作時,請考慮停機時間和影響,並遵循PostgreSQL VACUUM 文件。對於 SQLite,Synapse 的保留策略文件中指出了VACUUM對應的操作。
  • 在關閉維護任務之前,請確認預期文件或較舊的事件不再提供服務,並驗證您的備份仍然可用。

留下評論

無需猜測即可提高 Synapse 的 Systemd 檔案限制

無需猜測即可提高 Synapse 的 Systemd 檔案限制

診斷 Synapse 是否達到其每個程序開啟檔案上限,為正確的服務或工作進程設定 systemd drop-in,並驗證即時限制。

元素顯示“解密失敗”?恢復遺失的房間鑰匙

元素顯示“解密失敗”?恢復遺失的房間鑰匙

確定錯誤是否僅限於一個瀏覽器或一個事件,然後使用 Element 的恢復金鑰或受信任的設備,而不會危及您剩餘的加密歷史記錄。

清理舊的 Synapse 訊息和媒體檔案而不遺失數據

使用 Synapse 的歷史記錄和媒體清除 API 或保留設定安全地刪除過期數據,然後驗證完成情況和磁碟空間恢復情況。

使用 Simple-Matrix-Bot-Lib 在 Python 中建立矩陣迴聲機器人

使用 Simple-Matrix-Bot-Lib 在 Python 中建立矩陣迴聲機器人

安裝目前庫,連接專用 Matrix 帳戶,並運行一個小型 !echo 機器人,該機器人具有更安全的憑證處理和清晰的測試。

使用獨立橋接器將 Matrix 連接到 WhatsApp、Telegram 和 Discord

使用獨立橋接器將 Matrix 連接到 WhatsApp、Telegram 和 Discord

設定三個 Mautrix 橋接器,分別進行註冊、登入和測試-避免 Docker 網路、帳號原則和同步方面的意外情況。

無需破壞共用檔案即可回收 Synapse 媒體磁碟空間

尋找 Synapse 儲存空間佔用情況,設定安全媒體保留策略,並在不直接從磁碟刪除檔案的情況下清除遠端快取。

停用不活躍的矩陣用戶,而不刪除房間歷史記錄

停用不活躍的矩陣用戶,而不刪除房間歷史記錄

查看裝置活動,透過管理 API 停用已確認的非活動 Synapse 帳戶,並了解可選的擦除標誌實際刪除了哪些內容。

降低 Matrix Synapse 中的 PostgreSQL 記憶體壓力

找出 PostgreSQL 記憶體消耗是來自查詢工作、共享緩衝區、連接還是維護,然後進行有針對性的、Synapse 安全的變更。

為什麼 Matrix Synapse 會議室加入速度慢——以及需要檢查哪些方面

為什麼 Matrix Synapse 會議室加入速度慢——以及需要檢查哪些方面

在變更 Synapse 設定之前,請追蹤 Matrix 房間加入速度慢的原因,例如遠端 homeserver、聯盟退避、本機資料庫載入或出站傳送佇列。

關閉 Synapse 上的 Matrix 註冊或要求使用邀請令牌

停止在自架 Synapse 伺服器上建立公開帳戶,或保持註冊僅限邀請,並限制註冊令牌的使用次數。