修正 Matrix Synapse「SSL 憑證驗證失敗」聯合驗證錯誤

Matrix Synapse 的一個常見故障看似簡單：本機用戶端可以登錄，反向代理在線，Synapse 本身看起來也運作正常，但遠端伺服器無法與您建立聯合身分驗證。一方的日誌可能包含諸如“” certificate verify failed、hostname mismatch“”、 “”之類的短語unable to get local issuer certificate，或者由 TLS 驗證引起的通用聯合身份驗證請求失敗。

解決此問題的最快方法是測試 Matrix 聯盟發現解析到的確切主機名稱和端口，然後修復錯誤的憑證、憑證鍊或發現路徑。請勿先停用證書檢查。 Matrix 伺服器之間的通訊使用 HTTPS，而 Matrix 規格要求目標伺服器提供由受信任的憑證授權單位簽署的憑證。 Synapse 預設啟用出站聯盟憑證驗證。請參閱Matrix 伺服器間 API 規格和目前的 Synapse 設定文件。

1. 確定聯盟實際驗證的主機名

在變更 Nginx、Caddy、Synapse 或 DNS 之前，請先確定 Matrix 期望的憑證名稱。答案取決於您的配置server_name和伺服器發現機制。

如果您的 Matrix 伺服器名稱為 ` example.com<server_name>` 且您未委託聯合驗證，則其他主伺服器通常會嘗試與該名稱關聯的聯合驗證服務，該服務通常使用 TCP 8448 連接埠。如果您提供 `<server_name>` 服務https://example.com/.well-known/matrix/server，則該m.server值可以將聯合驗證委託給另一個主機名，例如 `<hostname> matrix.example.com:443`。在這種情況下，委託的主機名稱是 TLS 驗證路徑的一部分。 Matrix 也支援基於 SRV 的發現，但 Synapse 文件建議.well-known在典型部署中使用委託身份驗證，因為它更容易理解和正確配置。權威行為在 Matrix 規範的伺服器發現和Synapse 聯合身分驗證委託部分中有詳細說明。

curl -fsS https://example.com/.well-known/matrix/server

委託回應可以如下所示：

{
  "m.server": "matrix.example.com:443"
}

如果檔案不存在或無效，不要斷定這就是 TLS 漏洞本身。 Matrix 有備用發現規則。關鍵在於知道遠端伺服器最終會連接哪個主機名稱和連接埠。

2. 使用 OpenSSL 重現憑證驗證失敗問題

一旦確定了預期的聯合身份驗證端點，請直接使用 SNI 和主機名稱驗證進行測試。這樣可以將 TLS 身份驗證問題與 Synapse 應用程式問題區分開來。

openssl s_client   -connect example.com:8448   -servername example.com   -verify_hostname example.com   -showcerts </dev/null

對於 443 連接埠上的委託主機，請同時變更連線目標和預期主機名稱：

openssl s_client   -connect matrix.example.com:443   -servername matrix.example.com   -verify_hostname matrix.example.com   -showcerts </dev/null

重點關注最終驗證結果和證書主題備用名稱。連線可能在 TCP 和 TLS 協定層成功建立，但身份驗證仍然失敗。這就是為什麼「連接埠已開啟」是不夠的。

最常見的 OpenSSL 錯誤通常意味著什麼

• 主機名稱不符：反向代理提供的憑證是針對不同的主機名，或者您的發現記錄將聯合身份驗證指向憑證未涵蓋的主機名稱。
• 無法取得本機頒發者證書/無法驗證第一個證書：伺服器通常缺少鏈中的中間 CA 證書，或用戶端信任儲存體不信任頒發 CA。
• 證書已過期/尚未生效：請續約證書，並驗證伺服器和任何嚴格控制的私有聯邦用戶端上的系統時鐘。
• 自簽名憑證：公共聯盟通常會拒絕它。對於私有聯盟，請使用私有 CA 並明確配置信任關係，而不是全域關閉驗證。

3. 修復反向代理的主機名稱不符問題

當面向客戶端的網站和聯合身分驗證端點使用不同的虛擬主機時，主機名稱不符的情況尤其常見。例如，example.com可能託管一個網站，而matrix.example.com代理 Synapse。如果您的.well-known文件委託給matrix.example.com:443，則該主機上的 TLS 端點必須提供對有效的憑證matrix.example.com。

對於 Nginx，請檢查活動的虛擬主機，而不僅僅是您打算使用的設定檔：

sudo nginx -T | less

檢查server_name監聽連接埠和證書路徑。典型的 TLS 部分使用完整的憑證鏈：

server {
    listen 443 ssl;
    server_name matrix.example.com;

    ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem;

    location /_matrix {
        proxy_pass http://127.0.0.1:8008;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

僅在配置測試成功後才進行驗證並重新載入：

sudo nginx -t && sudo systemctl reload nginx

Synapse 建議在常見部署中使用反向代理，並將常用的用戶端連接埠 443 與預設的聯合連接埠 8448 區分開來。有關當前代理要求，請參閱Synapse 官方反向代理文件。

4. 提供完整的憑證鏈

即使葉子證書在您常用的瀏覽器中看起來正常，但如果您的伺服器沒有發送所需的中間證書，它仍然可能無法在其他伺服器上正常工作。 Synapse 文件明確指出，當 Synapse 本身配置了憑證時，PEM 檔案應包含完整的憑證鏈；對於 Certbot 而言，這表示需要使用完整的憑證鏈，fullchain.pem而不僅僅是中間憑證cert.pem。

當 TLS 連線終止於 Nginx、Caddy、HAProxy 或其他代理伺服器時，也適用相同的原則：設定該代理伺服器以提供正確的完整連接鏈。檢查實際提供的內容，而不僅僅是磁碟上的內容：

openssl s_client   -connect matrix.example.com:443   -servername matrix.example.com   -showcerts </dev/null

您應該看到葉證書，以及隨後所需的中間證書。根 CA 通常不需要由伺服器傳送，因為客戶端通常已經透過其信任儲存區信任根憑證。

5. 檢查 DNS 和 Matrix 發現是否有過時或分割的路由。

如果一台機器上的證書正確，但遠端聯盟仍然報告不同的證書，則可能是 DNS 將某些用戶端重新導向到了其他位址。請檢查 IPv4 和 IPv6 記錄，並記住，如果遠端主伺服器優先使用 IPv6，即使 A 記錄有效也無法彌補 AAAA 記錄的失效。

dig +short A example.com
dig +short AAAA example.com
dig +short A matrix.example.com
dig +short AAAA matrix.example.com

此外，還要檢查您有意使用的任何聯邦 SRV 記錄：

dig +short SRV _matrix-fed._tcp.example.com

如果您最近進行了更改.well-known，請啟用快取。 Matrix 規範允許客戶端快取發現回應，甚至包括失敗的發現嘗試，快取時間為一段時間。這意味著當前配置可能正確，而遠端伺服器可能暫時繼續使用先前發現的路由。

如果 A 和 AAAA 憑證都存在，則必要時對每條路由執行 TLS 檢查。如果負載平衡器前端有多個代理節點，請驗證每個節點是否具有相同的目前憑證和憑證鏈。

6. 在不削弱公共聯邦的前提下，修復私有 CA 信任問題

私有聯合是公共 CA 可能不適用的主要合法情況。 Synapse 提供federation_custom_ca_list自訂憑證授權單位。目前文件指出一個重要行為：此清單會取代作業系統環境提供的 CA 憑證。因此，如果您要設定此列表，請務必包含部署實際所需的完整信任集。

federation_custom_ca_list:
  - /etc/synapse/ca/private-federation-ca.pem

變更信任配置後，請使用安裝服務的機制重新啟動 Synapse，並檢查日誌中是否有憑證錯誤。容器部署也需要特別注意：主機可能信任私有 CA，而 Synapse 容器可能不信任。請確認信任材料已掛載到容器中，並且配置的路徑可以從容器內部讀取。

Synapse 也提供了federation_certificate_verification_whitelist全域federation_verify_certificates開關，但官方文件將其限制在特殊情況下使用。全域關閉驗證可能會使錯誤消失，但無法解決根本的身份問題。對於普通的公共聯合身份驗證，請修復憑證或路由。

7. 首先在TLS層驗證修復是否成功。

修改完成後，重複執行先前失敗的 OpenSSL 指令。目標是成功驗證 Matrix 發現解析到的端點的主機名稱和鏈。

然後向聯合端點發出 HTTPS 請求。例如，對於連接埠為 8448 的直接端點：

curl -v https://example.com:8448/_matrix/federation/v1/version

對於 443 連接埠上的委託端點：

curl -v https://matrix.example.com/_matrix/federation/v1/version

正常的 TLS 驗證結果應表示憑證驗證成功。此時，Matrix 端點應從主伺服器或代理程式路徑傳回 HTTP 回應，而不是在憑證驗證過程中失敗。版本端點本身可用於可達性測試；但它並不能證明每個房間或遠端伺服器都能正確聯合。

8. 檢查 Synapse 日誌，區分 TLS 錯誤和更高等級的聯合身分驗證錯誤。

如果 TLS 驗證成功但聯合身份驗證仍然失敗，則不要再將其視為憑證問題。向上追溯堆疊，檢查 Synapse 日誌，尋找 DNS 故障、連線逾時、HTTP 狀態錯誤、簽署金鑰問題、授權失敗或遠端伺服器退避等情況。

在基於 systemd 的安裝中，常見的起點是：

journalctl -u matrix-synapse -n 200 --no-pager

對於 Docker，請使用 Synapse 服務的容器日誌。搜尋最近一次聯合身份驗證嘗試的時間戳附近，而不是依賴可能不再相關的舊憑證訊息。

快速決策表

如何確定問題真的解決了

不要將「服務重啟後無錯誤」作為成功標準。可靠的修復應具備三個可觀察的標誌：聯盟主機名稱透過主機名稱驗證、提供的憑證鏈透過受信任的憑證授權單位 (CA) 驗證，以及新的聯盟 HTTPS 請求到達 Synapse 時沒有 TLS 驗證異常。

如果經過這些檢查後，仍然只有一個遠端主伺服器發生故障，請考慮快取、該遠端伺服器的信任儲存或特定於端點的網路路徑。如果多個不相關的公用主伺服器發生相同故障，請先重新檢查您自己的憑證、IPv6 路由、負載平衡器節點和發現配置。

對於生產系統，請保持憑證驗證啟用狀態，並確保憑證續約過程可觀察。根本的解決方案並非停用驗證，而是確保 Matrix 發現、DNS、SNI、反向代理程式和憑證鏈都指向同一個聯合端點。