如何修復 ONLYOFFICE 文件伺服器在 Nginx 後端的 502 Bad Gateway 錯誤

當瀏覽器開啟 ONLYOFFICE Docs URL 時顯示「502 Bad Gateway」錯誤，或 Nextcloud/ownCloud 連接器無法連線到文件伺服器。在這兩種情況下，Nginx 通常都收到了請求，但無法從上游伺服器獲得有效回應。上游伺服器可能是 ONLYOFFICE 的內部文件服務、Docker 容器或其他反向代理。首先確定是哪個 Nginx 伺服器回傳了 502 錯誤；然後在更改配置之前直接測試下一跳伺服器。

ONLYOFFICE 目前的 Linux 故障排除指南建議檢查ds-docservice服務ds-converter以及文件伺服器日誌。其反向代理指南也提到了轉送的主機頭和協定頭。以下步驟首先檢查服務運作狀況，然後檢查 Nginx 路由和 Docker 網路。

1. 找出哪個 Nginx 伺服器回傳了 502 錯誤

ONLYOFFICE 的軟體包安裝包包含其自身的 Nginx 配置，部署中可能還會包含外部 Nginx 反向代理程式。 Docker 可能會增加額外的網路躍點。僅憑 502 頁面的外觀可能無法確定特定層級，因此請將公用 URL 與本機健康檢查和 Nginx 錯誤日誌進行比較。

在基於軟體包的 Linux 安裝中，測試本機文件伺服器端點：

curl -i http://127.0.0.1/healthcheck

如果伺服器配置為在非預設本機連接埠上提供 ONLYOFFICE 服務，請使用該連接埠。正常情況下，伺服器會傳回帶有 . 的 HTTP 成功回應true。如果本機請求失敗，請先修復文件伺服器服務，然後再編輯外部代理程式。如果本機請求成功，但公用主機名稱傳回 502 錯誤，請專注於檢查外部 Nginx 上游伺服器、協定、標頭和防火牆路徑。

檢查哪些進程佔用了預期的連接埠：

sudo ss -ltnp | grep -E ':(80|443|8080|8000)\b'

連接埠因網路拓撲結構而異。常見的 Docker 對應會將主機連接埠（例如 8080）對應到容器連接埠 80；軟體包安裝可以使用主機上的 Nginx 伺服器。不要127.0.0.1:80因為兩個服務都在同一台機器上就假定上游伺服器配置正確。

2. 檢查 ONLYOFFICE 服務和日誌

在 Linux 軟體包安裝過程中，檢查文件服務和轉換器：

sudo systemctl status ds-docservice ds-converter
sudo journalctl -u ds-docservice -u ds-converter --since "15 minutes ago" --no-pager

ONLYOFFICE 的故障排除指南列出了這些服務，並指出當 Docs 服務啟動失敗時，應檢查記憶體不足、連接埠 80 衝突以及服務日誌。如果某個服務已停止，請先檢查其錯誤；然後僅重新啟動受影響的服務：

sudo systemctl restart ds-docservice

主 Linux 日誌目錄是/var/log/onlyoffice/documentserver/。請檢查 Nginx 錯誤日誌和 docservice 日誌，尋找類似「連線被拒絕」、「上游逾時」或檔案缺失之類的訊息。這些訊息指向不同的原因：連線被拒絕通常意味著上游進程或連接埠不可用，而逾時可能意味著服務過載或停滯。

如果服務重複退出，也要檢查可用磁碟空間和記憶體：

df -h
free -h

不要在不查看日誌的情況下不斷重啟故障服務；重啟可能會暫時掩蓋症狀，但並不能解決連接埠衝突、依賴項故障或資源問題。

3. 驗證 Nginx 是否指向可達的上游伺服器

讀取活動的虛擬主機配置，並確認其確切的位址和連接埠proxy_pass。從執行該 Nginx 的機器或容器中，直接向上游伺服器發出請求。例如，如果容器將連接埠 80 發佈為主機連接埠 8080：

curl -i http://127.0.0.1:8080/healthcheck

請將範例位址替換為代理實際可存取的端點。如果 Nginx 運行在單獨的 Docker 容器中，127.0.0.1請指 Nginx 容器本身，而不是 Docker 主機或 ONLYOFFICE 容器。請使用共用 Docker 網路上可存取的服務名稱，或正確的主機位址和已發佈的連接埠。

檢查上游協定是否與後端協定相符。僅http://當後端監聽器使用純 HTTP 協定且https://已配置 TLS 時才使用此方法。向 TLS 連接埠發送 HTTP 請求，或向純 HTTP 連接埠發送 TLS 請求，都可能導致 Nginx 認為正常服務不可用。

4. 檢查轉發的標頭和 WebSocket 代理

ONLYOFFICE 的反向代理指南建議保留原始協定和主機名X-Forwarded-Proto，X-Forwarded-Host以便應用程式能夠識別它們。官方的 Nginx 範例也傳遞了升級標頭。如果 ONLYOFFICE 前端使用了外部代理，請將其配置與符合您網路拓撲結構的官方範例進行比較。

下面展示了一個映射到主機連接埠 8080 的 Docker 容器的簡化範例。將該map指令放入 Nginx 的http上下文中，並根據您的設定調整主機名稱、TLS 配置和上游連接埠：

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

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

    location / {
        proxy_pass http://127.0.0.1:8080;
        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 $connection_upgrade;
    }
}

這只是一個參考模板，並非適用於所有安裝的直接替換方案。特別要注意的是，在不了解哪個伺服器區塊擁有 80 和 443 連接埠的情況下，切勿將其貼到 ONLYOFFICE 軟體包自帶的 Nginx 設定上。如果 Nginx 與軟體套件安裝的 ONLYOFFICE 共享主機，請先確認不存在連接埠衝突，並將外部代理程式路由至為您的部署設定的內部監聽器。

編輯完成後，請在重新載入 Nginx 之前測試配置：

sudo nginx -t
sudo systemctl reload nginx

如果配置測試失敗，請在重新載入之前修正報告的檔案和行。語法錯誤和上游 502 錯誤是兩個不同的問題；測試成功僅nginx -t確認語法正確，並不代表上游響應正常。

5. 如果 ONLYOFFICE 運作在 Docker 容器中，請檢查其運作狀況和連接埠對映。

檢查容器是否正在運作以及發布了哪個主機連接埠：

docker ps --filter name=onlyoffice
docker port <container_name_or_id>
docker logs --tail 100 <container_name_or_id>

官方 Docker 安裝指南將主機連接埠對應到容器連接埠 80，其範例會在歡迎頁面未載入時檢查容器日誌。請使用顯示的連接埠docker port作為主機端上游連接埠。如果 Nginx 和 ONLYOFFICE 都是容器，請將它們放在共用網路中，並將流量路由到 ONLYOFFICE 服務名稱和容器端口，而不是主機的回環位址。

如果您的 Compose 文件定義了健康檢查，請檢查容器的健康狀態。目前的上游 Compose 範例檢查的是http://localhost:8000/info/info.json容器內部。即使容器處於「運作中」狀態，其文件服務仍可能有健康問題。如果文件服務正在重新啟動或處於健康狀態，請在變更外部代理之前，使用日誌來調查資料庫啟動、記憶體和配置。

ONLYOFFICE 會記錄日誌、憑證和檔案快取的持久化 Docker 路徑。故障排除期間請避免刪除磁碟區；這些磁碟區可能包含復原服務所需的憑證或其他資料。

6. 重新加載，測試運行狀況端點，並重新測試集成

修復已確認的問題後，測試公共主機名稱並與本地端點進行比較：

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

請使用您的真實文檔伺服器 URL。如果本機上游和公用主機名稱都回應成功，則表示 Nginx 可以連線到後端並傳回其運作狀況回應。然後開啟文件伺服器歡迎頁面，並重試先前在 Nextcloud、ownCloud 或其他連接器中失敗的操作。

如果健康檢查成功但連接器仍然報告錯誤，則剩餘的問題可能不在 Nginx 502 路徑上，例如連接器 URL、TLS 信任或 JWT 設定。請將這些值與連接器和 ONLYOFFICE 配置進行比較，而不是盲目地繼續更改代理逾時時間。

快速診斷

官方參考資料

• ONLYOFFICE Docs Linux 系統故障排除
• ONLYOFFICE 文件透過代理伺服器訪問
• ONLYOFFICE 官方 Nginx HTTPS 到 HTTP 代理範例
• ONLYOFFICE Docs Docker 安裝和連接埠映射
• ONLYOFFICE 文件伺服器撰寫範例