How to Set Up Nextcloud Office with CODE Docker in 10 Minutes

Current note for 2026: Nextcloud 35 documentation now separates Nextcloud Office, which is powered by Euro-Office, from Collabora Online, which remains a supported alternative and can still be self-hosted with the official CODE Docker image. This guide uses that external Collabora/CODE path. The naming matters because older guides often describe CODE as if it were the only server behind “Nextcloud Office.” See the current Nextcloud Office overview before applying instructions written for older releases.

If your Nextcloud site already works over HTTPS, Docker is installed, and you have a DNS name such as office.example.com ready for Collabora, the integration itself can be completed in about 10 minutes. DNS propagation, certificate issuance, firewall changes, or troubleshooting a reverse proxy can take longer and are not included in that estimate.

What you need before starting

The fast path assumes one existing Nextcloud instance, one Linux host that can run Docker, and a dedicated HTTPS hostname for CODE. Nextcloud's current Docker example recommends a separate subdomain and a valid TLS certificate. CODE listens on port 9980 internally, while a reverse proxy exposes it securely to browsers and to Nextcloud.

A working Nextcloud server reachable at a URL such as https://cloud.example.com.
Docker Engine on the host that will run CODE.
A DNS record such as office.example.com pointing to your reverse proxy.
A valid HTTPS certificate for the office hostname.
Administrator access to Nextcloud and root or sudo access to the Docker host.

Nextcloud's current installation documentation says the built-in CODE server is easiest for personal or small-team use, but recommends a dedicated Collabora Online installation for better performance. The official collabora/code image on Docker Hub is the image used below.

終端機視窗顯示 Docker 版本輸出，並且正在拉取官方 collabora/code 映像。 — Verify Docker first, then pull the official Collabora CODE image. The exact Docker version shown is illustrative; use a currently supported Docker release on your host.

Step 1: Pull the CODE Docker image

On the Docker host, confirm that Docker is available and pull the official image:

docker --version
docker pull collabora/code:latest

The latest tag is convenient for a short setup guide because Collabora publishes updates frequently. For a production environment, consider pinning a specific version that you have tested, then schedule deliberate upgrades instead of allowing an unexpected image change during a rebuild.

Step 2: Start CODE for your Nextcloud host

目前的 Nextcloud Docker 範例使用aliasgroup1以下方式告知 CODE 允許整合哪些 Nextcloud 主機。請將範例中的主機名稱替換為您真實的 Nextcloud URL：

docker run -t -d   --name collabora-code   -p 127.0.0.1:9980:9980   -e 'aliasgroup1=https://cloud.example.com:443'   --restart always   --cap-add MKNOD   collabora/code:latest

當反向代理程式運行在同一台伺服器上時，綁定127.0.0.1連接埠 9980 可以防止其直接暴露在網路上。如果您的代理程式運行在另一台機器上，請設計網路規則，確保只有代理可以存取 CODE；不要簡單地將連接埠 9980 公開給所有人。

終端機視窗顯示在本機主機連接埠 9980 上啟動的 CODE 容器，由 docker ps 列出。 — 當同一主機上的反向代理提供公共 HTTPS 端點時，在 127.0.0.1:9980 上執行程式碼。

檢查容器是否正在運作：

docker ps --filter name=collabora-code
docker logs --tail 50 collabora-code

步驟 3：在程式碼前啟用 HTTPS 和反向代理。

Nextcloud 文件中將所需的 Collabora 路徑列為/browser`<path>` /hosting/discovery、` /hosting/capabilities<path>`、/cool/adminws`<path>`、/cool`<path>`，以及 WebSocket 流量/cool/.../ws。這就是為什麼通用的「代理 WebSocket 以外的所有流量」配置通常會導致編輯器部分開啟後斷開連線的原因。

設定編輯器顯示瀏覽器、主機發現、功能、酷炫和 WebSocket 路徑的反向代理路由。 — 您的反向代理必須轉發 Collabora 的瀏覽器、發現、功能、/cool 和 WebSocket 端點。請確保上游協定與您的 CODE 容器的 SSL 模式相符。

對於 Nginx，以下簡潔範例保留了 CODE 的預設內部 HTTPS，並在 Nginx 端終止了公共 TLS。請使用您自己的證書路徑：

server {
    listen 443 ssl http2;
    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 https://127.0.0.1:9980; proxy_set_header Host $host; proxy_ssl_verify off; }
    location ^~ /hosting/discovery { proxy_pass https://127.0.0.1:9980; proxy_set_header Host $host; proxy_ssl_verify off; }
    location ^~ /hosting/capabilities { proxy_pass https://127.0.0.1:9980; proxy_set_header Host $host; proxy_ssl_verify off; }
    location ^~ /cool/adminws { proxy_pass https://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_ssl_verify off; }
    location ~ ^/cool/(.*)/ws$ { proxy_pass https://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_ssl_verify off; }
    location ^~ /cool { proxy_pass https://127.0.0.1:9980; proxy_set_header Host $host; proxy_ssl_verify off; }
}

這只是一個極簡的路由範例，並非完整的 Nginx 安全基線。如果您在停用內部 TLS 的情況下執行 CODE，則上游伺服器將變為 HTTPS http://127.0.0.1:9980，且容器必須進行一致的設定。請勿將 HTTP 代理目標與仍期望使用 HTTPS 的 CODE 容器混用。

步驟 4：驗證公共 CODE 端點

在修改 Nextcloud 設定之前，請先在瀏覽器中開啟以下網址：

https://office.example.com/hosting/discovery

瀏覽器顯示來自 office.example.com 託管發現的 WOPI 發現 XML 回應。 — 來自 /hosting/discovery 的有效回應是確認公共 CODE 端點和反向代理是否回應的快速方法。

您應該收到 WOPI 發現 XML，而不是代理錯誤、證書警告或空白連接失敗訊息。您也可以透過命令列進行測試：

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

如果失敗，請先修復 DNS、TLS、代理或容器。將 Nextcloud 連接到故障的端點只會增加故障排除的難度。

步驟 5：啟用 Nextcloud 辦公室集成

以管理員身分登入 Nextcloud，開啟“應用程式”，前往“辦公室與文字”，然後啟用適用於您安裝的 Office 整合應用程式。儘管 Nextcloud 35 概述中已區分了 Euro-Office 和 Collabora 產品，但目前的 Nextcloud Collabora Docker 範例仍指導管理員安裝「Nextcloud Office」應用，然後在 Office 管理設定下設定外部伺服器。

Nextcloud 應用程式頁面位於「辦公室和文字」類別中，並已啟用 Nextcloud Office。 — 在輸入外部 CODE 伺服器位址之前，請先在 Nextcloud 中啟用 Office 整合應用程式。

如果您的 Nextcloud 版本使用了略有不同的標籤，請按照您自己的管理介面中顯示的產品名稱進行操作，而不是假設舊的螢幕截圖完全匹配。

步驟 6：將 Nextcloud 指向外部 CODE 伺服器

開啟管理設定 → Office。選擇外部 Collabora/Office 伺服器選項並輸入：

https://office.example.com

Nextcloud Office 管理介面，帶有外部 Collabora Online 伺服器 URL 欄位和連接成功指示器。 — 在代理伺服器可存取之後，需要在 Office 管理頁面中輸入外部 Collabora URL。

儲存設定並等待 Nextcloud 的連線檢查。 Nextcloud 建議兩端使用相同的協議，首選 HTTPS。檢查成功表示 Nextcloud 可以存取 Collabora 端點，但這並不保證在實際編輯過程中，所有瀏覽器 WebSocket 路由和 WOPI 請求都能正常運作。

步驟 7：限制 WOPI 請求

基本連線建立成功後，請加強 WOPI 配置。 Nextcloud 目前的設定指南強烈建議將 WOPI 請求限制為預期請求檔案的 Collabora 伺服器的 IP 位址。在「管理設定」→「Office」中，如果可用，請使用「WOPI 請求允許清單」欄位。

Nextcloud Office 管理頁面顯示 Collabora 伺服器 URL、連線成功狀態和 WOPI 允許清單欄位。 — 連線成功後，檢查 WOPI 允許列表，以便只有預期的 Collabora 伺服器位址才能請求檔案。

這是一項重要的安全控制措施，因為 WOPI 流程是 Collabora 代表 Nextcloud 使用者檢索和寫入文件的方式。請使用部署要求中實際代表 CODE 伺服器路徑的 IP 位址或網路；不要僅僅因為主機名稱看起來與伺服器 URL 欄位相似就將其貼到 IP 允許清單欄位中。請參閱 Nextcloud 的Collabora 配置和 WOPI 指南，以了解目前選項。

步驟 8：開啟實際文件並確認儲存

在 Nextcloud 中建立一個小的 ODT 或 DOCX 文件，打開它，輸入一句話，關閉編輯器，然後重新開啟文件。這將檢查完整的流程：瀏覽器 → 公共代碼主機名稱 → 反向代理 → 代碼 → 向 Nextcloud 發送 WOPI 請求 → 儲存回儲存。

在 Nextcloud 中開啟基於瀏覽器的 Collabora 文件編輯器，並顯示範例專案計畫文件。 — 最終測試是實際操作性的：建立或開啟一個文檔，並確認編輯器能夠載入、接受變更並將其儲存回 Nextcloud。

即使 Office 設定頁面顯示伺服器可訪問，設定也不代表完成。正常情況下，編輯器可以正常載入且沒有連接警告，文件可以正常編輯，並且儲存的變更在重新開啟後仍然保留。如果編輯器外殼可以載入但編輯/cool/.../ws過程中斷開連接，請先檢查 WebSocket 連線。如果編輯器完全無法載入文件，請檢查 CODE 日誌、Nextcloud 日誌、兩台伺服器之間的 DNS 解析以及 WOPI 允許清單規則。

快速故障排除清單

症狀	首先檢查
Nextcloud提示辦公室伺服器無法存取。	`/hosting/discovery`透過 Nextcloud 主機上的 HTTPS開啟。
瀏覽器返回 502 或 504	確認容器正在運行且代理可以存取`127.0.0.1:9980`。
編輯器打開後，斷開連接。	驗證 WebSocket 升級標頭和`/cool/(...)/ws`路由。
證書錯誤	修復公鑰憑證鏈，並確保配置的 URL 使用正確的主機名稱。
WOPI 存取被拒絕	查看 Nextcloud 的 WOPI 允許清單和 CODE 允許的 Nextcloud 主機配置。
在一個網路上可以正常運作，但在另一個網路上則不行。	檢查分離式 DNS、防火牆規則，以及 Nextcloud 和 CODE 是否可以解析對方的公共名稱。

保持程式碼更新，同時避免升級變成意外狀況

Collabora 會頻繁發布 CODE 更新。 Docker Hub 官方頁面會顯示正在積極維護的標籤，而 Nextcloud 的升級指南也指出，Docker 部署的更新是透過拉取新映像並重新建立容器來實現的。對於家庭伺服器來說，追蹤更新latest是合理的。對於企業用戶，建議鎖定一個經過測試的標籤，閱讀發行說明，備份配置，然後在維護視窗期間進行升級。

此外，也要注意 CODE 的適用範圍。 Docker Hub 將 CODE 描述為面向家庭用戶的開發版本，而 Nextcloud 文件則建議規模更大或對可靠性要求更高的部署使用受支援的企業級版本。 10 分鐘即可完成的 Docker 設定非常適合個人雲端、實驗室或小型團隊，但它無法取代容量規劃、監控、備份或企業級支援。

最終結果

容器運行正常、HTTPS 代理配置正確、/hosting/discovery響應及時、Nextcloud 集成指向https://office.example.com正確地址、WOPI 已限制訪問，並且實際文檔可以打開和保存後，集成即完成。最重要的不是命令的數量，而是保持網路路徑的一致性。 Nextcloud、CODE、反向代理以及使用者的瀏覽器都必須能夠透過正確的 WebSocket 和 WOPI 路由存取預期的 HTTPS 主機名稱。