Jak uruchomić serwer dokumentów ONLYOFFICE za pomocą modułu równoważenia obciążenia HAProxy

Najważniejsza zasada jest taka: umieszczenie serwera dokumentów ONLYOFFICE za HAProxy jest proste w przypadku pojedynczego zaplecza, ale klaster edytorów wielowęzłowych wymaga czegoś więcej niż tylko metody round-robin. Aktualna dokumentacja API ONLYOFFICE stwierdza, że ​​żądania dotyczące tego samego dokumentu muszą dotrzeć do tego samego węzła serwera dokumentów podczas wspólnej edycji. W przypadku nowoczesnych integracji zalecanym mechanizmem jest shardkeyparametr zapytania, którego moduł równoważenia obciążenia może użyć do określenia powinowactwa uwzględniającego dokumenty.

Jeśli masz tylko jeden serwer dokumentów i chcesz HAProxy do zakończenia HTTPS, stabilnej publicznej nazwy hosta lub scentralizowanych kontroli stanu, konfiguracja jest prostsza. Jeśli masz dwa lub więcej węzłów serwera dokumentów, użyj tych samych podstawowych ustawień proxy, ale dodaj routing oparty na routingu, shardkeyzamiast zakładać, że zwykła metoda round-robin wystarczy.

Poniższe przykłady zostały sprawdzone pod kątem bieżącej dokumentacji serwera proxy ONLYOFFICE , dokumentacji klucza shard-key ONLYOFFICE i bieżących wytycznych HAProxy WebSocket .

Kiedy ta konfiguracja jest dobra

HAProxy to sensowny front-end, gdy potrzebujesz jednego publicznego adresu URL, np. https://docs.example.comzakończenia TLS w module równoważenia obciążenia, aktywnych kontroli stanu lub wielu węzłów serwera dokumentów za jednym punktem końcowym. Jest on również przydatny, gdy NextCloud, ownCloud, niestandardowy DMS lub aplikacja nigdy nie powinna łączyć się bezpośrednio z pojedynczym węzłem serwera dokumentów.

W tym przewodniku przyjęto założenie:

• HAProxy może dotrzeć do każdego serwera dokumentów poprzez sieć wewnętrzną.
• Każdy serwer dokumentów działa już bezpośrednio przed wprowadzeniem modułu równoważenia obciążenia.
• Publiczna nazwa hosta to HAProxy.
• Twój certyfikat TLS obejmuje publiczną nazwę hosta.
• Jeśli używasz wielu węzłów, są one wdrażane w ramach obsługiwanej wieloserwerowej architektury ONLYOFFICE, a nie jako niezależne serwery, które po prostu współdzielą moduł równoważenia obciążenia.

Krok 1: Zweryfikuj każdy serwer dokumentów przed dodaniem HAProxy

Nie zaczynaj od modułu równoważenia obciążenia. Najpierw sprawdź, czy każdy backend jest sprawny, korzystając z hosta HAProxy. Dokumenty ONLYOFFICE /healthchecksłużą jako punkt końcowy do sprawdzania dostępności edytora. Serwer o dobrym stanie technicznym zwraca true; sprawdzenie obejmuje podstawowe zależności, takie jak baza danych, broker komunikatów, połączenie Redis i pamięć masowa.

curl -sS http://10.0.10.21/healthcheck
curl -sS http://10.0.10.22/healthcheck

Oczekiwany wynik:

true
true

Jeśli jeden z zapleczy zawiedzie, należy najpierw rozwiązać problem z tym węzłem. Typowe przyczyny to reguły zapory sieciowej, nieprawidłowy port wewnętrzny, niedziałające usługi serwera dokumentów lub niedostępne usługi pomocnicze.

Krok 2: Ustaw tryb HTTP i limity czasu, które tolerują połączenia edytora

ONLYOFFICE to aplikacja HTTP, która podczas edycji korzysta z długotrwałych połączeń WebSocket. HAProxy może automatycznie proxyować WebSocket po aktualizacji HTTP, ale jego polityka limitu czasu nadal ma znaczenie. Własna dokumentacja HAProxy zaleca timeout tunnelwartość dla zaktualizowanych połączeń WebSocket.

Praktyczna podstawa jest taka:

global
    log /dev/log local0
    log /dev/log local1 notice
    daemon
    maxconn 4096

defaults
    log global
    mode http
    option httplog
    option dontlognull
    timeout connect 5s
    timeout client 60s
    timeout server 60s
    timeout tunnel 1h

Godzinny limit czasu tunelu to przykład, a nie wymóg uniwersalny. Wybierz wartość, która pasuje do zachowań edycyjnych Twojej organizacji, polityki bezpieczeństwa i limitów zasobów. Jeśli edytorzy rozłączają się bardzo regularnie, porównaj ten interwał z limitami czasu bezczynności HAProxy i wszelkimi limitami czasu bezczynności zapory sieciowej lub odwrotnego proxy.

Krok 3: Zakończ protokół HTTPS i zachowaj oryginalny kontekst żądania

ONLYOFFICE wyraźnie wymaga przekierowanych nagłówków, gdy działa za serwerem proxy. W szczególności X-Forwarded-Protoinformuje serwer dokumentów, czy pierwotny klient użył protokołu HTTP, czy HTTPS, X-Forwarded-Hostzachowując jednocześnie nazwę hosta żądaną przez klienta.

Czysty interfejs użytkownika HAProxy może wyglądać następująco:

frontend onlyoffice_http
    bind *:80
    mode http
    http-request redirect scheme https code 301

frontend onlyoffice_https
    bind *:443 ssl crt /etc/haproxy/certs/docs.example.com.pem
    mode http
    option httplog

    http-request set-header X-Forwarded-Proto https
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]

    default_backend onlyoffice_docs

Zazwyczaj nie ma potrzeby ręcznego tworzenia reguł w stylu NGINX Upgradei Connectionnagłówków w nowoczesnym trybie HTTP HAProxy. HAProxy rozpoznaje aktualizację HTTP-WebSocket i przełącza połączenie w tryb tunelowy. Ważne jest, aby nie wstawiać reguł, które usuwają lub przerywają żądanie aktualizacji.

Aby zapewnić widoczność adresu IP klienta, dodaj option forwardforzaplecze. To wygeneruje X-Forwarded-Fornagłówek z adresu źródłowego klienta.

Krok 4: Dodaj kontrole stanu zdrowia i wybierz odpowiednią regułę równoważenia

Serwer pojedynczego dokumentu

Jeśli HAProxy jest frontem jednego Serwera Dokumentów, zaplecze może być proste:

backend onlyoffice_docs
    mode http
    option forwardfor
    option httpchk GET /healthcheck
    http-check expect status 200
    timeout tunnel 1h

    server ds1 10.0.10.21:80 check

W tym projekcie HAProxy jest przede wszystkim odwrotnym serwerem proxy, punktem końcowym TLS i bramką kontroli stanu.

Węzły serwera wielu dokumentów

W przypadku rzeczywistego wdrożenia wielowęzłowego nie należy polegać na zwykłym mechanizmie „round-robin” do wspólnej edycji. Aktualna dokumentacja ONLYOFFICE stanowi, że wszystkie żądania dotyczące tego samego dokumentu muszą docierać do tego samego serwera. Żądania edytora z przeglądarki do serwera automatycznie zawierają klucz partycji, a aplikacje powinny dodawać ?shardkey=<document-key>żądania do poleceń, konwersji i Kreatora Dokumentów, jeśli jest to udokumentowane.

HAProxy obsługuje haszowanie parametrów zapytania URL, więc odpowiednim zapleczem dla standardowego interfejsu API ONLYOFFICE Docs jest:

backend onlyoffice_docs
    mode http
    option forwardfor
    option httpchk GET /healthcheck
    http-check expect status 200
    timeout tunnel 1h

    balance url_param shardkey

    server ds1 10.0.10.21:80 check
    server ds2 10.0.10.22:80 check

Algorytm HAProxy url_paramhaszuje wybrany parametr ciągu zapytania. Jeśli ten parametr jest nieobecny, HAProxy powraca do standardowego działania równoważenia obciążenia. Dlatego szczególnie ważne jest, aby integracja wysyłała klucz fragmentu w przypadku żądań, w przypadku których ONLYOFFICE to zaleca.

WOPI jest inne. ONLYOFFICE stwierdza, że ​​integracje WOPI używają WOPISrcparametru zapytania do tego samego celu routingu. Nie kopiuj wiersza balance url_param shardkeybez zmian do projektu WOPI i nie zakładaj, że zapewnia on wymagane powinowactwo.

Bezpiecznie zweryfikuj i ponownie załaduj HAProxy

Przed ponownym załadowaniem usługi należy sprawdzić poprawność konfiguracji:

sudo haproxy -c -f /etc/haproxy/haproxy.cfg

Załaduj ponownie dopiero po pomyślnym sprawdzeniu składni:

sudo systemctl reload haproxy
sudo systemctl status haproxy

Jeśli Twoja dystrybucja korzysta z innego menedżera usług lub ścieżki konfiguracji, dostosuj odpowiednio te polecenia. Ponowne załadowanie jest lepsze niż niepotrzebny twardy restart, jeśli Twój pakiet HAProxy obsługuje łagodne ponowne ładowanie konfiguracji.

Testuj za pomocą publicznego adresu URL, a nie tylko z poziomu sieci zaplecza

Teraz sprawdź, do czego faktycznie dotrą użytkownicy i Twoja platforma do zarządzania dokumentami:

curl -sS https://docs.example.com/healthcheck

Oczekiwane ciało to:

true

Następnie zweryfikuj certyfikat TLS:

openssl s_client -connect docs.example.com:443   -servername docs.example.com </dev/null 2>/dev/null   | openssl x509 -noout -subject -issuer -dates

Na koniec otwórz prawdziwy dokument za pośrednictwem aplikacji integrującej. Kontrola stanu potwierdza jedynie gotowość punktu końcowego serwera dokumentów; nie potwierdza poprawności adresów URL wywołań zwrotnych, konfiguracji tokena JWT, pobierania dokumentów, wywołań zwrotnych zapisów ani powinowactwa wielowęzłowego.

Co sprawdzić, gdy edytor ładuje się, ale rozłącza się lub nie można go zapisać

Czy potrzebujesz intensywnych sesji?

Tradycyjna lepkość adresu IP źródłowego nie jest najlepszym domyślnym rozwiązaniem dla ONLYOFFICE. Wielu użytkowników edytujących ten sam plik może mieć różne adresy IP klienta, a jeden użytkownik może otwierać różne dokumenty, które nie muszą znajdować się na tym samym węźle. Powinowactwo uwzględniające dokumenty, oparte na kluczu partycji (shard key) w ONLYOFFICE, jest bardziej precyzyjne, ponieważ klucz routingu reprezentuje edytujący dokument, a nie adres sieciowy użytkownika.

To samo rozróżnienie wyjaśnia, dlaczego prosta, stała sesja oparta na plikach cookie nie powinna być traktowana jako substytut routingu udokumentowanego przez ONLYOFFICE. Podczas tworzenia wdrożenia API Docs z wieloma węzłami należy używać udokumentowanego klucza fragmentu aplikacji.

Ostateczna lista kontrolna konfiguracji

• Każdy serwer dokumentów powraca truez /healthcheckokresu przed dodaniem do HAProxy.
• HAProxy działa w trybie HTTP dla front-endu i back-endu ONLYOFFICE.
• Protokół HTTPS zakończony jest certyfikatem ważnym dla publicznej nazwy hosta serwera dokumentów.
• X-Forwarded-Protoi X-Forwarded-Hostsą przekazywane prawidłowo.
• Limit czasu tunelu WebSocket jest wystarczająco długi, aby umożliwić rzeczywiste sesje edycji.
• Kontrole stanu zaplecza usuwają uszkodzone węzły z usługi.
• Ruch wielowęzłowego interfejsu API Dokumentacji wykorzystuje shardkeypowinowactwo oparte na algorytmie -based, a nie zwykłą metodę round robin.
• Wdrożenia WOPI wykorzystują routing właściwy dla WOPISrc.
• Kontrola zdrowia publicznego działa, a dzięki integracji możliwe jest otwieranie, edytowanie i zapisywanie prawdziwego dokumentu.

W przypadku jednego serwera dokumentów HAProxy to przede wszystkim czysty serwer proxy odwrotnego i warstwa TLS. W przypadku kilku węzłów serwera dokumentów decydującą różnicą jest routing uwzględniający dokumenty. Najpierw należy zbudować serwer proxy w oparciu o to wymaganie, a następnie dodać do niego kontrole kondycji, HTTPS i regulację limitu czasu.