Rozwiąż błąd „Token jest nieprawidłowy” w aplikacji ONLYOFFICE w NextCloud

Jeśli Nextcloud zgłasza komunikat „Token jest nieprawidłowy” podczas łączenia się z ONLYOFFICE Docs, upewnij się, że klucz tajny JWT łącznika jest zgodny z kluczem tajnym używanym przez Document Server. W ONLYOFFICE Docs 7.2 i nowszych walidacja JWT jest domyślnie włączona, a klucz tajny jest generowany automatycznie. Zmiana samego ustawienia Nextcloud lub edycja wygenerowanego pliku konfiguracyjnego kontenera Docker może spowodować utratę synchronizacji między obiema stronami.

Pozostaw JWT włączone. Najpierw zidentyfikuj aktywny klucz tajny i typ wdrożenia, zaktualizuj poprawną konfigurację, a następnie uruchom sprawdzanie połączenia łącznika. Sprawdzenie powinno zgłosić pomyślne połączenie; samo otwarcie edytora w przeglądarce nie dowodzi, że pobieranie dokumentów i wywołania zwrotne działają.

Co mówi błąd?

JWT (JSON Web Token) to podpisany token służący do weryfikacji zaufania żądania między Nextcloud a ONLYOFFICE Docs. Łącznik podpisuje żądania za pomocą skonfigurowanego klucza tajnego, natomiast Serwer Dokumentów weryfikuje je za pomocą skonfigurowanego klucza tajnego. Jeśli klucze tajne podpisu się różnią, podpis tokena nie może zostać zweryfikowany, a żądanie zostaje odrzucone.

Najczęstszymi przyczynami są: sekret skopiowany ze starej instalacji, automatycznie wygenerowany sekret, który nigdy nie został wprowadzony w NextCloud, zmieniona zmienna środowiskowa Dockera, która nie została zastosowana poprzez ponowne utworzenie kontenera, lub niespójne wartości sekretu w konfiguracji serwera dokumentów. Niestandardowy nagłówek JWT może również powodować niezgodność, jeśli łącznik i serwer dokumentów nie używają tej samej nazwy nagłówka.

W tym artykule omówiono niezgodność tokena JWT. Jeśli błąd wskazuje na brak dostępu do serwera, nieprawidłowy certyfikat lub brak możliwości pobrania dokumentu, należy osobno sprawdzić adresy serwerów, certyfikat TLS oraz ścieżkę sieciową Nextcloud-to-Document-Server. Korekta tokena JWT nie rozwiąże tych problemów.

1. Znajdź aktywny tajny klucz serwera dokumentów

Użyj konfiguracji należącej do działającego Serwera Dokumentów. Nie zakładaj, że klucz tajny zapamiętany z poprzedniego kontenera lub serwera jest nadal aktywny.

• Linux: sprawdź /etc/onlyoffice/documentserver/local.json.
• Windows: sprawdź %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json.
• Docker: odczytaj sekret z działającego kontenera. Oficjalny obraz obsługuje również odczyt sekretu sesji za pomocą tego polecenia:

sudo docker exec <containerID> /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'

Zastąp <containerID>rzeczywistą nazwą lub identyfikatorem kontenera. Traktuj zwróconą wartość jako dane uwierzytelniające: nie wklejaj jej na forach pomocy technicznej, zrzutach ekranu ani w dziennikach publicznych.

W local.json, porównaj wartości w services.CoAuthoring.secret.inbox.string, services.CoAuthoring.secret.outbox.stringi services.CoAuthoring.secret.session.string. Wszystkie powinny być identyczne dla tej standardowej konfiguracji. Sprawdź również, czy walidacja tokenów jest włączona dla przeglądarki, skrzynki odbiorczej i skrzynki nadawczej. Wersje dokumentów wcześniejsze niż 7.2 wymagają jawnego włączenia walidacji tokenów; późniejsze wersje włączają ją domyślnie.

2. Zaktualizuj łącznik ONLYOFFICE w Nextcloud

1. Zaloguj się jako administrator Nextcloud i otwórz Ustawienia > Administracja > ONLYOFFICE .
2. W ustawieniach serwera w polu „Klucz tajny” wpisz dokładny klucz tajny znaleziony na działającym serwerze dokumentów . Unikaj spacji na początku i na końcu oraz nie dodawaj cudzysłowów, chyba że są częścią samego klucza tajnego.
3. Sprawdź ustawienia nagłówka JWT, jeśli Twoje wdrożenie używa niestandardowego nagłówka. Ustawienia łącznika jwt_headeri skonfigurowany nagłówek tokena serwera dokumentów muszą być zgodne. Jeśli nagłówek nie został celowo dostosowany, nie zmieniaj go w ramach tej naprawy.
4. Zapisz ustawienia. Pozostaw JWT włączone po obu stronach.

Udokumentowane ustawienia łącznika można również zmienić za pomocą occpolecenia Nextcloud z katalogu instalacyjnego Nextcloud:

sudo -u www-data php occ config:app:set onlyoffice jwt_secret --value='YOUR_SECRET'

Zastąp YOUR_SECRETrzeczywistą wartością. Użycie cudzysłowu w powłoce pomaga zachować interpunkcję, ale sekrety zawierające pojedynczy cudzysłów wymagają bezpieczniejszej metody niż wstawianie ich bezpośrednio do wiersza poleceń. Argumenty wiersza poleceń mogą być również widoczne dla uprzywilejowanej inspekcji procesów lub historii powłoki. Jeśli to możliwe, preferuj interfejs administratora, a następnie zweryfikuj zapisaną wartość bez jej ujawniania.

3. Zastosuj zmiany we właściwy sposób dla swojej instalacji

Docker lub Docker Compose

W przypadku wdrożeń Dockera skonfiguruj JWT za pośrednictwem środowiska kontenerowego, zamiast ręcznie edytować automatycznie wygenerowany plik local.json. Ustaw ten sam klucz tajny w definicji usługi serwera dokumentów:

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=YOUR_SECRET

Po zmianie pliku Compose utwórz ponownie kontener Serwera Dokumentów, aby środowisko zaczęło działać. Na przykład z katalogu zawierającego plik Compose:

docker compose up -d --force-recreate <documentserver-service>

Zastąp nazwę usługi z własnego pliku Compose. Zwykły restart nie zastosuje zmienionej wartości środowiskowej do istniejącego kontenera. Jeśli używasz docker run, utwórz kontener ponownie ze zaktualizowanymi wartościami JWT_ENABLEDi JWT_SECRET, zachowując istniejące porty, woluminy i inne wymagane opcje. Nie usuwaj kontenera produkcyjnego, dopóki nie potwierdzisz tych ustawień i trwałych montowań danych.

Po uruchomieniu kontenera ponownie odczytaj jego aktywny klucz tajny za pomocą powyższego polecenia i upewnij się, że wartość nadal odpowiada wartości NextCloud. Unikaj umieszczania klucza tajnego produkcyjnego w publicznie współdzielonym pliku Compose lub repozytorium źródłowym.

Pakiet Linux lub instalacja Windows

Jeśli celowo ustawisz niestandardowy klucz tajny w local.json, upewnij się, że trzy pola klucza tajnego są zgodne i że wymagane wartości walidacji tokenu są włączone. Zastosuj zmianę, uruchamiając ponownie odpowiednie usługi serwera dokumentów. Aktualna lista instrukcji ONLYOFFICE zawiera ds-converter, ds-docservice, oraz ds-metricsw systemie Linux; instalacje zarządzane przez innego nadzorcę usług mogą wymagać metody ponownego uruchomienia odpowiedniej dla danej konfiguracji. W systemie Windows uruchom ponownie usługi ONLYOFFICE po zapisaniu konfiguracji.

Niezgodność, która pojawia się po ponownym uruchomieniu, zazwyczaj oznacza, że ​​wygenerowana konfiguracja lub środowisko wdrożenia nadpisuje edytowany plik. W przypadku Dockera należy przenieść poprawkę do zmiennych środowiskowych i ponownie utworzyć kontener. W przypadku wdrożeń pakietowych, przed zmianą dalszych ustawień należy sprawdzić aktywną konfigurację i konfigurację startową usługi.

Sprawdź naprawę

1. W katalogu instalacyjnym Nextcloud uruchom oficjalne sprawdzenie łącznika:

sudo -u www-data php occ onlyoffice:documentserver --check

Jeśli nie, użyj konta serwera WWW odpowiedniego dla Twojej instalacji www-data. Polecenie powinno zgłosić pomyślne połączenie. Jeśli nadal zgłasza nieprawidłowy token, ponownie sprawdź, czy aktywny klucz tajny działającego serwera dokumentów jest dokładnie taki sam jak w Nextcloud i czy wszystkie niestandardowe nagłówki JWT są zgodne.

2. Otwórz mały dokument testowy z NextCloud za pomocą ONLYOFFICE. Sprawdź, czy edytor się załadował, wprowadź drobną zmianę, zapisz ją, zamknij edytor i ponownie otwórz plik, aby sprawdzić, czy zmiana została zachowana.
3. Jeśli teraz sprawdzanie zgłosi błąd sieci lub certyfikatu, zaprzestań zmiany wartości JWT. Sprawdź, czy Nextcloud może dotrzeć do adresu serwera dokumentów i czy serwer dokumentów może dotrzeć do adresu wywołania zwrotnego Nextcloud. W miarę możliwości używaj zaufanego certyfikatu TLS; wyłączenie weryfikacji certyfikatu to niebezpieczne obejście i nie naprawia walidacji tokena.

Te kontrole sprawdzają, czy skonfigurowane połączenie i podstawowa ścieżka zapisu działają. Nie dowodzą one poprawności każdej trasy odwrotnego serwera proxy, konfiguracji zewnętrznej pamięci masowej ani topologii wieloserwerowej; jeśli Twoje wdrożenie z nich korzysta, przetestuj te ścieżki osobno.

Oficjalne źródła

• ONLYOFFICE: integracja Nextcloud i konfiguracja JWT
• ONLYOFFICE: Konfigurowanie JWT dla serwera dokumentów
• Łącznik ONLYOFFICE Nextcloud: opcje konfiguracji i polecenia occ

Szczegóły konfiguracji zostały sprawdzone pod kątem zgodności z oficjalną dokumentacją ONLYOFFICE i repozytorium łączników dnia 9 października 2026 r. Etykiety interfejsu użytkownika i zarządzanie usługami mogą się różnić w zależności od łącznika, systemu operacyjnego i metody wdrożenia.