OnlyOffice Docs

OnlyOffice Docs to serwerowy komponent tego pakietu, umożliwiający współedycję dokumentów w przeglądarce.

Architektura OnlyOffice Docs i jego rola w pracy przeglądarkowej

OnlyOffice Docs jest serwerowym komponentem pakietu OnlyOffice, który udostępnia edytory dokumentów, arkuszy kalkulacyjnych, prezentacji i formularzy w interfejsie otwieranym z poziomu przeglądarki internetowej. Nie jest to pojedynczy program instalowany wyłącznie na laptopie użytkownika. Instalacja działa jako usługa dostępna przez sieć, a przeglądarka przekazuje do niej operacje wykonywane podczas otwierania i edycji pliku. Dokument pozostaje powiązany z systemem przechowywania, z którym OnlyOffice Docs współpracuje za pośrednictwem integracji dostarczonej przez aplikację nadrzędną.

W typowym wdrożeniu OnlyOffice Docs nie pełni samodzielnie funkcji kompletnego dysku sieciowego ani systemu zarządzania kontami. Aplikacja integrująca, na przykład platforma do współdzielenia plików, odpowiada za logowanie użytkownika, listę dokumentów, uprawnienia oraz wskazanie pliku do otwarcia. Serwer dokumentów uruchamia odpowiedni edytor i obsługuje operacje na treści. Komunikacja między przeglądarką, aplikacją integrującą i OnlyOffice Docs musi być poprawnie skonfigurowana, ponieważ błędny adres usługi, niedostępny port albo niezgodny mechanizm uwierzytelniania może uniemożliwić otwarcie dokumentu.

Formaty plików, edycja i współpraca wielu osób

OnlyOffice Docs jest przeznaczony przede wszystkim do pracy z dokumentami biurowymi, arkuszami i prezentacjami. W praktyce często obsługuje pliki DOCX, XLSX i PPTX, a także formaty OpenDocument, takie jak ODT, ODS i ODP. Zakres dostępnych operacji zależy od rodzaju pliku oraz wersji użytego komponentu. Przy diagnostyce nie należy zakładać, że każdy element dokumentu będzie interpretowany identycznie jak w programie, w którym został pierwotnie utworzony. Dotyczy to między innymi złożonych stylów, makr, nietypowych czcionek, obiektów osadzonych, zaawansowanych formuł i elementów prezentacji.

Współedycja polega na utrzymywaniu aktualnego stanu dokumentu po stronie usługi i przekazywaniu zmian do uczestników sesji. OnlyOffice Docs oferuje tryb szybkiej współpracy, w którym zmiany mogą być widoczne podczas pracy innych osób, oraz tryb ścisły, w którym część zmian jest ujawniana po zapisaniu lub zatwierdzeniu określonego etapu pracy. Dostępne są również komentarze, śledzenie zmian, historia wersji zależna od systemu integrującego oraz mechanizmy blokowania lub rozstrzygania konfliktów. Jeżeli kilku użytkowników widzi różne wersje treści, trzeba sprawdzić nie tylko przeglądarkę, lecz także połączenie między usługą dokumentów a magazynem plików.

Integracja przez Docs API, tokeny i adres zwrotny

Uruchomienie edytora odbywa się zwykle przez konfigurację obiektu JavaScript przekazywanego do biblioteki OnlyOffice Docs API. Konfiguracja określa między innymi adres pliku, jego identyfikator, typ dokumentu, tryb edycji, uprawnienia oraz adres callbacku. Parametr identyfikujący dokument, często nazywany document.key, służy do rozpoznawania konkretnej wersji pliku w sesji edycyjnej. Powinien zmieniać się wtedy, gdy aplikacja integrująca udostępnia nową wersję dokumentu; ponowne użycie nieaktualnego klucza może prowadzić do otwarcia starego stanu albo błędu cache.

Callback jest adresem, pod który OnlyOffice Docs przekazuje informacje o stanie edycji i zapisaniu dokumentu. Aplikacja integrująca musi obsłużyć te żądania oraz pobrać albo zapisać wskazany plik zgodnie ze swoim modelem przechowywania. Samo wyświetlenie edytora w przeglądarce nie potwierdza więc, że zapis działa prawidłowo. Należy oddzielnie zweryfikować możliwość odczytu pliku, poprawność callbacku, uprawnienia zapisu, obsługę odpowiedzi HTTP oraz dostępność adresu zarówno dla klienta, jak i dla serwera dokumentów.

OnlyOffice Docs może korzystać z podpisywania żądań za pomocą tokenów JWT. W takim układzie aplikacja integrująca i serwer dokumentów muszą używać zgodnego sekretu oraz tych samych zasad generowania i weryfikowania tokenu. Błąd podpisu, nieprawidłowy czas ważności, brak tokenu w oczekiwanym miejscu albo różnica między konfiguracją pliku a konfiguracją żądania może skutkować komunikatem o nieautoryzowanym dostępie. Przy analizie połączenia warto sprawdzić kod odpowiedzi HTTP, logi usługi dokumentów, logi aplikacji nadrzędnej i konsolę przeglądarki, zamiast ograniczać się do ponownego ładowania strony.

Diagnostyka instalacji OnlyOffice Docs na komputerze i w sieci lokalnej

Podstawowa diagnostyka powinna rozpocząć się od sprawdzenia, czy adres OnlyOffice Docs odpowiada po HTTPS lub HTTP zgodnie z konfiguracją i czy certyfikat jest akceptowany przez przeglądarkę. Następnie należy ustalić, czy aplikacja integrująca może pobrać plik z podanego adresu oraz czy serwer dokumentów może wysłać żądanie callback do aplikacji. Te dwa kierunki połączenia bywają mylone: użytkownik może poprawnie otworzyć stronę, a zapis nadal nie zadziała, gdy serwer dokumentów nie ma dostępu do adresu zwrotnego.

Na laptopie lub komputerze PC warto sprawdzić wersję przeglądarki, blokowanie plików cookie, rozszerzenia filtrujące skrypty, komunikaty w narzędziach deweloperskich oraz błędy połączeń WebSocket, jeżeli są używane przez wdrożenie do komunikacji w czasie rzeczywistym. Problemy mogą powodować także różnice czasu między hostami, niepełny łańcuch certyfikatów TLS, filtr ruchu na zaporze oraz zmiana adresu DNS. W przypadku nieudanego zapisu należy zachować identyfikator dokumentu, czas wystąpienia błędu i odpowiedź callbacku, ponieważ te dane pozwalają powiązać objaw w przeglądarce z konkretnym wpisem w logach usługi.

Jeżeli edytor otwiera plik, ale po ponownym wejściu znikają zmiany, trzeba rozdzielić problem konwersji, sesji i trwałego zapisu. Pomocne jest otwarcie prostego dokumentu testowego, wykonanie jednej zmiany, zamknięcie sesji i sprawdzenie pliku bezpośrednio w magazynie. Osobno należy przetestować dokument DOCX, arkusz XLSX i prezentację PPTX, ponieważ błąd może dotyczyć tylko określonego formatu lub elementu dokumentu. Przy serwisowaniu komputera trzeba również wykluczyć lokalne przyczyny, takie jak uszkodzony profil przeglądarki, nieprawidłowy zegar systemowy, problem z DNS albo ograniczenie zapory sieciowej.