如何使用 Helm 在 Kubernetes 上設定 Collabora CODE

即使 CODE pod 正在運行，Collabora Online 頁面仍可能保持空白或報告辦公室伺服器不可用。健康的 pod 只是設定的一部分：瀏覽器和您的 WOPI 應用程式必須透過公共主機名稱連接到 Collabora，TLS 和代理設定必須一致，並且 Collabora 必須信任 WOPI 主機。官方的 Collabora Helm chart 會將伺服器部署到 Kubernetes 中；它不會為您安裝或設定 Nextcloud、ownCloud 或其他 WOPI 主機。

本指南使用 Collabora 維護的 Helm Chart 以及 NGINX Ingress 範例。請將範例網域替換為您自己的網域。 CODE 是 Collabora Online 開發版，適用於評估、家庭使用和小團隊；Collabora 表示不建議將其用於需要穩定支援版本的生產環境。對於生產工作負載，請評估受支援的 Collabora Online 產品及其授權和支援條款。

安裝前需要準備什麼

• 一個可運行的 Kubernetes 集群，kubectl以及可以存取該集群的 Helm 3。
• 叢集中已安裝 Ingress 控制器。以下範例使用 ingress-nginx；Collabora chart 也記錄了 HAProxy 的使用，並支援其他路由配置。
• 指向公共入口位址的DNS 名稱office.example.com，以及儲存在 Collabora 命名空間中的 Kubernetes Secret 形式的 TLS 憑證。
• WOPI 應用程式（例如 Nextcloud，其 URL 類似cloud.example.com.）必須能夠存取該 WOPI 應用，並且該應用程式和使用者的瀏覽器也必須能夠存取 Collabora。
• 清晰的 TLS 協定方案。此範例在入口處終止 HTTPS 連接，並將 HTTP 請求傳送至叢集內部的 Collabora 服務。

對於快速的家庭或測試部署，單一 CODE Pod 可以簡化路由。多個副本可以提升容量，但 Collabora 的 Kubernetes 指南強調了基於 WOPISrc 的負載平衡要求，以確保對相同文件的編輯會話連接到同一個 Pod。在確認入口控制器能夠提供所需的親和力之前，請勿擴充副本。

步驟一：新增官方圖表並選擇版本

Collabora 透過 CollaboraOnline 計畫發布其圖表。發布頁面目前列出的圖表版本為 1.3.5（2026 年 10 月 6 日檢查）。請檢查您環境中可用的版本，並鎖定圖表版本，以防止後續的儲存庫更新在後台悄悄更改您部署的圖表：

helm repo add collabora https://collaboraonline.github.io/online/
helm repo update
helm search repo collabora/collabora-online --versions

官方圖表庫可用於在編寫覆蓋程式碼之前檢查當前的預設值：

helm show values collabora/collabora-online --version 1.3.5

如果您按照本指南操作後，發現儲存庫中列出了更新的相容圖表，請在取代該版本之前查看其發行說明和相關值。圖表版本和 CODE 應用程式鏡像版本是相關的發行輸入，但它們並非相同設定。

步驟 2：建立命名空間並保護管理員密碼

為圖表的可選 Collabora 管理員憑證建立命名空間和 Kubernetes Secret。將佔位符密碼替換為強金鑰，或透過組織的金鑰管理員或 GitOps 金鑰工作流程建立 Secret。請勿在 . 中提交真實密碼values.yaml。

kubectl create namespace collabora

kubectl -n collabora create secret generic collabora-admin \
  --from-literal=username=admin \
  --from-literal=password='REPLACE_WITH_A_LONG_RANDOM_PASSWORD'

此圖表支援引用現有 Secret。啟用此功能可避免將管理員密碼直接放入 Helm values 檔案中。請將 Secret 限制為僅供管理此部署的命名空間和使用者或服務帳戶使用。

步驟 3：設定主機名稱、WOPI 主機和入口

建立一個名為 . 的檔案collabora-values.yaml。此範例假設使用了 ingress-nginx、名為 的 TLS Secretoffice-example-com-tls以及位於 的 Nextcloud https://cloud.example.com。別名群組必須指定 Collabora 可以聯繫的 WOPI 應用程式主機；它不能是 Collabora 的公共主機名稱。

replicaCount: 1

autoscaling:
  enabled: false

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
  hosts:
    - host: office.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls:
    - secretName: office-example-com-tls
      hosts:
        - office.example.com

collabora:
  aliasgroups:
    - host: "https://cloud.example.com:443"
  extra_params: "--o:ssl.enable=false --o:ssl.termination=true"
  existingSecret:
    enabled: true
    secretName: collabora-admin

圖表文件中的範例aliasgroups允許 WOPI 主機和這些 SSL 參數在反向代理終止 TLS 連線時使用。在這種配置下，外部流量使用office.example.comHTTPS，而入口流量則透過 HTTP 轉送到叢集內部的 Collabora。如果您的入口使用 TLS 直通或其他內部協議，請勿直接複製這些 SSL 標誌；請根據實際的 TLS 路徑和圖表的當前值進行調整。

確認 TLS 密鑰存在於collabora命名空間中。如果您使用不同的入口控制器，請將類別和註解替換為該控制器文件中提供的等效項。保持 WebSocket 流量啟用並允許長時間連線；不同控制器的預設設定可能有所不同。

步驟 4：渲染並安裝圖表

首先渲染清單檔案以擷取 YAML 錯誤，並檢查產生的 Ingress、Service 和工作負載設定。然後安裝已鎖定的圖表版本：

helm template collabora-online collabora/collabora-online \
  --namespace collabora \
  --version 1.3.5 \
  --values collabora-values.yaml

helm upgrade --install collabora-online collabora/collabora-online \
  --namespace collabora \
  --version 1.3.5 \
  --values collabora-values.yaml

觀察資源的啟動：

kubectl get pods,services,ingress -n collabora
kubectl get events -n collabora --sort-by=.lastTimestamp

在連接 WOPI 應用程式之前，請等待 Pod 狀態變為 Ready。如果 Pod 仍處於 Pending 狀態，請檢查叢集是否有足夠的可調度 CPU 和內存，以及是否存在任何節點選擇器、污點或資源配額阻止部署。圖表中將資源請求和限制留給操作員選擇；Collabora 的 README 文件中提供了適用於生產環境的更大資源值範例，但實際資源配置取決於並發編輯和文件工作負載。

步驟 5：連接 Nextcloud 或其他 WOPI 主機

開啟 WOPI 應用的 Office 或 Collabora 設置，並輸入外部服務 URL https://office.example.com。在 Nextcloud 中，管理手冊介紹如何在 Office 管理設定中設定 Collabora Online 伺服器的 URL。如果您的設定限制了哪些主機可以連接，請同時檢查 Nextcloud WOPI 請求允許清單。該位址必須能夠被最終使用者的瀏覽器和發出 WOPI 請求的應用程式伺服器存取。

如果連線失敗並顯示「未授權的 WOPI 主機」或類似訊息，請將實際的 WOPI 主機 URL 與預期進行比較collabora.aliasgroups。檢查協定、主機名稱和端口，並主動添加任何合法的備用主機名稱。除非您了解其影響，否則請避免使用過於廣泛的主機模式。如果您使用多個 WOPI 應用程序，請為每個主機遵循圖表中記錄的別名組結構，而不是允許所有網域名稱。

何時應該將規模擴展到單一生產單位以上？

對於小型試驗，停用自動擴縮容的單一副本可以避免路由複雜性。對於多個副本，Collabora chart README 檔案中會根據WOPISrc查詢參數顯示 NGINX 親和性。使用 ingress-nginx 時，請將文件中說明的註解新增至入口配置：

nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"

這會將相同文件的請求定向到同一個後端 Pod，這對於協作編輯和剪貼簿請求至關重要。請查閱文件以確認您的 ingress-controller 版本是否支援；ingress-nginx 支援的註解並不一定適用於 HAProxy、Traefik 或 Gateway API 實作。啟用更多副本或自動擴縮容後，請測試對相同文件的並發編輯，並觀察 Collabora 日誌和入口存取日誌。資源大小、會話行為和高可用性需要根據特定的工作負載進行驗證。

從外部檢查部署情況

1. 確認 Kubernetes 報告 pod 狀態為 Ready，且 Service 和 Ingress 存在：kubectl get pods,svc,ingress -n collabora。
2. 檢查公共發現端點。它應該會傳回 XML 而不是瀏覽器或代理錯誤：

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

3. 開啟 WOPI 應用程式並編輯測試文件。確認編輯器已加載，變更已儲存，並且重新開啟文件後顯示已儲存的內容。
4. 如果使用多個副本，請在兩個會話中開啟同一文檔，並確認兩個會話都能協作而無需反覆重新連接。這有助於識別會話關聯性缺失的問題。
5. 檢視日誌，確認是否有 TLS、WOPI 授權或上游錯誤：

   kubectl logs -n collabora deploy/collabora-online --tail=100

   如果圖表建立了名稱不同的工作負載，請使用kubectl get deployments -n collabora並取代實際名稱。

成功的發現回應確認了公共端點正在提供 Collabora 元資料；但這並不能證明 WOPI 身份驗證或文件保存功能正常。端對端文件測試是最終的驗證步驟。

常見故障點

• Ingress 傳回 404 或 502：請驗證 DNS、Ingress 類別、TLS 金鑰和服務端點。確認 Ingress 可以透過圖表的服務連接埠存取 Collabora 服務。
• 發現功能正常，但編輯器仍然空白：請檢查瀏覽器控制台錯誤和代理程式日誌。檢查 HTTPS 終止設定、WebSocket 處理以及請求逾時時間。
• 未經授權的 WOPI 主機：允許 WOPI 應用程式的來源aliasgroups；不要取代 office-server 主機名稱。
• Pod 重新啟動或被驅逐：檢查kubectl describe pod容器日誌，然後為可用叢集設定合理的資源請求和限制。
• 新增副本後編輯變得不穩定：驗證基於 WOPISrc 的親和力，並確認控制器在路由請求時保留查詢參數。

圖表安裝完畢，發現端點可訪問，並且已透過 WOPI 應用程式成功開啟並保存了實際文檔，則核心 CODE 部署已正常工作。請保持圖表版本固定，並在圖表升級、入口變更或擴充變更後重複這些檢查。

官方參考資料

• Collabora 維護的 Kubernetes Helm Chart 和部署指南
• Collabora Helm 圖表值
• Collabora 圖表發布
• Collabora 線上開發版 (CODE) 指南
• Nextcloud Office 設定手冊
• ingress-nginx 註解文檔
• Helm 安裝指令參考