將 Nextcloud 連接到自託管的 Collabora CODE 容器

若要將 Nextcloud 與自託管的 Collabora Online Development Edition (CODE) 容器連接起來，請在單獨的主機名稱上執行 CODE，將其置於 HTTPS 之後，並在 Nextcloud Office 中輸入其公共 URL。 CODE 容器也必須允許 Nextcloud 網站作為 WOPI 主機進行存取。在下面的範例中，Nextcloud 是 `<Nextcloud_name>`，cloud.example.comCollabora 是 `<Collabora_name>` office.example.com；請將兩者替換為您的實際主機名稱。

Linux 終端機提示符號顯示了 docker pull collabora/code 命令 — 終端提示符，其中包含用於下載 Collabora CODE 鏡像的命令。

開始之前需要準備些什麼？

您需要一個可正常運作的 Nextcloud 安裝、一個能夠執行 CODE 容器的 Docker 主機、Nextcloud 和 Collabora 主機名稱的 DNS 記錄，以及兩個公共網站的有效 HTTPS 憑證。 Nextcloud 主機和 Collabora 伺服器必須能夠透過網路相互存取。專用的 Collabora 伺服器旨在提升容量，優於內建的 CODE 選項；它目前仍處於開發階段，因此在將其用於更大規模或業務關鍵型部署之前，請務必查看 Collabora 的最新條款和發布指南。

本教學假設反向代理程式運行在 Docker 主機上，並將 HTTPS 流量轉office.example.com送到容器的本機連接埠。如果您的代理程式運行在不同的容器或另一台機器上，請勿直接複製回環連接埠對映：請使用代理程式可以存取的私人 Docker 網路或私人主機位址，並對後端進行防火牆保護，使其不對外公開。

1. 啟動 CODE 容器

首先，拉取鏡像並啟動容器。在別名設定中，使用 Nextcloud 的公共來源，包括協定和連接埠。請勿在此填寫 Collabora URL。 Nextcloud 的 Docker 安裝範例使用了這種模式：

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

回環綁定意味著連接埠 9980 只能從 Docker 主機訪問，例如透過同一主機上的反向代理。該代理程式為瀏覽器和 Nextcloud 提供一個公共的 HTTPS 端點，同時保持容器連接埠的隱私。如果 Nextcloud 使用非標準連接埠或不同的公共主機名，請確保別名與使用者實際使用的來源相符。如果您有多個 Nextcloud 實例，請使用 Collabora 文件中提供的語法來設定每個允許的 WOPI 主機，而不是隨意允許任意網域名稱。

上述指令遵循 Nextcloud 35 管理手冊中的 Docker 範例。在正式環境使用前，請查閱目前的 CODE 鏡像文檔，並選擇符合您維護流程的版本/標籤更新策略。預設鏡像參考資訊可能會隨著版本發布而變更；請規劃更新、監控容器，並在升級後重新測試文件編輯功能。

Nextcloud 管理應用程式頁面顯示 Nextcloud Office 應用程式已啟用 — 應用程式管理視圖顯示，在伺服器設定之前已啟用 Nextcloud Office。

2. 將容器置於 HTTPS 反向代理程式之後

配置您現有的代理伺服器，使其能夠處理https://office.example.com並轉送 CODE 服務的請求127.0.0.1:9980。請使用 Collabora 目前的反向代理配置作為您的代理軟體。代理伺服器必須保留必要的路徑並支援 WebSocket 升級；編輯器的瀏覽器工作階段依賴這些路徑。 Nextcloud Docker 範例包含指向 `<path>` /browser、/hosting/discovery`<path>`、/hosting/capabilities`<path>` 和`<path>` 的路由/cool，其中包含 WebSocket 端點。某些整合也使用了相容性/lool路由。

不要將首頁成功載入視為代理伺服器已完成的證明。如果代理伺服器能夠處理普通的 HTTPS 請求，但無法升級 WebSocket 連接，則可能會顯示編輯器框架，然後保持載入狀態或斷開連接。請為 Collabora 主機名稱使用有效的公鑰憑證。如果代理伺服器是唯一的入口點，請將 9980 連接埠對公網關閉。

3. 啟用 Nextcloud Office 並輸入伺服器 URL

Nextcloud Office 管理頁面，已選擇外部伺服器，URL 為 https://office.example.com — 選擇外部伺服器選項，然後輸入 Collabora 的公共 HTTPS URL。

在 Nextcloud 中，開啟「應用」，安裝或啟用Nextcloud Office（richdocuments整合）。然後開啟「管理設定」→「Office」，選擇外部 Collabora 伺服器選項，並輸入 URL https://office.example.com。儲存設定。請使用公用 URL，而不是localhost:9980.NET Framework：Nextcloud 伺服器和使用者的瀏覽器需要解析相同的外部 Collabora 端點。

Nextcloud 的管理手冊指出，配置的伺服器 URL 應使用與 Collabora 安裝相同的協議，並建議使用 HTTPS。儲存後，Nextcloud 可能會顯示連線或發現狀態。如果報告證書、DNS 或 WOPI 問題，請先解決該特定問題，然後再嘗試開啟文件。

4. 檢查 WOPI 路徑並開啟測試文檔

WOPI 是 Nextcloud 用於授予 Collabora 對文件受控存取權限的協定。在 Nextcloud 的 Office 管理設定中，檢查WOPI 請求的允許列表，並將請求限制為 Collabora 服務連接到 Nextcloud 的 IP 位址。同時，配置 Collabora 僅接受預期的 WOPI 主機。當涉及容器、NAT 或反向代理程式時，確切位址可能會有所不同，因此請使用 Nextcloud 日誌中實際看到的來源位址，而不是猜測。

一個雲端文件介面，其中打開了一個線上文字處理文檔，並且可以看到其格式工具列。 — 開啟具有編輯工具列的文件是 Office 整合回應的最後一個視覺檢查。

為了進行功能檢查，請以普通 Nextcloud 使用者身分登錄，建立或上傳一個小的 DOCX 或 ODT 文件，然後從「文件」應用程式中開啟它。確認編輯器載入完畢後，進行一些無害的更改，等待儲存提示出現，關閉文檔，然後重新開啟並確認更改已生效。針對部署中涉及的每種檔案類型和使用者群組進行測試；DOCX 測試成功並不能證明所有格式或權限路徑都已配置。

如果編輯器無法打開，應該檢查什麼？

發現或連接錯誤：確認office.example.comNextcloud 伺服器和瀏覽器可以解析，其憑證有效，且代理程式已將請求傳送/hosting/discovery至 CODE。
無限載入或編輯器斷開連線：檢查反向代理的 WebSocket 升級處理和/cool路由。查看代理程式和容器日誌，確認是否有被拒絕的請求。
WOPI 主機被拒絕：請將設定的主機位址aliasgroup1與 Nextcloud 的公有網路來源位址（包括協定和連接埠）進行比對。請將 Nextcloud 的 WOPI 允許清單與 Nextcloud 可見的 Collabora 來源 IP 位址進行比對。
在主機上可以正常運作，但在 Nextcloud 中卻不行：測試從 Nextcloud 伺服器到公共 Collabora URL 的連線。容器的內部主機名稱或 Docker 主機的本機主機位址並非對所有其他容器都自動可存取。
憑證警告：請修復憑證鏈或主機名稱不符問題。停用證書驗證可能會掩蓋問題原因並削弱連線。

為了進行診斷，請將您的配置與 Nextcloud 官方Docker 安裝範例、其Office 和 WOPI 配置指南以及 Collabora 的CODE Docker 映像和反向代理文件進行比較。這些參考資料版本較舊，可能會有所更改；此處的命令反映的是 2026 年 10 月 10 日發布的 Nextcloud 35 管理範例。