Napraw opóźnienie w edycji wspólnej ONLYOFFICE na samodzielnie hostowanym serwerze Docker

Jeśli współedycja w ONLYOFFICE wydaje się powolna na samodzielnie hostowanym serwerze Docker, nie zaczynaj od zmiany nieudokumentowanych parametrów edytora. Najpierw podziel problem na trzy mierzalne obszary: obciążenie zasobów serwera, zachowanie odwrotnego proxy/WebSocket oraz błędy na poziomie pamięci masowej lub kontenera. Współedycja opiera się na długotrwałej komunikacji w czasie rzeczywistym, więc serwer, który poprawnie otwiera dokumenty, może nadal sprawiać wrażenie powolnego, gdy kilka osób pisze jednocześnie.

W tym przewodniku wykorzystano hipotetyczny przykład : niewielki zespół korzysta z ONLYOFFICE Docs w Dockerze, korzystając z NGINX. Jeden lub dwóch użytkowników może normalnie edytować dokument, ale gdy sześć osób otwiera ten sam dokument, aktualizacje kursora pojawiają się z opóźnieniem, a zmiany wprowadzone przez innych użytkowników pojawiają się po zauważalnej przerwie. Ten przykład to jedynie scenariusz szkoleniowy, a nie test porównawczy ani raport z rzeczywistego wdrożenia.

Od października 2026 roku w oficjalnym rejestrze zmian znajduje się ONLYOFFICE Docs 9.4. Wersja 9.4 zmieniła również architekturę Community Edition, usuwając zależności od RabbitMQ i baz danych, więc porady dotyczące starszych wydań mogą nie być już zgodne z aktualnym kontenerem Community Edition. Zawsze sprawdź zainstalowaną edycję i wersję przed skopiowaniem porady dotyczącej dostrajania ze starszego posta na forum.

1. Zmierz opóźnienie przed zmianą czegokolwiek

W hipotetycznym przypadku pierwszym błędem byłoby ponowne uruchomienie losowych usług i nadzieja na zniknięcie opóźnienia. Zamiast tego należy utworzyć powtarzalny test. Otwórz ten sam dokument z kilku sesji przeglądarki lub kont testowych, wprowadź krótkie zmiany i zanotuj, co jest opóźnione: naciśnięcia klawiszy na ekranie lokalnym, zdalne przesunięcie kursora, pojawienie się tekstu innego użytkownika, zapisanie statusu lub początkowe załadowanie dokumentu.

Te objawy wskazują na różne wąskie gardła. Jeśli sam edytor zawiesza się w lokalnej przeglądarce, przyczyną może być procesor po stronie klienta lub bardzo złożony dokument. Jeśli lokalne wprowadzanie tekstu jest natychmiastowe, a zdalne edycje pojawiają się z opóźnieniem, należy sprawdzić ścieżkę sieciową i sesję WebSocket. Jeśli każda czynność zwalnia po otwarciu większej liczby dokumentów, należy sprawdzić procesor serwera, pamięć, pamięć podręczną i dyskowe operacje wejścia/wyjścia.

ONLYOFFICE opisuje wdrożenie i podstawowe wymagania Dockera w oficjalnym przewodniku instalacji Dockera . W przypadku Docker Compose należy skorzystać z oficjalnych instrukcji Docker Compose .

2. Sprawdź obciążenie procesora i pamięci podczas edycji

Na hoście Docker uruchom:

docker stats

Obserwuj kontener Serwera Dokumentów podczas edycji przez grupę testową. Przeprowadź również inspekcję zasobów hosta za pomocą narzędzi takich jak:

free -h
uptime
vmstat 1
df -h

Oficjalne wymagania ONLYOFFICE dotyczące platformy Docker określają co najmniej 4 GB pamięci RAM i co najmniej 40 GB wolnego miejsca na dysku dla udokumentowanych konfiguracji, a także wymagania dotyczące pamięci wymiany. Wytyczne dla przedsiębiorstw wyraźnie wskazują również, że pojemność zależy od liczby jednoczesnych aktywnych użytkowników oraz liczby, rodzaju i rozmiaru dokumentów. Wartości te mają charakter bazowy, a nie stanowią gwarancji, że 4 GB zapewni płynną współpracę przy każdym obciążeniu.

W naszym przykładzie załóżmy, docker statsże kontener Serwera Dokumentów wielokrotnie zużywa większość dostępnego procesora, gdy sześć osób pisze jednocześnie. To wiarygodny dowód: dodanie limitów czasu dla serwerów proxy nie zwiększy zapotrzebowania na procesor. Następnym krokiem jest usunięcie zbyt restrykcyjnego limitu procesora Dockera, przeniesienie kontenera na szybszy host lub zmniejszenie obciążenia współbieżnego. Natomiast jeśli wydajność procesora pozostaje na niskim poziomie, należy kontynuować badania przed zakupem sprzętu.

Oficjalnym źródłem opublikowanych wytycznych dotyczących pojemności są wymagania systemowe ONLYOFFICE Docs Docker .

3. Sprawdź miejsce na dysku, montowania i pamięć podręczną plików

Dokumentacja Dockera ONLYOFFICE identyfikuje trwałe lokalizacje, w tym /var/log/onlyofficedla logów i /var/lib/onlyofficepamięci podręcznej plików. Sprawdź system plików, który obsługuje te ścieżki, a nie tylko główny system plików hosta.

df -h
docker inspect documentserver --format '{json .Mounts}'

Jeśli punkt montowania bind wskazuje na wolny system plików sieciowych lub przeciążony dysk, otwieranie dokumentów, konwersja i aktywność pamięci podręcznej mogą zwiększyć opóźnienie. Jeśli dysk jest prawie pełny, należy to naprawić przed dostrojeniem aplikacji. Dokumentacja rozwiązywania problemów z systemem Linux firmy ONLYOFFICE wyraźnie wskazuje na niewystarczającą ilość miejsca na dysku jako możliwą przyczynę problemów z konwersją.

Projekt zaleca również przechowywanie istotnych danych poza kontenerem, gdy potrzebne są trwałe logi, pamięć podręczna lub zewnętrzne usługi bazy danych/Redis/RabbitMQ. Zobacz oficjalne wytyczne dotyczące woluminów Docker .

4. Sprawdź, czy serwer proxy odwrotny utrzymuje połączenie w czasie rzeczywistym

Wiele wdrożeń hostowanych samodzielnie stawia ONLYOFFICE za NGINX, Apache, HAProxy lub Traefik. Oficjalna dokumentacja proxy ONLYOFFICE wyraźnie wymaga przekazywania nagłówków, takich jak X-Forwarded-Protoi X-Forwarded-Host. Konfiguracja dostarczana przez ONLYOFFICE obsługuje również obsługę aktualizacji HTTP/1.1 i WebSocket.

W przypadku NGINX porównaj swoją konfigurację z oficjalnym przykładem ONLYOFFICE, zamiast wklejać ogólny fragment kodu WebSocket z innego produktu. Przykładowy wzorzec obejmuje:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $proxy_connection;
proxy_set_header X-Forwarded-Host $the_host;
proxy_set_header X-Forwarded-Proto $the_scheme;

Dokładne mapdyrektywy i lokalizacje serwerów proxy mają znaczenie. Użyj kompletnego przykładu dostawcy dla swojej topologii. Obsługiwane konfiguracje są opublikowane w dokumencie Using ONLYOFFICE Docs behind the proxy .

W hipotetycznym zespole załóżmy, że host Dockera ma mnóstwo procesora i pamięci RAM, ale przeglądarka wielokrotnie łączy się ponownie z kanałem współpracy przez korporacyjną warstwę NGINX. Wskazuje to na ścieżkę proxy, a nie na moc obliczeniową serwera dokumentów.

5. Potwierdź sesję WebSocket w przeglądarce

Otwórz narzędzia programistyczne przeglądarki, wybierz panel Sieć, przefiltruj ruch WebSocket i ponownie załaduj edytor. Udane nawiązanie połączenia WebSocket zazwyczaj oznacza protokół HTTP 101 Switching Protocolsi połączenie, które pozostaje otwarte. Nie traktuj długotrwałego, „oczekującego” połączenia WebSocket jako awarii; oczekuje się, że aktywne połączenie WebSocket pozostanie otwarte.

Istotne są powtarzające się zachowania związane z rozłączaniem i ponownym łączeniem, nieudane uzgadnianie, błędy proxy lub długie przerwy, które korelują z opóźnieniem we współpracy. Jeśli zdalne edycje opóźniają się w tych samych momentach, w których następuje ponowne połączenie WebSocket, masz teraz konkretny problem sieciowy do rozwiązania.

Sprawdź zakończenie TLS, przekroczenie limitu czasu bezczynności serwera proxy, reguły modułu równoważenia obciążenia, polityki WAF i wszelkie pośrednie elementy, które mogą nie obsługiwać ruchu WebSocket. Jeśli występuje więcej niż jedna warstwa proxy, przetestuj każdy przeskok, zamiast zakładać, że tylko publiczna instancja NGINX jest zaangażowana.

6. Zweryfikuj oczekiwane kontenery i architekturę specyficzną dla danej edycji

Uruchomić:

docker compose ps
# or
docker ps

Nie zakładaj, że każde nowoczesne wdrożenie ONLYOFFICE musi mieć ten sam zbiór kontenerów Redis, PostgreSQL lub RabbitMQ. To właśnie wersja ma tu znaczenie. ONLYOFFICE twierdzi, że począwszy od Docs 9.4, open-source'owa edycja Community Edition została uproszczona do architektury jednoprocesowej i usunięta z zależności od RabbitMQ i baz danych. Wdrożenia Enterprise, Developer, starsze wdrożenia Community i niestandardowe stosy Compose mogą się różnić.

Oznacza to, że artykuł z 2023 roku dotyczący rozwiązywania problemów, który głosi, że „RabbitMQ musi być wąskim gardłem”, może być nieistotny dla obecnej instancji Community Edition. Zidentyfikuj obraz i wersję, którą faktycznie uruchamiasz:

docker inspect documentserver --format '{.Config.Image}'
docker image ls onlyoffice/documentserver

Oficjalny rejestr zmian ONLYOFFICE Docs wymienia wersję 9.4.0 z datą wydania 20 maja 2026 roku. Ogłoszenie dostawcy dotyczące wydania Docs 9.4 wyjaśnia zmianę w architekturze Community Edition.

7. Tymczasowo włącz rejestrowanie debugowania i skoreluj je z opóźnieniem

ONLYOFFICE udostępnia udokumentowaną zmienną środowiskową Dockera do rejestrowania debugowania. Aby uzyskać krótki czas na rozwiązywanie problemów, dodaj:

DS_LOG_LEVEL=DEBUG

Następnie utwórz ponownie lub uruchom ponownie odpowiedni kontener zgodnie z wybraną metodą wdrożenia i postępuj zgodnie z instrukcjami w dziennikach:

docker logs -f documentserver
# Docker Compose:
docker compose logs -f documentserver

Oficjalna dokumentacja podaje, że logi Dockera są również dostępne w /var/log/onlyoffice/documentserverkontenerze oraz w odpowiednim katalogu logów zamontowanym na hoście, jeśli go zamontujesz. Dziennik konwertera jest przydatny, gdy otwieranie lub konwertowanie plików przebiega wolno, a problemy ze współtworzeniem powinny być powiązane z dziennikami serwera dokumentów oraz obserwacjami przeglądarki/sieci.

Wyłącz ponownie DEBUG po zebraniu potrzebnych danych. Szczegółowe rejestrowanie służy do celów diagnostycznych, a nie jako stałe ustawienie wydajności. Postępuj zgodnie z procedurą dostawcy opisaną w dokumencie Włączanie rejestrowania debugowania w ONLYOFFICE Docs .

8. Aktualizuj ostrożnie, jeśli używasz starego obrazu

Jeśli wdrożenie znacznie odbiega od wspieranej wersji, aktualizacja może zawierać poprawki błędów i ulepszenia architektury. Jednak „pobranie najnowszej wersji i ponowne uruchomienie” nie jest bezpieczną receptą na wydajność na serwerze do współpracy produkcyjnej.

Najpierw zarejestruj aktualny tag obrazu, plik kompozycji, ustawienia JWT, zamontowane woluminy, konfigurację odwrotnego proxy i konfigurację integracji. Użyj wersji przypiętej, gdy proces zmian wymaga powtarzalności. Przewodnik instalacji Dockera ONLYOFFICE dokumentuje, jak określić konkretną wersję, a oficjalny dziennik zmian informuje o zmianach.

Przed celowym zatrzymaniem intensywnie działającego Serwera Dokumentów, należy postępować zgodnie z instrukcjami ONLYOFFICE dotyczącymi wyłączania dla danej edycji i wdrożenia, aby zapewnić bezpieczne działanie aktywnych sesji edycji. Nie należy używać dokumentu testowego zawierającego niezapisane prace użytkownika jako testu aktualizacji.

Jak hipotetyczny przypadek zawęża rzeczywiste rozwiązanie

Wróć do przykładowego zespołu z sześcioma współredaktorami. Wynik rozwiązywania problemów zależy od tego, co zaobserwujesz:

Praktyczna baza dla wdrożeń Dockera

W przypadku małej, samodzielnie hostowanej instalacji, zacznij od opublikowanych minimalnych wartości ONLYOFFICE, ale dostosuj rozmiar do rzeczywistej aktywności współbieżnej, a nie do łącznej liczby zarejestrowanych użytkowników. Utrzymuj trwałe logi i pamięć podręczną w pamięci masowej z przewidywalnym opóźnieniem. Unikaj ścisłych limitów procesora lub pamięci, chyba że zmierzysz obciążenie. Nie dopuść, aby sam host Dockera był w stanie przełączać się między serwerami przy normalnym obciążeniu edycyjnym.

Umieść ONLYOFFICE za konfiguracją odwrotnego proxy, pochodzącą z przykładów obsługiwanych przez dostawcę, zachowując aktualizacje WebSocket i przekierowane nagłówki hosta/protokołu. Monitoruj serwer podczas faktycznej edycji, a nie tylko w stanie bezczynności. Jeśli potrzebujesz bardziej szczegółowych dowodów, włącz tymczasowo rejestrowanie DEBUG i skoreluj znaczniki czasu logów z zachowaniem WebSocket przeglądarki i metrykami hosta.

Czego nie robić

• Nie zmieniaj nieudokumentowanych wartości local.jsontylko dlatego, że na forum jest napisane, że są to „poprawki wydajnościowe”.
• Nie zakładaj, że trwały protokół WebSocket oznaczony jako „oczekujący” jest uszkodzony; spodziewaj się trwałych protokołów WebSocket.
• Nie dodawaj Redis, RabbitMQ ani PostgreSQL tylko dlatego, że wykorzystywał je stary diagram wdrożenia. Najpierw sprawdź architekturę i wersję swojego wydania.
• Nie wyłączaj weryfikacji TLS, zabezpieczeń JWT ani ochrony serwera proxy, aby zmniejszyć opóźnienie.
• Nie porównuj metryk bezczynności serwera z okresem, w którym użytkownicy faktycznie zgłaszają opóźnienia.
• Nie należy uaktualniać instancji produkcyjnej bez zachowania woluminów, konfiguracji i ścieżki przywracania.

Podsumowanie

Opóźnienie w edycji wspólnej w ONLYOFFICE najłatwiej naprawić, traktując je jako mierzalny problem systemowy. Odtwórz opóźnienie, obserwuj zasoby Dockera i hosta pod obciążeniem, zweryfikuj pamięć masową, upewnij się, że przeglądarka utrzymuje prawidłowe działanie protokołu WebSocket na każdym serwerze proxy i przejrzyj logi tylko dla okresu, w którym wystąpiło opóźnienie. Gdy już wiesz, czy wąskim gardłem są zasoby obliczeniowe, pamięć, dysk, działanie sieci/serwera proxy, czy konkretna zmiana wersji/konfiguracji, poprawka staje się celowa, a nie spekulatywna.

Aktualne szczegóły wdrożenia można znaleźć w dokumentacji instalacji Dockera ONLYOFFICE , oficjalnych przykładach odwrotnego proxy , przewodniku rejestrowania debugowania i oficjalnym dzienniku zmian Docs .