Analyse des logs d'erreur Nginx pour le dépannage des connexions refusées

Analyser les logs d'erreur Nginx pour le dépannage des connexions refusées vous aide à passer d'une page 502 générique à un échec spécifique du backend. L'expression « connexion refusée » signifie généralement que Nginx a tenté de se connecter à une adresse en amont, mais qu'aucun processus n'a accepté la connexion.

Cela diffère d'un délai d'attente, d'un échec DNS ou d'une mauvaise réponse. Une fois que vous reconnaissez le modèle de log, vous pouvez rapidement réduire la correction.

Ce que signifie « Connexion refusée »

Dans les logs Nginx, un message courant ressemble à ceci :

connect() failed (111: Connection refused) while connecting to upstream

Cela signifie que le système d'exploitation a rejeté la tentative de connexion. Nginx a atteint l'hôte cible, mais rien n'écoutait sur le port cible, ou la connexion a été activement refusée.

Vous pouvez le voir lorsque Nginx fait proxy vers :

proxy_pass http://127.0.0.1:3000;

mais l'application est arrêtée ou écoute sur un port différent.

Cette erreur est courante après les déploiements. Un gestionnaire de processus peut ne pas redémarrer l'application, un conteneur peut planter, ou une nouvelle configuration peut changer le port de l'application sans mettre à jour Nginx.

Ne traitez pas chaque 502 comme une connexion refusée. Un message de délai d'attente indique une direction différente. Un message d'autorisation refusée pointe souvent vers des sockets ou une politique de sécurité. Le texte exact du log est important.

Trouver le bon log d'erreur Nginx

Le chemin du log d'erreur par défaut est souvent :

/var/log/nginx/error.log

Mais les blocs serveur peuvent définir des logs personnalisés :

error_log /var/log/nginx/app-error.log warn;

Vérifiez la configuration Nginx pertinente si le log par défaut n'affiche pas d'entrées récentes. Sur certains systèmes, les messages au niveau du service apparaissent également dans le journal système.

Les commandes utiles incluent :

tail -n 100 /var/log/nginx/error.log

et :

journalctl -u nginx -n 100

Lors des tests, déclenchez une requête dans le navigateur ou avec curl, puis vérifiez immédiatement les lignes de log les plus récentes. Cela facilite grandement la connexion entre l'erreur visible par l'utilisateur et l'échec du backend.

Une bonne revue de log capture quatre informations :

• L'horodatage de la requête échouée.
• L'adresse et le port en amont.
• Le chemin de la requête.
• L'erreur système exacte, comme 111: Connection refused.

Pour un dépannage plus large de Nginx, consultez correction des erreurs 502 Bad Gateway de Nginx.

Mapper l'entrée de log à l'amont

Une ligne de log typique peut inclure une valeur en amont comme :

upstream: "http://127.0.0.1:3000/api/status"

Cela vous indique exactement où Nginx a tenté d'envoyer la requête. Vérifiez maintenant si quelque chose écoute à cet endroit :

ss -ltnp

Recherchez 127.0.0.1:3000, 0.0.0.0:3000, ou l'adresse attendue. Si le port est manquant, l'application n'écoute pas là où Nginx l'attend.

Testez l'amont directement :

curl -i http://127.0.0.1:3000/api/status

Si cela échoue avec une connexion refusée, vous avez confirmé le problème sans Nginx au milieu.

Si l'application s'exécute dans Docker, faites attention à 127.0.0.1. Depuis l'hôte, cela signifie l'hôte. Depuis l'intérieur d'un conteneur Nginx, cela signifie le conteneur Nginx lui-même. Dans une configuration Compose, Nginx doit généralement faire proxy vers un nom de service tel que :

proxy_pass http://app:3000;

à condition que les deux conteneurs partagent le même réseau Docker.

Pour les sockets Unix, le log peut pointer vers un chemin au lieu d'un port :

upstream: "http://unix:/run/app/app.sock:/"

Dans ce cas, vérifiez si le socket existe et si l'utilisateur du worker Nginx peut y accéder.

Causes courantes et correctifs

La cause la plus courante est un service backend arrêté. Vérifiez-le avec :

systemctl status your-app

S'il a échoué, lisez les logs de l'application avant de redémarrer. Un redémarrage peut ramener le site, mais les logs expliquent pourquoi il a échoué.

Une autre cause courante est un décalage de port. Par exemple, l'application est passée du port 3000 à 8080, mais Nginx fait toujours proxy vers 3000. Corrigez la cible en amont de Nginx ou restaurez le port attendu de l'application.

Une troisième cause est la liaison à la mauvaise interface. Une application écoutant uniquement sur 127.0.0.1 est accessible depuis un Nginx local sur le même hôte. Mais si Nginx s'exécute dans un autre conteneur ou un autre serveur, il ne sera pas accessible via cette adresse de boucle locale. Dans ces configurations, l'application peut avoir besoin de se lier à 0.0.0.0 à l'intérieur du réseau privé.

Les règles de pare-feu peuvent également refuser ou rejeter les connexions, surtout entre serveurs. Si Nginx fait proxy vers un autre hôte, confirmez que le port en amont est ouvert depuis la machine Nginx, pas seulement depuis votre ordinateur portable.

Enfin, le timing de déploiement peut provoquer de brèves erreurs de connexion refusée. Si Nginx envoie du trafic avant que le nouveau processus d'application ne soit prêt, les utilisateurs peuvent voir des 502 intermittents. Une vérification de santé, une sonde de préparation ou une stratégie de redémarrage progressif peuvent l'empêcher.

Un flux de dépannage pratique

Utilisez cet ordre lorsque le log indique une connexion refusée :

1. Copiez l'hôte et le port en amont depuis le log d'erreur Nginx.
2. Exécutez curl vers cet amont exact depuis le serveur Nginx.
3. Exécutez ss -ltnp pour confirmer qu'un processus écoute.
4. Vérifiez l'état du service backend et les logs de l'application.
5. Comparez la valeur proxy_pass de Nginx avec l'adresse de liaison réelle de l'application.
6. Rechargez Nginx uniquement après que la configuration est correcte et que nginx -t réussit.

Ce flux évite une erreur courante : modifier Nginx alors que l'application est simplement arrêtée. Il évite également l'erreur inverse : redémarrer l'application à plusieurs reprises alors que Nginx pointe vers le mauvais endroit.

Pour les bases des commandes, consultez commandes de surveillance des logs Nginx.

Quand faire appel à un professionnel

Demandez de l'aide lorsque les erreurs de connexion refusée se produisent uniquement sous charge, sur plusieurs amonts, ou lors de déploiements progressifs. Ces cas peuvent impliquer la supervision des processus, la mise en réseau des conteneurs, les vérifications de santé des équilibreurs de charge ou les limites de capacité.

Vous devriez également escalader si l'amont est un service de production de paiement, d'authentification ou une API orientée client. La récupération rapide est importante, mais la préservation des logs et la compréhension de l'échec le sont aussi.

La connexion refusée est l'une des erreurs Nginx les plus claires une fois que vous la lisez attentivement. Trouvez l'amont dans le log, testez cette cible directement, et corrigez le service, le port, l'interface ou le chemin réseau qui empêche Nginx de se connecter. Le log vous donne déjà le point de départ.