無需猜測即可提高 Synapse 的 Systemd 檔案限制
診斷 Synapse 是否達到其每個程序開啟檔案上限,為正確的服務或工作進程設定 systemd drop-in,並驗證即時限制。
為了安全地刪除舊的 Matrix Synapse 數據,請將房間歷史記錄和媒體檔案作為單獨的任務處理。使用「清除歷史記錄管理 API」清除舊的房間事件,使用媒體文件刪除 API 清除本機媒體文件,使用遠端媒體快取 API 清除從其他主伺服器下載的文件。對於定期清理,請為訊息和媒體檔案配置保留策略。清除資料庫行並不總是會立即縮小磁碟上的資料庫檔案大小。
| 什麼東西佔據了空間? | 使用 | 重要限制 |
|---|---|---|
| 舊消息和其他房間事件 | 清除歷史記錄管理 API 或自動訊息保留 | 歷史記錄清除是針對特定房間的。房間狀態會被保留;Synapse 會在每個房間中至少保留一則訊息。 |
| 您的家庭伺服器儲存的媒體 | 刪除本機媒體 API 或本機媒體保留 | 個人資料和房間頭像中使用的媒體預設受日期/大小端點保護。 |
| 從其他伺服器快取的媒體 | 清除遠端媒體 API 或遠端媒體保留 | 如果再次請求,Synapse 會再次從來源伺服器取得該檔案。 |
這些控制選項會影響 Synapse 本身的資料庫和媒體庫。如果您使用外部媒體庫(例如 Matrix Media Repository),Synapse 的本機媒體刪除端點不會刪除儲存在其中的檔案。刪除資料前,請務必查看該媒體庫的文件和備份策略。
enable_media_repo: true;這可能是主進程。在診斷清理程序似乎未執行的問題之前,請先確認您的路由和設定。在下列範例中,請將 `<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 和回應儲存到維護日誌中。VACUUM FULL可以使用 VACUUM 操作回收磁碟空間,但這需要獨佔鎖定;因此,在安排此操作時,請考慮停機時間和影響,並遵循PostgreSQL VACUUM 文件。對於 SQLite,Synapse 的保留策略文件中指出了VACUUM對應的操作。診斷 Synapse 是否達到其每個程序開啟檔案上限,為正確的服務或工作進程設定 systemd drop-in,並驗證即時限制。
確定錯誤是否僅限於一個瀏覽器或一個事件,然後使用 Element 的恢復金鑰或受信任的設備,而不會危及您剩餘的加密歷史記錄。
使用 Synapse 的歷史記錄和媒體清除 API 或保留設定安全地刪除過期數據,然後驗證完成情況和磁碟空間恢復情況。
安裝目前庫,連接專用 Matrix 帳戶,並運行一個小型 !echo 機器人,該機器人具有更安全的憑證處理和清晰的測試。
設定三個 Mautrix 橋接器,分別進行註冊、登入和測試-避免 Docker 網路、帳號原則和同步方面的意外情況。
尋找 Synapse 儲存空間佔用情況,設定安全媒體保留策略,並在不直接從磁碟刪除檔案的情況下清除遠端快取。
查看裝置活動,透過管理 API 停用已確認的非活動 Synapse 帳戶,並了解可選的擦除標誌實際刪除了哪些內容。
找出 PostgreSQL 記憶體消耗是來自查詢工作、共享緩衝區、連接還是維護,然後進行有針對性的、Synapse 安全的變更。
在變更 Synapse 設定之前,請追蹤 Matrix 房間加入速度慢的原因,例如遠端 homeserver、聯盟退避、本機資料庫載入或出站傳送佇列。
停止在自架 Synapse 伺服器上建立公開帳戶,或保持註冊僅限邀請,並限制註冊令牌的使用次數。