Correction des erreurs 502 Bad Gateway de Nginx : Guide étape par étape
Tracez les erreurs 502 de Nginx en vérifiant la configuration, la santé des services amont, les logs, les sockets, le réseau Docker et les symptômes de timeout.
Correction des erreurs 502 Bad Gateway de Nginx : Guide étape par étape
Corriger les erreurs 502 Bad Gateway de Nginx commence par comprendre que Nginx est généralement le messager, et non la source originale de la panne. Un code 502 signifie que Nginx a tenté de communiquer avec un service amont et n'a reçu aucune réponse valide.
Ce service amont peut être une application Node.js, PHP-FPM, Gunicorn, Puma, un conteneur ou un autre serveur HTTP. Votre travail consiste à trouver où la transmission échoue.
Ce que signifie une erreur 502 Bad Gateway dans Nginx
Nginx se place généralement devant un serveur d'application. Il accepte le trafic public, gère TLS, sert les fichiers statiques et transmet les requêtes dynamiques en amont.
Une erreur 502 apparaît lorsque cette connexion amont échoue ou renvoie quelque chose que Nginx ne peut pas utiliser. Les causes courantes incluent :
- Le processus de l'application est arrêté.
- Nginx pointe vers le mauvais port ou socket.
- Un socket Unix a les mauvaises permissions.
- Le service amont plante pendant la requête.
- Un pare-feu ou un réseau de conteneurs bloque la connexion.
- L'amont envoie une réponse HTTP invalide.
Commencez par le chemin de requête exact qui échoue. Si seulement /api renvoie 502 mais que les pages statiques se chargent, votre service de fichiers statiques fonctionne et le proxy ou le backend de l'application est probablement le problème. Si chaque page échoue, le problème peut être plus large : Nginx, DNS ou disponibilité de l'amont.
Étape 1 : Vérifier l'état et la configuration de Nginx
Confirmez d'abord que Nginx est en cours d'exécution :
systemctl status nginx
Testez ensuite la configuration :
nginx -t
Si le test de configuration échoue, corrigez-le avant de vous attaquer à l'application. Nginx peut toujours fonctionner avec une configuration plus ancienne, ou il peut échouer lors du rechargement.
Après un test de configuration réussi, rechargez Nginx :
systemctl reload nginx
Ne redémarrez pas aveuglément sur un serveur chargé sauf si vous comprenez l'impact. Le rechargement est généralement suffisant après un changement de configuration et est moins perturbateur.
Ensuite, inspectez le bloc serveur actif. Recherchez proxy_pass, fastcgi_pass ou uwsgi_pass. Un proxy inverse typique pourrait inclure :
location / {
proxy_pass http://127.0.0.1:3000;
}
Cela signifie que Nginx attend une application sur le port local 3000. Si l'application écoute en réalité sur 3001, ou seulement à l'intérieur d'un réseau Docker, Nginx échouera.
Pour des vérifications plus axées sur les commandes, consultez Commandes de test de configuration Nginx.
Étape 2 : Vérifier le service amont
Testez maintenant l'amont directement depuis l'hôte Nginx. Si Nginx fait proxy vers 127.0.0.1:3000, exécutez :
curl -i http://127.0.0.1:3000/
Si cela échoue, le problème ne vient ni du navigateur ni du DNS public. Nginx ne peut pas atteindre le backend car le backend est hors service, écoute ailleurs ou rejette la requête.
Vérifiez le processus de l'application :
ss -ltnp
Recherchez le port attendu. Si le service utilise un socket Unix, vérifiez le chemin du socket :
ls -l /run/app/app.sock
L'utilisateur du processus worker Nginx doit pouvoir accéder à ce socket. Sur de nombreux systèmes Linux, Nginx s'exécute en tant que www-data, nginx ou un utilisateur spécifique au service. Si le socket appartient à un utilisateur différent et n'est pas accessible en lecture ou écriture par le groupe selon les besoins, Nginx peut enregistrer une erreur de permission et renvoyer 502.
Pour une configuration PHP-FPM, confirmez que le pool est en cours d'exécution :
systemctl status php-fpm
Le nom du service peut inclure une version, comme php8.2-fpm, selon la distribution.
Étape 3 : Lire le journal d'erreurs de Nginx
Le journal d'erreurs de Nginx vous indique généralement quel mode de défaillance vous rencontrez. Les messages de journal courants incluent :
connect() failed (111: Connection refused) while connecting to upstream
Cela signifie que Nginx a atteint l'hôte mais que rien n'a accepté la connexion sur ce port.
upstream timed out while reading response header from upstream
Cela signifie que Nginx s'est connecté, mais que le backend n'a pas répondu à temps.
permission denied while connecting to upstream
Cela indique souvent des permissions de socket Unix ou des contrôles de sécurité comme SELinux.
Vérifiez les erreurs récentes avec :
tail -n 100 /var/log/nginx/error.log
Sur les systèmes basés sur systemd, vous pouvez également vérifier :
journalctl -u nginx -n 100
Faites correspondre l'horodatage dans le journal avec l'heure de votre requête navigateur. Cela vous évite de poursuivre d'anciennes erreurs qui ne sont plus pertinentes.
Pour un workflow de journal plus approfondi, consultez Analyse des journaux d'erreurs Nginx.
Étape 4 : Corriger les causes racines les plus courantes
Une fois que vous connaissez le mode de défaillance, appliquez la correction la plus petite qui lui correspond.
Si l'application ne fonctionne pas, démarrez ou redémarrez le service d'application :
systemctl restart your-app
Testez ensuite l'amont avec curl avant de tester via Nginx.
Si Nginx pointe vers le mauvais port, mettez à jour la cible proxy_pass et rechargez Nginx. Assurez-vous également que votre application et Nginx sont d'accord sur IPv4 par rapport à IPv6. Une application qui écoute sur 127.0.0.1 n'est pas la même que celle qui écoute uniquement sur ::1.
Si Docker est impliqué, vérifiez si Nginx s'exécute sur l'hôte ou à l'intérieur d'un conteneur. 127.0.0.1 à l'intérieur d'un conteneur pointe vers ce conteneur, pas vers l'hôte. Vous pouvez avoir besoin d'un nom de service Docker, d'un réseau bridge ou d'un port publié.
Si l'amont expire, vérifiez les journaux de l'application. Le backend peut être bloqué sur des requêtes de base de données, des appels API externes ou des travaux de démarrage. Augmenter les timeouts de Nginx peut masquer les symptômes, mais cela ne corrigera pas une application cassée ou surchargée.
Quand faire appel à un professionnel
Faites appel à un ingénieur senior ou à un hébergeur lorsque les erreurs 502 affectent la production et que la cause n'est pas évidente après avoir vérifié les journaux, l'état de l'amont et les déploiements récents. Demandez également de l'aide si le problème touche les équilibreurs de charge, l'orchestration de conteneurs, la politique SELinux ou le réglage des timeouts en cas de trafic élevé.
Pour les systèmes de production, évitez les redémarrages aléatoires répétés. Ils peuvent effacer les preuves et rendre la panne plus difficile à comprendre.
Une erreur 502 Bad Gateway est réparable lorsque vous tracez le chemin de la requête dans l'ordre. Confirmez que Nginx est valide, testez l'amont directement, lisez la ligne exacte du journal d'erreurs et appliquez la correction qui correspond à la défaillance. Cette approche est plus rapide et plus sûre que de modifier les timeouts ou de redémarrer les services aveuglément.