Как настроить Collabora CODE в Kubernetes с помощью Helm

Страница Collabora Online может оставаться пустой или сообщать о недоступности офисного сервера даже после запуска CODE-пода. Здоровый под — это лишь часть настройки: браузер и ваше WOPI-приложение должны взаимодействовать с Collabora по общедоступному имени хоста, настройки TLS и прокси должны совпадать, и Collabora должна доверять WOPI-хосту. Официальный Helm-диаграмма Collabora развертывает сервер в Kubernetes; она не устанавливает и не настраивает Nextcloud, ownCloud или другой WOPI-хост.

В этом руководстве используется поддерживаемая Collabora диаграмма Helm с примером NGINX Ingress. Замените примеры доменов своими собственными. CODE — это Collabora Online Development Edition, предназначенная для ознакомительных целей, домашнего использования и небольших команд; Collabora заявляет, что она не рекомендуется для производственных сред, требующих стабильной поддерживаемой версии. Для производственных нагрузок оцените поддерживаемое предложение Collabora Online, а также его условия лицензирования и поддержки.

Что вам понадобится перед установкой

• Рабочий кластер Kubernetes, kubectlHelm 3 и доступ к кластеру.
• В кластере установлен контроллер Ingress. В приведенном ниже примере используется ingress-nginx; в диаграмме Collabora также описан HAProxy и поддерживаются другие конфигурации маршрутизации.
• DNS-имя, например, office.example.comуказывающее на публичный адрес входящего трафика, плюс TLS-сертификат, хранящийся в виде секрета Kubernetes в пространстве имен Collabora.
• Приложение WOPI, такое как Nextcloud, с URL-адресом, например cloud.example.com, . Collabora должно иметь возможность связаться с приложением WOPI, а браузеры приложения и пользователей должны иметь возможность связаться с Collabora.
• Четкий план TLS. В этом примере HTTPS завершается на входящем соединении и отправляется HTTP-запрос к сервису Collabora внутри кластера.

Для быстрого развертывания дома или на тестовом сервере один под CODE упрощает маршрутизацию. Множество реплик может увеличить пропускную способность, но в руководстве Collabora по Kubernetes указано требование балансировки нагрузки на основе WOPISrc, чтобы сеансы редактирования одного и того же документа достигали одного и того же пода. Не масштабируйте количество реплик, пока не убедитесь, что ваш контроллер входящего трафика может обеспечить необходимую привязку.

Шаг 1: Добавьте официальную диаграмму и выберите версию.

Collabora публикует свой чарт из проекта CollaboraOnline. На странице релизов в настоящее время указана версия чарта 1.3.5 (проверено 6 октября 2026 г.). Проверьте доступные версии в вашей среде и зафиксируйте версию чарта, чтобы последующее обновление репозитория не привело к незаметному изменению развернутого вами чарта:

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: Создайте пространство имен и защитите пароль администратора.

Создайте пространство имен и секрет Kubernetes для необязательных учетных данных администратора Collabora для диаграммы. Замените пароль-заполнитель надежным секретом или создайте секрет с помощью менеджера секретов вашей организации или рабочего процесса создания секретов GitOps. Не указывайте реальный пароль в файле 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. Держите Secret в секрете только для пространства имен и пользователей или учетных записей служб, которые управляют этим развертыванием.

Шаг 3: Настройте имя хоста, хост WOPI и входящий трафик.

Создайте файл с именем collabora-values.yaml. В этом примере предполагается наличие ingress-nginx, секрета TLS с именем office-example-com-tlsи Nextcloud по адресу https://cloud.example.com. Группа псевдонимов должна указывать хост приложения WOPI, с которым Collabora может взаимодействовать; это не общедоступное имя хоста 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.comиспользует HTTPS, в то время как входящий трафик перенаправляется в Collabora по HTTP внутри кластера. Если ваш входящий трафик использует сквозную передачу 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. Если он остается в состоянии «Ожидание», проверьте, достаточно ли у кластера планируемых ресурсов ЦП и памяти, а также не препятствуют ли размещению какие-либо селекторы узлов, метки или квоты ресурсов. Диаграмма оставляет запросы на ресурсы и ограничения на выбор оператора; в файле README Collabora приведены более крупные примеры значений ресурсов для производственных сред, но фактический размер зависит от одновременного редактирования и рабочей нагрузки на документы.

Шаг 5: Подключите Nextcloud или другой хост WOPI.

Откройте настройки Office или Collabora вашего WOPI-приложения и введите URL-адрес внешней службы https://office.example.com. В Nextcloud руководство администратора описывает настройку URL-адреса сервера Collabora Online в настройках администрирования Office. Также проверьте список разрешенных запросов WOPI в Nextcloud, если ваша конфигурация ограничивает доступ для подключения каких-либо хостов. Адрес должен быть доступен как для браузеров конечных пользователей, так и для сервера приложений, выполняющего запросы WOPI.

Если соединение не удается с сообщением «несанкционированный хост WOPI» или аналогичным, сравните фактический URL-адрес хоста WOPI с collabora.aliasgroups. Проверьте схему, имя хоста и порт, а также преднамеренно добавьте все допустимые альтернативные имена хостов. Избегайте широких шаблонов хостов, если вы не понимаете их влияния. Если вы используете более одного приложения WOPI, следуйте описанной в диаграмме структуре групп псевдонимов для каждого хоста, а не разрешайте все домены.

Когда следует масштабировать систему за пределы одного модуля?

Для небольшого пробного периода достаточно одной реплики с отключенным автомасштабированием, чтобы избежать сложностей маршрутизации. Для нескольких реплик в файле README диаграммы Collabora указана привязка к NGINX на основе WOPISrcаргумента запроса. Добавьте описанную в документации аннотацию к ingress при использовании ingress-nginx:

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

Это направляет запросы к одному и тому же документу в один и тот же бэкэнд-под, что важно для совместного редактирования и запросов к буферу обмена. Проверьте документацию для вашей конкретной версии ingress-controller; аннотация, поддерживаемая ingress-nginx, не является автоматически допустимой для HAProxy, Traefik или реализации Gateway API. После включения большего количества реплик или автомасштабирования протестируйте одновременное редактирование одного и того же документа и просмотрите журналы Collabora и журналы доступа ingress. Размер ресурсов, поведение сессий и высокая доступность требуют проверки, специфичной для рабочей нагрузки.

Проверьте развертывание извне.

1. Подтвердите, что Kubernetes сообщает о готовности пода, а также о существовании сервиса и 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-соединения, обработку веб-сокетов и длительные тайм-ауты запросов.
• Несанкционированный хост WOPI: разрешите источник приложения WOPI в aliasgroups; не заменяйте имя хоста office-server.
• Если под перезапускается или вытесняется: проверьте kubectl describe podлоги контейнера, затем установите реалистичные запросы ресурсов и ограничения для доступного кластера.
• После добавления реплик редактирование становится нестабильным: проверьте соответствие на основе WOPISrc и убедитесь, что контроллер сохраняет аргумент запроса при маршрутизации запросов.

После установки диаграммы, обеспечения доступности конечной точки обнаружения и успешного открытия и сохранения реального документа через приложение WOPI, основная реализация CODE работает. Сохраняйте версию диаграммы и повторяйте эти проверки после обновления диаграммы, изменения входящего трафика или изменения масштабирования.

Официальные ссылки

• Диаграмма Helm для Kubernetes, поддерживаемая Collabora, и руководство по развертыванию.
• Значения диаграммы Collabora Helm
• Выпуски чартов Collabora
• Руководство по использованию Collabora Online Development Edition (CODE).
• Руководство по настройке Nextcloud Office
• документация по аннотациям ingress-nginx
• Справочник команд установки Helm