修正 Collabora Online CODE 中的「未授權的 WOPI 主機」錯誤

最快捷可靠的解決方法是讓 Collabora Online CODE 信任儲存平台發送的 WOPI 來源 URL 中顯示的確切主機名稱和連接埠。對於單一 Nextcloud 伺服器，請將 CODE 主機允許清單設定為該 Nextcloud 主機名，重新建立容器，然後再次測試。如果您執行多個 Nextcloud 實例，請明確地允許每個實例。不要透過向每個主機開放 WOPI 存取權限來解決此錯誤。

「未經授權的 WOPI 主機」通常表示 Collabora 拒絕了 WOPI 請求中指定的儲存主機。但這本身並不能證明使用者的密碼、文件權限、TLS 憑證或反向代理有問題。這些元件可能會導致其他連線失敗，因此在變更設定之前，請使用 Collabora 日誌確認具體原因。

選擇與您的部署相符的更改

部署	建議更改	權衡
一個帶有 Docker 程式碼的 Nextcloud 實例	設定一個明確的受信任主機，通常`aliasgroup1`是`domain`您的鏡像版本支援的設定。	審核簡單且具有限制性；確認該值與 WOPI 請求中使用的主機和連接埠相符。
多個 Nextcloud 實例使用同一個 CODE 伺服器	為每個儲存主機名稱及其別名新增一個明確主機群組。	集中編輯，但每增加一個主機，允許發送 WOPI 請求的系統集就會擴大。
打包後的 Collabora Online 而非 CODE Docker	更新服務託管配置中的 WOPI 主機部分，然後重新啟動服務。	提供直接配置控制；手動編輯產生的檔案可能會被軟體包或組態管理更新覆蓋。
Nextcloud 報告 WOPI 允許清單警告	另行在 Nextcloud 的 Office 管理設定中允許預期的 Collabora 伺服器 IP 位址。	這是第二次反向檢查；它不會取代 CODE 的受信任主機配置。

以下範例假設 Nextcloud 的位址為 `<hostname>` https://cloud.example.com，Collabora 的位址為 `<port>` https://office.example.com。請將名稱和連接埠替換為您實際安裝中使用的值。 Nextcloud 的 Docker 設定指南使用 ` aliasgroup1<hostname>` 表示單一儲存主機，並描述如何為第二個 Nextcloud 主機新增另一個別名群組。 Collabora 的 WOPI 配置定義了主機名稱和連接埠的符合規則；別名用於相同儲存主機的備用名稱。

1. 確認 Collabora 拒絕了哪一台主機

首先檢視 CODE 容器日誌。在 Docker Compose 部署中，運行：

docker compose logs --since=10m collabora

替換collabora為 Compose 檔案中的服務名稱。對於純 Docker，請使用docker logs --since 10m CONTAINER_NAME。在文件開啟失敗嘗試附近尋找類似的訊息No acceptable WOPI hosts found matching the target host [cloud.example.com] in config。方括號內的主機名稱是關鍵：新增其中顯示的儲存主機，而不是 Collabora 伺服器的公共主機名稱。

如果日誌中顯示了 WOPI URL 中的主機和端口，也請記錄下來。將它們與配置的條目進行比較。即使兩個名稱解析到同一台機器，cloud.example.com:443對內部容器名稱（例如 `<container_name>`）的請求也可能與條目不符nextcloud。反向代理、分割 DNS 和多個公用 URL 都可能導致這種不符很容易被忽略。

如果日誌顯示其他錯誤，例如 DNS 查找失敗、連線被拒絕或憑證錯誤，請修復該問題，而不是擴大 WOPI 主機清單。

2. 更新 CODE 的受信任 WOPI 主機設置

對於一個服務於單一 Nextcloud 主機的 Docker Compose 安裝，其相關服務部分可能如下所示：

services:
  collabora:
    image: collabora/code
    environment:
      - aliasgroup1=https://cloud.example.com:443

保留您現有的其他服務選項、金鑰、磁碟區、連接埠和反向代理設定。範例僅展示了允許清單條目，並非完整的生產環境 Compose 檔案。請使用您執行的 CODE 版本已支援的設定樣式，並在變更後檢查渲染或啟動配置。容器鏡像和配置介面可能會隨時間而變化。

對於單一主機，使用精確的主機名稱條目比使用寬泛的正規表示式更容易審核。如果您的安裝依賴domain環境變量，請驗證鏡像文件中記錄的轉義規則，並確保表達式僅符合目標儲存主機名稱。請勿複製未轉義的通配符或會符合無關子網域的父域模式。

對於多個 Nextcloud 實例，請使用您的 CODE 版本支援的機制，為每個獨立的主機新增一個單獨的明確群組。例如，Nextcloud 的 Docker 整合指南中提供了一個aliasgroup2用於第二個雲端主機名稱的額外條目。只有當一個 Nextcloud 伺服器確實可以透過多個名稱存取時（例如內部名稱和公共名稱），才需要新增別名。請保留一份這些名稱的列表，以便在遷移後刪除舊的主機名稱。

3. 重新建立容器並檢查 Nextcloud 的單獨允許列表

編輯 Compose 檔案後，重新建立服務以套用新環境：

docker compose up -d --force-recreate collabora

請使用正確的服務名稱。然後檢查容器是否正常啟動，以及預期的主機是否出現在其啟動配置或日誌中。避免在支援請求中貼上完整的環境轉儲資訊：這可能會洩露密碼或其他敏感資訊。

Nextcloud 的 Office 管理設定中有一個名為「WOPI 請求允許清單」的單獨設定。此清單限制哪些 IP 位址可以向 Nextcloud 發出 WOPI 請求；Collabora 建議將其限制為預期的 Collabora 伺服器位址。如果 Nextcloud 報告此警告，請新增 Nextcloud 實際看到的請求位址，當涉及代理程式或容器網路時，該位址可能有所不同。請確保此檢查與 CODE 主機條目區分開來：CODE 信任儲存主機名，而 Nextcloud 的允許清單關注的是請求伺服器的 IP 位址。

如果您使用反向代理，請確認 Nextcloud 在 WOPI 連結中發布的主機名稱與 CODE 配置為信任的主機名稱一致。檢查 Nextcloud Office 伺服器 URL 和反向代理的公共主機配置。除非 Office 主機名稱確實是 WOPI URL 中的儲存主機，否則請勿將其新增至 WOPI 儲存允許清單中。

4. 驗證連線是否完整

首先，請分別從瀏覽器和 Nextcloud 伺服器檢查 Collabora 服務端點。將範例主機名稱替換為您的 Office URL：

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

這些檢查顯示端點有回應；但它們並不能證明 WOPI 文件請求會被授權。接下來，驗證 CODE 是否可以使用 Nextcloud 發佈內容的相同主機存取 Nextcloud，例如：

curl -fsS https://cloud.example.com/status.php

最後，開啟一個測試文檔，同時檢視 CODE 和 Nextcloud 日誌。成功的結果應該是編輯器加載完畢，“沒有可接受的 WOPI 主機”的錯誤訊息消失，並且保存小的更改也能正常工作。請使用與受影響用戶具有相同共享和編輯權限的普通用戶帳戶進行測試。

主要選項的比較

一個精確的主機與正規表示式

對於單雲部署，使用包含目標連接埠的精確主機名稱通常是最佳選擇：它易於審核，並能最大限度地減少意外匹配。當一組精心管理的主機名稱遵循某種模式時，正規表示式可以提供幫助，但它更難審核，並且如果定義過於寬泛，可能會授權使用非預期的子網域。請使用滿足已驗證需求的、定義最精確的表達式。

一個 CODE 實例與多個實例

共享的 CODE 服務可以減少需要維護的服務數量，而明確分組可以支援多個 Nextcloud 實例。當團隊需要更強的配置隔離或獨立的維護視窗時，使用獨立的 CODE 實例則更為合適。但這樣做需要更多的基礎設施來打補丁、監控和路由。兩個方案都無法自動修復 WOPI 主機名稱不符的問題；每個執行個體都必須信任正確的儲存主機。

容器環境設定與編輯 XML

對於 Docker CODE 部署，請使用映像支援的配置接口，並將其保存在 Compose 或其他部署權威來源中。這樣，當容器重新建立時，變更可以重複執行。coolwsd.xml直接編輯對於託管軟體包或自訂部署可能很有用，但編輯運行中容器內產生的檔案非常不穩定，可能會在容器替換或升級時遺失。請遵循您所使用的軟體包、Helm Chart 或鏡像的具體說明。

避免的常見錯誤

允許office.example.com在被拒絕的 WOPI 儲存主機為cloud.example.com.
當 WOPI URL 包含公用 DNS 名稱時，輸入私有容器名稱，反之亦然。
假設空白的 Nextcloud WOPI IP 允許清單和 CODE 的主機配置是相同的控制。
添加廣泛通配符或禁用主機驗證只是為了讓編輯器加載。
同時更改代理、TLS 和 WOPI 規則，這使得問題更難診斷。
僅測試發現端點，並將其視為文件授權有效的證明。

何時使用其他修復方法

如果被拒絕的主機名稱在請求之間發生變化，請在新增更多名稱之前檢查 Nextcloud 的規格 URL、受信任的代理程式標頭以及任何備用網站根目錄。如果所有主機名稱都符合但錯誤仍然存在，請將目前 CODE 配置與您編輯的檔案或環境設定進行比較，並確認容器已重新建立。對於 Kubernetes 或 Helm，請編輯 chart 值或託管設定來源，而不是編輯執行中的 Pod。如果日誌顯示憑證、防火牆、WebSocket 或 DNS 錯誤，請使用對應的伺服器日誌和網路檢查來排查該層的問題。

這些步驟遵循 2026 年 10 月 6 日發布的 Nextcloud 35 管理手冊以及 Collabora 發布的 WOPI 組態架構。特定的配置項目可能因部署方法和鏡像版本而異，因此在進行任何變更之前，請務必對照已安裝版本的文件進行驗證。