Comment résoudre l'erreur 502 (Bad Gateway) du serveur de documents ONLYOFFICE derrière un serveur Nginx ?

Un navigateur affiche une erreur « 502 Bad Gateway » lors de l'ouverture d'une URL ONLYOFFICE Docs, ou un connecteur Nextcloud/ownCloud ne parvient pas à joindre le serveur de documents. Dans les deux cas, Nginx reçoit généralement une requête, mais ne parvient pas à obtenir de réponse valide de son serveur en amont. Ce serveur peut être le service de documents interne d'ONLYOFFICE, un conteneur Docker ou un autre proxy inverse. Commencez par identifier quel serveur Nginx a renvoyé l'erreur 502 ; puis testez directement le serveur suivant avant de modifier la configuration.

Le guide de dépannage Linux d'ONLYOFFICE recommande de vérifier les ds-docserviceservices ds-converteret les journaux du serveur de documents. Son guide sur le proxy inverse mentionne également les en-têtes d'hôte et de protocole transférés. La procédure ci-dessous vérifie d'abord l'état des services, puis le routage Nginx et le réseau Docker.

1. Identifiez le serveur Nginx qui renvoie une erreur 502.

L'installation du package ONLYOFFICE inclut sa propre configuration Nginx, et un déploiement peut également comporter un proxy inverse Nginx externe. Docker peut ajouter un saut réseau supplémentaire. L'affichage de la page 502 à lui seul ne permet pas d'identifier la couche concernée ; il est donc conseillé de comparer l'URL publique avec un contrôle d'intégrité local et le journal d'erreurs Nginx.

Sur une installation Linux basée sur des paquets, testez le point de terminaison du serveur de documents local :

curl -i http://127.0.0.1/healthcheck

Si le serveur est configuré pour utiliser ONLYOFFICE sur un port local autre que celui par défaut, utilisez ce port. Une installation fonctionnelle renvoie normalement une réponse HTTP de succès true. Si cette requête locale échoue, corrigez le service Serveur de documents avant de modifier un proxy externe. Si la requête réussit localement mais que le nom d'hôte public renvoie une erreur 502, examinez la configuration Nginx externe : serveur en amont, protocole, en-têtes et chemin du pare-feu.

Vérifiez quels processus possèdent les ports attendus :

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

Les ports varient selon la topologie. Un mappage Docker classique expose un port hôte, par exemple 8080, vers le port 80 du conteneur ; une installation de paquet peut utiliser sa propre instance Nginx sur l'hôte. Ne présumez pas qu'il 127.0.0.1:80s'agit du serveur Nginx approprié simplement parce que les deux services sont sur la même machine.

2. Vérifiez les services et les journaux ONLYOFFICE

Lors de l'installation d'un paquet Linux, examinez le service de documents et le convertisseur :

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

Le guide de dépannage d'ONLYOFFICE répertorie ces services et indique que la mémoire insuffisante, un conflit sur le port 80 et les journaux de service sont des éléments à vérifier en cas de non-démarrage des services Docs. Si un service est arrêté, examinez d'abord l'erreur, puis redémarrez uniquement le service concerné.

sudo systemctl restart ds-docservice

Le répertoire principal des journaux Linux est `/etc/logs` /var/log/onlyoffice/documentserver/. Consultez le journal d'erreurs Nginx et les journaux du service de documentation pour rechercher des messages tels que « connexion refusée », « délai d'attente dépassé » ou un fichier manquant. Ces messages indiquent des causes différentes : une connexion refusée signifie généralement que le processus ou le port en amont est indisponible, tandis qu'un délai d'attente dépassé peut indiquer que le service est surchargé ou bloqué.

Vérifiez également l'espace disque et la mémoire disponibles si les services s'arrêtent de manière répétée :

df -h
free -h

Ne redémarrez pas sans cesse un service défaillant sans consulter ses journaux ; un redémarrage peut masquer temporairement le symptôme sans pour autant résoudre un conflit de ports, une dépendance défaillante ou un problème de ressources.

3. Vérifiez que Nginx pointe bien vers le serveur en amont accessible.

Lisez l'hôte virtuel actif et confirmez l'adresse et le port exacts proxy_pass. Depuis la machine ou le conteneur où Nginx s'exécute, interrogez directement le serveur en amont. Par exemple, si le conteneur publie le port 80 comme port hôte 8080 :

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

Remplacez l'adresse d'exemple par le point de terminaison réellement accessible depuis le proxy. Si Nginx s'exécute dans un conteneur Docker distinct, 127.0.0.1indiquez qu'il s'agit bien de ce conteneur Nginx, et non de l'hôte Docker ou du conteneur ONLYOFFICE. Utilisez un nom de service accessible sur un réseau Docker partagé ou l'adresse hôte et le port publié corrects.

Vérifiez que le protocole en amont correspond au protocole côté serveur. Utilisez cette option http://si le serveur côté serveur utilise HTTP simple et https://uniquement s'il est configuré pour TLS. Envoyer du HTTP vers un port TLS, ou du TLS vers un port HTTP simple, peut rendre un service fonctionnel indisponible pour Nginx.

4. Vérifiez les en-têtes transférés et le proxy WebSocket

Le guide de proxy inverse d'ONLYOFFICE recommande de conserver les en-têtes X-Forwarded-Protode X-Forwarded-Hostprotocole et de nom d'hôte d'origine afin que l'application les connaisse. Les exemples officiels de Nginx transmettent également les en-têtes de mise à niveau. Si un proxy externe est placé devant ONLYOFFICE, comparez sa configuration avec le scénario officiel correspondant à votre topologie.

Vous trouverez ci-dessous un exemple simplifié de conteneur Docker mappé sur le port hôte 8080. Placez la mapdirective dans le contexte Nginx httpet adaptez le nom d'hôte, la configuration TLS et le port en amont à votre configuration :

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

Il s'agit d'un modèle de référence, et non d'une solution de remplacement universelle. En particulier, ne le copiez pas par-dessus la configuration Nginx fournie avec ONLYOFFICE sans avoir préalablement identifié le bloc serveur qui gère les ports 80 et 443. Si Nginx partage le même hôte qu'ONLYOFFICE, vérifiez d'abord l'absence de conflit de ports et redirigez le proxy externe vers le serveur interne configuré pour votre déploiement.

Après modification, testez la configuration avant de recharger Nginx :

sudo nginx -t
sudo systemctl reload nginx

Si le test de configuration échoue, corrigez le fichier et la ligne signalés avant de recharger. Une erreur de syntaxe et une erreur 502 du serveur sont deux problèmes distincts ; un test réussi nginx -tconfirme la syntaxe, et non la réponse du serveur.

5. Si ONLYOFFICE s'exécute dans un conteneur Docker, vérifiez son état et le mappage des ports.

Vérifiez si le conteneur est en cours d'exécution et quel port hôte est publié :

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

Le guide d'installation officiel de Docker associe les ports hôtes au port 80 du conteneur et son exemple vérifie les journaux du conteneur si la page d'accueil ne se charge pas. Utilisez le port indiqué comme docker portport amont côté hôte. Si Nginx et ONLYOFFICE sont tous deux des conteneurs, placez-les sur un réseau partagé et configurez la redirection vers le nom de service ONLYOFFICE et le port du conteneur, plutôt que vers l'adresse de bouclage de l'hôte.

Vérifiez l'état de santé du conteneur si votre fichier Compose définit un contrôle d'intégrité. L'exemple Compose actuel effectue ce contrôle http://localhost:8000/info/info.jsonà l'intérieur du conteneur. Un conteneur « en cours d'exécution » peut néanmoins présenter un service de documents défaillant. En cas de redémarrage ou de défaillance du conteneur, consultez les journaux pour examiner le démarrage de la base de données, la mémoire et la configuration avant de modifier le proxy externe.

ONLYOFFICE documente les chemins d'accès Docker persistants pour les journaux, les certificats et le cache de fichiers. Évitez de supprimer des volumes lors du dépannage ; ils peuvent contenir des certificats ou d'autres données nécessaires à la restauration du service.

6. Rechargez, testez le point de terminaison d'intégrité et testez à nouveau l'intégration.

Après avoir corrigé un problème confirmé, testez le nom d'hôte public et comparez-le avec le point de terminaison local :

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

Utilisez l'URL réelle de votre serveur de documents. Une réponse positive à la fois sur le serveur local et sur le nom d'hôte public indique que Nginx peut accéder au serveur et renvoyer une réponse positive. Ouvrez ensuite la page d'accueil du serveur de documents et réessayez l'action qui avait initialement échoué dans Nextcloud, ownCloud ou votre autre connecteur.

Si le contrôle d'intégrité réussit mais que le connecteur signale toujours une erreur, le problème peut provenir d'un autre contexte que celui des erreurs 502 de Nginx : par exemple, l'URL du connecteur, la confiance TLS ou les paramètres JWT. Comparez ces valeurs avec la configuration du connecteur et d'ONLYOFFICE plutôt que de modifier les délais d'expiration du proxy sans discernement.

Diagnostic rapide

Références officielles

• Dépannage de la documentation ONLYOFFICE pour Linux
• ONLYOFFICE Documents derrière un proxy
• Exemple officiel de proxy HTTPS vers HTTP avec Nginx pour ONLYOFFICE
• Documentation ONLYOFFICE : Installation de Docker et configuration des ports
• Exemple de composition du serveur de documents ONLYOFFICE