防止 Matrix Synapse 記憶體崩潰(客戶端同步期間)

如果 Matrix Synapse 在客戶端同步時記憶體不足,首先要確認 Linux 是否真的終止了 Synapse 進程,然後在正常/_matrix/client/v3/sync負載下測量記憶體使用量。如果問題出在快取成長上,請進行適度的快取調整,而不是立即強制設定一個極低的快取限制;緩慢的資料庫回應會導致請求積壓,從而使問題更加嚴重。

截至 2026 年 10 月 10 日,Synapse 官方發布歷史記錄顯示,最新穩定版本為 1.162.0(9 月 29 日),預發布版本為 1.163.0rc1。更新過時的版本是明智之舉,但僅憑版本號並不能診斷或保證修復與同步相關的記憶體耗盡問題。

1. 證明這是記憶體不足導致的故障

用戶端出現無限同步、網關錯誤或會話斷開連線等情況本身並不會觸發記憶體溢位 (OOM) 事件。在典型的 Linux systemd 安裝中,請檢查用戶端故障發生時間附近的核心日誌和服務日誌:

sudo journalctl -k --since "1 hour ago" | grep -Ei 'oom|out of memory|killed process'
sudo journalctl -u matrix-synapse --since "1 hour ago" --no-pager

尋找內核 OOM 終止訊息,其中可能包含 Synapse 或 Python 程序的名稱、systemd狀態(例如oom-kill`sudo % synapse ...MemoryErrorMemoryError

接下來,記錄主機壓力和最大進程數,同時重現一次普通的同步過程:

free -h
ps -eo pid,rss,%mem,args --sort=-rss | head -n 12
systemctl show matrix-synapse -p MemoryCurrent -p MemoryMax

RSS駐留記憶體以千位元組為單位,並非應用程式獨立記憶體的精確計量單位;共享頁面可能被多個進程佔用。在 Docker 容器中,還需檢查docker stats並設定容器記憶體限制。如果 PostgreSQL、Redis 和多個 Synapse 工作進程共享相同主機,則應評估它們的總記憶體佔用,而不是僅僅歸咎於 Synapse 主進程。

2. 保守地調整快取內存

Synapse 會刻意將最近事件和房間資料保存在記憶體中,以便快速回應同步請求。其預設caches.global_factor值為 1 0.5;降低此值通常會縮小緩存,但會增加資料庫操作的次數。 Synapse管理員常見問題解答警告說,在慢速儲存裝置上使用過小的快取會導致請求積壓,甚至增加整體記憶體使用量。

備份目前配置homeserver.yaml,檢查是否有caches:阻塞,然後僅變更相關值。這是一個針對快取使用量不斷增長的實例的試用配置,並非通用的調優目標:

caches:
  global_factor: 0.3
  sync_response_cache_duration: 1m

同步回應快取設定控制已完成/sync結果的快取保留時間;Synapse 文件中提供了2m預設值。較短的快取時間可能會減少保留的回應數量,但也可能增加連線不穩定的客戶端的工作量。如果已存在一個鍵,請勿新增第二個caches:鍵。如果您的安裝SYNAPSE_CACHE_FACTOR在其服務或容器環境中設定了該變量,則該變數的優先順序高於 YAML 檔案中的設定。

使用 Synapse 安裝所使用的 Python 環境驗證該文件,並根據需要調整配置路徑:

python -m synapse.config -c /etc/matrix-synapse/homeserver.yaml

僅在驗證後重啟。對於 Debian 風格的 systemd 打包,這通常是必要的sudo systemctl restart matrix-synapse;容器部署使用它們自己的編排機制。重新啟動後立即檢查服務日誌,查看是否有設定錯誤。 Synapse設定參考文件也介紹如何使用 `--reloading cache factors` 重新載入快取因子SIGHUP,但這並不代表其他設定(包括同步回應保留)也可以重新載入。同時更改這兩項設定可以更清楚地了解受控重啟過程。

3. 檢查慢同步是否累積

如果記憶體佔用持續上升而客戶端仍然卡頓,進一步降低快取可能適得其反。請比較 RSS 上升的時間與 CPU 壓力、磁碟 I/O 和資料庫活動。主機資源緊張或 PostgreSQL 查詢速度緩慢會導致更多並發請求,每個請求都可能在完成之前保留資料。

首先,請確認資料庫回應正常,磁碟空間和 I/O 狀況良好。生產環境的 Synapse 是為 PostgreSQL 而非 SQLite 設計的,詳情請參閱Synapse 設定參考文件。如果這是一個較舊的、基於 SQLite 的實例,請使用經過測試的備份文件,並規劃一次受支援的資料庫遷移;切勿嘗試在緊急情況下進行資料庫即時交換。

如果您之前將快global_factor取值降低到極低,導致同步延遲惡化,請恢復到先前的設置,或者嘗試稍高一些的設置,同時觀察響應時間和總記憶體使用情況。 Synapse 的Synapse 管理員常見問題明確指出,當後端速度慢導致排隊時,增加快取可以有所幫助。沒有一個固定的 RAM 目標值能夠完美適應所有房間數量、聯盟負載和部署佈局。

對於繁忙的多進程部署,請確定是主進程還是某個特定的同步工作進程正在成長。工作進程允許客戶端同步流量分散式處理,但每個工作進程也需要內存,因此在沒有額外容量的情況下添加工作進程可能會加劇主機內存不足 (OOM) 的壓力。請遵循Synapse 工作進程文檔,而不是在沒有進行必要共用配置的情況下將客戶端請求路由到任意工作進程。

4. 僅當滿足先決條件時才考慮快取自動調優。

在已支援並驗證了適當的 jemalloc 配置的系統上,Synapse 提供了相應的功能cache_autotuning。它需要所有三個已記錄的值max_cache_memory_usage——`$1`、target_cache_memory_usage`$2` 和min_cache_ttl`$3`——並使用快取驅逐機制來控制快取使用量,使其接近目標值。以下圖示僅供參考,實際使用量必須根據 Python、資料庫、其他服務以及突發的活躍請求量進行調整:

caches:
  cache_autotuning:
    max_cache_memory_usage: 512M
    target_cache_memory_usage: 384M
    min_cache_ttl: 5m

將此配置區塊與現有快取設定合併,而不是取代它們。這些數值是快取預算,而非進程 RSS 限制;使用這些數值並不能保證進程的快取佔用始終低於 512 MiB。 Synapse配置參考文件要求此功能使用 jemalloc,而Synapse 管理員常見問題則警告 Python 的分配器可能會幹擾 jemalloc 的記憶體佔用,從而導致需要進行其他PYTHONMALLOC=malloc配置。由於分配器的預先載入路徑和打包方式各不相同,因此在進行變更之前,請務必驗證部署環境中實際的程式庫和啟動環境LD_PRELOAD。切勿盲目複製特定於架構的庫路徑。

5. 驗證同步是否穩定

每次變更後,執行與先前觸發故障時相同的實際客戶端操作:重新連接現有客戶端,在條件允許的情況下進行初始同步,並等待幾次正常的增量同步。記錄所有 Synapse 程序的 RSS 峰值、交換活動、資料庫回應速度,以及核心是否記錄了其他 OOM 事件。重啟後立即出現的短暫下降並不能證明問題已持久解決;快取自然會在冷啟動時啟動。

如果啟用了監控,請使用 Synapse 的指標端點比較進程記憶體使用情況和請求行為隨時間的變化。 Synapse監控文件解釋說,工作流程會獨立揭露指標,因此必須單獨監控;請將指標端點設為私人或受保護,而不是公開發佈內部資料。

如果用戶端在同步過程中無需反覆重連即可完成同步,則日誌中沒有新的記憶體耗盡事件,並且在相同工作負載下記憶體穩定在一個可持續的水平,則此變更有效。如果即使同步延遲正常且快取已精心調優,OOM 問題仍然存在,則下一步切實可行的措施是增加可用記憶體或降低每個主機的工作負載,並根據實際測量的峰值消耗量而非任意推薦的伺服器配置來調整。

留下評論

透過操作解決矩陣房間管理員權限錯誤

追蹤 M_FORBIDDEN 到房間功率等級、成員資格或 Synapse 伺服器管理員存取權限,然後僅恢復被封鎖操作所需的權限。

讓您的 Matrix Synapse 伺服器可存取以進行聯邦通訊。

讓您的 Matrix Synapse 伺服器可存取以進行聯邦通訊。

設定 Synapse 發現、HTTPS 和代理路由,以便其他 Matrix 主伺服器可以找到並聯絡您的伺服器。

透過 Synapse OIDC 將 Element Web 連接到 Keycloak

配置 Keycloak OIDC 用戶端和 Synapse 提供程序,以便 Element Web 使用者可以透過您的身分伺服器登錄,而無需暴露客戶端金鑰。

安全地設定元素金鑰備份和交叉簽名

安全地設定元素金鑰備份和交叉簽名

儲存恢復金鑰,驗證您的 Element 會話,並檢查加密訊息金鑰是否可以恢復,而不會將備份與您的帳戶密碼混淆。

防止 Matrix Synapse 記憶體崩潰(客戶端同步期間)

診斷 Synapse 在同步過程中記憶體不足的故障,安全地調整緩存,識別請求積壓,並驗證穩定的記憶體使用量。

解決 Synapse Federation TLS 憑證錯誤

追蹤矩陣聯合憑證故障到正確的伺服器,修復 TLS 鍊或 CA 信任,並在不停用安全檢查的情況下驗證修復。

安全地將 Synapse Matrix 伺服器部署在 Cloudflare 之後

安全地將 Synapse Matrix 伺服器部署在 Cloudflare 之後

Route Matrix 用戶端和透過 Cloudflare 在 HTTPS 443 上進行聯合,可以保留 Synapse 探索功能,避免快取 API 流量或中斷媒體上傳。

使用 PostgreSQL 轉儲安全地還原 Matrix Synapse

使用 pg_dump 備份 Synapse,保護其簽章金鑰和介質,並將其還原到乾淨的 PostgreSQL 資料庫中,而無需重複使用過時的一次性金鑰。

使用 Docker 將 Mjölnir 運行為 Matrix Room 管理機器人

使用 Docker 將 Mjölnir 運行為 Matrix Room 管理機器人

使用專用 Matrix 帳戶、加密管理室、Docker Compose、政策清單和權限檢查來設定 Mjölnir。

啟用原生矩陣滑動同步,加快行動端載入速度

啟用原生矩陣滑動同步,加快行動端載入速度

跳過已停用的代理,配置 Synapse 內建的滑動同步功能。檢查客戶端發現情況,然後在相容的手機上測量房間清單載入和重新連接行為。