如何將 Collabora Online 與 ownCloud Infinite Scale 集成

將 Collabora Online 與 ownCloud Infinite Scale (oCIS) 集成是一種 WOPI 集成，與 ownCloud Classic 使用的設定不同。 WOPI，即 Web 應用程式開放平台接口，是一種允許線上辦公室套件從儲存平台請求文件、在瀏覽器中編輯文件並將結果寫回儲存平台的協定。

這種區別至關重要，因為目前的 Infinite Scale 部署使用內建的協作服務作為 oCIS 和 Collabora 之間的橋樑。您無需安裝舊版 ownCloud Classic Collabora 應用程式並將其指向伺服器 URL。辦公室應用是透過協作和應用註冊服務進行註冊的。官方ownCloud WOPI 文件將 Collabora 列為受支援的辦公室應用，而協作服務文件則解釋了該服務及其所需的設定。

截至 2026 年 10 月，ownCloud 的官方 GitHub 版本包含 Infinite Scale 8.2.0（發佈於 2026 年 8 月 10 日）。該專案的部署範例可能會獨立更新，因此請使用經過測試的生產版本標籤，而不是想當然地認為滾動鏡像就適用。官方的 oCIS 完整部署範例目前建議26.04.3.1.1在其環境文件中使用 Collabora CODE 標籤。在確定版本之前，請務必查看官方的 Infinite Scale 版本和官方部署範例的環境檔案。

首先，了解三個終點

生產整合通常涉及三個邏輯端點：

端點	目的	例子
無限尺度	面向使用者的 ownCloud Web 和儲存 API	`https://cloud.example.com`
Collabora Online	瀏覽器編輯器和WOPI客戶端	`https://office.example.com`
WOPI/協作服務	Collabora 透過此橋接器讀取和寫入 oCIS 文件	內部服務 URL 或外部路由的 WOPI 主機名，取決於拓樸結構

已驗證： COLLABORATION_APP_ADDR是 Collabora URL，COLLABORATION_WOPI_SRC用於識別辦公室應用程式使用的 WOPI 來源。環境相關：當 Collabora 和協作服務共享受信任的容器網路時，WOPI 來源不必是單獨的公共主機名稱。目前的官方 Compose 範例http://collaboration:9300在內部使用。獨立部署可能需要路由的 HTTPS WOPI 主機名稱。

實用技巧：在複製配置值之前，請先確定拓樸結構。如果所有元件都運行在同一個官方 Compose 堆疊中，請以此範例為基礎。如果 Collabora 位於另一台主機或 Kubernetes 叢集上，請記錄每一端實際上可以解析和存取的 DNS 名稱。

第一階段：驗證 DNS、HTTPS 和 Collabora Discovery

在修改 oCIS 設定之前，請確保 ownCloud 和 Collabora 名稱解析正確，並且 Collabora 已公開其發現端點。 Collabora 透過 WOPI 發布功能/hosting/discovery。一個基本的檢查方法是：

dig +short cloud.example.com
dig +short office.example.com

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

您應該會從發現端點收到 XML 資料。如果 TLS 在反向代理處終止，請確認所提供的憑證office.example.com對於 oCIS 主機或容器網路而言是否有效。

終端機正在檢查 ownCloud 和 Collabora 主機名稱的 DNS，並請求 Collabora 主機發現端點。

/hosting/discovery標題：在 Infinite Scale 中偵錯 WOPI 註冊之前，請檢查名稱解析和 Collabora端點。

常見誤解：在瀏覽器中看到 Collabora 登入頁面並不能證明 WOPI 整合成功。它只能證明 Web 端點可存取。協作服務也必須能夠存取 Collabora，而 Collabora 也必須能夠存取 WOPI 來源。

有用的操作：從與相關服務相同的網路命名空間執行連接性測試——例如，在使用 Docker 時，從協作容器內部執行。

第二階段：配置無限擴充協作服務

協作服務不會在通用的ocis server監督模式下自動啟動。 ownCloud 文件指出，必須明確啟動該服務，因為管理員可能會為不同的辦公室產品執行多個協作服務實例。

Collabora 的重要設置包括：

COLLABORATION_APP_NAME=CollaboraOnline
COLLABORATION_APP_PRODUCT=Collabora
COLLABORATION_APP_ADDR=https://office.example.com
COLLABORATION_WOPI_SRC=http://collaboration:9300
OCIS_URL=https://cloud.example.com

上述 WOPI 來源與目前官方 Compose 範例所使用的拓樸結構完全一致：Collabora 和協作服務共用同一個 Docker 網路。如果您的 Collabora 伺服器位於外部，請將內部 URL 替換為 Collabora 可以存取的位址。

該服務也依賴 Infinite Scale 的網關和應用程式提供者基礎架構。在分離容器部署中，ownCloud 文件特別警告說，oCIS 配置必須與協作容器共用，因為跨服務需要產生金鑰。請參閱目前的官方 Collabora Compose 定義。

Infinite Scale 協作服務的終端視圖，包含 Collabora、辦公地址、WOPI 來源和 HTTP 監聽器資訊。

標題：協作服務流程應從預期的 Collabora 位址和 WOPI 來源開始；使用實際服務日誌來確認部署中的值。

有用的操作：如果您手動建立了部署，請將您的環境與官方環境進行比較，collabora.yml而不是從舊的 cs3org/wopiserver 教學中複製設定。

第三階段：配置 Collabora 以支援 WOPI 主機和瀏覽器嵌入

Collabora 必須信任 WOPI 主機，並被允許在 ownCloud 網頁內進行渲染。官方的 oCIS Compose 範例會將 Collabora 選項傳遞給反向代理，終止 TLS 連接，並將網域設為net.frame_ancestorsoCIS 網域。此外，它還會在啟動 Collabora 之前產生一個 WOPI 驗證金鑰。

在官方範例中，相關的 Collabora 端值包括：

DONT_GEN_SSL_CERT=YES

extra_params:
  --o:ssl.enable=...
  --o:ssl.ssl_verification=...
  --o:ssl.termination=true
  --o:welcome.enable=false
  --o:net.frame_ancestors=cloud.example.com

具體的 SSL 標誌取決於 TLS 終止的位置。建議以網際網路為導向的設定是啟用憑證驗證的 HTTPS。範例中的選項INSECURE=true適用於使用自簽名憑證的本機設定；ownCloud 的部署指南明確告知管理員，對於公用伺服器，應移除此選項或將其設為 false。

標題：可存取的 Collabora 端點是先決條件之一；生產部署應透過 HTTPS 公開該端點，並使用其他元件信任的憑證。

有效措施：如果文件載入出現空白 iframe 或 CSP 錯誤，請檢查瀏覽器開發者工具和反向代理程式標頭。不要僅僅為了讓頁面載入而大幅停用憑證驗證或內容安全限制。

第四階段：註冊辦公室文件類型與測驗編輯

Infinite Scale 的應用程式註冊服務決定哪些應用程式可以開啟每種 MIME 類型的檔案。其配置可以定義 MIME 類型、副檔名、圖示、預設應用程序，以及使用者是否可以建立該類型的新檔案。官方的應用程式註冊文件對這些欄位進行了描述。

關鍵在於，註冊表中使用的應用程式名稱必須與您實際註冊的協作提供者名稱一致。目前官方的 Collabora 部署範例使用 ` CollaboraOnlineas`COLLABORATION_APP_NAME和 ` Collaboraas` 作為產品名稱。請勿在未檢查部署版本的情況下，混用從舊範例複製的名稱。

啟動後，登入 ownCloud Web 並開啟一個受支援的 Office 文件。成功流程如下圖所示：

ownCloud Web 會根據文件的 MIME 類型選擇註冊辦公室應用程式。
協作服務創建 WOPI 發布資訊。
Collabora 在瀏覽器中加載，並透過 WOPI 請求文件。
編輯內容透過相同的整合方式寫回 Infinite Scale。

基於瀏覽器的 Collabora 文件編輯器正在顯示從 ownCloud Infinite Scale 開啟的 DOCX 檔案。

圖註：最終測試是從 ownCloud Web 打開一個真實的辦公室文檔，在 Collabora 中編輯它，關閉它，並確認保存的版本在 Infinite Scale 中再次可見。

實用操作：對一個臨時測試文件進行少量修改，關閉編輯器，重新開啟文件，並驗證變更是否生效。僅僅載入編輯器的頁面並非完整的寫入路徑測試。

當您不需要自訂拓撲時，請使用官方 Compose 範例

對於傳統的 Docker 部署，風險最低的方案是採用 ownCloud 維護的ocis_full範例。此範例包含 Infinite Scale、協作服務 Collabora 和 Traefik。官方指南指出，部署需要為 oCIS 和 Collabora 配置域名，並將 WOPI 元件作為堆疊的一部分進行文件說明。請參閱完整的官方部署指南。

一個典型的生產環境文件包含以下概念性值：

OCIS_DOCKER_IMAGE=owncloud/ocis
OCIS_DOCKER_TAG=<tested-production-version>
OCIS_DOMAIN=cloud.example.com

COLLABORA=:collabora.yml
COLLABORA_DOCKER_TAG=<tested-collabora-version>
COLLABORA_DOMAIN=office.example.com

INSECURE=false

然後以如下方式開始堆疊：

docker compose pull
docker compose up -d
docker compose ps

已驗證：目前的官方反向代理範例在 HTTPS 入口點啟用了編碼斜線、問號和百分號，因為 Collabora 需要這些字元。環境相關：如果您使用 Nginx、HAProxy、Ingress 控制器或雲端負載平衡器而不是 Traefik，則必須在該平台上重現所需的 URL 處理、WebSocket/代理行為、憑證和逾時設定。

實用技巧：不要直接將 Traefik 標籤複製到其他代理伺服器。應該利用它們來理解路由需求，然後使用代理伺服器文件中提供的語法來實現這些需求。

故障排除參考

症狀	可能區域	下一個
沒有針對 DOCX/ODT 的辦公室選項	應用程式註冊/提供者註冊	確認協作服務已註冊，並且 MIME 類型指向正確的應用程式名稱。
Collabora頁面可以正常顯示，但文件無法開啟。	WOPI可達性	驗證 Collabora 是否可以存取`COLLABORATION_WOPI_SRC`和檢查協作日誌。
空白幀或瀏覽器 CSP 錯誤	幀/CSP配置	檢查`frame_ancestors`oCIS CSP 以及瀏覽器實際使用的來源。
TLS 或憑證錯誤	反向代理/信任鏈	在生產環境中使用有效的證書，並從服務容器（而不僅僅是您的工作站）測試 HTTPS。
編輯器已打開，但儲存失敗	WOPI 寫入路徑/共用金鑰	檢查協作和 Collabora 日誌，並確認共享的 oCIS 配置已按要求掛載。
一個文件意外地在多個辦公室軟體中打開	多重辦公室集成	目前官方環境文件警告不要啟用重疊的辦公室應用程序，因為同一文件的應用程式互鎖功能不可用。