Come risolvere l'errore 502 Bad Gateway del server documenti ONLYOFFICE dietro Nginx

Un browser visualizza l'errore "502 Bad Gateway" quando si apre un URL di ONLYOFFICE Docs, oppure un connettore Nextcloud/ownCloud non riesce a raggiungere il server dei documenti. In entrambi i casi, Nginx riceve solitamente una richiesta ma non riesce a ottenere una risposta valida dal suo server di origine. Il server di origine potrebbe essere il servizio di documenti interno di ONLYOFFICE, un container Docker o un altro reverse proxy. Innanzitutto, identifica quale istanza di Nginx ha restituito l'errore 502; quindi, testa direttamente il server di destinazione prima di modificare la configurazione.

La guida alla risoluzione dei problemi Linux di ONLYOFFICE consiglia di controllare i ds-docserviceservizi ds-convertere i log del Document Server. La sua guida al reverse proxy menziona anche gli host inoltrati e le intestazioni di protocollo. La sequenza seguente verifica prima lo stato dei servizi, poi il routing di Nginx e la rete di Docker.

1. Scopri quale Nginx sta restituendo 502

L'installazione del pacchetto ONLYOFFICE include la propria configurazione Nginx e un'implementazione potrebbe anche prevedere un proxy inverso Nginx esterno. Docker può aggiungere un ulteriore passaggio di rete. L'aspetto della pagina 502 da solo potrebbe non essere sufficiente a identificare il livello, quindi confronta l'URL pubblico con un controllo di integrità locale e il log degli errori di Nginx.

Su un'installazione Linux basata su pacchetti, testare l'endpoint locale del Document Server:

curl -i http://127.0.0.1/healthcheck

Se il server è configurato per servire ONLYOFFICE su una porta locale diversa da quella predefinita, utilizzare quella porta. Un'installazione corretta normalmente restituisce una risposta HTTP di successo con true. Se questa richiesta locale fallisce, correggere il servizio Document Server prima di modificare un proxy esterno. Se localmente ha successo ma il nome host pubblico restituisce 502, concentrarsi sul server Nginx esterno, sul protocollo, sulle intestazioni e sul percorso del firewall.

Verifica quali processi sono proprietari delle porte previste:

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

Le porte variano a seconda della topologia. Una mappatura Docker comune pubblica una porta host, ad esempio la 8080, sulla porta 80 del container; l'installazione di un pacchetto può utilizzare il proprio Nginx sull'host. Non dare per scontato che questo 127.0.0.1:80sia il server upstream corretto solo perché entrambi i servizi si trovano sulla stessa macchina.

2. Controlla i servizi e i registri di ONLYOFFICE

In un'installazione di pacchetto Linux, esaminare il servizio documenti e il convertitore:

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

La guida alla risoluzione dei problemi di ONLYOFFICE elenca questi servizi e identifica la memoria insufficiente, un conflitto sulla porta 80 e i registri dei servizi come elementi da controllare quando i servizi di Documenti non si avviano. Se un servizio è arrestato, esamina prima l'errore; quindi riavvia solo il servizio interessato:

sudo systemctl restart ds-docservice

La directory principale dei log di Linux è /var/log/onlyoffice/documentserver/. Controlla il log degli errori di Nginx e i log del servizio di documentazione per messaggi come "connessione rifiutata", "timeout upstream" o un file mancante. Questi indicano cause diverse: una connessione rifiutata di solito significa che il processo o la porta upstream non sono disponibili, mentre un timeout può significare che il servizio è sovraccarico o bloccato.

Verifica inoltre lo spazio su disco e la memoria disponibili se i servizi si arrestano ripetutamente:

df -h
free -h

Non riavviare ripetutamente un servizio non funzionante senza prima averne esaminato i log; un riavvio potrebbe nascondere temporaneamente il problema senza risolvere un conflitto di porte, una dipendenza non funzionante o un problema di risorse.

3. Verificare che Nginx punti all'upstream raggiungibile

Leggi l'host virtuale attivo e conferma l'indirizzo e la porta esatti in proxy_pass. Dalla macchina o dal container in cui è in esecuzione Nginx, richiedi direttamente l'upstream. Ad esempio, se il container pubblica la porta 80 come porta host 8080:

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

Sostituisci l'indirizzo di esempio con l'endpoint effettivamente raggiungibile dal proxy. Se Nginx è in esecuzione in un container Docker separato, 127.0.0.1fai riferimento al container Nginx stesso, non all'host Docker o al container ONLYOFFICE. Utilizza un nome di servizio raggiungibile su una rete Docker condivisa oppure l'indirizzo host e la porta pubblicati corretti.

Verifica che lo schema upstream corrisponda a quello backend. Utilizzalo http://solo se il listener backend utilizza HTTP non crittografato e https://solo se è configurato per TLS. L'invio di HTTP a una porta TLS, o di TLS a una porta HTTP non crittografata, può far apparire un servizio funzionante non disponibile per Nginx.

4. Verificare le intestazioni inoltrate e il proxy WebSocket

La guida al reverse proxy di ONLYOFFICE raccomanda di preservare il protocollo e il nome host originali X-Forwarded-Proto, in X-Forwarded-Hostmodo che l'applicazione li conosca. Anche gli esempi ufficiali di Nginx includono gli header di aggiornamento. Se ONLYOFFICE si trova davanti a un proxy esterno, confronta la sua configurazione con lo scenario ufficiale che corrisponde alla tua topologia.

Di seguito viene mostrato un esempio semplificato di un container Docker mappato sulla porta host 8080. Inserisci la mapdirettiva nel contesto di Nginx httpe adatta il nome host, la configurazione TLS e la porta upstream alla tua configurazione:

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

Questo è uno schema di riferimento, non una soluzione sostitutiva universale per ogni installazione. In particolare, non sovrascrivete la configurazione Nginx di ONLYOFFICE preinstallata senza prima aver compreso quale blocco server gestisce le porte 80 e 443. Se Nginx condivide l'host con ONLYOFFICE preinstallato, verificate innanzitutto che non vi siano conflitti di porte e instradate il proxy esterno al listener interno configurato per la vostra implementazione.

Dopo aver apportato le modifiche, testa la configurazione prima di ricaricare Nginx:

sudo nginx -t
sudo systemctl reload nginx

Se il test di configurazione fallisce, correggere il file e la riga segnalati prima di ricaricare. Un errore di sintassi e un errore 502 a monte sono problemi distinti; un esito positivo nginx -tconferma la sintassi, non che il server a monte risponda.

5. Se ONLYOFFICE è in esecuzione in Docker, verifica il suo stato e la mappatura delle porte.

Verifica se il container è in esecuzione e quale porta host è pubblicata:

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

La guida ufficiale all'installazione di Docker mappa le porte dell'host alla porta 80 del container e il suo esempio controlla i log del container se la pagina di benvenuto non viene caricata. Utilizza la porta mostrata come docker portupstream lato host. Quando sia Nginx che ONLYOFFICE sono container, posizionali su una rete condivisa e instrada il traffico al nome del servizio ONLYOFFICE e alla porta del container, anziché all'indirizzo di loopback dell'host.

Verifica lo stato di salute del container se il tuo file Compose definisce un controllo di integrità. L'esempio Compose upstream corrente esegue il controllo http://localhost:8000/info/info.jsonall'interno del container. Un container che risulta "in esecuzione" potrebbe comunque avere un servizio documenti non integro. Se si riavvia o non è integro, utilizza i log per analizzare l'avvio del database, la memoria e la configurazione prima di modificare il proxy esterno.

ONLYOFFICE documenta i percorsi Docker persistenti per i log, i certificati e la cache dei file. Evita di eliminare i volumi durante la risoluzione dei problemi; potrebbero contenere certificati o altri dati necessari per ripristinare il servizio.

6. Ricarica, testa l'endpoint di integrità e ritesta l'integrazione.

Dopo aver risolto un problema confermato, testa il nome host pubblico e confrontalo con l'endpoint locale:

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

Utilizza l'URL reale del tuo Document Server. Una risposta positiva sia all'hoststream locale che all'hostname pubblico indica che Nginx è in grado di raggiungere il backend e restituire la sua risposta di integrità. Quindi apri la pagina di benvenuto del Document Server e riprova l'azione che inizialmente non è riuscita in Nextcloud, ownCloud o nell'altro connettore.

Se il controllo di integrità ha esito positivo ma il connettore continua a segnalare un errore, il problema potrebbe risiedere al di fuori del percorso 502 di Nginx, ad esempio nell'URL del connettore, nella fiducia TLS o nelle impostazioni JWT. Confronta questi valori con la configurazione del connettore e di ONLYOFFICE anziché continuare a modificare i timeout del proxy alla cieca.

Diagnosi rapida

Riferimenti ufficiali

• Documentazione ONLYOFFICE per la risoluzione dei problemi di Linux
• Documenti ONLYOFFICE dietro un proxy
• Esempio ufficiale di proxy Nginx HTTPS-to-HTTP di ONLYOFFICE
• Documentazione ONLYOFFICE: Installazione di Docker e mappatura delle porte
• Esempio di composizione per il server di documenti ONLYOFFICE