Jak skonfigurować klaster Collabora Online z wieloma węzłami

Klaster Collabora Online to nie tylko kilka sprawnych coolwsdserwerów z systemem równoważenia obciążenia typu round-robin. Edycja grupowa polega na wysyłaniu żądań dotyczących tego samego dokumentu do tego samego węzła Collabora. WOPISrcZ tego powodu wykres Kubernetes w Collabora dokumentuje routing według identyfikatora dokumentu WOPI, . Niniejszy przewodnik wykorzystuje utrzymywany wykres Helm w Collabora w Kubernetes jako konkretną konfigurację wielowęzłową i wskazuje, co należy zmienić w przypadku innego kontrolera wejściowego lub wdrożenia innego niż Kubernetes.

Zweryfikowano: Wykres Collabora obsługuje wiele replik i opisuje powinowactwo dokumentów za pomocą WOPISrc. Zależne od wdrożenia: adnotacje przychodzące, zakończenie TLS, żądania zasobów oraz to, czy kontroler sesji jest odpowiedni. Nie należy zakładać, że jakikolwiek moduł równoważenia obciążenia lub każde ustawienie „trwałej sesji” zachowa powinowactwo dokumentów. Potwierdź zachowanie specyficzne dla kontrolera i przetestuj je przed przeniesieniem użytkowników do klastra.

Co klaster robi, a czego nie robi

W standardowym wdrożeniu z wieloma replikami, każdy węzeł Collabora może obsługiwać dokumenty, podczas gdy serwer proxy wysyła żądania każdego dokumentu do jednego węzła. To powoduje rozproszenie oddzielnych dokumentów w puli. Nie oznacza to jednak, że każdy węzeł współdzieli ten sam proces edycji na żywo ani że uruchomiony dokument zawsze może płynnie przenieść się, jeśli jego węzeł się zatrzyma.

Collabora dokumentuje również kontroler COOL dla Kubernetes, który wprowadza inne podejście do zarządzania sesjami. Jego routing i konfiguracja różnią się od samodzielnego puli replik. W tym artykule opisano konfigurację prostszego modelu powinowactwa źródła WOPI; nie należy łączyć go z ustawieniami tokenów tras specyficznymi dla kontrolera, chyba że kontroler został wdrożony i skonfigurowany dla danej wersji.

Działanie: zdecyduj, czy potrzebujesz podstawowej, replikowanej usługi Collabora dla zapewnienia pojemności i redundancji węzłów, czy konfiguracji zarządzanej przez kontroler z zachowaniem uwzględniającym sesję. Ta druga opcja ma dodatkowe komponenty i konfigurację zależną od wersji. Zapoznaj się z omówieniem kontrolera Collabora Online, jeśli rozważasz tę ścieżkę.

Przed wdrożeniem

• Działający klaster Kubernetes, Helm, DNS dla publicznej nazwy hosta Collabora oraz serwer proxy przychodzący lub odwrotny obsługujący protokół TLS.
• Integracja WOPI, taka jak Nextcloud, skonfigurowana do używania pojedynczej publicznej nazwy hosta Collabora, a nie indywidualnych adresów kontenerów.
• Host lub hosty WOPI, które Collabora ma prawo akceptować, wprowadzone w konfiguracji wykresu collabora.aliasgroups.
• Wystarczająca moc obliczeniowa procesora i pamięci do obsługi obciążenia dokumentami, a także możliwość sprawdzania stanu kontenera, dzienników przychodzących i wykorzystania zasobów.
• Okno konserwacyjne dla początkowego wdrożenia i dokument testowy z dwoma oddzielnymi kontami użytkowników.

Dedykowana usługa Collabora Online różni się od wbudowanego serwera CODE w Nextcloud. Nextcloud opisuje swoją wbudowaną opcję jako przeznaczoną do użytku osobistego lub dla małych zespołów i pozbawioną zaawansowanych funkcji skalowalności serwera dedykowanego. Działanie: jeśli potrzebujesz wielowęzłowej puli Collabora, zaplanuj dedykowaną usługę i sprawdź, czy model licencjonowania i wsparcia jest odpowiedni dla Twojego wdrożenia. Zapoznaj się z instrukcją instalacji Nextcloud Office .

Krok 1: Wybierz model routingu

Udokumentowany model autonomiczny haszuje na WOPISrc, co identyfikuje dokument w żądaniach WOPI. Żądania dotyczące jednego dokumentu muszą dotrzeć do tego samego kontenera; żądania dotyczące różnych dokumentów mogą być rozproszone między kontenerami. Ogólna reguła round-robin nie spełnia tego wymogu.

Działanie: użyj implementacji ingress obsługiwanej przez dokumentację diagramu, takiej jak udokumentowane przykłady ingress NGINX lub HAProxy, albo użyj odwrotnego proxy w przestrzeni nazw diagramu, jeśli klaster nie zezwala na odpowiedni kontroler ingress. Jeśli używasz innego proxy, sprawdź, czy może ono spójnie kierować żądania przez źródło WOPI zarówno dla zwykłych żądań HTTP, jak i długotrwałych połączeń WebSocket.

Krok 2: Przejrzyj wykres i wybierz wersję

Wykres i jego wartości zmieniają się z czasem. Przed instalacją zapoznaj się z aktualnym oficjalnym plikiem README i wartościami wykresu, zamiast kopiować konfigurację napisaną dla starszej wersji. Poniższe przykłady opierają się na aktualizowanej dokumentacji wykresów Collabora, zweryfikowanej 6 października 2026 r.; traktuj aktualne informacje o wersji i wartości w repozytorium jako miarodajne w dniu instalacji.

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

Działanie: wybierz wersję wykresu zgodną z Twoją polityką kontroli zmian i zapisz wdrożoną przez nią wersję obrazu Collabora. Przypnij wersję wykresu do powtarzalnych aktualizacji; unikaj polegania na niesprawdzonej wersji pływającej w środowisku produkcyjnym. Przewodnik konfiguracji wykresu znajduje się w pliku README Collabora Online for Kubernetes .

Krok 3: Przygotuj wartości dla trzech replik

W tym przykładzie przyjęto kontroler NGINX Ingress, zakończenie TLS na wejściu oraz zewnętrzny host WOPI na cloud.example.com. Zastąp obie nazwy hostów swoimi własnymi. Jeśli TLS kończy się gdzie indziej lub używasz HAProxy, użyj odpowiedniej, udokumentowanej konfiguracji tego kontrolera.

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

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

Powyższe wartości adnotacji skrótu i ​​limitu czasu są pokazane w przykładzie NGINX na wykresie. Ten extra_paramswiersz jest odpowiedni tylko wtedy, gdy odwrotny serwer proxy kończy TLS i łączy się z Collabora przez HTTP. Nie należy go stosować bez zmian, jeśli topologia TLS jest inna. Skonfiguruj klucz tajny TLS i hosta dla ruchu przychodzącego zgodnie z wartościami menedżera certyfikatów i lokalnymi wartościami wykresu; fragment pomija te ustawienia specyficzne dla dostawcy.

Akcja: zapisz jako my_values.yaml, dodaj konfigurację TLS wymaganą przez Twój serwer wejściowy i porównaj każdy klucz z wybranym wydaniem wykresu values.yaml. Zachowaj spójność publicznej nazwy hosta Collabora w DNS, TLS, adresie URL Collabora integracji i routingu proxy.

Krok 4: Zainstaluj wersję Collabora

Zainstaluj w dedykowanej przestrzeni nazw. Zastąp <chart-version>wersją wybraną w kroku 2; nawiasy kątowe w tym miejscu pełnią funkcję objaśniającą i nie należy ich wpisywać dosłownie.

helm install --create-namespace   --namespace collabora   collabora-online collabora/collabora-online   --version <chart-version>   -f my_values.yaml

W przypadku istniejącej wersji skorzystaj z zaplanowanej aktualizacji Helm po sprawdzeniu notatek dotyczących migracji i wyrenderowanych zmian. Unikaj wdrażania dużej aktualizacji obrazu lub wykresu w tym samym czasie, co pierwszej zmiany skalowania; zmiana jednej zmiennej na raz ułatwia izolację błędów.

Działanie: sprawdź wydanie i poczekaj, aż wszystkie repliki będą gotowe:

helm status collabora-online -n collabora
kubectl get pods,svc,ingress -n collabora
kubectl get events -n collabora --sort-by=.lastTimestamp

Trzy pożądane repliki nie są dowodem na to, że trzy sprawne węzły obsługują ruch. Sprawdź gotowość, ostatnie restarty, harmonogram i punkty końcowe dla ruchu przychodzącego. Jeśli kontenery nadal oczekują, sprawdź dostępną pojemność klastra oraz żądania i limity zasobów w wartościach wykresu.

Krok 5: Połącz aplikację WOPI

W ustawieniach integracji biurowej platformy plików ustaw adres URL serwera Collabora na publiczny punkt końcowy, na przykład https://office.example.com. Nie kieruj aplikacji na adres IP kontenera ani nazwę usługi wyłącznie dla Kubernetes, chyba że sama integracja działa w klastrze, a prywatny routing jest wyraźnie obsługiwany przez Twój projekt.

Nazwa hosta aliasgroupsmusi identyfikować hosta WOPI, który przechowuje i udostępnia dokumenty; nie jest to nazwa hosta Collabora. Niezgodność może spowodować błędy walidacji hosta WOPI, nawet gdy kontenery Collabora i ingres są sprawne.

Działanie: wprowadź ten sam publiczny adres URL Collabora w konfiguracji integracji, zapisz go i sprawdź, czy sprawdzanie łączności lub wykrywania zakończyło się pomyślnie. Jeśli się nie powiedzie, przed zmianą liczby replik sprawdź listę dozwolonych WOPI aplikacji, grupy aliasów Collabora, DNS, TLS i nagłówki proxy.

Krok 6: Przetestuj zgodność dokumentów i współpracę

Otwórz dokument testowy i sprawdź logi wejściowe lub proxy, aby potwierdzić, który serwer go obsługuje. Następnie otwórz ten sam dokument w sesji drugiego użytkownika i sprawdź, czy obaj użytkownicy mogą edytować i widzieć zmiany wprowadzone przez siebie nawzajem. Otwórz inny dokument i sprawdź, czy moduł równoważenia obciążenia może go wysłać do innego sprawnego kontenera. Test dotyczy routingu i współpracy, a nie tylko tego, czy strona docelowa zwraca HTTP 200.

Działanie: sprawdź, czy skrót źródłowy WOPI jest obecny i spójnie stosowany do żądań generowanych dla tego samego dokumentu, w tym aktualizacji WebSocket. Jeśli użytkownicy nie widzą zmian wprowadzanych przez innych użytkowników, porównaj wybór zaplecza dla tego samego dokumentu przed sprawdzeniem hosta WOPI lub pamięci podręcznej przeglądarki.

Krok 7: Testowanie obsługi stanu i utraty węzła

Kontrole gotowości powinny utrzymywać niesprawny lub uruchamiany pod poza zasięgiem. Wykres zawiera ustawienia sondy rozruchu, gotowości i aktywności, ale dokładne zachowanie i czas zależą od wybranej wersji wykresu i klastra. Niedostępność podu może przerwać działanie dokumentów aktualnie w nim uruchomionych; podstawowa pula powinowactwa nie powinna być określana jako replikacja sesji na żywo.

Działanie: w środowisku testowym usuń jeden kontener z usługi podczas aktywnej sesji edycji, obserwuj zachowanie klienta i routing proxy, a następnie ponownie otwórz dokument i upewnij się, że dotarł do sprawnego kontenera. Nie wykonuj tego testu na aktywnych dokumentach produkcyjnych bez zatwierdzonego planu konserwacji. Aby zapewnić większą ciągłość sesji, oceń kontroler COOL i jego konfigurację tokenów trasowania dla konkretnej wersji.

Krok 8: Monitoruj, dostosowuj i ulepszaj świadomie

Śledź ponowne uruchomienia kontenerów, użycie procesora i pamięci, błędy żądań i WebSocket, opóźnienia wejściowe oraz zgłoszenia użytkowników dotyczące ładowania lub ponownego łączenia się z dokumentami. Dokumentacja wykresów Collabora zawiera wskazówki dotyczące monitorowania Kubernetes. Ustaw zasoby na podstawie obserwowanego obciążenia, zamiast kopiować przykładowe liczby: rozmiar dokumentu, sesje równoczesne, czcionki i wzorce edycji – wszystkie te czynniki wpływają na pojemność.

Collabora zaleca uruchamianie tej samej wersji na wszystkich węzłach z równoważeniem obciążenia, aby klienci otrzymywali spójne zasoby internetowe dla poszczególnych wersji. Podczas aktualizacji należy korzystać ze strategii wdrażania obsługiwanej przez wykres, monitorować gotowość i logi oraz testować otwarty dokument przez wielu użytkowników przed zadeklarowaniem zmiany jako zakończonej.

Działanie: zachowaj wersję wykresu, wersję obrazu, plik wartości i wyniki testów razem w rekordzie zmian. Zaplanuj aktualizacje, upewnij się, że wszystkie repliki są zgodne z wersją docelową i zachowaj plan wycofywania zgodny z obsługiwanym mechanizmem wycofywania wykresu.

Typowe błędne przekonania, które należy sprawdzić

• „Trzy repliki automatycznie tworzą działający klaster”. Same repliki nie konfigurują powinowactwa dokumentów. Sprawdź, czy skróty wejściowe w źródle WOPI lub czy kontroler zapewnia odpowiednie routing sesji.
• „Wystarczą sesje stałe oparte na adresie IP użytkownika”. Nie jest to reguła opisana na wykresie Collabora dla jej samodzielnej puli Kubernetes. Użytkownicy współpracujący nad jednym dokumentem muszą konwergować na tym samym węźle, nawet jeśli pochodzą z różnych urządzeń lub sieci. Skonfiguruj powinowactwo oparte na dokumentach i przetestuj z dwoma użytkownikami.
• „Sprawna strona główna dowodzi, że klaster jest gotowy”. Dowodzi ona jedynie, że jedno żądanie HTTP zostało pomyślnie zwrócone. Przetestuj otwieranie i wspólną edycję dokumentu, aktualizacje WebSocket oraz zachowanie w przypadku niedostępności kontenera.
• „Dodanie węzła gwarantuje, że aktywne sesje przetrwają utratę węzła”. Podstawowa pula powinowactwa źródłowego WOPI kieruje dokument do węzła; nie sprawdza, czy proces edycji w pamięci jest replikowany. Potwierdź oczekiwane zachowanie odzyskiwania w teście kontrolowanym lub oceń oddzielne funkcje zarządzania sesjami kontrolera.

W przypadku instalacji innych niż Kubernetes zasada architektury jest taka sama, ale polecenia wykresów Kubernetes i adnotacje ingress nie mają zastosowania. Użyj konfiguracji proxy dla swojej wersji Collabora i modułu równoważenia obciążenia, upewnij się, że obsługiwane są długotrwałe połączenia WebSocket i zaimplementuj routing per-document z wykorzystaniem źródła WOPI. Podręcznik Collabora Online SDK opisuje równoważenie obciążenia i WOPISrcwymóg powinowactwa; sprawdź odpowiednią sekcję w podręczniku dla używanej wersji.