修正 systemd 上的 Matrix Synapse “打開的檔案過多”錯誤

Matrix Synapse 可能會正常啟動，然後停止接受連接，日誌顯示“打開的檔案過多”，或在高負載下卡住。在 systemd 系統上，首先要檢查的是正在執行的 Synapse 程序繼承的檔案描述符限制。更改 shellulimit或編輯 PAM 限製檔通常不會改變 systemd 啟動的服務的限制。

以下步驟適用於 Synapse 作為 systemd 服務運行的 Linux 主機。該單元的名稱可能是 `<systemd_system_service_name>` matrix-synapse.service、matrix-synapse@.service`<systemd_system_service_name>` 或特定於軟體包的名稱。複製指令前，請確認實際的單元名稱。如果 Synapse 運行在 Docker、Kubernetes 或其他容器中，請參閱下面的單獨章節。

「打開的文件過多」是什麼意思？

Linux 為每個進程設定了開啟的檔案描述符數量上限。描述符可以指向檔案、套接字、管道或其他資源；因此，網路連線也會消耗描述符。當進程達到其軟上限時，嘗試開啟或接受另一個描述符可能會失敗EMFILE。 Linux 還有一個獨立的系統層級檔案表限制：耗盡該限制也會導致問題ENFILE。提高某個 Synapse 服務的限制並不能解決系統層級的檔案表不足問題。

Synapse 官方管理 FAQ 指出，高連線數和聯盟活動會佔用大量檔案句柄，而檔案句柄耗盡會導致伺服器停止接受新的 TCP 連線。其指南建議，在預設值為 1024 或 256 的情況下，應將限制至少提高到 4096。請將此視為針對所述情況的故障排除最低限值，而非適用於所有家庭伺服器的通用容量建議。首先，請檢查有效限制和實際使用情況。

Linux 的 getrlimit 和 prlimit 文件描述了每個進程的軟限制和硬限制。 Synapse 也提供了對應的soft_file_limit設定；Synapse 設定參考文件中指出預設值為零，這表示 Synapse 將軟限制設為它可以使用的硬限制。

1. 確認設備並診斷故障

首先找到實際的服務名稱。在許多軟體包安裝中，服務名稱是 `service_name` matrix-synapse.service，但如果您的安裝使用了自訂單元或工作進程，則不要想當然地使用這個名稱。

systemctl list-units --type=service --all | grep -i synapse
systemctl status matrix-synapse.service --no-pager
journalctl -u matrix-synapse.service --since "30 minutes ago" --no-pager

尋找特定的錯誤訊息、錯誤發生的時間，以及錯誤是否出現在流量高峰、聯盟活動期間或系統重新啟動時。接下來，檢查 systemd 目前報告的限制：

systemctl show matrix-synapse.service -p LimitNOFILE -p MainPID

LimitNOFILE顯示服務管理器配置的限制；它並非目前開啟的描述符數量。類似這樣的 shell 指令ulimit -n僅報告目前 shell 的限制，並不能證明服務的限制。

2. 透過插入式更新提高 systemd 服務限制

使用 systemd 的 drop-in 元件，這樣軟體包更新就不需要編輯 vendor 單元檔案。以下值僅供參考，並非適用於所有伺服器的理想值。選擇一個高於實際峰值使用量的限制值，並在設定異常高的值之前檢查應用程式及其相依性的相容性。

sudo systemctl edit matrix-synapse.service

在編輯器的新增插件下新增以下內容：

[Service]
LimitNOFILE=65536

儲存並退出，然後在適當的維護視窗期內重新載入 systemd 並重新啟動 Synapse：

sudo systemctl daemon-reload
sudo systemctl restart matrix-synapse.service
systemctl show matrix-synapse.service -p LimitNOFILE

單一LimitNOFILE值即可同時設定 systemd 服務的軟限制和硬限制。 systemd 手冊也允許使用軟限制和soft:hard硬限制的組合。軟限制不能超過硬限制。在選擇非常高的值之前，請查閱systemd.exec 文檔，其中指出了使用舊select(2)接口且描述符超過 1023 的程式可能存在的兼容性問題。不要假設部署中的每個程式庫或外掛程式都支援任意限制。

3. 檢查 Synapse 本身的設定和工作服務

如果您的 Synapse 配置明確地將軟限制設為soft_file_limit一個較小的值，則應用程式的設定可能會使軟限制低於 systemd 的上限。請在活動設定檔和包含的配置中尋找該鍵。您可以刪除不必要的覆蓋設置，或刻意設定該值；文件中記錄的預設值為零，它會要求 Synapse 將軟限制提高到可用的硬限制。

對於多進程部署，每個工作進程都是獨立的進程，可以由不同的單元或模板實例啟動。提高主服務的限制並不能自動證明每個工作進程都達到了預期的限制。請使用 `<workspace>` 指令檢查實際的工作流程單元名稱systemctl list-units，然後為每個需要的服務套用並驗證對應的 drop-in 設定。

同樣，/etc/security/limits.conf登入 shell中的設定ulimit通常無法控制 systemd 直接啟動的系統服務。對於這種設置，請變更單元的資源限制，並在 systemd 實際啟動的進程上進行驗證。

4. 如果 Synapse 運行在容器中

針對不同服務的主機級 systemd 配置覆蓋不會自動更改容器的檔案描述符限制。請配置容器運作時或編排層。對於 Docker Compose，服務定義支援按容器配置ulimits；例如：

services:
  synapse:
    ulimits:
      nofile:
        soft: 65536
        hard: 65536

此數值僅供參考；請依實際使用情況和主機限制進行調整。 Docker Compose 服務參考文件中對此ulimits設定有詳細說明。從 Docker Engine 29 開始，Docker 發行說明中描述了與 containerd 2.1.5 關聯的預設 nofile 限制的變更：容器的 nofile 限制可能從先前的 1,048,576 變更為 1,024。如果此問題在 Engine 升級後出現，請檢查實際容器限制，並在部署配置中明確設定所需的 ulimit 值。請參閱Docker Engine 29 發行說明和docker run 參考文件。

5. 驗證正在運行的 Synapse 進程的限制

重啟後，不僅要檢查 systemd 的配置，還要檢查進程層級的限制。取得主進程 ID (PID) 並檢查其核心報告的限制：

PID=$(systemctl show --property=MainPID --value matrix-synapse.service)
grep "Max open files" "/proc/$PID/limits"
find "/proc/$PID/fd" -mindepth 1 -maxdepth 1 | wc -l

如果主進程 ID 為零或屬於包裝器而非 Synapse 進程，請在服務的 cgroup 中找到 Synapse 進程並檢查該進程的 PID。描述符計數是快照；請在典型負載期間重複此操作。確認「最大開啟檔案數」符合您預期的軟限制和硬限制，計數始終低於軟限制，且日誌不再報告錯誤。

如果計數持續上升直至達到新的上限，那麼限制可能只是延緩了故障的發生。 Synapse 常見問題指出，在調查檔案句柄耗盡問題時，卡住或緩慢的請求可能與此相關。應該檢查相關的日誌和請求處理過程，比較一段時間內的描述符計數，並調查是否有洩漏或異常持久的連接，而不是盲目地繼續提高上限。

當提高單次服務限額還不夠時

如果日誌報告系統層級檔案表耗盡錯誤（例如）ENFILE，請檢查主機範圍內的使用情況和其他服務；單獨LimitNOFILE變更某個服務不會增加核心的系統級容量。在未確認錯誤並了解對主機範圍的影響之前，請勿變更全域核心限制。如果在進行替換後，服務報告的限制仍然很低，請執行命令systemctl cat matrix-synapse.service確認替換已加載，驗證單元名稱，重新載入 systemd，然後重新啟動正確的單元。