在 Kubernetes 節點上執行 Collabora Online

對於多節點 Collabora Online 部署，請使用 Collabora 的 Kubernetes Helm Chart，並在其後方部署 Ingress 或反向代理，以確保對同一文件的所有請求都由同一個 Collabora Pod 處理。這種會話親和性至關重要：普通的輪詢負載平衡可能會將使用者的編輯和剪貼簿請求傳送到不同的 Pod，從而中斷協作編輯。以下範例使用三個副本、NGINX Ingress 和固定的副本數；請將範例中的主機名稱和 TLS 金鑰替換為您自己的資訊。

終端提示符，其中包含新增官方 Collabora Helm 倉庫的命令 — 終端指令會在部署前新增 Collabora 的官方 Helm chart 倉庫。

在添加副本之前需要準備什麼？

您需要一個至少包含兩個工作節點的 Kubernetes 叢集、Helm、支援所需親和性規則的 Ingress 控制器、一個 DNS 名稱（例如 `<DNS_NAME>` office.example.com）以及該名稱的 TLS 憑證。每個 Collabora Pod 都必須能夠透過其公共 WOPI 來源存取 Nextcloud，例如 `<DNS_NAME>` https://cloud.example.com。 CODE 和 Nextcloud 是獨立的服務；本指南將設定 Collabora 層，然後將其公共 URL 連接到 Nextcloud Office。

請使用 Collabora Chart 文件中記錄的多重副本設置，而不是將多個獨立的 Docker 容器放置在通用負載平衡器之後。如果負載平衡器在分發每個請求時忽略文件的 WOPI 來源，則可能會導致會話中斷。本指南遵循 2026 年 10 月 10 日發布的 Collabora 官方 Helm Chart 說明。 Chart 的值可能會更改，因此請檢查您計劃安裝的 Chart 版本對應的值。

1. 配置副本、入口親和性和 WOPI 主機

新增圖表庫，更新其索引，並在編寫覆蓋檔案之前檢查圖表的當前預設設定：

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

使用下列核心設定建立my_values.yaml實例。此範例使用了 Collabora 圖表 README 中所示的 NGINX Ingress 註解。它會對請求進行雜湊處理，以確保WOPISrc與相同文件關聯的請求到達同一個 Pod。此外，它還在入口處終止公共 TLS 連線；所示的 Collabora 伺服器設定適用於此代理終止的 TLS 模式。

一個 YAML 編輯器，顯示三個 Collabora 副本，自動擴縮容已停用，NGINX 入口哈希由 WOPISrc 提供 — values 檔案設定固定的副本數，並透過 WOPISrc 路由每個文件的請求。

replicaCount: 3
autoscaling:
  enabled: false

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
  tls:
    - secretName: office-example-tls
      hosts:
        - office.example.com

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

此處的aliasgroups條目是 Nextcloud WOPI 主機名，而非 Collabora 主機名稱。請保持配置簡潔，並使用 Nextcloud 提供的確切方案、主機名稱和連接埠。入口 TLS 金鑰必須存在於入口命名空間中，並且包含有效的憑證office.example.com。如果 TLS 連線終止於其他位置，請遵循圖表文件中匹配的代理模式，而不是extra_params盲目複製這兩個標誌。

自動擴縮容存在版本相關的注意事項：圖表 README 檔案中的範例預設關閉了自動擴縮容，並警告擴縮容可能會中斷協作編輯和複製/貼上操作；而目前發布的值檔案預設啟用了自動擴縮容。為了獲得可預測的初始集群，請明確停用自動擴縮容並選擇固定的副本數。只有在查閱圖表版本的具體指南並在實際編輯會話中測試了擴容和縮容後，才能重新考慮啟用自動擴縮容。

2. 安裝圖表並檢查吊艙位置

將圖表安裝到指定的命名空間。官方圖表倉庫文件中記錄了這種命令模式：

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

然後檢查部署是否達到所需的副本數，並查看哪些工作節點託管了這些 Pod：

使用 `kubectl get pods -n collabora -o wide` 指令在終端機提示符號下檢查 pod 位置。 — 使用寬 pod 清單檢查就緒狀態以及指派給每個副本的節點。

kubectl get pods -n collabora -o wide
kubectl get ingress -n collabora
helm status collabora-online -n collabora

確認所有三個 Pod 都已就緒，入口點配置了預期的主機，並且如果需要節點級彈性，副本已分佈在各個工作節點上。僅憑副本數量並不能保證 Kubernetes 會將 Pod 放置在不同的節點上。官方的 Chart 範本提供了節點選擇器、親和性和容錯性設定；請為您的叢集配置合適的調度規則，並在使用前驗證渲染後的 Chart。如果您的 Chart 版本沒有提供所需的策略，請使用受支援的 Chart 擴充功能或 Kubernetes 部署自訂，而不是假設 Pod 已分佈在不同的節點上。

3. 連接 Nextcloud 並驗證文件關聯性

在 Nextcloud 中，安裝或啟用Nextcloud Office應用，然後開啟「管理設定」→「Office」。選擇外部 Collabora 伺服器並輸入伺服器 URL https://office.example.com。伺服器 URL 是 Nextcloud 伺服器和使用者瀏覽器均可存取的公共 TLS 端點；請勿輸入 pod IP 或內部服務位址。

從 Nextcloud 開啟一個測試用的 DOCX 或 ODT 檔案。使用兩個不同的使用者會話編輯該文件，並確認兩個使用者都能看到變更。同時檢查瀏覽器開發者工具或 Ingress 日誌中是否有 WebSocket 錯誤；Ingress 必須保持長時間的編輯器連線開啟。如果一個檔案的請求分佈在多個 Pod 中，請驗證WOPISrcIngress 應用哈希規則的位置是否存在查詢參數，以及已安裝的 Ingress 控制器是否支援該註解。

Collabora Online 文件編輯器，顯示叢集部署清單和格式工具列 — 在 Nextcloud 指向叢集 Collabora URL 之後，開啟的文件會提供一個使用者導向的檢查。

健康的細胞群能證明什麼？

成功的測試證實 Nextcloud 可以連接到 Collabora 端點，並且可以透過配置的入口編輯文件。但這並不能證明每個活躍會話都能在 Pod 或節點故障後繼續運作。編輯狀態由服務該文件的 Pod 處理，因此即使其他副本仍然可用，故障也可能需要使用者重新連接或重新開啟檔案。請使用非關鍵文件測試維護和故障場景，並在規劃升級時，確保能夠妥善處理長時間運行的 WebSocket 工作階段。

有關當前語法和注意事項，請參閱 Collabora官方的 Kubernetes Helm chart README 和值檔案、已發布的 chart 值檔案以及 Nextcloud 的Office 設定手冊。請務必根據您安裝的 chart 版本驗證設置，因為倉庫中的範例和預設值可能不完全相同。