如何為 Collabora CODE 容器設定 SSL 終止

如果您希望使用一個公共 HTTPS 端點，同時將憑證管理保留在 Nginx 等反向代理程式上，那麼 SSL 終止非常適合 Collabora 線上開發版 (CODE) 容器。在這種設計中，瀏覽器透過 HTTPS 連接到 Nginx，Nginx 會對流量進行解密，然後 Collabora 在其內部連接埠接收純 HTTP 資料。品質目標不僅僅是「頁面載入成功」。成功的部署應該具備有效的公共憑證、可存取的 WOPI 發現端點、正常工作的 WebSocket 升級以及保持連線的真實文件編輯會話。

Collabora 本身的代理文件將此 SSL 卸載模式描述為代理伺服器和 Collabora 之間僅使用 HTTP 的連接，而Collabora 端ssl.enable=false也需要進行相應的配置。請參閱Collabora Online 反向代理設定。以下範例使用 Nginx 和 Docker Compose，但如果其他反向代理程式能夠保留所需的 host 和 WebSocket 行為，也可以達到相同的效果。ssl.termination=true

一個好的 SSL 終止設定應該達到什麼目標

步驟 1：更改 Collabora 之前確認網路邊界

確定 TLS 的終止位置以及哪些主機可以存取 9980 連接埠。如果 Nginx 與 Docker 運行在同一台機器上，將發布的連接埠綁定到本機127.0.0.1網路是防止直接存取網際網路的簡單方法。 Docker 文件指出，將連接埠發佈127.0.0.1到本機網路會使其僅限於本機主機；請參閱Docker 的連接埠發佈文件。

如果 Nginx 運行在另一個容器中，共享的私人 Docker 網路通常比公開 9980 連接埠更簡潔。原理相同：客戶端應該使用 HTTPS 反向代理的主機名，而不是直接使用 Collabora 容器的主機名稱。

步驟 2：以 SSL 終止模式執行程式碼

對於代理端 TLS 終止，即使 Collabora 的直接上游連線是 HTTP，它也應該知道面向客戶端的原始方案是 HTTPS。相關設定如下：

--o:ssl.enable=false --o:ssl.termination=true

一個最簡 Compose 範例如下所示：

services:
  collabora:
    image: collabora/code:YOUR_TESTED_TAG
    restart: unless-stopped
    ports:
      - "127.0.0.1:9980:9980"
    environment:
      - "extra_params=--o:ssl.enable=false --o:ssl.termination=true"
      - "server_name=office.example.com"

請替換YOUR_TESTED_TAG為您已驗證的版本，而不是想當然地認為它latest適用於生產環境部署。此外，請為您的整合配置對應的 WOPI 主機或別名設定；這些值取決於您連接的是 Nextcloud、ownCloud、其他 WOPI 主機還是自訂整合。

啟動容器後，請確認其正在運行，並且連接埠對映與您預期的邊界相符：

docker compose up -d
docker compose ps
docker logs --tail=100 collabora

26.04 版本部署說明

在排查目前 26.04 鏡像的問題時，不要將這兩個 SSL 標誌作為唯一的變數。 2026 年中，Collabora 追蹤了 distroless Docker 映像和停用 SSL 配置相關的迴歸問題。官方 GitHub issue 記錄了 26.04 啟動時的回歸問題，Collabora 社群後續報告稱，受影響的 SSL 終止行為在後續的 26.04.2.4.1 鏡像中已恢復正常。如果先前正常工作的終止配置在鏡像升級後立即失效，請查看CollaboraOnline/online 中的 issue #16019 。

這也是鎖定並測試鏡像版本的原因之一。配置錯誤和容器鏡像回歸在 Nginx 上的表現可能很相似：兩者都可能表現為 502 回應或上游連線失敗。

步驟 3：設定 Nginx 終止 TLS 連線並代理 Collabora 路徑

Nginx 需要為 Collabora 主機名稱配置有效的證書，並且必須轉送 Collabora 的 HTTP 端點和 WebSocket 流量。 Collabora 的代理指南列出了瀏覽器資源、服務發現、功能、主 WebSocket 連線、下載/上傳路徑以及管理 WebSocket 的專用位置。以下配置遵循該結構，並添加了常用的轉發標頭：

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;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    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 "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 36000s;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    location ^~ /cool/adminws {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 36000s;
    }
}

WebSocket 標頭並非無關緊要。 Nginx 官方文件解釋說，Upgrade`http ://example.com/webSocket` 和`http: //example.com/webSocket`Connection是逐跳標頭，對於反向代理的 WebSocket 連接，必須明確傳遞這些標頭。請參閱Nginx WebSocket 代理程式。標準代理模組文件也涵蓋了proxy_set_header`http: //example.com/webSocket`、`http://example.com/webSocket` 和 ` http://example.com/webSocket`：ngx_http_proxy_module。proxy_passproxy_read_timeout

步驟 4：重新載入前驗證 Nginx

在替換已知運作良好的 Nginx 配置之前，請先測試該配置：

sudo nginx -t

僅當語法測試成功時才重新載入：

sudo systemctl reload nginx

然後確認 Nginx 本身可以存取本地 Collabora 後端。在同主機配置中，一個有用的檢查方法是：

curl -I http://127.0.0.1:9980/hosting/discovery

具體的回應頭可能因 Collabora 版本而異，但關鍵在於 TCP 連線能夠成功建立，並且端點能夠回應，而不是逾時或拒絕連線。如果此本機請求失敗，變更公用 TLS 設定並不能解決底層容器或網路問題。

步驟 5：驗證公用 HTTPS 端點

從能夠解析公用主機名稱的客戶端，透過 Nginx 請求發現端點：

curl -I https://office.example.com/hosting/discovery

瀏覽器請求https://office.example.com/hosting/discovery應傳回 XML。這比依賴根 URL 是更好的功能性檢查，因為根頁面的行為並非 WOPI 的主要約定，並且可能因版本而異。

此外，請使用瀏覽器或 TLS 診斷工具檢查憑證鏈。主機名稱應與憑證匹配，憑證鏈應受信任，且不應出現因 Collabora 向瀏覽器發布純 HTTP URL 而導致的混合內容警告。

步驟 6：測試真實文件和 WebSocket

發現連線成功是必要條件，但並非充分條件。請從您的 WOPI 主機開啟一個文檔，並保持開啟狀態足夠長的時間以測試即時會話。在瀏覽器開發者工具中，Collabora WebSocket 請求應該能夠成功升級，而不是重複重新連線或傳回 400/502 錯誤。一個正常的會話應該允許您輸入、儲存並重新開啟文件。

如果編輯器外殼載入完畢但文件隨後載入失敗，請優先檢查 WebSocket 路徑、代理逾時、WOPI 允許清單和主機頭行為。如果 Nginx 日誌顯示 WebSocket 連線建立之前存在上游連線錯誤，請先檢查 CODE 的監聽器和鏡像版本。

如何診斷常見故障模式

502錯誤的網關

502 錯誤通常表示 Nginx 無法從設定的上游伺服器取得有效回應。請檢查 CODE 是否實際監聽 9980 端口，以及您是否使用了正確的上游協定。在預期的 SSL 終止設計中，代理程式到 CODE 的躍點應為 HTTP。如果鏡像回歸導致 CODE 儘管已啟用 HTTPS 標誌，但內部仍提供 HTTPS 服務，則日誌和直接curl測試將揭示此不匹配之處。不要僅僅為了掩蓋無法解釋的配置回歸而永久切換到 HTTPS 上游伺服器；請先驗證您正在運行的 CODE 鏡像的行為。

發現功能正常，但文件無法開啟。

這通常指向 WebSocket 轉送或 WOPI 授權問題，而非 TLS 本身。請檢查/cool/.../ws路由、升級標頭以及您允許作為 WOPI 來源的主機。 Collabora 可以透過 HTTPS 正常訪問，但仍可能拒絕或導致編輯會話失敗。

混合內容或錯誤的 URL 方案

如果瀏覽器發現 HTTPS 頁面引用了 HTTP 資源，請驗證ssl.termination=true轉送的協定標頭和伺服器名稱。即使私有躍點是 HTTP，部署的公共端也必須始終將自身標識為 HTTPS。

即使編輯功能正常，容器仍報告不健康。

最近發布的 26.04 版本引入了健康檢查行為，該行為在 distroless-image 過渡期間發生了變化。 Collabora 追蹤到一個案例，其中探測程式未能正確識別 TLS 終止後的 HTTP 後端配置。如果功能測試通過但 Docker 健康狀態意外顯示為紅色，請在重新設計工作代理之前，先查看特定版本的 issue 歷史記錄。參見CollaboraOnline/online issue #16032。

何時使用不同的設計

當反向代理和 Collabora 透過可信任的本地介面或隔離的私有網路通訊時，代理端 SSL 終止是適當的。如果 Nginx 和 CODE 之間的流量經過不受信任的網絡，則內部躍點上的純 HTTP 可能無法滿足您的安全要求。在這種情況下，也應使用 TLS 連接到後端，或將這兩個服務都放在一個受保護的網路上，以避免被攔截的風險。

同樣，如果您已經運行了一個平台管理的入口，能夠正確處理證書、路由和 WebSocket，那麼僅僅為了 Collabora 添加第二個 Nginx 層意義不大。正確的架構應該提供一個單一的、可觀察的 TLS 邊界，避免不必要的躍點。

最終驗證清單

• Collabora 主機名稱解析到反向代理程式。
• 連接埠 443 提供該主機名稱的受信任憑證。
• CODE 不會不必要地透過 9980 連接埠暴露給公共網際網路。
• ssl.enable=false並ssl.termination=true應用於HTTP後端設計。
• Nginx 可以透過其私有位址存取 CODE。
• /hosting/discovery透過公共 HTTPS URL 進行回應。
• WebSocket/cool/.../ws升級成功。
• 實際文件可以開啟、編輯、儲存和重新開啟。
• 您已鎖定並測試了您計劃部署的確切 CODE 鏡像版本。

如果所有這些檢查都通過，則 SSL 終止機制運作正常：外部流量受到 HTTPS 保護，Collabora 會將公共連接識別為安全連接，編輯路徑仍然可用。如果其中一項檢查失敗，請在該層進行故障排除，而不是一次性更改協定堆疊的多個部分。