透過操作解決矩陣房間管理員權限錯誤
追蹤 M_FORBIDDEN 到房間功率等級、成員資格或 Synapse 伺服器管理員存取權限,然後僅恢復被封鎖操作所需的權限。
當 Matrix Synapse 日誌顯示SSL: CERTIFICATE_VERIFY_FAILED聯盟加入程序可能停滯、遠端伺服器拒絕連線或訊息無法到達時,首先要確定是哪個憑證發生故障:是遠端伺服器在出站請求期間的證書,還是其他伺服器連線時您自己的聯盟端點的憑證。然後修復日誌和聯盟測試中發現的憑證鏈、主機名稱或信任配置問題。不要透過停用 TLS 驗證來解決問題。
Matrix 伺服器間通訊使用 HTTPS,而 Matrix 規格要求目標伺服器提供由認可的憑證授權單位 (CA) 簽署的 TLS 憑證。驗證錯誤通常意味著提供的憑證已過期、不完整、頒發給不同的主機名,或由連接伺服器不信任的 CA 簽署。即使 Synapse 本身的配置看起來正確,反向代理也可能提供錯誤的憑證。
檢查 Synapse 日誌中故障發生前後的條目,並記下遠端伺服器名稱和特定的憑證錯誤訊息。如果 Synapse 在向另一台主伺服器發出請求時報告故障,則可能是遠端伺服器的憑證或 Synapse 程序使用的 CA 信任關係存在問題。如果其他伺服器無法與您的網域聯合,請檢查您的公共 TLS 端點和伺服器發現機制。
請確認您的 Matrix 伺服器名稱homeserver.yaml,尤其是 ` <domain> server_name`。這是本地 Matrix ID 的網域部分,決定了其他主伺服器如何存取您。請勿將其與機器或容器的內部主機名稱混淆。目前的Synapse 安裝文件解釋說,伺服器名稱是聯合身份,建議在安裝前選擇它。
使用Matrix 聯盟測試器並輸入您的 Matrix 伺服器名稱。它會檢查聯盟發現和連接性,並能揭示外部可見的憑證或路由是否有故障。在調整 Synapse 的出站信任設定之前,請先修正它所識別出的問題。
從一台可以存取您的聯合端點的機器上,檢查 TLS 憑證。將 `<hostname>` 替換matrix.example.org為應該提供該憑證的主機名,並使用您實際的聯合連接埠。連接埠 8448 很常用,但反向代理或委託伺服器可能使用其他連接埠。
openssl s_client -connect matrix.example.org:8448 \
-servername matrix.example.org -showcerts </dev/null
此-servername選項會傳送 SNI(伺服器名稱指示),以便虛擬主機代理程式可以選擇與請求名稱相符的憑證。檢查輸出結果是否驗證成功,然後檢查證書的主題和有效期限:
openssl s_client -connect matrix.example.org:8448 \
-servername matrix.example.org </dev/null 2>/dev/null | \
openssl x509 -noout -subject -issuer -dates -ext subjectAltName
Matrix 聯盟使用的名稱必須與憑證的「使用者備用名稱」中的 DNS 名稱相符。此外,請檢查憑證目前是否有效,以及端點是否發送了其中間憑證。如果您使用反向代理,請測試公共代理位址:即使 Synapse 主機上的憑證檔案正確,如果代理提供的憑證過期或不相關,也無濟於事。
如果測試人員報告伺服器憑證有問題,請續約或重新核發聯合主機名稱的證書,並將公用 TLS 端點設定為提供完整的憑證鏈。 Synapse 目前的設定手冊規定,tls_certificate_path必須指向包含中間憑證的 PEM 憑證;對於 Certbot,請使用 `<Certbot_name>` fullchain.pem,而不是 `<Certbot_name> cert.pem`。將私鑰保存在單獨的tls_private_key_path文件中,並防止其被公開存取。
當 TLS 在 Nginx、Caddy 或其他反向代理程式終止時,請更新該代理程式配置中的憑證和憑證鏈,然後使用適合您安裝的方法重新載入代理程式。在此配置中,Synapse 本身的 TLS 憑證路徑可能無法控制聯盟對等方看到的憑證。請遵循Synapse 官方反向代理文件中關於您使用的監聽器和代理設定的相關說明。
同時檢查 DNS 和 Matrix 伺服器發現機制。聯盟可能直接解析您的伺服器名稱,也可能透過/.well-known/matrix/server委派到不同的主機名稱和連接埠。憑證必須對此發現路徑所到達的主機名稱有效。過期的 DNS 記錄或錯誤的委派可能會將對等方重新導向到提供不相關憑證的端點。
如果失效的憑證屬於私有網路上的遠端主伺服器,請先確認該憑證是否由您的私有憑證授權單位 (CA) 核發。盡可能在 Synapse 主機上安裝並維護該 CA。 Synapse 也支援federation_custom_ca_list用於聯合身份驗證的自訂 CA 憑證。此選項需要 PEM 文件,並會取代作業系統提供的 CA 列表,因此請確保包含部署所需的所有 CA,而不是盲目地只新增一個私有 CA。
federation_custom_ca_list:
- /etc/matrix-synapse/certs/private-root-ca.pem
設定 CA 憑證的路徑,而不是伺服器私鑰的路徑。確保 Synapse 進程可以讀取該證書,驗證 YAML 縮進,然後根據您的部署方式重新啟動或重新載入 Synapse。 Synapse設定手冊指出,此選項通常用於私人家庭伺服器網路。
請勿設定federation_verify_certificates: false以屏蔽公共聯盟錯誤。其預設值為「關閉」true;關閉此選項會移除出站聯盟的憑證驗證,並削弱防冒充保護。此選項federation_certificate_verification_whitelist僅用於特定情況,例如 Tor 隱藏服務或受控私人環境,而非用於修復公用憑證。對於私有基礎設施,通常建議使用受信任的私有 CA。
如果憑證日期顯示無效,即使憑證仍然有效,請檢查 Synapse 主機和所有代理程式上的系統時鐘和時間同步狀況。時鐘嚴重錯誤會導致有效憑證顯示為無效或已過期。此外,也要確認續訂自動化功能是否已實際更新公開提供的檔案;磁碟上的憑證續約並不能保證代理程式已重新載入該檔案。
修正後,重新執行聯合身分驗證測試工具,並重試先前失敗的連線。確認測試工具能夠識別預期的主機名稱、有效日期和可信任憑證鏈,並檢查 Synapse 日誌中是否有新的聯合身分驗證嘗試,且未出現憑證驗證錯誤。如果測試工具通過,但仍有一個遠端伺服器失敗,請記錄該伺服器名稱、時間戳記和相關的已脫敏日誌條目:其自身的憑證或信任環境可能是剩餘的問題所在。故障排除期間,請勿共用私鑰、存取權杖或使用者訊息內容。
追蹤 M_FORBIDDEN 到房間功率等級、成員資格或 Synapse 伺服器管理員存取權限,然後僅恢復被封鎖操作所需的權限。
設定 Synapse 發現、HTTPS 和代理路由,以便其他 Matrix 主伺服器可以找到並聯絡您的伺服器。
配置 Keycloak OIDC 用戶端和 Synapse 提供程序,以便 Element Web 使用者可以透過您的身分伺服器登錄,而無需暴露客戶端金鑰。
儲存恢復金鑰,驗證您的 Element 會話,並檢查加密訊息金鑰是否可以恢復,而不會將備份與您的帳戶密碼混淆。
診斷 Synapse 在同步過程中記憶體不足的故障,安全地調整緩存,識別請求積壓,並驗證穩定的記憶體使用量。
追蹤矩陣聯合憑證故障到正確的伺服器,修復 TLS 鍊或 CA 信任,並在不停用安全檢查的情況下驗證修復。
Route Matrix 用戶端和透過 Cloudflare 在 HTTPS 443 上進行聯合,可以保留 Synapse 探索功能,避免快取 API 流量或中斷媒體上傳。
使用 pg_dump 備份 Synapse,保護其簽章金鑰和介質,並將其還原到乾淨的 PostgreSQL 資料庫中,而無需重複使用過時的一次性金鑰。
使用專用 Matrix 帳戶、加密管理室、Docker Compose、政策清單和權限檢查來設定 Mjölnir。
跳過已停用的代理,配置 Synapse 內建的滑動同步功能。檢查客戶端發現情況,然後在相容的手機上測量房間清單載入和重新連接行為。