Cum să remediați problema ONLYOFFICE Document Server 502 Gateway defect în spatele Nginx

Un browser afișează eroarea „502 Bad Gateway” la deschiderea unei adrese URL ONLYOFFICE Docs sau un conector Nextcloud/ownCloud nu poate ajunge la serverul de documente. În ambele cazuri, Nginx primește de obicei o solicitare, dar nu poate obține un răspuns valid de la serverul său upstream. Serverul upstream poate fi serviciul intern de documente ONLYOFFICE, un container Docker sau un alt proxy invers. Mai întâi identificați care Nginx a returnat eroarea 502; apoi testați direct următorul hop înainte de a modifica configurația.

Ghidul actual de depanare Linux al ONLYOFFICE recomandă verificarea serviciilor ds-docserviceși ds-convertera jurnalelor Document Server. Ghidul său de proxy invers solicită, de asemenea, anteturile de gazdă și protocol redirecționate. Secvența de mai jos verifică mai întâi starea serviciilor, apoi rutarea Nginx și rețeaua Docker.

1. Află care Nginx returnează eroarea 502

Instalarea pachetului ONLYOFFICE include propria configurație Nginx, iar o implementare poate avea și un proxy invers Nginx extern. Docker poate adăuga un alt hop de rețea. Aspectul paginii 502 în sine poate să nu identifice stratul, așa că comparați adresa URL publică cu o verificare locală a stării de funcționare și cu jurnalul de erori Nginx.

Pe o instalare Linux bazată pe pachete, testați endpoint-ul local al serverului de documente:

curl -i http://127.0.0.1/healthcheck

Dacă serverul este configurat să deservească ONLYOFFICE pe un port local diferit de cel implicit, utilizați acel port în schimb. O instalare sănătoasă returnează în mod normal un răspuns HTTP de succes cu true. Dacă această solicitare locală eșuează, remediați serviciul Document Server înainte de a edita un proxy extern. Dacă reușește local, dar numele de gazdă public returnează 502, concentrați-vă pe protocolul Nginx extern în amonte, protocol, anteturi și calea firewall.

Verificați ce procese dețin porturile așteptate:

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

Porturile variază în funcție de topologie. O mapare Docker obișnuită publică un port gazdă, cum ar fi 8080, pe portul containerului 80; o instalare de pachet poate utiliza propriul Nginx pe gazdă. Nu presupuneți că acesta 127.0.0.1:80este portul corect în amonte doar pentru că ambele servicii se află pe aceeași mașină.

2. Verificați serviciile și jurnalele ONLYOFFICE

La instalarea unui pachet Linux, inspectați serviciul de documente și convertorul:

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

Ghidul de depanare ONLYOFFICE listează aceste servicii și identifică memoria insuficientă, un conflict de port 80 și jurnalele de servicii ca elemente de verificat atunci când serviciile Docs nu pornesc. Dacă un serviciu este oprit, verificați mai întâi eroarea sa; apoi reporniți doar serviciul afectat:

sudo systemctl restart ds-docservice

Directorul principal al jurnalelor Linux este /var/log/onlyoffice/documentserver/. Verificați jurnalul de erori Nginx și jurnalele docservice pentru mesaje precum „conexiune refuzată”, „expirare timp în amonte” sau un fișier lipsă. Acestea indică cauze diferite: o conexiune refuzată înseamnă de obicei că procesul sau portul din amonte nu este disponibil, în timp ce o expirare poate însemna că serviciul este supraîncărcat sau blocat.

Verificați și discul și memoria disponibile dacă serviciile se întrerup în mod repetat:

df -h
free -h

Nu reporniți în mod repetat un serviciu defect fără a-i revizui jurnalele; o repornire poate ascunde pentru scurt timp simptomul fără a remedia un conflict de porturi, o dependență eșuată sau o problemă de resurse.

3. Verificați dacă Nginx indică spre upstream-ul accesibil

Citiți gazda virtuală activă și confirmați adresa exactă și portul în proxy_pass. De pe mașina sau containerul pe care rulează Nginx, solicitați direct upstream-ul. De exemplu, dacă containerul publică portul 80 ca port gazdă 8080:

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

Înlocuiți adresa exemplu cu endpoint-ul care este de fapt accesibil din proxy. Dacă Nginx rulează într-un container Docker separat, 127.0.0.1se referă la containerul Nginx în sine, nu la gazda Docker sau la containerul ONLYOFFICE. Folosiți un nume de serviciu accesibil într-o rețea Docker partajată sau adresa corectă a gazdei și portul publicat.

Verificați dacă schema upstream se potrivește cu backend-ul. Folosiți-o http://dacă listener-ul backend folosește HTTP simplu și https://numai dacă este configurat pentru TLS. Trimiterea HTTP către un port TLS sau TLS către un port HTTP simplu poate face ca un serviciu sănătos să pară indisponibil pentru Nginx.

4. Verificați anteturile redirecționate și proxy-ul WebSocket

Ghidul ONLYOFFICE pentru reverse proxy recomandă păstrarea protocolului X-Forwarded-Proto, X-Forwarded-Hostastfel încât aplicația să cunoască protocolul și numele de gazdă originale. Exemplele oficiale Nginx transmit și antete de actualizare. Dacă un proxy extern se află în fața ONLYOFFICE, comparați configurația sa cu scenariul oficial care corespunde topologiei dvs.

Un exemplu simplificat pentru un container Docker mapat la portul gazdă 8080 este prezentat mai jos. Plasați mapdirectiva în contextul Nginx httpși adaptați numele gazdei, configurația TLS și portul upstream la configurația dvs.:

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;
    }
}

Acesta este un model de referință, nu un înlocuitor drop-in pentru fiecare instalare. În special, nu îl lipiți peste configurația ONLYOFFICE Nginx din pachet fără a înțelege ce bloc de server deține porturile 80 și 443. Dacă Nginx partajează gazda cu ONLYOFFICE instalat în pachet, confirmați mai întâi că nu există nicio coliziune de porturi și direcționați proxy-ul extern către listener-ul intern configurat pentru implementarea dvs.

După editare, testați configurația înainte de a reîncărca Nginx:

sudo nginx -t
sudo systemctl reload nginx

Dacă testul de configurare eșuează, corectați fișierul și linia raportate înainte de reîncărcare. O eroare de sintaxă și un mesaj 502 din amonte sunt probleme separate; o eroare reușită nginx -tconfirmă sintaxa, nu faptul că amontele răspunde.

5. Dacă ONLYOFFICE rulează în Docker, verificați starea de funcționare și maparea porturilor.

Verificați dacă containerul rulează și ce port gazdă este publicat:

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

Ghidul oficial de instalare Docker mapează porturile gazdă la portul 80 al containerului, iar exemplul său verifică jurnalele containerului dacă pagina de bun venit nu se încarcă. Folosiți portul afișat de docker portca portul gazdă în amonte. Când atât Nginx, cât și ONLYOFFICE sunt containere, plasați-le într-o rețea partajată și rutați-le către numele serviciului ONLYOFFICE și portul containerului, mai degrabă decât către adresa de loopback a gazdei.

Verificați starea de funcționare a containerului dacă fișierul Compose definește o verificare a stării de funcționare. Exemplul Compose actual din amonte verifică http://localhost:8000/info/info.jsoninteriorul containerului. Un container care „rulează” poate avea în continuare un serviciu de documente nesănătos. Dacă repornește sau este nesănătos, utilizați jurnalele pentru a investiga pornirea bazei de date, memoria și configurația înainte de a schimba proxy-ul extern.

ONLYOFFICE documentează căile persistente Docker pentru jurnale, certificate și memoria cache a fișierelor. Evitați ștergerea volumelor în timpul depanării; acestea pot conține certificate sau alte date necesare pentru recuperarea serviciului.

6. Reîncărcați, testați endpoint-ul de funcționare și retestați integrarea

După corectarea unei probleme confirmate, testați numele de gazdă public și comparați-l cu endpoint-ul local:

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

Folosește adresa URL reală a serverului de documente. Un răspuns reușit atât la adresa locală upstream, cât și la adresa publică de gazdă arată că Nginx poate ajunge la backend și poate returna răspunsul său privind starea de funcționare. Apoi, deschide pagina de bun venit a serverului de documente și reîncearcă acțiunea care inițial a eșuat în Nextcloud, ownCloud sau celălalt conector al tău.

Dacă verificarea stării de funcționare reușește, dar conectorul raportează în continuare o eroare, problema rămasă poate fi în afara căii Nginx 502 - de exemplu, adresa URL a conectorului, încrederea TLS sau setările JWT. Comparați aceste valori cu configurația conectorului și a ONLYOFFICE, în loc să continuați să modificați orbește timeout-urile proxy.

Diagnostic rapid

Referințe oficiale

• Depanarea ONLYOFFICE Docs pentru Linux
• Documente ONLYOFFICE în spatele unui proxy
• Exemplu oficial de proxy ONLYOFFICE Nginx HTTPS-to-HTTP
• Instalarea Docker-ului ONLYOFFICE Docs și maparea porturilor
• Exemplu de compunere pentru serverul de documente ONLYOFFICE