Jak naprawić błąd 502 w serwerze dokumentów ONLYOFFICE za Nginx

Przeglądarka wyświetla błąd „502 Bad Gateway” podczas otwierania adresu URL ONLYOFFICE Docs lub łącznik Nextcloud/ownCloud nie może nawiązać połączenia z serwerem dokumentów. W obu przypadkach Nginx zazwyczaj odbiera żądanie, ale nie może uzyskać prawidłowej odpowiedzi od swojego serwera nadrzędnego. Serwerem nadrzędnym może być wewnętrzna usługa dokumentów ONLYOFFICE, kontener Docker lub inny odwrotny serwer proxy. Najpierw zidentyfikuj, który serwer Nginx zwrócił błąd 502, a następnie przetestuj bezpośrednio kolejny przeskok przed zmianą konfiguracji.

Aktualny poradnik rozwiązywania problemów z Linuksem ONLYOFFICE zaleca sprawdzenie logów usług ds-docservicei ds-converteroraz serwera dokumentów. W poradniku dotyczącym odwrotnego proxy znajdują się również przekierowane nagłówki hosta i protokołu. Poniższa sekwencja sprawdza najpierw stan usług, a następnie routing Nginx i sieć Docker.

1. Dowiedz się, który Nginx zwraca błąd 502

Instalacja pakietu ONLYOFFICE obejmuje własną konfigurację Nginx, a wdrożenie może również obejmować zewnętrzny odwrotny serwer proxy Nginx. Docker może dodać kolejny przeskok sieciowy. Sam wygląd strony 502 może nie identyfikować warstwy, dlatego należy porównać publiczny adres URL z lokalnym sprawdzeniem kondycji i dziennikiem błędów Nginx.

W przypadku instalacji systemu Linux opartej na pakiecie przetestuj lokalny punkt końcowy serwera dokumentów:

curl -i http://127.0.0.1/healthcheck

Jeśli serwer jest skonfigurowany do obsługi TYLKO-BIURA na innym niż domyślny porcie lokalnym, użyj tego portu. Prawidłowa instalacja zazwyczaj zwraca odpowiedź HTTP o pomyślnym wykonaniu z true. Jeśli to lokalne żądanie się nie powiedzie, napraw usługę serwera dokumentów przed edycją zewnętrznego serwera proxy. Jeśli żądanie lokalnie się powiedzie, ale publiczna nazwa hosta zwraca 502, skoncentruj się na zewnętrznym serwerze nadrzędnym Nginx, protokole, nagłówkach i ścieżce zapory sieciowej.

Sprawdź, które procesy są właścicielami oczekiwanych portów:

sudo ss -ltnp | grep -E ':(80|443|8080|8000)\b'

Porty różnią się w zależności od topologii. Typowe mapowanie Dockera publikuje port hosta, taki jak 8080, na port kontenera 80; instalacja pakietu może korzystać z własnego serwera Nginx na hoście. Nie należy zakładać, że 127.0.0.1:80jest to właściwy port nadrzędny tylko dlatego, że obie usługi znajdują się na jednej maszynie.

2. Sprawdź usługi i logi ONLYOFFICE

W przypadku instalacji pakietu Linux sprawdź usługę dokumentów i konwerter:

sudo systemctl status ds-docservice ds-converter
sudo journalctl -u ds-docservice -u ds-converter --since "15 minutes ago" --no-pager

Przewodnik rozwiązywania problemów ONLYOFFICE wymienia te usługi i wskazuje na niewystarczającą ilość pamięci, konflikt portu 80 oraz dzienniki usług jako elementy, które należy sprawdzić w przypadku problemów z uruchomieniem usług Dokumentów. Jeśli usługa jest zatrzymana, najpierw sprawdź jej błąd, a następnie uruchom ponownie tylko tę usługę, której dotyczy problem:

sudo systemctl restart ds-docservice

Główny katalog dziennika systemu Linux to /var/log/onlyoffice/documentserver/. Sprawdź dziennik błędów Nginx i dzienniki docservice pod kątem komunikatów takich jak „odmowa połączenia”, „przekroczenie limitu czasu upstream” lub brak pliku. Wskazują one na różne przyczyny: odrzucone połączenie zazwyczaj oznacza, że ​​proces upstream lub port jest niedostępny, a przekroczenie limitu czasu może oznaczać przeciążenie lub zatrzymanie usługi.

Sprawdź także dostępny dysk i pamięć, jeśli usługi ciągle się zamykają:

df -h
free -h

Nie uruchamiaj ponownie usługi, która uległa awarii, bez przejrzenia jej dzienników. Ponowne uruchomienie może na krótko ukryć objaw, a Ty nie rozwiążesz problemu związanego z konfliktem portów, niedziałającą zależnością lub zasobami.

3. Sprawdź, czy Nginx wskazuje na dostępny upstream

Odczytaj aktywny wirtualny host i potwierdź dokładny adres i port w pliku proxy_pass. Z komputera lub kontenera, na którym działa Nginx, zażądaj bezpośrednio upstreamu. Na przykład, jeśli kontener publikuje port 80 jako port hosta 8080:

curl -i http://127.0.0.1:8080/healthcheck

Zastąp przykładowy adres punktem końcowym, do którego faktycznie można dotrzeć z serwera proxy. Jeśli Nginx działa w oddzielnym kontenerze Docker, 127.0.0.1należy odwołać się do tego kontenera Nginx, a nie do hosta Docker ani kontenera ONLYOFFICE. Użyj nazwy usługi dostępnej w sieci współdzielonej Docker lub prawidłowego adresu hosta i opublikowanego portu.

Sprawdź, czy schemat nadrzędny jest zgodny z backendem. Użyj tej opcji, http://jeśli nasłuchiwacz backendu obsługuje zwykły protokół HTTP i https://tylko wtedy, gdy jest skonfigurowany do obsługi protokołu TLS. Wysyłanie protokołu HTTP na port TLS lub protokołu TLS na zwykły port HTTP może sprawić, że sprawna usługa będzie niedostępna dla Nginx.

4. Sprawdź przekazane nagłówki i proxy WebSocket

Przewodnik po odwrotnym serwerze proxy w ONLYOFFICE zaleca zachowanie oryginalnego protokołu i nazwy hosta X-Forwarded-Proto, aby X-Forwarded-Hostaplikacja znała oryginalny protokół i nazwę hosta. Oficjalne przykłady Nginx również przekazują nagłówki aktualizacji. Jeśli przed ONLYOFFICE znajduje się zewnętrzny serwer proxy, porównaj jego konfigurację z oficjalnym scenariuszem odpowiadającym Twojej topologii.

Poniżej przedstawiono uproszczony przykład kontenera Dockera zmapowanego na port hosta 8080. Umieść dyrektywę mapw kontekście Nginx httpi dostosuj nazwę hosta, konfigurację TLS i port nadrzędny do swojej konfiguracji:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl;
    server_name docs.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

To wzorzec referencyjny, a nie zamiennik dla każdej instalacji. W szczególności nie należy go wklejać w konfiguracji Nginx pakietu ONLYOFFICE bez zrozumienia, który blok serwera jest właścicielem portów 80 i 443. Jeśli Nginx współdzieli hosta z ONLYOFFICE zainstalowanym w pakiecie, najpierw upewnij się, że nie ma kolizji portów i skieruj zewnętrzny serwer proxy do wewnętrznego odbiornika skonfigurowanego dla wdrożenia.

Po edycji przetestuj konfigurację przed ponownym załadowaniem Nginx:

sudo nginx -t
sudo systemctl reload nginx

Jeśli test konfiguracji się nie powiedzie, popraw zgłoszony plik i wiersz przed ponownym załadowaniem. Błąd składni i błąd 502 w systemie nadrzędnym to oddzielne problemy; pomyślne nginx -tpotwierdzenie składni, a nie odpowiedź systemu nadrzędnego.

5. Jeśli ONLYOFFICE działa w Dockerze, sprawdź jego stan i mapowanie portów

Sprawdź, czy kontener jest uruchomiony i który port hosta jest opublikowany:

docker ps --filter name=onlyoffice
docker port <container_name_or_id>
docker logs --tail 100 <container_name_or_id>

Oficjalny przewodnik instalacji Dockera mapuje porty hosta na port kontenera 80, a przykład sprawdza logi kontenera, jeśli strona powitalna się nie ładuje. Użyj portu wskazanego przez docker portjako portu nadrzędnego po stronie hosta. Gdy zarówno Nginx, jak i ONLYOFFICE są kontenerami, umieść je w sieci współdzielonej i kieruj ruch do nazwy usługi ONLYOFFICE i portu kontenera, a nie do adresu pętli zwrotnej hosta.

Sprawdź stan kontenera, jeśli plik Compose definiuje kontrolę stanu. Aktualny przykład Compose sprawdza stan http://localhost:8000/info/info.jsonwewnątrz kontenera. Kontener, który jest „uruchomiony”, może nadal mieć nieprawidłową usługę dokumentów. Jeśli kontener się restartuje lub jest w stanie nieprawidłowego działania, użyj logów, aby zbadać uruchamianie bazy danych, pamięć i konfigurację przed zmianą zewnętrznego serwera proxy.

ONLYOFFICE dokumentuje trwałe ścieżki Dockera dla logów, certyfikatów i pamięci podręcznej plików. Unikaj usuwania woluminów podczas rozwiązywania problemów; mogą one zawierać certyfikaty lub inne dane potrzebne do przywrócenia usługi.

6. Załaduj ponownie, przetestuj punkt końcowy stanu zdrowia i ponownie przetestuj integrację

Po rozwiązaniu potwierdzonego problemu przetestuj publiczną nazwę hosta i porównaj ją z lokalnym punktem końcowym:

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

Użyj prawdziwego adresu URL serwera dokumentów. Pomyślna odpowiedź zarówno na lokalnym serwerze nadrzędnym, jak i na publicznej nazwie hosta oznacza, że ​​Nginx może połączyć się z zapleczem i zwrócić odpowiedź o stanie. Następnie otwórz stronę powitalną serwera dokumentów i spróbuj ponownie wykonać akcję, która pierwotnie nie powiodła się w NextCloud, ownCloud lub innym łączniku.

Jeśli kontrola stanu zakończy się powodzeniem, ale łącznik nadal zgłasza błąd, problem może leżeć poza ścieżką Nginx 502 — na przykład w adresie URL łącznika, zaufanym TLS lub ustawieniach JWT. Porównaj te wartości z konfiguracją łącznika i ONLYOFFICE, zamiast bezmyślnie zmieniać limity czasu serwera proxy.

Szybka diagnoza

Oficjalne referencje

• Rozwiązywanie problemów z dokumentami ONLYOFFICE dla systemu Linux
• ONLYOFFICE Dokumenty za pośrednictwem serwera proxy
• Oficjalny przykład serwera proxy HTTPS-HTTP dla Nginx ONLYOFFICE
• ONLYOFFICE Docs Instalacja Dockera i mapowanie portów
• Przykład tworzenia serwera dokumentów ONLYOFFICE