如何在 Nginx 後設定 Collabora Online

一個正常工作的反向代理該做什麼

一個運作良好的 Collabora Online 部署在 Nginx 之後，會為使用者提供一個公共 HTTPS 位址用於編輯器，同時將 Collabora 服務保持在私人網路上。編輯器應該能夠載入瀏覽器資源、發現辦公室功能、透過連接的儲存平台開啟文檔，並在編輯過程中保持 WebSocket 連線。僅憑有效的 Nginx 語法檢查並不能證明這些路徑都能正常運作。

此範例假設一個獨立的 Collabora 伺服器或 CODE 容器監聽 9980 端口，Nginx 提供服務office.example.com，TLS 連接終止於 Nginx。請將主機名稱和憑證路徑替換為您自己的主機名稱和憑證路徑。後端位址127.0.0.1:9980僅適用於 Nginx 和 Collabora 共用相同主機且服務綁定至回環位址的情況。對於獨立的容器，請在私有 Docker 網路上使用 Collabora 服務名稱，例如 `<command>` http://collabora:9980。

瀏覽器將 HTTPS 流量傳送至連接埠 443 上的 Nginx，Nginx 將其轉送至連接埠 9980 上的私人 Collabora Online 服務。 — 範例部署路徑顯示，公用 HTTPS 連線終止於 Nginx，而私有連線則連線到 Collabora Online。

在更改 Nginx 之前

確認公網 DNS 名稱解析到代理伺服器，TLS 憑證涵蓋該名稱，且 Nginx 可以透過其內部位址存取 Collabora。如果您使用 Docker，請將這兩個服務都連接到使用者自訂網絡，並且不要公開 Collabora 連接埠。如果 Nginx 運行在主機上，請將容器連接埠綁定到回環位址，例如 `/etc/ 127.0.0.1:9980:9980collabora/bin ...

選擇一種 TLS 方案。以下配置使用瀏覽器到 Nginx 的 TLS 協議，並透過受信任的私有躍點使用純 HTTP 協定連接到 Collabora。這是 TLS 終止。如果政策要求代理程式和 Collabora 之間也進行加密，請對上游使用 HTTPS，並設定 Nginx 信任後端憑證。不要只切換協定：伺服器端的 TLS 設定必須與實際的 Collabora 監聽器設定相符。 Collabora 在其Nginx 反向代理指南和25.04 SDK 手冊proxy_pass中記錄了這兩種代理方案。

設定 Collabora 的代理感知 TLS 選項

若要啟用 TLS 終止，請使用 `--tls-terminal` 和 `--tls- terminal`設定 Collaboracoolwsd服務。這些值的設定方式取決於 Collabora 的安裝方式：您可以編輯支援的配置，也可以使用適用於您的軟體套件或容器的文件化選項。對於 CODE Docker 映像，部署通常會將選項作為 `--tls-terminal` 傳遞；請查看映像檔以了解您的版本，並在 Compose 中正確引用參數。更改配置後，請重新啟動或重新建立 Collabora 服務。ssl.enable=falsessl.termination=truecoolwsd.xmlextra_params

這些設定告知 Collabora，即使代理到後端的躍點使用 HTTP，外部連線也受到代理的保護。這些設定不會安裝公共憑證、設定 DNS 或授權儲存伺服器使用 Collabora。請根據您的儲存平台單獨配置 WOPI 主機允許清單或整合設定。

設定 Nginx 以轉送編輯器路由

Nginx 必須傳遞服務發現和瀏覽器資源，並保留互動式編輯使用的 WebSocket 升級。以下是一個單一伺服器範例。請map在 Nginxhttp上下文（例如主上下文）中定義nginx.conf，而不是在虛擬主機中定義：

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

將伺服器區塊新增至 Nginx 提供的網站配置中。這假設 TLS 憑證已安裝，且代理程式到 Collabora 的連線是 HTTP：

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

    ssl_certificate     /etc/letsencrypt/live/office.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/office.example.com/privkey.pem;

    location ^~ /browser {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
        proxy_buffering off;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
    }
}

以 `/webSocket/` 開頭的路徑/cool承載主要的 WebSocket 和編輯器請求；該模式還包含一些舊版/lool路徑以保持相容性。 Nginx 的 WebSocket 代理需要 HTTP/1.1 升級標頭，因為 `/webSocket/`Upgrade和`/webSocket Connection/` 是逐跳標頭。較長的讀取逾時時間有助於避免因普通的短代理逾時而關閉原本活躍的編輯連線。請參閱Nginx WebSocket 代理文件和代理模組參考。

Nginx 虛擬主機設定編輯器顯示辦公室主機名稱、TLS 憑證路徑以及 Collabora 瀏覽器和託管端點的位置。 — 範例虛擬主機將 Collabora 的瀏覽器資源和託管端點路由到私有服務。

對於上游的 HTTPS，請變更後端 URLhttps://並正確設定 Nginx 的上游憑證驗證和受信任憑證鏈。請勿將禁用證書驗證作為永久性解決方案。如果 Nginx 位於另一個容器中，請將回環位址替換為 Collabora 服務名稱；127.0.0.1代理容器內部的位址將指向該代理容器。

當您使用 URI 前綴（例如 ` /collabora//`）而不是專用主機名稱時，配置和 Collabora 產生的發現 URL 需要額外的路徑處理。除非您的平台明確支援子路徑部署，否則請先使用專用主機名稱。將請求轉發到根目錄的伺服器區塊不會自動使發現產生的 URL 在前綴下正常運作。

重新載入並驗證每一層

請先驗證 Nginx 配置，然後再套用配置，最後重新載入服務：

sudo nginx -t
sudo systemctl reload nginx

如果語法檢查失敗，請先修復報告的檔案和行。重新載入成功表示 Nginx 已接受配置，但不代表後端、憑證或 WebSocket 路徑有效。請分別檢查 DNS 和憑證的有效性，然後透過公用主機名稱請求兩個 Collabora 端點：

curl -fsS https://office.example.com/hosting/discovery | head
curl -fsS https://office.example.com/hosting/capabilities

發現端點應傳回 XML 數據，而不是 Nginx 404 頁面或登入頁面；功能請求應傳回來自 Collabora 的回應。檢查發現 XML 的編輯器 URL：它們應使用公共 HTTPS 主機名稱和可存取路徑，而不是容器名稱或僅限內部使用的位址。下面的範例圖片展示了需要尋找的回應類型；其顯示的值僅供參考，並非實際伺服器的輸出。

兩個瀏覽器面板分別以 XML 格式和 JSON 格式顯示 Collabora 發現端點和功能端點，主機名稱皆為安全主機 office.example.com。 — 使用公用主機名稱檢查發現功能是否回傳 XML，以及功能端點是否有回應。

最後，配置您的文件平台以使用https://office.example.comCollabora 伺服器，並開啟一個測試文件。一個有效的成功標誌是編輯器能夠加載，並且在輸入、儲存和重新開啟文件時保持回應。在瀏覽器開發者工具中，WebSocket 請求/cool/應該升級成功；HTTP 狀態碼101 Switching Protocols應為預期的 WebSocket 握手結果。請勿將範例狀態碼視為您的伺服器已通過此檢查的證據。

瀏覽器網路面板上方顯示一個通用的線上文件編輯器，面板中列出了瀏覽器資源、發現、功能和 WebSocket 請求。 — 在實際編輯工作階段期間，檢查瀏覽器網路面板，查看資源請求是否成功以及 WebSocket 是否升級。

根據症狀解讀失敗案例

502 Bad Gateway： Nginx 無法連線到上游伺服器。請檢查服務名稱、連接埠、容器網路、監聽器和日誌。如果容器是獨立的，請勿使用代理容器的回環位址。
發現或瀏覽器資源時出現 404 錯誤：確認請求已到達正確的虛擬主機，且該位置轉送的路徑沒有發生意外的 URI 重寫。測試公用 URL，而不僅僅是後端 URL。
編輯器載入後卡住或斷開連接：檢查/cool/.../ws請求。缺少升級標頭、上游連線為 HTTP/1.0、逾時時間過短或代理伺服器緩衝連線都可能導致編輯中斷。確認請求升級成功，並在文件處於活動狀態時保持開啟。
未經授權的 WOPI 主機：代理伺服器可能運作正常，但 Collabora 會拒絕該儲存平台。請將實際的 WOPI 主機名稱與 Collabora 的允許清單和平台的連接器配置進行比對。切勿透過將後端暴露於公共互聯網來解決此問題。
混合內容或憑證警告：請確保公共編輯器 URL 和發現過程中的 URL 均使用 HTTPS，並且憑證與主機名稱相符。如果您在 Nginx 上終止 TLS，請同時驗證 Collabora 的終止設定。

這些檢查通過後，請將 Collabora 後端保持私有狀態，並在升級任一元件時監控 Nginx 和 Collabora 日誌。此單上游範例未配置高可用性、負載平衡或基於文件的會話親和性。對於多個 Collabora 副本，請遵循相關 Collabora 控制器或負載平衡器的部署指南，並在路由生產流量之前測試文件親和性。

來源和版本說明

2026年10月6日，我們對照Collabora的代理文件、25.04 SDK手冊以及Nginx的WebSocket和代理模組參考文件檢查了配置詳情。軟體包和容器選項可能會因Collabora版本而異；請在應用程式設定前確認您所執行版本的設定名稱。本文並未假設使用特定的儲存平台，也未提供實際部署的證明。