修正 Matrix Synapse 媒體儲存庫佔用過多磁碟空間的問題

Matrix Synapse 媒體庫佔用磁碟空間的速度可能比主伺服器資料庫更快，因為它包含多種不同類型的檔案：本機使用者上傳的媒體檔案、縮圖、從遠端主伺服器取得的快取媒體檔案以及用於 URL 預覽的資源。正確的解決方法並非隨意刪除媒體目錄中的檔案。首先應該確定哪些檔案正在成長，然後使用 Synapse 的管理 API 或保留策略，以確保資料庫元資料和磁碟上的檔案保持一致。

截至 2026 年 10 月，Synapse 的最新版本為 1.162，官方媒體管理文件包含用於查詢媒體、刪除本地媒體、清除快取的遠端媒體以及配置自動保留策略的 API。如果您的Synapse 安裝版本較舊，請查看官方版本說明，因為不同版本之間的端點行為和設定選項可能有所不同。

快速分診檢查清單

問題	需要檢查什麼	下一步最佳行動
檔案系統真的快滿了嗎？	`df -h`	確認哪個已掛載的檔案系統包含媒體儲存。
Synapse Media 是主要消費市場嗎？	`du -sh <media_store_path>`	刪除任何內容之前，請先與其他大型目錄進行比較。
遠端快取是最大的類別嗎？	`du -sh <media_store_path>/* \| sort -h`	先清除舊的遠端媒體；通常可以再次取得。
本地用戶媒體是主要類別嗎？	管理員 API 媒體列表和年齡/尺寸數據	制定明確的本地媒體保留策略；刪除是永久性的。
成長會持續嗎？	`media_retention`上傳限制、監控	新增自動保留和容量提醒功能。

1. 確認媒體儲存庫是磁碟空間不足的問題所在

首先從檔案系統入手，而不是從 Synapse 開始。運行：

df -h
du -sh /path/to/media_store

路徑取決於特定的安裝方式。 Synapse 的media_store_path設定定義了用於上傳圖片和配件的目錄，其預設路徑是media_store相對於 Synapse 資料目錄的相對路徑。發行版軟體包和容器部署通常會設定一個明確的路徑，因此請檢查您的實際配置，而不是隨意假設路徑。

Linux 終端機顯示根檔案系統幾乎已滿，並且有一個很大的 Matrix Synapse media_store 目錄。

標題：在確定清理媒體是否是正確的解決方法之前，請將檔案系統使用情況與配置的 Synapse 媒體儲存的大小進行比較。

如果磁碟空間即將用完，請避免在同一檔案系統上執行會建立大型暫存檔案或備份的大規模遞歸作業。如果空間即將耗盡，請先停止無關的寫入密集型作業或新增臨時儲存空間，然後以可控的方式執行清理工作。

2. 驗證活動介質配置並確定哪些內容正在成長

打開活動資料夾homeserver.yaml並尋找media_store_path。同時檢查max_upload_size所有設定、任何選項media_storage_providers以及任何現有media_retention區塊。官方Synapse 設定手冊中記錄了這些選項。

Synapse homeserver.yaml 檔案顯示了 server_name、media_store_path 和 max_upload_size 設定

說明：media_store_path測量或變更儲存媒體前，請確認目前儲存媒體是否處於作用中狀態。此處所示路徑僅為配置範例。

接下來，測量一級子目錄：

du -sh /path/to/media_store/* 2>/dev/null | sort -h

Synapse 的媒體庫文件描述了重要的磁碟類別。本機上傳的檔案儲存在以下位置local_content，本地縮圖儲存在以下位置local_thumbnails，快取的遠端檔案儲存在以下位置remote_content，遠端縮圖儲存在以下位置remote_thumbnail，URL 預覽資料儲存在以下位置url_cache和以下位置url_cache_thumbnails。

Linux 終端機顯示了 Synapse local_content、local_thumbnails、remote_content、remote_thumbnail 和 URL 快取目錄的大小排序明細。

標題：目錄級大小細分有助於區分可恢復的遠端快取和本地用戶上傳的文件，後者可能是您的家庭伺服器儲存的唯一副本。

請勿將rm -rf這些目錄內部的文件清理方法作為常規清理方法。 Synapse也會追蹤其資料庫中的媒體檔案。繞過支援的清理路徑可能會導致元資料指向已不存在的文件，或刪除使用者仍希望檢索的內容。

3. 當遠端媒體快取是主要消耗者時，優先回收它

通常情況下，快取的遠端媒體是回收空間風險最低的地方。 Synapse 會儲存原本由其他伺服器所託管的媒體副本。官方的「清除遠端媒體」API 會刪除上次存取時間早於某個時間戳記的快取遠端媒體。如果使用者再次要求該媒體，Synapse 會再次從原始伺服器請求該媒體。

管理 API 需要伺服器管理員存取權杖。 Synapse 建議將其/_synapse/admin/...對公眾隱藏，通常在本地呼叫。請參閱官方管理 API 指南。

例如，計算過去 30 天的截止時間，並清除早於該時間的遠端快取：

export SYNAPSE_ADMIN_TOKEN='your-admin-token'
CUTOFF_MS=$(( $(date -d '30 days ago' +%s) * 1000 ))

curl -sS -X POST   -H "Authorization: Bearer $SYNAPSE_ADMIN_TOKEN"   "http://127.0.0.1:8008/_synapse/admin/v1/purge_media_cache?before_ts=$CUTOFF_MS"

響應中包含一個deleted計數。截止時間是基於上次存取時間，而不僅僅是文件修改時間。選擇一個與使用者通常瀏覽時間範圍相符的時間段。只有當來源伺服器仍然提供已清除的遠端內容時，才能再次取得這些內容。

4. 除非您有資料保留政策，否則請將本地媒體資料視為永久資料。

本地媒體檔案有所不同。它已上傳到您的主伺服器，因此刪除它可能會永久破壞附件、映像或其他 MXC 引用。在大量刪除本機媒體檔案之前，請透過管理 API 檢查代表性項目或使用者媒體檔案。

查詢特定媒體項目：

curl -sS   -H "Authorization: Bearer $SYNAPSE_ADMIN_TOKEN"   "http://127.0.0.1:8008/_synapse/admin/v1/media/example.org/MEDIA_ID"

回應可能包含media_length檔案、檔案類型created_ts、last_access_tsMIME 類型和隔離狀態。官方媒體管理 API 文件定義了這些欄位以及支援的刪除操作。

終端機顯示已通過驗證的 Synapse Admin API 媒體查詢和 JSON 字段，包括 media_length、created_ts 和 last_access_ts。

說明：在應用刪除規則之前查詢媒體元數據，以便根據 Synapse 的記錄而不是檔案系統時間戳來決定媒體的年齡和大小。

Synapse 可以按最後存取日期刪除本機媒體，也可以選擇按大小刪除：

CUTOFF_MS=$(( $(date -d '180 days ago' +%s) * 1000 ))

curl -sS -X POST   -H "Authorization: Bearer $SYNAPSE_ADMIN_TOKEN"   "http://127.0.0.1:8008/_synapse/admin/v1/media/delete?before_ts=$CUTOFF_MS&size_gt=0&keep_profiles=true"

before_ts是 Unix 時間戳，單位為毫秒，表示上次造訪時間。size_gt是位元組閾值，預設值為零。keep_profiles=true是預設值，會保留仍用作個人資料或房間圖像的媒體。除非有特殊原因需要刪除這些影像，否則請保留此保護。

您也可以列出或刪除特定本機使用者上傳的媒體檔案/_synapse/admin/v1/users/<user_id>/media。當某個帳戶導致媒體檔案數量異常增長時，此功能非常有用。在使用刪除操作之前，請務必查看使用者管理 API 文檔，特別是其排序和限制參數。

5. 防止媒體儲存再次填滿磁碟

啟用自動介質保留

Synapse 提供持續控制功能media_retention。以下是一個基於官方配置格式的範例：

media_retention:
  local_media_lifetime: 180d
  remote_media_lifetime: 30d

如果媒體文件在設定的有效期內未被訪問，則會被移除。如果從未被訪問過，Synapse 會使用其建立時間作為移除條件。原始文件和縮圖都會被移除。如果省略或設定為空的有效期，則該類別不會自動清除。

謹慎選擇本機值：與遠端快取不同，已刪除的本機媒體無法透過簡單地向另一台伺服器請求原始檔案來復原。隔離的媒體不會被自動保留刪除，受保護的本機媒體也會根據設定文件被排除在外。

使用上傳控制功能以促進未來成長

max_upload_size它限制每次上傳的大小，但不限制儲存庫的總大小。目前的 Synapse 版本也支援media_upload_limits限制使用者在特定時間內的上傳量。這些控制措施可以減少成長，但不能取代保留策略或容量監控。

當本機檔案系統成為瓶頸時，請考慮使用儲存供應商

Synapse 支援media_storage_providers多種儲存介質，包括可將媒體放置在其他目錄中的檔案系統提供者。如果您擁有專用儲存磁碟區或儲存層，這將非常有用。這是一種儲存架構變更，而非緊急清理命令，因此在遷移生產媒體之前，請務必測試備份、權限、工作進程存取權限和復原行為。

清理後的驗證

每次清除資料後，請驗證容量和應用程式運行：

df -h
du -sh /path/to/media_store
du -sh /path/to/media_store/* 2>/dev/null | sort -h

在 Matrix 用戶端中開啟最近本機上傳的附件。
打開一個較早的遠端附件，並確認是否可以再次取得它。
檢查 Synapse 日誌，查看是否有媒體工作進程或檔案系統錯誤。
如果您使用專用媒體工作進程，請確認管理 API 要求已路由至媒體儲存庫工作進程。 Synapse 的工作流程文件列出了必須在那裡處理的媒體特定管理端點。
清理後記錄媒體儲存規模，幾天後再次進行比較，以衡量實際成長率。

快速決策參考

什麼是大？	首選回覆	主要風險
`remote_content`/`remote_thumbnail`	按上次存取截止時間清除遠端快取；然後設定`remote_media_lifetime`。	舊媒體檔案需要重新下載，如果來源網站不再提供服務，則可能無法使用。
`local_content`/`local_thumbnails`	定義業務保留規則，檢查媒體元數據，然後使用本地媒體管理 API。	伺服器上託管的內容一旦刪除，即為永久性刪除。
URL預覽快取	在手動介入之前，請確認 URL 預覽行為和目前的 Synapse 清理情況。	手動刪除檔案系統可能會導致儲存的元資料不同步。
所有類別都在持續成長	新增`media_retention`、上傳控制、監控或專用媒體儲存。	單靠清理工作只能延緩下一次產能事故的發生。

結論

當 Matrix Synapse 媒體庫填滿磁碟空間時，首先要確定是哪個媒體類別導致了這種情況。遠端快取通常是最安全的首選目標，因為 Synapse 擁有專用的清除 API，通常可以重新取得該內容。本地媒體需要更嚴格的策略，因為它可能是附件在伺服器端的唯一副本。一旦釋放了可用空間，就配置media_retention並監控媒體儲存的成長率，使清理工作成為可預測的維護任務，而不是緊急情況。