如何修復 Zimbra 的「Nginx 代理服務已停止」錯誤

當 Zimbra 報告「Nginx 代理服務已停止」時，表示代理程式已停止運作或其狀態檢查無法確認其正在運作。如果停止只是暫時的，重新啟動代理即可恢復存取；但如果 Nginx 無法載入其產生的設定、綁定所需的連接埠、讀取憑證或連接到有效的上游伺服器，則仍會傳回相同的訊息。理想的結果不僅僅是狀態顯示為綠色：代理應該保持運行，Zimbra Webmail 應該可以透過預期的公共 URL 加載，並且代理程式日誌不應再顯示啟動失敗的資訊。

本指南適用於使用 Zimbra Proxy 服務的 Zimbra 部署。具體命令和配置細節可能因 Zimbra 版本和拓撲結構而異。在多伺服器安裝中，請先檢查代理節點，不要僅僅因為其他伺服器報告代理程式已停止運行，就在郵箱或郵件傳輸代理程式 (MTA) 節點上啟用代理程式。 Zimbra 的代理指南和代理 CLI 參考文件詳細介紹了該服務及其診斷文件。部分技術中心故障排除頁面仍在開發中，請將其與已安裝版本的文件結合使用。

1. 確認代理伺服器是否應該在此伺服器上執行

連接到託管代理的 Zimbra 伺服器，並切換到 Zimbra 帳戶。檢查整體服務清單和代理的特定狀態：

su - zimbra
zmcontrol status
zmproxyctl status
zmprov gs `zmhostname` zimbraServiceEnabled

請查看proxy已啟用服務清單以及狀態輸出中是否顯示正在執行的 NGINX 進程。 Zimbra 文件中zmproxyctl包含相關說明，例如 `<commail-name>` start、`<command-name>` stop、 `<command-name> ` 和`<command-name>` 操作。如果此主機僅用作郵箱或郵件傳輸代理程式 (MTA) 節點，則代理程式可能已停止運作。在嘗試啟用伺服器之前，請確認其在部署中的角色。restartreloadstatus

如果代理程式應該處於活動狀態但狀態顯示為停止，請在進行任何變更之前擷取目前狀態。這有助於區分重啟失敗和節點上從未啟用過的服務。

2. 重啟前請閱讀 NGINX 錯誤日誌。

Zimbra 的代理程式故障排除指南將 `<proxy_log_name>`/opt/zimbra/log/nginx.log和/opt/zimbra/log/nginx.access.log`<proxy_log_name>` 列為關鍵代理程式日誌。請檢查最近的錯誤條目以及主設定檔是否存在：

tail -n 100 /opt/zimbra/log/nginx.log
tail -n 50 /opt/zimbra/log/nginx.access.log
ls -l /opt/zimbra/conf/nginx.conf

錯誤訊息通常會指向下一個檢查點。缺少某個參數nginx.conf表示產生的配置需要調查。指令中的「無效連接埠」listen指向連接埠或綁定設定。私鑰或憑證錯誤指向 SSL 相關內容。綁定失敗表示另一個程序可能已經佔用了該位址和連接埠。

請勿刪除 NGINX 設定檔或編輯產生的檔案來消除錯誤。 Zimbra 會根據儲存在其配置目錄和 LDAP 中的範本和值來建構 NGINX 配置。供應商的代理配置和範本指南解釋了這種生成模型。手動編輯產生的檔案可能會在後續重新啟動或設定更新時被覆寫。

3. 嘗試重啟支援的代理伺服器並檢查結果

如果日誌未顯示持久性設定或憑證錯誤，請以 Zimbra 使用者身分透過 Zimbra 控制器重新啟動服務：

zmproxyctl restart
zmproxyctl status

然後再查看完整的服務清單：

zmcontrol status

成功的結果應該是代理報告正在運行，並且在命令執行完畢後仍然保持運行狀態。 Zimbra 的代理文件將此描述zmproxyctl restart為同時觸發配置產生的服務操作。請勿使用系統級指令systemctl restart nginx作為替代方案：Zimbra 管理自己的代理程式設定和服務。如果重新啟動失敗，請返回最新的錯誤訊息nginx.log；在未讀取錯誤訊息的情況下重複重新啟動通常無法解決問題。

4. 將錯誤與針對性的修復措施相匹配

如果設定檔缺失或產生失敗

Zimbra 針對代理程式設定缺失問題的故障排除說明/opt/zimbra/conf/nginx.conf描述了代理程式設定產生失敗的情況，原因是上游屬性包含不存在的伺服器或非郵件伺服器。請先檢查相關的伺服器級和全域值：

zmprov -l gs `zmhostname` zimbraReverseProxyAvailableLookupTargets
zmprov -l gs `zmhostname` zimbraReverseProxyUpstreamEwsServers
zmprov -l gs `zmhostname` zimbraReverseProxyUpstreamLoginServers
zmprov -l gcf zimbraReverseProxyAvailableLookupTargets
zmprov -l gcf zimbraReverseProxyUpstreamEwsServers
zmprov -l gcf zimbraReverseProxyUpstreamLoginServers

將每個主機名稱與實際伺服器清單和您預期的路由設計進行比較。只有在確認哪個伺服器應該接收該流量後，才能修正過時或無效的條目。切勿將供應商頁面上的範例主機名稱直接複製到生產環境中。官方的「Nginx 啟動失敗」故障排除說明中提供了一個針對特定缺失配置/生成器錯誤模式的設定產生器命令：

/opt/zimbra/libexec/zmproxyconfgen -s `zmhostname`
zmproxyctl restart

僅當觀察到的故障與該模式相符，並在檢查相關值後才使用此方法。如果生成器仍然拋出異常或檔案仍然丟失，請停止並檢查完整的堆疊追蹤和伺服器屬性，而不是重複重新運行。

如果日誌報告無效連接埠或綁定失敗

首先確定哪個已配置的監聽器故障。檢查該節點的 Zimbra 服務和代理埠值，然後檢查是否有其他程序已經在監聽受影響的位址。例如，如果訊息中提到連接埠 443，請驗證公用 HTTPS 監聽器是由 Zimbra NGINX 還是由單獨的 Web 伺服器或負載平衡代理程式擁有。在了解用戶端如何存取服務之前，請勿終止未知進程或指派新連接埠。

出現此類錯誤invalid port ...:0並非猜測連接埠號碼的理由。它可能表示代理設定或產生的配置不一致。請將該值與預期拓撲進行比較，檢查最近的更改，並透過 Zimbra 支援的工具更正來源設定。然後重新啟動zmproxyctl並確認產生的監聽器有效。

如果在載入憑證或私鑰時啟動失敗

仔細閱讀完整的 SSL 錯誤訊息，並確定其中提到的憑證路徑。確認憑證和私鑰匹配，且預期的服務帳戶可以讀取，且憑證未過期。 Zimbra 的代理故障排除文件中包含代理無法載入金鑰材料的情況。請按照適用於您 Zimbra 版本的憑證部署流程進行操作，而不是隨意取代檔案。成功重新啟動後，SSL 啟動錯誤應該會消失，瀏覽器應該會顯示公共 Webmail 主機名稱的預期憑證。

如果 NGINX 啟動但使用者看到網關錯誤

代理伺服器運作正常並不能證明郵件信箱後端伺服器運作良好。對於「無路由到主機」的錯誤，Zimbra 建議檢查代理節點的 DNS 解析以及連接埠到目標後端伺服器的可及性。對於 502 或 503 回應，請驗證郵件服務以及上游主機和連接埠；代理指南指出，不可用的郵件信箱進程可能會導致 503 錯誤。請使用與您的版本和拓撲結構完全匹配的後端伺服器和端口，並在更改代理逾時或故障閾值之前檢查郵箱伺服器日誌。

5. 從伺服器和瀏覽器驗證恢復情況

完成針對性維修後，請確認以下所有事項：

zmproxyctl status報告代理正在運行。
zmcontrol status顯示此節點的預期服務。
最新幾行程式碼/opt/zimbra/log/nginx.log沒有重複出現相同的啟動失敗問題。
預期的監聽器存在，並且屬於目標服務。在 Linux 系統中，管理員可以使用指令檢查監聽器ss -ltnp；權限和輸出詳情因發行版而異。
瀏覽器可以透過 HTTPS 存取 Zimbra 的常規 Webmail 主機名，登入並載入郵件信箱。如果 IMAP 或 POP 用戶端也使用此代理，請單獨測試這些協定。

這些檢查定義了一個有效的恢復狀態：服務已啟動，監聽器存在，瀏覽器路徑有效，且故障未立即再次出現。如果服務狀態為綠色但 Webmail 仍然無法存取，則應檢查 DNS、TLS、防火牆規則、負載平衡器路由或郵箱後端健康狀況。如果服務再次停止，請保留新的日誌行和配置產生器輸出；這些資訊比盲目重新啟動更有用。

僅在進行簡短、可控的調查時才使用調試日誌。

如果常規日誌無法解釋持續存在的故障，Zimbra 會記錄暫時提高 NGINX 代理程式日誌等級的操作。偵錯日誌可能會洩露敏感訊息，包括身份驗證令牌，因此除非必要，否則請勿在生產系統中啟用此功能。如果技術支援人員指示您使用此功能，請限制對日誌的訪問，僅收集必要的信息，然後將設定恢復到先前的值，並根據您的安全策略處理偵錯日誌。有關適用於您版本的命令，請參閱 Zimbra 的NGINX 偵錯日誌記錄說明。

如果設定產生持續失敗、代理憑證無法驗證、錯誤提示存在未知監聽器或節點角色不明確，請聯絡您的 Zimbra 管理員或供應商支援團隊。服務控制器可以重新啟動正常配置，但它無法自行決定正確的郵件路由、修復無效憑證或解決損壞的網路路徑。