修復 Matrix Synapse Federation 延遲和房間加入緩慢問題

首先找到延遲點

當 Matrix 房間開啟或加入時間過長時，首先要確定延遲是影響單一遠端主伺服器、單一房間，或是整個 Synapse 實例。區分這一點至關重要：聯盟是主伺服器之間的雙向交換，而房間加入可能涉及多個伺服器。加入緩慢可能是由 Synapse 進程、遠端伺服器、DNS 或 TLS 路由、資料庫或房間的大小和狀態引起的。沒有一個單一的「聯盟延遲」開關可以解決所有這些問題。

已驗證： Synapse 會記錄遠端目標重試資訊、公開 Prometheus 指標，並包含房間加入速率限制。具體情況取決於實際情況：究竟是哪些因素導致了單一房間加入緩慢。僅憑症狀無法判斷：是其他主伺服器還是中間網路速度慢。首先選擇一個受影響的使用者、一個房間以及一次緩慢嘗試的大致時間；將這些資訊與正常加入的對照房間進行比較。

檢查聯邦是否可達

使用官方的Matrix Federation Tester 測試您的家庭伺服器的 Matrix 伺服器名稱。它可以發現常見的 DNS、委派、憑證和可及性問題。使用者 ID 中的伺服器名稱可能與執行 Synapse 的機器或代理伺服器不同，因此請檢查已設定的聯盟端點和委派，而不是假設使用者 ID 網域必須直接託管 Synapse。

Synapse 的聯盟文件將預設聯盟連接埠描述為 TCP 8448，而委託或反向代理部署可以使用連接埠 443 上的 HTTPS。相關連接埠必須可從其他主伺服器訪問，且出站防火牆可能也需要允許聯盟流量。檢查符合的入站和出站防火牆規則，然後從聯盟測試器再次進行測試。如果您的部署配置為僅使用一個端口，請勿隨意打開兩個端口。

如果結果顯示憑證、DNS 或路由錯誤，則表示存在設定或網路可及性問題，而非伺服器容量問題。請檢查 Matrix 伺服器名稱的 DNS 記錄和委派、反向代理的 TLS 憑證鏈，以及代理程式是否將聯合路徑轉送至 Synapse。 Synapse 文件指出，在某些配置中，聯合伺服器不會執行 308 永久重定向，因此也需要調查意外重定向。修復特定的失敗檢查並重新測試後，再更改工作節點數量或速率限制。

參考資料：Synapse 聯盟設定與故障排除以及Synapse 防火牆指南。

查看某個遠端伺服器是否處於重試冷卻期

Synapse 在聯盟請求失敗後會暫時將遠端目標標記為離線。重試延遲採用退避機制，因此重複失敗可能會導致涉及該目標的訊息或加入操作出現延遲。但這並不意味著您的整個主伺服器運行緩慢：可能只是某個遠端伺服器無法存取或請求失敗。

管理員可以查看 Synapse 的 Federation Admin API，其中有相關文件GET /_synapse/admin/v1/federation/destinations。使用伺服器管理員存取令牌並妥善保管。檢查受影響房間中涉及的 homeserver 的目標記錄和重試欄位。這些記錄有助於識別目標何時重試，但它們本身並不能證明連接失敗的原因。將這些記錄與 Synapse 日誌、代理日誌、DNS/TLS 測試以及使用者報告問題的時間進行關聯分析。

聯合身份驗證管理 API 的文件顯示其為實驗性功能，且可能會發生變化。請勿像對待穩定的公共客戶端 API 那樣對其進行腳本編寫。 Synapse 還記錄了一個重置連線逾時操作，該操作可能會觸發對已處於冷卻狀態的目標伺服器的再次後台連線嘗試。只有在糾正或了解根本故障後，才能將此操作視為診斷或恢復操作；反覆清除冷卻時間並不能使不正常的遠端伺服器回應。從重置端點收到成功的 HTTP 回應並不表示後台聯合身份驗證嘗試已完成。

參考：Synapse Federation 管理 API。此 API 的實驗狀態和可用欄位可能會隨 Synapse 版本而變化，因此在使用操作之前，請務必查看您所執行版本的文件。

在擴充之前，請先測量 Synapse 及其資料庫。

僅在受信任的內部網路或存取控制後啟用 Synapse 的 Prometheus 指標端點。官方監控指南記錄/_synapse/metrics並示範如何透過指標監聽器或現有 HTTP 監聽器公開此端點。指標可能包含操作詳情；請勿公開此端點。如果您已收集指標，請將慢速連線的時間與 CPU、記憶體、請求延遲、資料庫交易持續時間以及傳入和傳出的聯合活動進行比較。

使用圖表來區分普遍的過載和聯邦特有的延遲。如果普通用戶端請求和資料庫事務與連接操作同時變慢，則應檢查主機 CPU 和記憶體壓力、PostgreSQL 運行狀況、連接限制、磁碟延遲以及長時間運行的查詢。如果本地房間活動保持回應，但某個遠端目標故障或重試延遲，則應優先考慮聯邦可達性和該遠端伺服器。如果只有一個大型房間受到影響，則房間狀態和參與伺服器的數量可能會有所影響；在得出結論之前，請將其與較小的房間進行比較。

Synapse 的 Grafana 指南建議檢查訊息傳送時間、CPU 和記憶體使用情況、資料庫事務計數和持續時間以及聯合圖。事務計數高並不一定意味著瓶頸所在；持續時間和系統負載也很重要。請檢查您安裝的 Synapse 版本的指標名稱和最新的儀表板文檔，因為指標名稱可能會隨時間而變更。

參考資料：Synapse Prometheus 監控並透過 Grafana 圖表了解 Synapse。

檢查房間加入節流和突發狀況

Synapserc_joins對本機加入和遠端加入分別設定了不同的限制。遠端加入可能比加入伺服器已參與的房間需要更多資源。 Synapse 也提供了rc_joins_per_room限制房間近期加入次數的功能，以幫助緩解大規模加入的情況。如果日誌或用戶端回應顯示存在速率限制，請在變更這些設定之前檢查這些設定和近期加入次數。

不要為了提升速度而隨意提高速率限制。更高的限制會增加伺服器和其他子伺服器的負載，並可能降低對加入流量攻擊的防護能力。如果合法的遷移或新使用者加入高峰達到了配置的限制，請確定特定的限制值，並查看 Synapse 版本目前文件中記錄的值。考慮將加入工作負載分散到一段時間內。每次只更改一個相關的值，保留先前的配置，並在根據部署需要重新載入或重新啟動後監控錯誤率和資源使用情況。

參考：Synapse 設定：rc_joins和Synapse 設定：rc_joins_per_room。預設值和支援的選項可能因版本而異；編輯前請將其與您已安裝的版本進行比較。

使用受控連接測試

選擇一個受影響的房間，並記錄房間別名或房間 ID、加入使用者的 homeserver、時間以及特定的客戶端錯誤訊息。切勿在支援日誌中包含存取令牌。
檢查聯盟測試器中的伺服器名稱，並確認已設定的聯盟端點、憑證和代理程式路由。
查看該時間戳附近的 Synapse 日誌，尋找聯盟失敗、遠端目標錯誤、逾時或速率限制回應。搜尋反向代理和資料庫日誌，尋找匹配的延遲。
檢查聯盟管理 API 中與相關遠端目標關聯的重試狀態。將受影響的房間與能夠立即加入的控制房間進行比較。
比較同一時間段內的 Prometheus 和主機指標。尋找請求延遲升高、資料庫交易持續時間延長、CPU 或記憶體壓力增加，或聯邦活動出現高峰的情況。
進行一項有針對性的修正——例如修復 DNS/TLS/代理問題、解決資料庫瓶頸或調整已確認的速率限制——然後重複相同的測試並比較結果。

應避免的常見假設

「加入速度慢意味著我的伺服器 8448 連接埠關閉了。」不一定。委託或反向代理可能會使用 443 連接埠。請檢查實際配置的聯合端點並進行測試。
「成功的聯盟測試表明每次加入房間的速度都很快。」它只檢查常見的聯盟配置和連接性。遠端伺服器運行狀況、房間狀態、本地負載和資料庫效能仍然會影響加入速度。請測試受影響的房間並檢查日誌。
「聯盟延遲總是源自於我的 Synapse 執行個體。」 Synapse 本身的設定文件也提醒，觀察到的聯盟延遲可能源自於任一端點，也可能源自於它們之間的網路。請盡可能比較兩端的地址並收集相關證據。
「增加工作線程或提高速率限制是首要的解決方法。」這些變更僅在測量結果指向容量不足或限速時才有效。首先要確定問題是出在連線性、遠端重試、本地飽和、資料庫延遲或連線速率限制。

確認修復是否有效

更改後重複相同的加入測試。確認使用者加入成功，受影響的目標不再反覆失敗，聯合測試器正確報告相關檢查結果，並且請求/資料庫延遲恢復正常範圍。注意在後續繁忙時段是否再次出現此問題；一次成功的嘗試並不能證明遠端伺服器或網路始終運作良好。

如果本機指標和聯盟檢查結果正常，但只有一個遠端主伺服器持續故障，請將時間戳記、目標位址、已脫敏的錯誤訊息以及相關的請求 ID 分享給該伺服器的管理員。如果多個房間和目標位址受到影響，且本機要求速度緩慢，請在調整聯盟行為之前，先檢查 Synapse 和 PostgreSQL 的容量。由於設定和管理 API 的詳細資訊會不斷更新，請在事件記錄中記錄您的 Synapse 版本。