修復自訂連接埠上的 Kopano SSL 握手錯誤

明確成功修復的標準

Kopano SSL 握手錯誤表示客戶端和伺服器無法就 TLS 連線達成一致或完成連線。自訂連接埠可能對某些配置部分有效，但對其他部分無效。在變更憑證或協定設定之前，請先確定哪個服務擁有該連接埠，以及該連接埠是否需要使用 TLS。

對於正常工作的配置，目標連接埠應接受 TLS 連接，提供對客戶端主機名稱有效的證書，並允許完成下一個協定步驟。瀏覽器應能正常存取 WebApp 登入頁面，而不會出現憑證警告。 Kopano Core 用戶端應使用相符的 TLS 連接埠進行連接，並在配置的情況下使用其受信任的用戶端憑證。 TLS 偵測成功本身並不能證明 WebApp 登入、Kopano 驗證或郵件投遞功能正常。

首先區分兩種常見的連接埠配置

經驗證適用於 Kopano Core： Kopano Core 管理員手冊 8.0 描述了一個由 Kopano 控制的本機 TLS 監聽器server_listen_tls。其範例使用 237 端口，並指出端口可以更改，同時在 Kopano 中配置了證書和 CA 檔案/etc/kopano/server.cfg。該手冊還展示了用戶端如何使用https://匹配連接埠和用戶端憑證的伺服器套接字。另請參閱Kopano Core：SSL 連線和憑證以及Kopano Core 特殊配置。

另外，對於 Web 應用程式存取：使用者通常會開啟由 Apache、Nginx 或 Kopano Web 提供服務的瀏覽器 URL。 TLS 可以在前端伺服器終止，同時該伺服器會將請求轉送至 Kopano 服務。 Kopano 的手冊中記錄如何將 HTTP 代理到 236 連接埠上的核心監聽器，而其 Kopano Web 指南則記錄了 TLS 憑證的設定/etc/kopano/kwebd.cfg。前端 HTTPS 連接埠不一定與核心 TLS 連接埠相同。請參閱核心反向代理範例和Kopano Web 安裝指南。

操作：記下客戶端 URL、自訂連接埠、預期監聽該連接埠的進程，以及 TLS 連線是在代理伺服器或 Kopano Core 終止。請勿同時更改兩個監聽器。

1. 檢查自訂連接埠上正在監聽的進程

在 Kopano 主機上，將8443以下內容替換為故障的連接埠：

sudo ss -ltnp | grep ':8443'

符合的行應該顯示一個正在監聽的套接字。如果沒有符合的行，則表示該服務未綁定到該端口，或綁定到了其他位址。如果該連接埠屬於本機反向代理，請檢查代理程式的虛擬主機配置。如果它應該是 Kopano Core 的原生 TLS 端口，請檢查server_listen_tls其配置/etc/kopano/server.cfg。僅監聽該連接埠的進程127.0.0.1無法直接接受遠端連線；當前端存在代理程式時，這可能是有意為之。

同時檢查主機防火牆、雲端防火牆以及任何負載平衡器或 NAT 規則。公共連接埠必須能夠連接到預期的內部監聽器。逾時或連線被拒絕通常指向可達性問題或監聽器配置問題；但這本身並不一定表示憑證無效。

2. 使用確切的主機名稱和連接埠探測 TLS。

在客戶端電腦上，使用 OpenSSL 測試公共端點。請使用憑證中顯示的 DNS 名稱，而不是無關的 IP 位址：

openssl s_client -connect mail.example.com:8443 -servername mail.example.com -showcerts

檢查是否提供了證書、協商的協定和密碼套件，以及是否有任何驗證錯誤。此-servername選項會傳送 TLS SNI 主機名稱；當伺服器託管多個 TLS 網站時，這一點至關重要。 OpenSSL 在其s_client 手冊中記錄了這些選項。按 Ctrl+C 退出互動式探測。

如果憑證缺失，則可能是端點正在使用純 HTTP 協議，連接埠被錯誤的伺服器佔用，或者代理伺服器將請求轉送到了錯誤的上游伺服器。如果憑證存在，但其名稱、頒發者或有效期限錯誤，請修正 TLS 端點上的憑證選擇或憑證鏈。主機名稱不符無法透過變更 Kopano Core 監聽器連接埠來解決。

對於面向瀏覽器的端點，請執行下列操作：

curl -v https://mail.example.com:8443/webapp/

詳細的輸出資訊有助於區分 TLS 驗證和 HTTP 回應（例如重定向、404 或 502）。握手完成後回傳 404 錯誤是路徑或路由問題，而非 TLS 協商失敗。此功能僅用於一次性診斷，curl -vk可顯示繞過憑證驗證是否會改變結果。請勿在瀏覽器、用戶端或代理程式中停用憑證檢查。

重要限制： Kopano Core 原生 TLS 可以使用客戶端憑證。s_client即使 TLS 監聽器運作正常，未提供用戶端憑證的基本測試也可能會失敗。如果伺服器要求用戶端身份驗證，請使用已授權的用戶端憑證和金鑰重複測試，或使用已設定的 Kopano 服務用戶端進行測試。切勿在命令記錄或支援工單中洩漏私鑰。

3. 將協定與監聽器匹配

常見的自訂連接埠錯誤是將 HTTPS 用戶端設定為連接普通的 HTTP 監聽器，或將 HTTPS 流量轉送到期望接收 HTTP 流量的上游伺服器。協定和連接埠必須指向同一個端點。

https://mail.example.com:8443/webapp/這意味著瀏覽器期望在 8443 連接埠上使用 TLS。
Kopano Core 文件中的範例會將代理程式的 HTTP 傳送到。如果您的部署使用了這種模式，即使公共瀏覽器連線使用 HTTPS，127.0.0.1:236上游代理也必須使用。http://
對於 Kopano Core 原生 TLS，手冊中的範例使用server_listen_tls = *:237以 `<your_client_url>` 開頭的客戶端 URL https://。如果您將 237 變更為自訂端口，請將所有依賴的客戶端或代理更新為相同的值。

檢查是否存在連接埠或協定不一致的已複製配置行。在多伺服器環境中，也要檢查已發佈的伺服器或代理 URL：用戶端可能在初始連線成功後，由於 Kopano 將其重新導向到舊的主機名稱或連接埠而導致連線失敗。

4. 修復監聽器和憑證配置

如果這是 Kopano Core 的原生 TLS 監聽器，請編輯現有配置，而不是新增重複指令。以下是自訂連接埠的簡化範例；請確保憑證路徑和 CA 與您的實際安裝情況相符：

server_listen_tls = *:1237
server_ssl_ca_file = /etc/kopano/ssl/ca.pem
server_ssl_key_file = /etc/kopano/ssl/server.pem
server_ssl_key_pass = your-key-passphrase

Kopano 手冊詳細說明了監聽器、CA、伺服器金鑰和金鑰傳遞設置，並要求kopano-server在更改原生監聽器後重新啟動。請確認已安裝的版本支援所示選項；軟體包佈局和指令可能有所不同。保護金鑰目錄，並確保 Kopano 服務帳戶可以讀取所需檔案。

驗證憑證是否與用戶端實際使用的主機名稱相符，是否在有效期內，以及是否包含所有必需的中間憑證。 Kopano 手冊指出，其元件會檢查憑證的通用名稱 (CN) 和主題備用名稱 (SANN)。在多伺服器 TLS 設定中，伺服器也必須信任簽署用戶端憑證的 CA，並且必須設定授權用戶端憑證。切勿為了方便使用公共瀏覽器服務而使用自簽名憑證取代官方憑證。

如果 TLS 終止於 Apache、Nginx 或 Kopano Web，則應在該前端設定憑證和自訂listen連接埠。然後根據後端實際監聽的協定和連接埠設定上游協定和連接埠。不要因為公網端使用 HTTPS 就啟用上游 TLS；首先要確認後端連接埠也支援 TLS。

5. 驗證並重新載入正確的服務

在重新載入 Web 伺服器之前，請執行其設定檢查，例如sudo nginx -tNginx 或sudo apachectl configtestApache 的設定檢查。如果檢查報告錯誤，請在重新載入之前進行更正。使用發行版中安裝的服務名稱；例如：

sudo systemctl restart kopano-server
sudo systemctl status kopano-server --no-pager

只有當您更改 Kopano Core 的配置時才需要重新啟動它。如果僅更改了前端連接埠或證書，請驗證並重新載入前端服務。變更後立即檢查其日誌或錯誤日誌，並從客戶端網路重複執行相同的 OpenSSL 探測。此時握手應該會傳回預期的證書。然後測試實際的 Web 應用程式 URL 或 Kopano 用戶端連接，因為僅 TLS 連接成功並不能驗證應用程式路由或驗證。

請先閱讀結果再進行更多更改

沒有監聽套接字：檢查已設定的監聽器、服務狀態和綁定位址。
連線被拒絕或逾時：檢查防火牆、NAT、負載平衡器以及目標連接埠是否可達。
證書錯誤：檢查在回應該連接埠的端點上配置的證書，包括 SNI 選擇和證書鏈。
TLS 在本機上有效，但在遠端無效：請將公用代理程式或負載平衡器路徑與本機監聽器進行比較，並檢查轉送的主機和連接埠值。
握手成功但 Web 應用程式失敗：檢查 HTTP 狀態、代理程式路徑、PHP/Web 應用程式日誌以及 Kopano Core 連線性。繼續在應用層進行操作。
只有核心用戶端會失敗：請檢查其server_socket自訂連接埠、受信任的 CA 和用戶端憑證設定。核心 TLS 路徑可能需要雙向憑證認證。