修正 Matrix Synapse 在 PostgreSQL 上資料庫記憶體使用率過高的問題

Matrix Synapse 伺服器看起來可能運作良好，但幾天後 PostgreSQL 卻突然佔用了機器的大部分可用記憶體。常見的症狀也很明顯：交換空間不斷成長，客戶端同步速度變慢，聯合作業排隊，原本配置不高的伺服器變得難以管理。首先，切勿想當然地認為 PostgreSQL 有記憶體洩漏。高記憶體使用率可能來自多個獨立來源，包括共享緩衝區快取、每個查詢的工作記憶體、多個資料庫後端、維護工作進程，以及由於統計資訊過時或表變更導致的低效查詢。

Synapse 的官方文件推薦生產環境使用 PostgreSQL，並公開了諸如 `--connection-pool-controls` 和 `--connection-pool-controls` 之類的資料庫連接池控制cp_min選項cp_max。而 PostgreSQL 則警告說，諸如 `--connection-pool-controls` 之類的設定work_mem可能會被單一查詢中的多個操作以及多個會話同時使用。正是由於這種組合，一些看似無害的設置，在高負載時期可能會造成巨大的性能開銷。最穩健的解決方法是先進行效能測量，其次減少不必要的並發，然後僅在效能測量結果明確的情況下調整記憶體和維護行為。

步驟 1：確認 PostgreSQL 確實是記憶體壓力來源。

先從作業系統層面入手。在Linux系統中，比較總記憶體、可用記憶體、交換空間、佔用記憶體最大的進程：

free -h
ps aux --sort=-%mem | head -n 15

不要僅憑單行進程資料來判斷伺服器效能。 PostgreSQL 後端進程同時使用共享記憶體和私有內存，因此真正重要的問題是主機是否真的面臨壓力：例如可用內存不足、交換空間不斷增長、內存溢出導致的進程終止，或者持續的延遲。分別在伺服器空閒期和繁忙期記錄相關資料。這樣建立的基準線能夠使後續的變更變得可量化，而不是靠猜測。

圖註：在進行任何配置變更之前，先進行記憶體檢查，將主機級可用 RAM 與 PostgreSQL 和 Synapse 進程進行比較。

接下來，檢查最有可能影響記憶體的 PostgreSQL 設定：

SHOW shared_buffers;
SHOW work_mem;
SHOW maintenance_work_mem;
SHOW autovacuum_work_mem;
SHOW max_connections;

PostgreSQL資源消耗文件描述了關鍵差異。 `$ shared_bufferscache` 是伺服器範圍的共用快取。與之相對的是，`$cache_file`work_mem是單一排序或哈希操作的記憶體使用量限制，超過限制後記憶體就會溢出到臨時檔案；一個複雜的查詢可能包含多個此類操作，並且多個會話可以並發運行這些操作。 PostgreSQL 目前將預設work_mem值設為 4 MB，並指出總使用量可能是該值的數倍。

標題：在更改 PostgreSQL 記憶體相關設定之前，請先閱讀這些設定；危險的值通常是設定和並發性的組合，而不是單一數字。

步驟 2：統計 Synapse 資料庫連線數並尋找活躍工作

大型連接池並非會自動work_mem為每個連接分配內存，而是每個 PostgreSQL 後端都有自己的進程和私有內存，並發查詢越多，每次操作分配內存的機會就越多。請檢查實際開啟的連線數及其狀態：

SELECT state,
       usename,
       application_name,
       count(*) AS connections
FROM pg_stat_activity
GROUP BY state, usename, application_name
ORDER BY connections DESC;

然後檢查長時間運行的活動查詢：

SELECT pid,
       usename,
       state,
       now() - query_start AS running_for,
       wait_event_type,
       wait_event,
       left(query, 180) AS query
FROM pg_stat_activity
WHERE state <> 'idle'
ORDER BY query_start;

官方文件pg_stat_activity解釋了會話和活動字段。大量空閒會話與少量高開銷的活動查詢情況不同，因此解決方法也應有所不同。如果問題出在連線數上，則應調整連線池大小。如果問題是少量記憶體密集型查詢，則僅降低連接池大小可能只是掩蓋了問題。

標題：分組pg_stat_activity可以更容易地區分許多空閒後端和較少的活動資料庫會話。

步驟 3：調整 Synapse PostgreSQL 連線池的大小

Synapse 會將大部分資料庫參數傳遞給 PostgreSQL，同時使用以 `--database-param-name` 開頭的選項來管理cp_其 Twisted 連線池。目前的Synapse PostgreSQL 指南cp_min: 5提供了一個包含 `--database-param -name` 和 ` --database-param-name`的範例cp_max: 10。請將這些值視為範例，而非通用目標值。

檢查database以下程式碼區塊homeserver.yaml：

database:
  name: psycopg2
  args:
    user: synapse_user
    password: "your-secret"
    dbname: synapse
    host: 127.0.0.1
    cp_min: 5
    cp_max: 10

如果您之前大幅提高了連線cp_max池大小，並且pg_stat_activity發現大量 Synapse 連線大多處於空閒狀態，請逐步降低連線池大小並觀察請求延遲。在基於 Worker 的 Synapse 部署中，請記住資料庫請求來自多個 Synapse 進程，因此應評估連接池的總連接數，而不是單獨評估單一 Worker 的連接數。 Synapse設定手冊確認了這些cp_選項用於設定連接池。

編輯配置後，請根據您的部署方式重新啟動受影響的 Synapse 進程，然後再次執行連線數查詢。不要為了節省幾兆位元組而減少連線池，直到請求開始排隊為止。連接池過小會導致資料庫並發性降低，進而造成應用程式延遲。

標題：Synapse 公開了cp_minPostgreSQLcp_max資料庫配置，讓管理員限制不必要的後端並發。

步驟 4：保守調整 PostgreSQL 內存

連接數達到合理水準後，應結合資料庫實際可用的記憶體（RAM）來檢查 PostgreSQL 的記憶體設定。 PostgreSQL 建議，在至少配備 1 GB 記憶體的專用資料庫伺服器上，系統記憶體的 25% 左右是一個合理的初始值shared_buffers。該建議明確針對專用資料庫伺服器。如果 Synapse、反向代理、Redis、監控程式和 PostgreSQL 共享一台小型虛擬機，則 PostgreSQL 並非擁有整台機器的資源，因此應相應地進行記憶體預算。

最容易讓管理員感到意外的設定是 `<max_name>` work_mem。避免將 `<max_name>`work_mem乘以max_connections`<max_name>` 並將其視為硬性預留；PostgreSQL 不會以這種方式預先分配記憶體。相反，應該從並發查詢操作的角度來考慮。單一查詢可以使用多個排序或雜湊節點，而雜湊操作可能需要 `<max_name>` 的倍數work_mem。如果work_mem因為某個報表速度慢而全域設定 `<max_name>` 為一個非常大的數字，那麼聯邦突發或同步密集期可能會導致比預期大得多的記憶體峰值。

一個合理的做法是保持全域值保守，僅在特定管理會話中，當已知查詢需要更多記憶體時才提高該值。在變更值之前，請保留現有設定並記錄哪些參數需要重新啟動 PostgreSQL。shared_buffers例如，`$_ROOT_ROOT_HOME` 就是一個伺服器啟動設定。更改應安排在計劃時間內進行，以便比較更改前後的記憶體使用情況、延遲和臨時檔案行為。

另請檢查`autovacuum_workers`maintenance_work_mem和 ` autovacuum_work_memautovacuum_workers`。 PostgreSQL 指出，自動清理工作進程可以並發分配維護記憶體。如果 `autovacuum_workers`autovacuum_work_mem保持其預設行為，異常大的maintenance_work_mem記憶體佔用會導致多個自動清理工作進程同時運行，從而增加記憶體消耗。不要為了節省記憶體而停用自動清理；這樣做通常會以短期記憶體不足為代價，換取表膨脹、統計資訊過時和效能下降。

步驟 5：檢查真空系統健康狀況，然後在實際負載下驗證修復效果。

Synapse 會寫入和更新大量的事件和狀態資料。 PostgreSQL 需要定期執行清理操作，以回收已失效的元組以供重用，並保持查詢規劃器統計資料的更新。 PostgreSQL常規清理指南建議大多數安裝使用自動清理（autovacuum）。

尋找包含大量估計已失效元組或過期維護時間戳記的表：

SELECT relname,
       n_live_tup,
       n_dead_tup,
       last_autovacuum,
       last_autoanalyze
FROM pg_stat_user_tables
ORDER BY n_dead_tup DESC
LIMIT 20;

如果某個表格明顯需要處理，VACUUM (ANALYZE)通常首先要考慮的是手動工具：

VACUUM (ANALYZE) your_table_name;

避免直接使用`VACUUM` VACUUM FULL。官方的 VACUUM 文件解釋說，常規的 `VACUUM`VACUUM操作可以與正常的讀寫操作同時進行，而 `VACUUM`VACUUM FULL會重寫磁碟表並加鎖ACCESS EXCLUSIVE。只有當回收磁碟空間值得為此造成計劃內的中斷時，才應使用後者。

如何判斷改變是否真正奏效

在與導致問題相同的工作負載下驗證結果。成功的修復並非僅僅是「Postgres 立即減少了記憶體使用量」。資料庫快取本來就應該佔用記憶體。相反，應該關注內存可用性是否穩定、交換空間是否幾乎沒有或完全沒有意外增長、是否發生內存溢出 (OOM) 事件、連接數是否符合預期並發量以及 Synapse 響應時間是否在可接受範圍內。

• 運行free -h並按照與基準相同的流量等級列出進程清單。
• 重複pg_stat_activity連線查詢，並確認更改 Synapse 池後空閒後端計數是否會下降。
• 降低延遲後觀察查詢和同步延遲cp_max；如果資料庫等待時間明顯增加，則撤銷變更。
• pg_stat_user_tables定期檢查以確認自動吸塵功能是否確實在清潔繁忙的餐桌。
• 如果你降低了該值work_mem，請先監控大型排序是否過度溢出到臨時文件，然後再進一步降低該值。

如果經過這些檢查後，PostgreSQL 仍然持續成長，直到主機大量使用交換空間，則應在記憶體峰值期間擷取活動查詢清單並調查工作負載，而不是反覆縮小全域記憶體限制。在受支援的 PostgreSQL 版本上，pg_backend_memory_contexts可以檢查目前後端的記憶體上下文；PostgreSQL 系統視圖文件描述了該視圖及其權限。與假設每個高記憶體 Synapse 部署都由相同原因導致相比，這種方法更有助於進行有針對性的資料庫調查。

結論

對於 Matrix Synapse on PostgreSQL，解決資料庫記憶體使用過高問題的最佳方法是分層解決：首先，確認主機確實面臨記憶體壓力；其次，統計資料庫會話數；最後，合理調整 Synapse 的進程池大小；再次，保持 PostgreSQL 的單次操作記憶體佔用量較低；最後，確保自動清理機制運作正常。我們的目標並非追求最小的 PostgreSQL 記憶體佔用，而是實現可預測的記憶體使用，避免將正常的資料庫快取和並發操作轉換為可避免的交換、記憶體溢出事件或 Matrix 用戶端運作緩慢等問題。