如何修復 Zimbra “無法啟動 TLS：SSL 握手失敗”錯誤

此訊息Unable to start TLS: SSL handshake failed表示客戶端和伺服器無法完成建立加密連線的協商。在 Zimbra 中，該訊息可能來自不同來源。常見的變體是，在zmcontrol status連接 LDAP 主伺服器期間出現，提示憑證驗證失敗。郵件用戶端或 SMTP 中繼也可能報告公共郵件連接埠上的握手問題。

修復方法取決於哪個連線出現故障。首先，在相關的日誌行中確定服務和主機名稱。然後，檢查憑證、其頒發鏈、系統時鐘和 TLS 端點。切勿先停用 TLS：這可能會掩蓋問題，同時削弱甚至破壞內部郵件伺服器通訊。

在改變任何事情之前需要了解什麼

TLS是用於加密網路連線的協定。 TLS握手是初始階段的通訊過程，在此過程中，兩個系統會就加密參數達成協議並驗證伺服器憑證。 STARTTLS連線最初使用明文協議，然後在雙方都要求時切換到 TLS。 LDAP 和 SMTP 都可以使用 STARTTLS，因此僅憑此錯誤無法確定是哪個服務故障。

在執行修復指令前，請記錄 Zimbra 版本、安裝是單節點或多節點、出現錯誤的確切指令或用戶端，以及相關的完整日誌行。請在維護視窗期間安排憑證部署或服務重新啟動。編輯憑證檔案和設定前，請務必備份。

使用 Zimbra 版本所需的帳號和權限來執行管理指令。
請勿將私鑰、密碼或未經編輯的郵件日誌貼到工單或公共論壇。
在確定哪個端點發生故障並檢查其憑證之前，請勿變更 LDAP 安全標誌或協定設定。

步驟 1：辨識失敗的 TLS 連接

首先重現問題並閱讀完整錯誤訊息。如果錯誤訊息出現在 Zimbra 檢查服務狀態時，並且包含類似「」這樣的措辭when connecting to ldap master，請檢查內部 LDAP TLS 設定。如果只有郵件用戶端在提交 SMTP 請求時失敗，請檢查公用 SMTP 端點以及用戶端的主機名稱、連接埠和加密模式。

su - zimbra
zmcontrol status

查看近期相同時間戳記的 Zimbra 日誌條目。在許多安裝中，主日誌位於 `/etc/zimbra/log /var/log/zimbra.log/`；請使用伺服器上設定的日誌位置。

grep -Ei 'Unable to start TLS|SSL handshake|certificate|ldap|STARTTLS' /var/log/zimbra.log | tail -n 80

尋找進程名稱、遠端主機、連接埠以及任何更具體的 OpenSSL 詳細信息，例如憑證驗證失敗、憑證過期、未知頒發者或協定警報。這些詳細資訊有助於將憑證信任問題與網路或協定不符問題區分開來。

如果遇到內部 LDAP 錯誤，請檢查此伺服器設定所使用的 LDAP 主機。逐一查詢本機設定項，並將其主機名稱與 DNS 和伺服器憑證進行比較：

zmlocalconfig ldap_url
zmlocalconfig ldap_master_url
zmlocalconfig ldap_starttls_supported
zmlocalconfig ldap_starttls_required

金鑰的可用性和輸出可能因 Zimbra 版本和節點角色而異。這些是診斷性讀取；請勿僅因某個值出現在輸出中就對其進行更改。 Zimbra 文件描述了 LDAP STARTTLS 設定的作用，並建議保持啟用內部 TLS：Zimbra TLS 和 STARTTLS 本機設定值。

步驟 2：檢查系統時鐘、DNS 和可及性

憑證驗證取決於伺服器時鐘。如果伺服器時鐘嚴重延遲或超前，即使憑證有效，也可能顯示為無效或已過期。請確認 Zimbra 主機以及連線中涉及的任何 LDAP 主伺服器或副本伺服器的時間。

date -u
getent hosts ldap.example.com

替換ldap.example.com為設定或日誌中找到的 LDAP 主機名稱。確認該主機名稱解析到預期的伺服器位址，且配置的 LDAP 連接埠可透過主機防火牆和網路存取。在多節點部署中，請從記錄故障的 Zimbra 節點到實際的 LDAP 節點進行測試，而不僅僅是從您的工作站進行測試。

對於面向客戶端的 SMTP STARTTLS 連接，Zimbra 的 SMTP 故障排除指南示範如何使用 OpenSSL 測試連接埠 25。連接埠 587 也常用於透過 STARTTLS 發送郵件。請使用郵件用戶端中設定的主機名稱和連接埠：

openssl s_client -starttls smtp -connect mail.example.com:587 -servername mail.example.com -showcerts

對於連接埠 25 上的 SMTP 服務，請替換587為25。連接埠 465 使用隱式 TLS，因此在測試該連接埠時無需新增-starttls smtp。成功的 TCP 連線本身並不能證明憑證受信任或用戶端使用了正確的安全模式。請參閱Zimbra 的 SMTP 和 OpenSSL 故障排除指南。

步驟 3：檢查 Zimbra 實際部署的憑證

證書是伺服器的簽章身分證明文件。憑證必須對用戶端所使用的主機名稱有效，必須在有效期限內，並且必須指向連線元件信任的憑證授權單位。一個憑證在瀏覽器中可能看起來正常，但部署在 LDAP、Postfix 或代理節點上的憑證可能不同。

作為 Zimbra 管理員，請查看 Zimbra 報告的已部署憑證：

/opt/zimbra/bin/zmcertmgr viewdeployedcrt

檢查每個列出的憑證的主題或主題備用名稱 (SAN)、頒發者、到期日期和服務。 SAN 應包含 LDAP 或郵件連線實際使用的主機名稱。此外，還要檢查多伺服器部署中的所有節點是否都具有預期的憑證和憑證鏈。 Zimbra 指出，已部署憑證的檢視權限僅限於伺服器本地，因此請在每個相關節點上執行此檢查。

如果您有來源證書文件，請在部署前檢查其日期和名稱：

openssl x509 -in /tmp/commercial.crt -noout -dates -subject -issuer -ext subjectAltName

請將範例路徑替換為您正在評估的憑證檔案路徑。缺少 SAN、葉憑證或中間憑證過期、主機名稱錯誤或憑證是為其他伺服器頒發的，都可能導致驗證失敗。

步驟 4：驗證私鑰和憑證鏈

證書鍊是一組頒發者證書，它允許客戶端追溯伺服器證書到受信任的證書頒發機構。如果憑證鏈檔案缺少中間憑證或包含錯誤的憑證鏈，即使葉子憑證是有效的，用戶端也可能拒絕與伺服器通訊。此外，憑證和私鑰必須匹配。

對於商業證書，Zimbra 的證書工具提供了一個驗證步驟。請根據您的安裝目錄和憑證授權單位調整檔案路徑：

/opt/zimbra/bin/zmcertmgr verifycrt comm   /opt/zimbra/ssl/zimbra/commercial/commercial.key   /tmp/commercial.crt   /tmp/ca_chain.crt

僅當驗證確認憑證和私鑰匹配且憑證鏈有效時，才繼續操作。驗證失敗後，請勿部署憑證。請使用憑證授權單位提供的中間憑證鏈，並遵循 Zimbra 版本所需的憑證鏈格式；切勿透過猜測或附加無關的根憑證來建立憑證鏈。

Zimbra 的憑證指南詳細記錄了驗證和部署順序，包括 CA 鏈：Zimbra 憑證安裝和 CLI 工具。其憑證鏈故障排除頁面也解釋了頒發者鏈驗證錯誤：Zimbra 憑證鏈指南。

步驟 5：更正並安全地部署證書

如果驗證結果顯示憑證過期、金鑰錯誤、缺少中間憑證或主機名稱不匹配，請在部署前取得或產生正確的檔案。請按照您的 Zimbra 版本和憑證類型的步驟進行操作。對於商業證書，文件中記錄的命令格式如下：

/opt/zimbra/bin/zmcertmgr deploycrt comm /tmp/commercial.crt /tmp/ca_chain.crt

請使用與已安裝版本文件中完全一致的命令語法和權限。 Zimbra 的 CLI 可以為 MTA、LDAP 和代理程式等元件安裝證書，因此部署可能會影響多個服務。在多節點環境中，請確認憑證已正確部署至所有相關伺服器，包括 LDAP 主伺服器。

部署驗證完成後，如果發布流程需要，請在計劃維護視窗期間重新啟動 Zimbra 服務，然後確認服務狀態和已部署的憑證：

su - zimbra
zmcontrol restart
zmcontrol status
/opt/zimbra/bin/zmcertmgr viewdeployedcrt

重啟會中斷郵件和網頁訪問，因為服務會停止並恢復。請勿在繁忙的生產伺服器上隨意執行此操作。 Zimbra 憑證指南文件記錄了zmcontrol restart部署後如何使用該指令檢查結果viewdeployedcrt。

步驟 6：在不停用 TLS 的情況下檢查 LDAP 信任設定。

如果證書本身驗證通過，但 Zimbra 的 LDAP 用戶端仍然拒絕該證書，請檢查 LDAP 信任材料和故障的節點。 Zimbra 檔案的 MTA 故障排除說明列出了/opt/zimbra/conf/caLDAP STARTTLS 失敗的可能原因，包括無效的 CA 鏈、過期的 CA 憑證和意外檔案。請將此視為診斷線索，而不是刪除檔案的理由：將目錄與已知有效的備份或特定版本的指南進行比較，並在進行任何更改之前保留其內容。

對於簡單的 LDAP STARTTLS 探測，OpenLDAP 用戶端可以要求啟用 StartTLS 並查詢根 DSE，而無需提供帳戶憑證：

ldapsearch -x -ZZ -H ldap://ldap.example.com:389 -b "" -s base namingContexts

請在部署中使用實際的 LDAP 主機和連接埠。使用 OpenLDAP 工具時，-ZZ會要求 StartTLS 連接，並將連線建立失敗視為錯誤。如果此探測失敗並顯示信任或憑證訊息，請將 LDAP 端點傳回的憑證與已部署的憑證以及用戶端可用的 CA 信任進行比較。如果測試在一個節點上成功，但在另一個節點上失敗，請檢查 DNS、CA 檔案或本機配置的差異。

步驟 7：僅在憑證檢查之後才考慮協定相容性

如果用戶端和伺服器無法就 TLS 協定版本或密碼套件達成一致，握手也可能會失敗。這種情況可能發生在客戶端版本過舊、自訂加固措施或特定版本預設設定上。請使用最新的 OpenSSL 用戶端測試端點，並檢查 Zimbra 的 TLS 設置，確認產品版本是否完全符合。避免將舊版本中的協定命令從存檔頁面複製到新安裝的系統中；不同版本之間的密碼套件和協定配置可能會發生變化。

請勿透過啟用 SSLv3、降低驗證等級或全域停用 LDAP STARTTLS 來「修復」此錯誤。 Zimbra 論壇上的一個貼文提供了一個關閉 LDAP STARTTLS 的舊版解決方法，但另一位回覆者正確地指出，停用安全功能並非可靠的憑證修復方法。 Zimbra 官方的本地設定說明建議保持進程間 TLS 和 LDAP STARTTLS 啟用狀態。只有在 Zimbra 支援人員指示的情況下，才可將其作為嚴格控制的臨時診斷方法，並立即恢復安全設定。

如何確認維修完成

zmcontrol status如果失敗的操作是 LDAP TLS 錯誤，則操作將順利完成，不會出現 LDAP TLS 錯誤。
受影響的 LDAP 或 SMTP 端點呈現預期的、未過期的憑證和完整的發行者鏈。
從同一主機和網路路徑進行的測試成功，符合預期的 TLS 模式。
Zimbra 日誌不再顯示測試時的憑證驗證或握手錯誤。
對於 SMTP，向兩個方向發送測試訊息，並在相關佇列或日誌中確認送達。

如果故障仍然存在，請收集完整的錯誤訊息，包括 Zimbra 版本、受影響的服務和主機名稱、憑證日期和 SAN、驗證輸出以及相關的日誌行。在共享之前，請對私鑰、憑證、使用者地址和敏感的主機詳細資訊進行編輯。具體的錯誤訊息只是一個症狀，並非完整的診斷；相關的服務名稱和 OpenSSL 原因才能確定正確的修復方法。

文件說明： Zimbra 的公共憑證和 TLS 頁麵包含多個版本的內容，部分故障排除頁面已明確存檔。此處的指令符合文件中記錄的 CLI 模式，但憑證路徑、權限和重新啟動要求應與已安裝 Zimbra 版本的文件進行核對。審核日期：2026 年 10 月 6 日。