使用 Helm 在 Kubernetes 上部署 Collabora CODE

截至 2026 年 10 月 10 日，上游軟體包倉庫將 Chart 版本 1.3.0 列為最新版本。安裝 Chart 只是部署的一部分。您還需要一個公開的 Collabora 主機名稱、一個有效的文檔儲存主機 WOPI 允許清單條目，以及一個入口配置，確保每個文件的請求都在同一個 Pod 中。在撰寫本文時，上游軟體包倉庫列出的 Chart 版本為 1.3.0；安裝前請檢查倉庫，因為 Helm Chart 版本和 CODE 容器鏡像版本是不同的值。

此流程使用官方collabora/collabora-online圖表和 NGINX Ingress 控制器。圖表的 README 檔案中也包含 HAProxy 範例；Ingress 註解是特定於控制器的，因此請使用與您已安裝的控制器相符的範例，避免混用註解。

首先要準備什麼？

具有建立命名空間、Deployment、Service 和 Ingress 權限的 Kubernetes 叢集。
Helm 3 和一個已安裝的入口控制器，可以為諸如這樣的主機名稱提供 HTTPS office.example.com。
WOPI客戶端（例如Nextcloud或Seafile）的公共主機名稱。這是Collabora必須允許的主機名稱；它不是Collabora的主機名稱。
用於 Collabora 管理控制台憑證的 Kubernetes Secret。請勿保留 chart 的範例密碼，也不要將真實密碼提交到 values 檔案中。

1. 新增官方圖表庫並檢查版本

Collabora 會從專案的線上儲存庫發布其圖表。新增圖表後，請刷新本機索引，並在安裝前檢查圖表元資料和預設值：

helm repo add collabora https://collaboraonline.github.io/online/
helm repo update
helm show chart collabora/collabora-online
helm show values collabora/collabora-online

圖表版本標識的是軟體包，而非 CODE 鏡像標籤。請檢查發佈值中的鏡像倉庫和標籤，然後鎖定您已審核過的圖表版本，以便進行可重複的升級。

使用您已核准的金鑰管理工作流程建立命名空間範圍的金鑰。此圖表的值支援現有金鑰和可設定的金鑰名稱；預設金鑰名稱為 `<Secret_name>` 和username`<Secret_name> password`。安裝前，請先驗證該金鑰是否存在於collabora命名空間中。

2. 設定 WOPI 主機、入口和代理選項

創建my_values.yaml。將兩個範例主機名稱替換為您實際的公共網域。該aliasgroups值標識 WOPI 用戶端（例如，Seafile 或 Nextcloud 伺服器）。 Ingress 主機server_name識別使用者瀏覽器所存取的 Collabora 服務。

replicaCount: 1

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"
    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

autoscaling:
  enabled: false

collabora:
  aliasgroups:
    - host: "https://files.example.com:443"
  extra_params: --o:ssl.enable=false --o:ssl.termination=true
  server_name: office.example.com:443
  existingSecret:
    enabled: true
    secretName: collabora-admin
    usernameKey: username
    passwordKey: password

此範例遵循 Collabora 文件中記錄的 NGINX 入口模式：請求使用WOPISrc參數進行雜湊處理，且文件會話的代理程式讀取和傳送逾時時間已延長。請根據您的入口控制器版本確認註解名稱。如果您使用 HAProxy，請改用圖表 README 中的 HAProxy 註解和負載平衡配置。

這ssl.enable=false兩個ssl.termination=true選項適用於 TLS 在入口處終止，且從入口到 Pod 的流量為內部流量的設計。它們並不意味著公共端點應該使用 HTTP。請將入口主機名稱保留為 HTTPS，並且不要將 Pod 的純 HTTP 服務直接暴露給網際網路。server_name當 Collabora 位於反向代理程式之後或無法直接推斷其外部主機名稱時，請設定此選項。

對於多個固定副本，請replicaCount謹慎設定並保持會話親和性。上游 README 檔案目前指出 HPA 已停用，因為擴充功能可能會中斷協作編輯和複製/貼上功能。僅增加副本數量並不能提供正確的路由；請確認您的入口是否將對同一文件的請求傳送到同一個 Pod。

3. 安裝 Collabora 程式碼

從官方倉庫安裝此版本，並等待部署完成：

helm install --create-namespace \
  --namespace collabora \
  collabora-online collabora/collabora-online \
  --values my_values.yaml

kubectl get pods -n collabora
kubectl get ingress -n collabora

如果要更新現有版本，請使用helm upgrade相同的版本名稱、命名空間和值文件，而不是建立第二個版本。在升級生產實例之前，請先查看圖表的版本說明和渲染變更。

檢查 Pod 是否已準備就緒，以及 Ingress 是否報告了預期的主機和位址。如果仍然處於掛起狀態，請在變更資源設定之前檢查事件和日誌：

kubectl describe pods -n collabora
kubectl logs -n collabora deployment/<deployment-name>

根據工作負載和叢集容量配置 CPU 和記憶體。圖表 README 文件中提供了範例請求和限制，但不保證適用於所有部署。請注意是否有限流、記憶體不足導致的終止以及重啟等情況。

4. 核實發現和文件編輯情況

DNS 和 TLS 啟動後，透過公共主機名稱請求 Collabora 的發現端點：

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

成功的回應應包含 WOPI 發現 XML，而不是入口錯誤頁面或憑證警告。然後，使用相同的公共 Collabora URL 來設定 WOPI 用戶端，並確認 Collabora 的 URL 中aliasgroups包含該用戶端的 HTTPS 主機名稱和連接埠。客戶端的具體設定取決於儲存產品。

從 WOPI 用戶端開啟一個測試文件並進行少量修改。確認編輯器載入正常，如果需要協作，第二個瀏覽器工作階段可以加入，並且修改已儲存回儲存服務。此端對端檢查涵蓋 DNS、入口 TLS、會話路由、WOPI 主機授權和檔案傳輸。

需要核查的常見假設

「Helm 已安裝，Collabora 已準備好投入生產環境。」該 Chart 會建立 Kubernetes 資源，但 DNS、TLS、WOPI 主機授權、入口路由和資源大小仍取決於您的叢集。請驗證以上各項。
「入口主機和 WOPI 主機是同一設定。」但它們通常不同：入口主機是 Collabora 的公共位址；WOPI 主機是儲存伺服器。請將它們分別放入正確的圖表欄位中。
「增加副本數量會自動提升協作效率。」上游圖表記錄了會話親和性，目前禁用了高優先級屬性 (HPA)，因為擴充可能會中斷協作編輯。建議從單一副本或預先設定的固定數量開始，並保持路由親和性。
「可以提供一小段 XML 程式碼作為自訂配置。」圖表的coolwsd_xml_content值會取代預設設定文件，因此需要完整的設定檔內容。除非您擁有完整且版本相容的 XML 配置，否則請優先使用圖表專用的別名群組和參數值。