Śledź błędy połączenia Collabora za pomocą dzienników coolwsd

W przypadku kontenera Collabora Online Development Edition (CODE) należy podnieść coolwsdpoziom rejestrowania do debug, upewnić się, że obszary Socketi WebSocketnie są wyłączone, a następnie odtworzyć jeden nieudany dokument, otwierając go zgodnie z logami kontenera. W Docker Compose należy przekazać ustawienia przez zmienną środowiskową obrazu CODE extra_paramsi ponownie utworzyć usługę. Należy używać tej opcji tracetylko wtedy, gdy dane wyjściowe debugowania nie wskazują miejsca, w którym połączenie się kończy, a po zakończeniu wrócić do poprzedniego poziomu.

Ta metoda sprawdza się we wdrożeniu Docker lub Compose, gdzie można aktualizować konfigurację kontenera. Instalacja pakietu natywnego korzysta /etc/coolwsd/coolwsd.xmlz menedżera usług. To ustawienie dodaje szczegółowe informacje diagnostyczne; samo w sobie nie naprawia problemu z serwerem proxy, hostem WOPI, certyfikatem ani siecią.

1. Zacznij od jednej kontrolowanej reprodukcji

Wybierz jeden dokument i zanotuj czas próby jego otwarcia, publiczny adres URL Collabora oraz nazwę kontenera lub usługi Compose. Unikaj wielokrotnego odświeżania kilku plików: jedna próba ułatwia sprawdzenie symptomu przeglądarki, logu proxy, logu serwera integracyjnego i wpisów coolwsd.

Sprawdź, czy kontener jest uruchomiony i zidentyfikuj jego nazwę:

docker ps --format 'table {.Names}	{.Status}	{.Ports}'

Zastąp collaboraponiższą nazwę kontenera widoczną na Twoim hoście. Zacznij wyświetlać poniższe dane na krótko przed odtworzeniem problemu:

docker logs --since 2m --follow --timestamps collabora

--followPrzesyła nowe dane wyjściowe, --sinceogranicza początkową historię i --timestampsdodaje znaczniki czasu Dockera. Docker dokumentuje te opcje w swoich logach kontenerów . W Compose możesz użyć docker compose logs --since=2m --follow collabora, gdzie collaborajest kluczem usługi.

2. Uruchom coolwsd w celu debugowania w celu przeprowadzenia testu

Schemat konfiguracji Collabora obsługuje nazwane poziomy, takie jak warning, notice, information, debugi trace. Definiuje również disabled_areas; udokumentowana wartość domyślna wyłącza między innymi dane wyjściowe o dużej szczegółowości z Socketi . Ma to znaczenie przy rozwiązywaniu problemów z połączeniem: sama zmiana poziomu może nadal powodować pomijanie najbardziej przydatnych szczegółów uzgadniania. Opcje te są udokumentowane w szablonie konfiguracji Collabora coolwsd oraz podręczniku Collabora Online SDK (sekcja konfiguracji Dockera; sprawdzono w październiku 2026 r.).WebSocket

Aby uzyskać oficjalny collabora/codeobraz, dodaj te dwie opcje do istniejącej wartości usługi extra_params. Zachowaj wszystkie opcje wymagane przez instalację, takie jak zakończenie SSL lub nazwa serwera:

services:
  collabora:
    environment:
      extra_params: "--o:logging.level=debug --o:logging.disabled_areas=Admin,Pixel"

Druga opcja pozostawia Socketi WebSocketudostępnia logowanie o wysokiej szczegółowości, zachowując jednocześnie Admini Pixelwyłączone. Nie dodawaj tych dwóch obszarów z powrotem do listy wyłączonych podczas tego testu. Dokumentacja obrazu CODE opisuje extra_paramssposób przekazywania opcji wiersza poleceń do coolwsd. Jeśli wdrożenie korzysta z zamontowanego pliku konfiguracyjnego lub obrazu zarządzanego przez dostawcę, należy zastosować metodę konfiguracji tego wdrożenia.

Zastosuj edycję „Utwórz”, ponownie tworząc usługę:

docker compose up -d --force-recreate collabora

Użyj rzeczywistej nazwy usługi Compose. W przypadku kontenera o krótkim czasie istnienia uruchomionego za pomocą docker run, zaktualizuj jego konfigurację uruchomieniową i utwórz go ponownie z tymi samymi woluminami, sieciami, portami i innymi opcjami. W podręczniku CODE napisano, że obraz akceptuje się extra_paramspodczas uruchamiania; nie zakładaj, że zmiana środowiska już utworzonego kontenera zmienia uruchomiony proces coolwsd.

3. Przeczytaj połączenie w kolejności

Odtwórz awarię raz i przejrzyj tylko ten interwał. Wyszukaj w wynikach takie terminy jak WebSocket, WOPI, ERRi WRN, a następnie porównaj znaczniki czasu. Dokładne sformułowania i obszary dziennika różnią się w zależności od wersji Collabora, dlatego traktuj je jako kategorie do sprawdzenia, a nie jako gwarantowane komunikaty dosłowne.

• Brak nowych wpisów coolwsd w czasie testu: żądanie może nie docierać do tego kontenera. Sprawdź skonfigurowany publiczny adres URL, DNS, moduł równoważenia obciążenia, dzienniki dostępu/błędów odwrotnego serwera proxy oraz czy śledzisz prawidłową replikę.
• Przeglądarka łączy się z usługą, ale WebSocket nie pozostaje otwarty: sprawdź obsługę aktualizacji WebSocket przez serwer proxy, przekierowanego hosta i schematu, zakończenie TLS, routing ścieżki i przekroczenia limitu czasu bezczynności. Porównaj z konsolą programisty przeglądarki i dziennikami proxy; coolwsd nie potrafi wyjaśnić żądania, którego serwer proxy nigdy nie przekazuje.
• Żądanie WOPI pojawia się i kończy się niepowodzeniem: sprawdź adres URL WOPI serwera integracyjnego, listę dozwolonych hostów lub konfigurację aliasu, dostępność z kontenera Collabora oraz odpowiedź serwera integracyjnego. Błąd WOPI to oddzielny etap od połączenia przeglądarki z Collabora WebSocket.
• WOPI działa, ale przeglądarka nadal się rozłącza: skup się teraz na ścieżce WebSocket i błędach połączenia po stronie przeglądarki. Ta sekwencja zawęża zakres wyszukiwania; nie dowodzi, które ustawienia proxy lub sieci są nieprawidłowe.

Jeśli Docker nie wyświetla żadnych danych wyjściowych, mimo że usługa jest aktywna, sprawdź konfigurację rejestrowania w kontenerze. Polecenie log Dockera odczytuje standardowe wyjście kontenera i strumienie błędów; instalacja skonfigurowana do zapisu do pliku może zamiast tego używać ścieżki, takiej jak /var/log/coolwsd.log, zdefiniowanej w jej konfiguracji. Sprawdź rzeczywisty plik, zamiast zakładać, że ścieżka jest taka sama:

docker exec collabora sh -c 'grep -n -A25 "<logging>" /etc/coolwsd/coolwsd.xml'

Jeżeli rejestrowanie plików jest włączone, użyj skonfigurowanej ścieżki, na przykład:

docker exec collabora sh -c 'tail -n 200 /var/log/coolwsd.log'

4. Sprawdź wynik i przywróć normalne rejestrowanie

Po przeprowadzeniu testu należy wykonać odczyt ograniczony, aby potwierdzić, że zamierzona próba wygenerowała nowe wpisy:

docker logs --since 5m --timestamps collabora

Uzyskujesz użyteczny wynik, gdy możesz powiązać nieudane otwarcie ze zdarzeniem coolwsd lub ustalić, że żądanie nigdy nie dotarło do tego kontenera, a następnie zidentyfikować etap połączenia wymagający dalszych działań. Jeśli musisz filtrować dane wyjściowe, użyj najpierw krótkiego okna czasowego:

docker logs --since 5m collabora | grep -Ei 'coolwsd|WOPI|WebSocket|ERR|WRN'

Przywróć poprzednie wartości logging.leveli disabled_areas, a następnie utwórz usługę ponownie. Poziomy debugowania i śledzenia mogą generować znacznie więcej danych wyjściowych i mogą obejmować poufne szczegóły operacyjne. Przed udostępnieniem logów usuń tokeny dostępu, nazwy dokumentów, identyfikatory użytkowników, nazwy hostów i adresy wewnętrzne. Jeśli usługa nie jest oficjalnym obrazem CODE, potwierdź ścieżkę konfiguracji i obsługiwane parametry z opiekunem tego obrazu.