將 Collabora 部署在 Nginx 後面而不破壞 WebSocket

將 Collabora 部署在 Nginx 的專用 HTTPS 主機名稱上，將其編輯器和發現路徑轉送到該主機名coolwsd，並在即時套接字路由上明確傳遞 WebSocket 升級標頭。對於單一主機，Nginx 可以終止公共 TLS 連接，並透過私有介面向 Collabora 發送 HTTP 請求；如果 Nginx 和 Collabora 運行在不同的容器中，則使用它們共享網路上的 Collabora 服務名稱，而不是使用 `<hostname>` 127.0.0.1。

此範例假設使用者已開啟伺服器https://office.example.com，並且 Nginx 會處理其憑證。 Collabora 的預設監聽連接埠為 9980；請使用部署環境中可存取的連接埠。 URL 前綴（例如 `<URL>`）https://example.com/collabora/需要協調路徑和服務根設置，因此此根主機配置將不會直接套用。

1. 定義上游和 WebSocket 連線映射

在 Nginx設定中，為 Collabora 新增一個上游名稱，並新增一個映射，僅在客戶端請求 WebSocket 時才http設定連線頭。將此程式碼區塊放在任何其他配置區塊之外。如果 Nginx 透過其他方式連接到 Collabora，請替換此位址。upgradeserver

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

upstream coolwsd {
    server 127.0.0.1:9980;
}

如果 Nginx 本身就是一個容器，127.0.0.1則指向該 Nginx 容器，而不是 Collabora 容器。在共用的 Docker 網路中，上游服務可以改為server collabora:9980;使用在該網路中解析的服務名稱。

2. 新增 HTTPS 虛擬主機和 Collabora 路由

在 `<URL>` 的HTTPSserver設定區塊內office.example.com，轉送瀏覽器資源、服務發現端點、WebSocket 連線以及其餘的 Collabora 路徑。這些位置遵循 Collabora 的代理指南。請將特定的套接字位置放在更廣泛的cool`/`lool路由之上，以便 Nginx 正確應用 WebSocket 標頭。

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

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/private-key.pem;

    location ^~ /browser {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://coolwsd;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location ^~ /cool/adminws {
        proxy_pass http://coolwsd;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

將憑證路徑替換為您主機上的檔案路徑。如果您的安裝未使用管理控制台，則/cool/adminws文件編輯可能不需要此位置；主/cool/.../ws路由至關重要。proxy_read_timeout此處以一小時為例，並非普遍要求。 Nginx 的預設代理程式讀取逾時時間為連續讀取之間的 60 秒。請選擇比會話所需空閒時間更長的值，或在支援的情況下依賴適當的 WebSocket ping 流量。

3. 將 Collabora 的 TLS 模式與代理人躍點相符

使用者應透過 HTTPS 存取 Collabora，即使私有 Nginx 到 Collabora 的跳躍使用 HTTP。在這種 TLS 終止設定中，請將coolwsd代理伺服器設定為 TLS 終止器：停用內部監聽器的 SSL，並啟用 SSL 終止。透過您的軟體包或容器鏡像支援的方法套用這些設置，然後按照 Collabora 文件的要求重新啟動/重新載入 Collabora。

僅在受信任的私人網路上使用 HTTP 上游伺服器，並阻止對 9980 連接埠的公共存取。如果政策要求 Nginx 和 Collabora 之間進行加密，請使用 HTTPS 上游伺服器並正確配置憑證驗證；不要為了掩蓋憑證不符而停用驗證。 Collabora 的代理設定文件區分了代理端的 SSL 和代理與 . 之間的 SSL coolwsd。

此外，請將儲存整合中的 Collabora URL 設定為公共 HTTPS 主機名稱。 Nextcloud 的管理手冊要求瀏覽器和兩個伺服器能夠透過 HTTP(S) 相互訪問，並且外部協定必須匹配。請將 WOPI 允許清單限制為預期的儲存主機和 Collabora 位址；不要為了解決代理路由錯誤而大幅放寬允許清單。

4. 從兩側測試配置

重新載入 Nginx 之前，請檢查其語法：

sudo nginx -t
sudo systemctl reload nginx

如果 Nginx 運行在容器中，請改用該容器的驗證和重新載入流程。從 Nextcloud 主機，使用實際主機名稱測試公共 Collabora 端點：

curl -fsS https://office.example.com/hosting/discovery -o /dev/null
curl -fsS https://office.example.com/hosting/capabilities -o /dev/null

使用者瀏覽器也應開啟這些 HTTPS URL。雖然它們會檢查可及性，但僅憑成功的發現回應並不能證明文件編輯功能正常。開啟文件並使用瀏覽器的網路面板確認資源已載入且連線/cool/.../ws保持開啟。成功的 HTTP/1.1 WebSocket 連線通常會顯示 405 錯誤101 Switching Protocols；具體顯示內容可能因瀏覽器和傳輸協定而異。如果此標準設定在 Firefox 中有效，但在 Chromium 中失敗，請檢查請求方法和協定。 Collabora 25.04 版本中有一個問題報告記錄了 Chromium 使用 HTTP/2 進行 WebSocket 連線CONNECT並收到 405 錯誤的情況；截至 2026 年 10 月 9 日，該問題仍處於開放狀態。這是一個特定版本的報告，並非普遍現象。在更改 HTTP/2 設定之前，請先比較您的 Collabora、Nginx 和瀏覽器版本。參見Collabora 問題 12155。

如果發現失敗，請檢查 Nginx 的錯誤日誌，並驗證上游主機名稱、連接埠和協定。如果發現成功但編輯功能無法連接，請檢查 WebSocket 路由、標頭、逾時以及 Collabora 日誌。 WOPI 授權錯誤通常指向儲存主機允許清單。 Nextcloud Office 故障排除指南建議檢查瀏覽器、Nextcloud 和 Collabora 的連結性，然後查看兩台伺服器的日誌。

Nginx WebSocket 代理指南解釋了為什麼必須明確傳遞Upgrade`and` 參數，以及空閒逾時行為為何重要。有關指令行為，請參閱Nginx 代理模組參考文件。檢查通過後，請開啟、編輯、儲存並重新開啟測試文檔，然後再邀請使用者使用新路由。Connection