追蹤上游以清除 ONLYOFFICE 的 Nginx 502

首先檢查 Nginx 和 ONLYOFFICE Docs 之間的連接，然後查看與 502 回應對應的錯誤日誌。 502 Bad Gateway 表示網關無法從其上游伺服器取得有效回應；但這本身並不能證明是公共 Nginx 設定的問題。在 Docker 中，通常的解決方法是將 Nginx 指向文件伺服器服務名稱的內部連接埠 80，並確保兩個容器共用同一個網路。

編輯 Nginx 檔案之前應該檢查哪些內容？

反向代理伺服器接收客戶端請求並將其轉發到另一個伺服器。在常見的部署環境中，公用 Nginx 伺服器處理 HTTPS 請求，並透過 HTTP 將請求轉送到 ONLYOFFICE Docs。 ONLYOFFICE Docs 內部也運行著自己的 Nginx 伺服器，因此 502 錯誤頁面可能由外部代理伺服器或文件伺服器容器本身產生。

首先確定是哪個伺服器發出了回應。將頁面的伺服器頭和時間戳記與外部代理程式日誌和文件伺服器日誌進行比較。對於 Docker 環境，請檢查容器狀態和最近的啟動訊息：

docker ps --filter name=onlyoffice-documentserver
docker logs --tail 100 onlyoffice-documentserver

Docker 狀態輸出範例顯示 ONLYOFFICE 容器處於運作狀態；在變更代理程式之前，請檢查此狀態。 — Docker 狀態是第一個檢查項目：在追蹤 Nginx 路由之前，確認 ONLYOFFICE 容器正在運作。

如果容器正在重新啟動或剛啟動，請在變更代理設定之前檢查日誌。 ONLYOFFICE 指出，首次啟動可能需要一到兩分鐘，因為資料庫需要初始化。對於原生 Linux 安裝，請檢查ds-docservice並ds-converter執行systemctl status；文件伺服器日誌位於/var/log/onlyoffice/documentserver/。

如果服務停止運行，請使用 ONLYOFFICE 官方提供的相應Linux 故障排除說明。

Nginx 能否連接到上游的文檔伺服器？

請在 Nginx 容器或主機上進行測試，而不僅僅是在您的筆記型電腦上。位於不同 Docker 網路中的容器即使都在運行，也無法透過服務名稱相互解析。當 Nginx 和 ONLYOFFICE 共用使用者定義的 Docker 網路時，請使用 Compose 服務名稱或可解析的容器名稱以及容器的監聽連接埠。官方 Docker 安裝指南指出，預設的文件伺服器監聽連接埠為 80；已發佈的主機連接埠（例如 8080:80）不會變更內部連接埠。

從代理容器中運行：

curl -I http://onlyoffice-documentserver:80/

來自代理網路的範例 curl 回應，顯示與 ONLYOFFICE 服務名稱建立成功的 HTTP 200 連線。 — 代理網路傳回 200 回應，確認上游名稱和連接埠可達。

請將 `<your-compes-service-name> ` 替換onlyoffice-documentserver為您實際的 Compose 服務名稱。如果要求顯示“無法解析主機”，請將兩個容器連接到同一個 Docker 網路或修正上游名稱。「連線被拒絕」通常表示目標主機已解析，但該連接埠上沒有任何服務接受連線、容器未準備就緒或使用了錯誤的連接埠。如果是本機安裝，請改為測試本機位址和配置的連接埠，例如curl -I http://127.0.0.1/：

ONLYOFFICE 的 Docker 指南涵蓋了預設連接埠、連接埠對映、啟動延遲和容器日誌：Docker 安裝和驗證。

如何修正 Nginx 代理目標？

在 ONLYOFFICE 主機名稱的 HTTPS 虛擬主機配置中，指向proxy_pass可存取的上游伺服器。此範例假設使用共用的 Docker 網路和服務名稱如上所示；請根據您的部署情況進行變更：

location / {
    proxy_pass http://onlyoffice-documentserver:80;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

範例 Nginx location block 將請求轉送至連接埠 80 上的 ONLYOFFICE 服務（透過 HTTP）。 — 代理目標指向容器服務名稱及其內部端口，而不是無關的主機端口。

127.0.0.1:8080除非文件伺服器實際監聽在同一容器中，或主機位址已明確配置且可訪問，否則請勿將容器化代理指向該主機位址。在容器內部，127.0.0.1指的是容器本身。此外，當文件伺服器端點為純 HTTP 時，也應避免傳送 HTTPS 請求至上游。

轉送的協定和主機資訊會告知 ONLYOFFICE 用戶端使用的公共 URL，而升級標頭則允許使用 WebSocket 連線進行即時編輯器通訊。 ONLYOFFICE 提供了在代理伺服器後執行文件的維護範例，包括其Nginx HTTPS 到 HTTP 的配置。如果您的環境有多個代理跳轉或使用了 URL 路徑前綴，請參考該完整範例。

在套用變更之前，請先使用 `nginx update` 驗證配置nginx -t，然後使用適用於您的主機或容器的 `nginx update` 方法重新載入 Nginx。不要一次重啟所有服務；分階段重新加載可以更輕鬆地查看上游修復是否改變了結果。

如果 ONLYOFFICE 仍然回傳 502 錯誤怎麼辦？

如果外部代理可以存取文檔伺服器的歡迎頁面但/healthcheck傳回 502 錯誤，則問題可能出在文檔伺服器內部，而不是公共 Nginx 伺服器。請檢查文檔伺服器容器日誌和內部服務日誌。對於原生 Linux 安裝，請查看上述服務狀態指令和記錄目錄。如果服務/welcome/回應正常但健康檢查未回應，請將這兩種情況視為不同的訊號：靜態歡迎頁面並不能證明文件服務及其相依性運作正常。

請勿透過停用 JWT 來「解決」此問題。 JSON Web Token (JWT) 驗證用於驗證整合請求；JWT 不符通常會導致授權錯誤，而不是網路層級無法連接到上游伺服器。僅當代理伺服器回應但整合報告授權或令牌錯誤時，才應檢查 JWT 設定。

最後，確認 Nginx 是否將正確的主機名稱路由到正確的虛擬主機。主機名稱server_name、上游 DNS 名稱或連接埠號碼的拼字錯誤都可能導致流量被重定向到其他位置，或代理伺服器使用過時的設定。檢查 Nginx 錯誤日誌，尋找類似 `<hostname>`、`<up>` 或 `<port>` 的行host not found in upstream；connect() failed每upstream timed out行都指向不同的層級。

如何驗證修復是否成功？

從代理網路重新測試上游，然後檢查公共衛生端點，並透過連接的平台開啟文件：

curl -I https://docs.example.com/healthcheck

範例 curl 回應顯示來自公用 ONLYOFFICE 健康檢查 URL 的 HTTP 200。 — 成功的公共衛生檢查回應確認請求已透過 Nginx 傳遞到文件伺服器。

成功的健康檢查回應不應再返回 502 錯誤，並且應該能夠打開文件並在編輯過程中保持連接。如果上游測試成功但公共請求仍然失敗，請專注於檢查所選的 Nginx 虛擬主機、其已載入的配置以及日誌。如果公共歡迎頁面可以正常顯示但健康檢查仍傳回 502 錯誤，請繼續執行 ONLYOFFICE 的內部服務診斷。

有關 Nginx 指令的行為，請參閱Nginx 代理模組的官方文件。特定的命令和服務名稱可能會因 Docker Compose 專案、Linux 發行版和 ONLYOFFICE 版本而異，因此請替換為您自己的實際名稱，並查看產生回應的元件的日誌。