Traccia la catena a monte per risolvere l'errore Nginx 502 di ONLYOFFICE.

Iniziate verificando la connessione tra Nginx e ONLYOFFICE Docs, quindi leggete il log degli errori corrispondente alla risposta 502. Un errore 502 Bad Gateway indica che il gateway non è riuscito a ottenere una risposta valida dal server a monte; di per sé, non dimostra che la configurazione pubblica di Nginx sia la causa. In Docker, la soluzione più comune è quella di indirizzare Nginx al servizio Document Server sulla sua porta interna 80 e assicurarsi che entrambi i container condividano la stessa rete.

Cosa bisogna controllare prima di modificare Nginx?

Un reverse proxy è un server che accetta una richiesta da un client e la inoltra a un altro server. In una configurazione tipica, Nginx pubblico gestisce HTTPS e inoltra le richieste a ONLYOFFICE Docs tramite HTTP. ONLYOFFICE Docs esegue anche un proprio server Nginx internamente, quindi una pagina di errore 502 può essere generata dal proxy esterno o dal container del Document Server stesso.

Innanzitutto, identifica il server che ha emesso la risposta. Confronta l'intestazione del server e il timestamp della pagina con i log del proxy esterno e i log del Document Server. Nel caso di una configurazione Docker, verifica lo stato del container e i messaggi di avvio recenti:

docker ps --filter name=onlyoffice-documentserver
docker logs --tail 100 onlyoffice-documentserver

Se il container si sta riavviando o è appena stato avviato, controlla il log prima di modificare le impostazioni del proxy. ONLYOFFICE segnala che il primo avvio può richiedere uno o due minuti per l'inizializzazione del database. Per un'installazione nativa di Linux, controlla ds-docservicee ds-convertercon systemctl status; i log del Document Server si trovano in /var/log/onlyoffice/documentserver/.

Se un servizio è arrestato, utilizzare le istruzioni ufficiali di ONLYOFFICE Linux per la risoluzione dei problemi .

Nginx riesce a raggiungere il Document Server a monte?

Eseguite il test dal container o dall'host Nginx, non solo dal vostro laptop. I container su reti Docker separate non possono risolversi a vicenda tramite il nome del servizio, anche quando entrambi sono in esecuzione. Quando Nginx e ONLYOFFICE condividono una rete Docker definita dall'utente, utilizzate il nome del servizio Compose o un nome di container risolvibile e la porta di ascolto del container. La guida ufficiale all'installazione di Docker identifica la porta 80 come porta di ascolto predefinita del Document Server; una porta host pubblicata come 8080:80 non modifica la porta interna.

Dal container proxy, eseguire:

curl -I http://onlyoffice-documentserver:80/

Sostituisci onlyoffice-documentservercon il nome effettivo del tuo servizio Compose. Se la richiesta indica "Impossibile risolvere l'host", collega entrambi i container alla stessa rete Docker o correggi il nome upstream. "Connessione rifiutata" di solito significa che l'host di destinazione è stato risolto ma nulla accetta connessioni su quella porta, il container non è pronto oppure è stata utilizzata la porta sbagliata. Se si tratta di un'installazione nativa, prova invece l'indirizzo locale e la porta configurata, ad esempio curl -I http://127.0.0.1/.

La guida Docker di ONLYOFFICE illustra la porta predefinita, le mappature delle porte, il ritardo di avvio e i log dei container: Installazione e verifica di Docker .

Come si corregge il target del proxy Nginx?

Nell'host virtuale HTTPS per l'hostname ONLYOFFICE, assicurarsi proxy_passche punti all'upstream raggiungibile. Questo esempio presuppone una rete Docker condivisa e il nome del servizio mostrato sopra; modificarlo in base alla propria implementazione:

location / {
    proxy_pass http://onlyoffice-documentserver:80;
    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 "upgrade";
}

Non puntare un proxy containerizzato a 127.0.0.1:8080meno che Document Server non sia effettivamente in ascolto nello stesso container o l'indirizzo host non sia configurato e raggiungibile intenzionalmente. All'interno di un container, 127.0.0.1significa il container stesso. Evita inoltre di inviare HTTPS al server upstream quando l'endpoint di Document Server è HTTP semplice.

Il protocollo inoltrato e l'host indicano a ONLYOFFICE quale URL pubblico ha utilizzato il client, e le intestazioni di aggiornamento consentono le connessioni WebSocket utilizzate per la comunicazione in tempo reale con l'editor. ONLYOFFICE fornisce esempi aggiornati per l'esecuzione di Docs dietro un proxy , inclusa la configurazione Nginx da HTTPS a HTTP . Confrontate questo esempio completo se il vostro ambiente prevede più hop proxy o utilizza un prefisso di percorso URL.

Prima di applicare le modifiche, convalida la configurazione con nginx -t, quindi ricarica Nginx utilizzando il metodo per il tuo host o container. Non riavviare tutti i servizi contemporaneamente; un ricaricamento controllato semplifica la verifica dell'esito della correzione upstream.

Cosa succede se ONLYOFFICE continua a restituire un errore 502?

Se il proxy esterno riesce a raggiungere la pagina di benvenuto del Document Server ma /healthcheckrestituisce un errore 502, il problema potrebbe risiedere all'interno del Document Server stesso anziché nell'istanza pubblica di Nginx. Controllare i log del container del Document Server e i log interni del servizio. Per le installazioni native su Linux, esaminare i comandi relativi allo stato del servizio e la directory dei log indicati in precedenza. Se /welcome/il servizio risponde ma il controllo di integrità non lo fa, considerarli come segnali separati: una pagina di benvenuto statica non dimostra che il servizio di documentazione e le sue dipendenze siano integri.

Non "risolvi" questo problema disabilitando JWT. La convalida JSON Web Token (JWT) autentica le richieste di integrazione; una mancata corrispondenza del JWT di solito causa un errore di autorizzazione, non un'impossibilità a livello di rete di connettersi a un server upstream. Verifica le impostazioni JWT solo se il proxy risponde ma l'integrazione segnala un errore di autorizzazione o di token.

Infine, verifica che Nginx stia instradando il nome host corretto all'host virtuale corretto. Un errore di battitura nel server_namenome DNS upstream o nella porta può reindirizzare il traffico altrove o far sì che il proxy utilizzi una configurazione obsoleta. Controlla il log degli errori di Nginx per righe come host not found in upstream, connect() failed, o upstream timed out; ognuna punta a un livello diverso.

Come si verifica la correzione?

Ritestare il flusso a monte dalla rete proxy, quindi controllare l'endpoint di salute pubblica e aprire un documento tramite la piattaforma connessa:

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

Una risposta positiva al controllo di integrità non dovrebbe più essere un errore 502 e il documento dovrebbe aprirsi e rimanere connesso durante la modifica. Se il test a monte ha esito positivo ma la richiesta pubblica continua a fallire, concentrarsi sull'host virtuale Nginx selezionato, sulla sua configurazione caricata e sui relativi log. Se la pagina di benvenuto pubblica funziona ma il controllo di integrità continua a restituire un errore 502, procedere con la diagnosi interna del servizio ONLYOFFICE.

Per informazioni sul comportamento delle direttive Nginx, consultare la documentazione ufficiale del modulo proxy Nginx . I comandi e i nomi dei servizi esatti possono variare a seconda del progetto Docker Compose, della distribuzione Linux e della versione di ONLYOFFICE, quindi sostituite i nomi con quelli effettivi e controllate i log del componente che ha generato la risposta.