Jak skonfigurować Collabora CODE na Kubernetes z Helm

Strona Collabora Online może pozostać pusta lub zgłaszać, że serwer biurowy jest niedostępny, nawet po uruchomieniu modułu CODE. Sprawny moduł to tylko jeden z elementów konfiguracji: przeglądarka i aplikacja WOPI muszą połączyć się z Collabora za pośrednictwem publicznej nazwy hosta, ustawienia TLS i proxy muszą być zgodne, a Collabora musi ufać hostowi WOPI. Oficjalny schemat Collabora Helm wdraża serwer w Kubernetes; nie instaluje on ani nie konfiguruje NextCloud, ownCloud ani innego hosta WOPI.

W tym przewodniku wykorzystano diagram Helm obsługiwany przez Collabora z przykładem NGINX Ingress. Zastąp przykładowe domeny swoimi własnymi. CODE to Collabora Online Development Edition, przeznaczona do ewaluacji, użytku domowego i małych zespołów; Collabora nie zaleca korzystania z niej w środowiskach produkcyjnych wymagających stabilnej, obsługiwanej wersji. W przypadku obciążeń produkcyjnych należy zapoznać się z obsługą Collabora Online oraz warunkami licencji i wsparcia.

Czego potrzebujesz przed instalacją

• Działający klaster Kubernetes kubectli Helm 3 z dostępem do klastra.
• Kontroler Ingress zainstalowany w klastrze. Poniższy przykład wykorzystuje ingress-nginx; diagram Collabora dokumentuje również HAProxy i obsługuje inne konfiguracje routingu.
• Nazwa DNS, np. office.example.comwskazująca na publiczny adres wejściowy, plus certyfikat TLS przechowywany jako tajny klucz Kubernetes w przestrzeni nazw Collabora.
• Aplikacja WOPI, taka jak Nextcloud, z adresem URL takim jak cloud.example.com. Collabora musi mieć możliwość połączenia się z aplikacją WOPI, a przeglądarka aplikacji i użytkowników musi mieć możliwość połączenia się z Collabora.
• Przejrzysty plan TLS. W tym przykładzie HTTPS jest przerywany na wejściu i wysyłany do usługi Collabora w klastrze.

W przypadku szybkiego wdrożenia domowego lub testowego, pojedynczy pod CODE upraszcza routing. Wiele replik może zwiększyć wydajność, ale przewodnik Collabora po Kubernetesie podkreśla wymóg równoważenia obciążenia opartego na WOPISrc, aby sesje edycji tego samego dokumentu docierały do ​​tego samego podu. Nie skaluj replik przed upewnieniem się, że kontroler wejściowy może zapewnić wymagane powinowactwo.

Krok 1: Dodaj oficjalny wykres i wybierz wersję

Collabora publikuje swoje wykresy w ramach projektu CollaboraOnline. Strona wydania zawiera obecnie wersję wykresu 1.3.5 (sprawdzono 6 października 2026 r.). Sprawdź wersje dostępne w swoim środowisku i przypnij wersję wykresu, aby późniejsza aktualizacja repozytorium nie zmieniła automatycznie wdrożonego wykresu:

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

Oficjalne repozytorium wykresów jest przydatne do sprawdzenia bieżących ustawień domyślnych przed zapisaniem nadpisów:

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

Jeśli postępując zgodnie z tym przewodnikiem, Twoje repozytorium wyświetla nowszy, kompatybilny wykres, zapoznaj się z jego informacjami o wydaniu i wartościami przed zastąpieniem tej wersji. Wersja wykresu i wersja obrazu aplikacji CODE to powiązane dane wejściowe wydania, ale nie są to te same ustawienia.

Krok 2: Utwórz przestrzeń nazw i chroń hasło administratora

Utwórz przestrzeń nazw i klucz tajny Kubernetes dla opcjonalnych danych logowania administratora Collabora dla wykresu. Zastąp hasło zastępcze silnym kluczem tajnym lub utwórz klucz tajny za pomocą menedżera kluczy tajnych w swojej organizacji lub przepływu pracy GitOps. Nie zatwierdzaj prawdziwego hasła w 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'

Wykres obsługuje odwoływanie się do istniejącego klucza tajnego. Włączenie tej opcji pozwala uniknąć umieszczania hasła administratora bezpośrednio w pliku wartości Helm. Klucz tajny powinien być ograniczony do przestrzeni nazw i użytkowników lub kont usług, które administrują tym wdrożeniem.

Krok 3: Skonfiguruj nazwę hosta, hosta WOPI i wejście

Utwórz plik o nazwie collabora-values.yaml. W tym przykładzie przyjęto ingress-nginx, klucz tajny TLS o nazwie office-example-com-tlsoraz Nextcloud w https://cloud.example.com. Grupa aliasów musi określać hosta aplikacji WOPI, z którym Collabora może się kontaktować; nie jest to publiczna nazwa hosta 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

Udokumentowany przykład wykresu pozwala aliasgroupsna użycie hosta WOPI i tych parametrów SSL, gdy odwrotny serwer proxy kończy TLS. W tym układzie ruch zewnętrzny do serwera office.example.comkorzysta z protokołu HTTPS, podczas gdy ruch przychodzący przekierowuje ruch do platformy Collabora przez protokół HTTP wewnątrz klastra. Jeśli ruch przychodzący korzysta z protokołu TLS passthrough lub innego protokołu wewnętrznego, nie kopiuj tych flag SSL bezmyślnie; dostosuj je do rzeczywistej ścieżki TLS i bieżących wartości wykresu.

Sprawdź, czy klucz tajny TLS istnieje w przestrzeni collaboranazw. Jeśli używasz innego kontrolera wejściowego, zastąp klasę i adnotacje udokumentowanymi odpowiednikami tego kontrolera. Utrzymuj włączony ruch websocket i zezwalaj na połączenia o długim czasie trwania; ustawienia domyślne kontrolera mogą się różnić.

Krok 4: Wyrenderuj i zainstaluj wykres

Najpierw wyrenderuj manifesty, aby wychwycić błędy YAML i przejrzyj wygenerowane ustawienia Ingress, Service i obciążenia. Następnie zainstaluj przypiętą wersję wykresu:

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

Obejrzyj materiały od razu po uruchomieniu:

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

Poczekaj, aż kontener stanie się gotowy, zanim podłączysz aplikację WOPI. Jeśli stan nadal oczekuje, sprawdź, czy klaster ma wystarczającą ilość dostępnego procesora i pamięci oraz czy selektory węzłów, taint lub limity zasobów nie uniemożliwiają rozmieszczenia. Wykres pozostawia operatorowi wybór żądań zasobów i limitów; plik README Collabora zawiera bardziej szczegółowe przykładowe wartości zasobów dla środowisk produkcyjnych, ale rzeczywisty rozmiar zależy od edycji współbieżnej i obciążenia dokumentami.

Krok 5: Połącz się z Nextcloud lub innym hostem WOPI

Otwórz ustawienia Office lub Collabora w aplikacji WOPI i wprowadź adres URL usługi zewnętrznej https://office.example.com. W NextCloud instrukcja administracyjna opisuje ustawianie adresu URL serwera Collabora Online w ustawieniach administracyjnych Office. Sprawdź również listę dozwolonych żądań WOPI w NextCloud, jeśli Twoja konfiguracja ogranicza liczbę hostów, które mogą się łączyć. Adres musi być dostępny zarówno dla przeglądarek użytkowników końcowych, jak i dla serwera aplikacji wysyłającego żądania WOPI.

Jeśli połączenie nie powiedzie się z komunikatem „nieautoryzowany host WOPI” lub podobnym, porównaj rzeczywisty adres URL hosta WOPI z collabora.aliasgroups. Sprawdź schemat, nazwę hosta i port oraz rozważnie dodaj wszelkie dozwolone alternatywne nazwy hostów. Unikaj szerokich wzorców hostów, chyba że rozumiesz ich wpływ. Jeśli używasz więcej niż jednej aplikacji WOPI, postępuj zgodnie z udokumentowaną strukturą grup aliasów dla każdego hosta, zamiast zezwalać na każdą domenę.

Kiedy należy przejść na skalę większą niż jeden pod?

W przypadku małej próby jedna replika z wyłączonym autoskalowaniem pozwala uniknąć złożoności routingu. W przypadku wielu replik plik README wykresu Collabora pokazuje powinowactwo NGINX na podstawie WOPISrcargumentu zapytania. Dodaj udokumentowaną adnotację do ingress podczas korzystania z ingress-nginx:

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

Kieruje to żądania dotyczące tego samego dokumentu do tego samego kontenera zaplecza, co jest ważne w przypadku edycji grupowej i żądań do schowka. Sprawdź dokumentację, aby poznać dokładną wersję kontrolera ingress; adnotacja obsługiwana przez ingress-nginx nie jest automatycznie prawidłowa dla HAProxy, Traefik ani implementacji API Gateway. Po włączeniu większej liczby replik lub automatycznego skalowania przetestuj jednoczesne edycje tego samego dokumentu i obserwuj logi Collabora oraz logi dostępu ingress. Rozmiar zasobów, zachowanie sesji i wysoka dostępność wymagają walidacji specyficznej dla obciążenia.

Sprawdź wdrożenie z zewnątrz

1. Sprawdź, czy Kubernetes zgłasza kontener jako gotowy oraz czy usługa i dane przychodzące istnieją: kubectl get pods,svc,ingress -n collabora.
2. Sprawdź publiczny punkt końcowy. Powinien zwrócić kod XML, a nie błąd przeglądarki lub serwera proxy:

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

3. Otwórz aplikację WOPI i edytuj dokument testowy. Sprawdź, czy edytor się załadował, zmiany zostały zapisane, a ponowne otwarcie dokumentu wyświetli zapisaną zawartość.
4. Jeśli używasz wielu replik, otwórz ten sam dokument w dwóch sesjach i sprawdź, czy obie mogą ze sobą współpracować bez konieczności ponownego łączenia. Pomoże to zidentyfikować brakujące powinowactwo sesji.
5. Przejrzyj dzienniki pod kątem błędów TLS, autoryzacji WOPI lub błędów upstream:

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

   Jeśli wykres utworzy obciążenie pracą o innej nazwie, użyj kubectl get deployments -n collaborai zastąp je rzeczywistą nazwą.

Pomyślna odpowiedź na żądanie odkrycia potwierdza, że ​​publiczny punkt końcowy obsługuje metadane Collabora; nie dowodzi to jednak, że uwierzytelnianie WOPI lub zapisywanie dokumentów działa. Kompleksowy test dokumentu to ostateczna kontrola.

Typowe punkty awarii

• Ingress zwraca 404 lub 502: sprawdź DNS, klasę ingress, klucz tajny TLS i punkty końcowe usługi. Potwierdź, że ingress może dotrzeć do usługi Collabora na porcie usługi wykresu.
• Odkrywanie działa, ale edytor pozostaje pusty: sprawdź błędy konsoli przeglądarki i logi proxy. Sprawdź ustawienia zakończenia HTTPS, obsługę websocketów i długie limity czasu żądań.
• Nieautoryzowany host WOPI: zezwól na użycie nazwy hosta WOPI z serwera aliasgroupsbiurowego; nie zastępuj jej nazwą hosta serwera biurowego.
• Pod uruchamia się ponownie lub zostaje eksmitowany: sprawdź kubectl describe poddzienniki kontenerów, a następnie ustaw realistyczne żądania zasobów i limity dla dostępnego klastra.
• Edycja staje się niestabilna po dodaniu replik: sprawdź powinowactwo oparte na WOPISrc i upewnij się, że kontroler zachowuje argument zapytania podczas kierowania żądaniami.

Po zainstalowaniu wykresu, osiągnięciu punktu końcowego wykrywania i pomyślnym otwarciu i zapisaniu rzeczywistego dokumentu za pomocą aplikacji WOPI, wdrożenie głównego kodu działa. Zachowaj przypiętą wersję wykresu i powtórz te sprawdzenia po każdej aktualizacji wykresu, zmianach w ingressie lub zmianach skalowania.

Oficjalne referencje

• Schemat i przewodnik wdrażania Helm Kubernetes utrzymywany przez Collabora
• Wartości wykresu Collabora Helm
• Publikacje wykresów Collabora
• Wskazówki dotyczące Collabora Online Development Edition (CODE)
• Instrukcja konfiguracji pakietu NextCloud Office
• dokumentacja adnotacji ingress-nginx
• Odniesienie do polecenia instalacji Helm