Correction des erreurs 'Connexion refusée' de Nginx : Guide pratique de dépannage

Rencontrer une erreur 'Connexion refusée' en essayant d'accéder à un service fonctionnant derrière Nginx est une expérience courante, bien que frustrante. Contrairement à une erreur 'Timeout', qui suggère un délai réseau ou une perte de paquets, une erreur 'Connexion refusée' est définitive : le système d'exploitation a immédiatement rejeté la tentative de connexion car aucune application n'écoutait activement sur le port et l'adresse IP spécifiés.

Ce rejet immédiat identifie le problème à quelques domaines critiques : le service est arrêté, le pare-feu bloque le trafic localement, ou la configuration dirige le trafic vers un port inexistant. Ce guide propose une approche systématique en quatre phases pour diagnostiquer et résoudre les erreurs 'Connexion refusée', vous permettant de rétablir rapidement la connectivité du service.

Phase 1 : Vérification de l'état du serveur Nginx (l'écouteur principal)

La cause la plus basique d'un refus de connexion est que le service Nginx lui-même ne fonctionne pas ou est mal configuré.

1. Vérifier l'état du service Nginx

Utilisez le gestionnaire de services de votre système (généralement systemd) pour confirmer que Nginx est actif et en cours d'exécution. Un échec ici est la cause directe du refus sur le port d'écoute principal (généralement 80 ou 443).

sudo systemctl status nginx

Sortie attendue (succès) : Recherchez Active: active (running).

Correction applicable : Si l'état indique inactive ou failed, essayez de démarrer le service et vérifiez les journaux pour les détails de l'échec.

sudo systemctl start nginx
sudo journalctl -xe | grep nginx

2. Confirmer les ports d'écoute actifs

Utilisez l'outil ss (statistiques de socket) ou netstat pour vérifier que Nginx se lie effectivement à l'adresse IP et au port attendus (par exemple, 0.0.0.0:80 ou 127.0.0.1:8080).

# Utilisation de ss (préféré sur les distributions Linux modernes)
sudo ss -tuln | grep 80

# Utilisation de netstat
sudo netstat -tuln | grep 80

Si vous ne voyez pas le port attendu (par exemple, :80 ou :443) listé sous un processus (PID) associé à Nginx, cela signifie que Nginx n'a pas réussi à se lier, probablement en raison d'une erreur de configuration ou d'un autre service occupant déjà ce port.

Astuce : Si un autre service occupe le port, vous devez soit arrêter ce service, soit modifier la configuration de Nginx pour écouter sur un port différent et disponible.

Phase 2 : Pare-feu et configuration réseau

Si Nginx fonctionne et écoute localement, le refus de connexion peut se produire en dehors du service, généralement en raison de règles de pare-feu bloquant le trafic entrant.

1. Vérifier les pare-feux du serveur local

Assurez-vous que les ports sur lesquels Nginx écoute (par exemple, 80, 443) sont explicitement autorisés à travers le pare-feu de l'hôte (UFW, firewalld ou iptables).

Exemple UFW (Ubuntu/Debian)

sudo ufw status verbose
# Si fermé, autorisez les ports :
sudo ufw allow 'Nginx Full'
# Ou spécifiquement :
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Exemple Firewalld (CentOS/RHEL)

sudo firewall-cmd --list-all
# Si fermé, ajoutez les services :
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

2. Vérifier les groupes de sécurité du fournisseur cloud

Si votre serveur est hébergé dans un environnement cloud (AWS EC2, Azure VM, GCP Compute Engine), le refus de connexion peut provenir de la couche de sécurité du réseau virtuel.

Groupes de sécurité AWS (SG) : Vérifiez le SG associé et assurez-vous que les règles entrantes autorisent le trafic sur les ports 80 et 443 depuis les adresses IP sources (généralement 0.0.0.0/0 pour un accès public).
Groupes de sécurité réseau Azure (NSG) : Vérifiez les règles de port entrant.

Phase 3 : Validation de la configuration Nginx

Des directives de configuration incorrectes peuvent amener Nginx à tenter d'écouter sur un port ou une IP indisponible, entraînant un échec de démarrage et un refus de connexion ultérieur.

1. Examiner les directives `listen`

Inspectez votre fichier de configuration principal (souvent /etc/nginx/nginx.conf) et tous les blocs serveur pertinents (généralement dans /etc/nginx/conf.d/ ou /etc/nginx/sites-enabled/). Assurez-vous que les directives listen sont correctes.

Exemple d'un bloc listen correctement configuré :

server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    # ... autres directives
}

Si Nginx est configuré pour écouter uniquement sur 127.0.0.1 (localhost) mais que vous essayez d'y accéder en utilisant l'IP publique, la connexion sera refusée.

2. Exécuter la vérification de syntaxe de configuration

Avant de redémarrer Nginx, validez toujours la syntaxe de la configuration. Une erreur d'analyse empêchera le service de démarrer, provoquant le refus.

sudo nginx -t

Si le test échoue, corrigez l'erreur identifiée, relancez le test, puis rechargez ou redémarrez Nginx.

sudo systemctl reload nginx

Phase 4 : Dépannage des problèmes de proxy inverse (amont)

Si Nginx fonctionne avec succès sur les ports 80/443, mais que l'accès à un chemin spécifique (/api/) entraîne une 'Connexion refusée', le problème se situe entre Nginx et le service backend (l'amont).

Dans ce scénario, Nginx a accepté la connexion initiale, mais lorsqu'il a tenté de proxyer la requête, la connexion au backend a été refusée. Les journaux d'erreurs le confirmeront.

1. Vérifier les journaux d'erreurs Nginx

Examinez les journaux d'erreurs Nginx (généralement /var/log/nginx/error.log) immédiatement après avoir tenté la connexion échouée. Recherchez des messages liés à la directive proxy_pass, mentionnant spécifiquement des erreurs de connexion.

tail -f /var/log/nginx/error.log

Vous pourriez voir une entrée comme :

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

2. Vérifier l'état du service backend

C'est la correction la plus courante dans les scénarios de proxy : l'application backend (par exemple, Node.js, Python Gunicorn, Apache) est arrêtée ou n'écoute pas là où Nginx l'attend.

Étapes applicables :

a. Vérifier l'état du service backend : Confirmez que l'application backend est en cours d'exécution.

b. Vérifier le port d'écoute du backend : Utilisez ss -tuln sur le serveur hébergeant le backend pour confirmer que l'application écoute sur l'IP/Port spécifié dans la directive proxy_pass de Nginx.

3. Tester la connectivité du backend directement

Testez la connexion du serveur Nginx au backend en utilisant curl ou telnet pour isoler le problème de Nginx.

Supposons que votre proxy_pass soit défini sur http://127.0.0.1:8080 :

# Tester la connexion du serveur Nginx au port backend
curl -v http://127.0.0.1:8080

# Ou en utilisant telnet
telnet 127.0.0.1 8080

Si curl ou telnet échoue : Le service backend est définitivement le problème (il n'écoute pas ou son pare-feu interne bloque l'accès à 127.0.0.1).
Si curl ou telnet réussit : Le problème pourrait être une erreur subtile dans votre directive proxy_pass (par exemple, point-virgule manquant, résolution de nom d'hôte incorrecte, ou une incompatibilité de protocole—HTTP vs. HTTPS).

Erreur courante de `proxy_pass`

Assurez-vous que l'adresse IP dans votre proxy_pass correspond à l'endroit où le backend est réellement lié. Si le backend se lie à une IP spécifique (par exemple, 192.168.1.10:8080) mais que Nginx utilise localhost:8080, la connexion échouera si la liaison est restrictive.

Vérifications finales des étapes clés de dépannage

Vérification système : Nginx est-il en cours d'exécution (systemctl status nginx) ?
Vérification du port : Nginx écoute-t-il sur l'IP/Port correct (ss -tuln) ?
Vérification du pare-feu : Le port entrant est-il ouvert sur le pare-feu de l'hôte (UFW, iptables) ?
Vérification de la configuration : nginx -t réussit-il et les directives listen sont-elles correctes ?
Vérification du proxy (si applicable) : Le service amont est-il en cours d'exécution et écoute-t-il sur l'IP/Port exact défini dans proxy_pass ? Testez la connectivité directement en utilisant curl.

Parcourez les vérifications dans l'ordre : écouteur, port, pare-feu, configuration, puis amont. Ce chemin vous permet de rester concentré sur l'endroit exact où la connexion est refusée.