E-NO Logo
EN FR
Nginx troubleshooting 10 Min Read

Dépannage Nginx avec des exemples pratiques

calendar_today Published: 2026-07-09
update Last Updated: 2026-07-09
analytics SEO Efficiency: 100%
Technical guide illustration for Dépannage Nginx avec des exemples pratiques.

Intro

Cette version française explique Nginx troubleshooting with practical examples avec le même objectif pratique que l article source : aider le lecteur à comprendre le contexte, les décisions à prendre et les points à vérifier avant de passer à l action.

Nginx est un reverse proxy et serveur web rapide et flexible, mais les incidents de production peuvent être piégeux quand les symptômes se recoupent. Ce guide propose un workflow de Nginx troubleshooting concret, avec des commandes sûres, des conseils de lecture des Nginx logs et des mini runbooks pour les pannes les plus courantes. Vous serez capable de :

  • Identifier ce qui casse et où : Nginx, le réseau ou l'application upstream.
  • Lire et filtrer access/error logs pour voir la cause et l'effet.
  • Valider la configuration en toute sécurité avant un reload.
  • Corriger des Nginx errors fréquentes : 502, 504, 413, 403, 404, et échecs de négociation TLS.
  • Appliquer la même approche sur Linux, dans Docker et avec Kubernetes Ingress.

Des exemples pratiques sont inclus pour s'exercer en local et réduire les temps d'arrêt quand cela compte. Les termes clés tels que Nginx commands et Nginx recovery sont intégrés au fil de l'article.

Vue d'ensemble du workflow

Utilisez cette boucle en production en gardant des étapes petites et observables. Chaque étape inclut des commandes concrètes et des astuces.

  1. Confirmer le symptôme
  • Relevez l'erreur exacte et le chemin d'URL. Exemple : 502 sur GET /api.
  • Reproduisez avec curl pour éviter le bruit côté client :
curl -iv http://example.com/api
curl -kiv https://example.com/secure
  1. Vérifier processus et ports
# Nginx est-il démarré ?
systemctl status nginx || service nginx status

# Écoute-t-il où vous l'attendez ?
ss -tulpn | grep -E ':80|:443'

# Qui utilise les ports s'il ne s'agit pas de Nginx ?
fuser -v 80/tcp 443/tcp || lsof -i :80 -i :443
  1. Inspecter rapidement les logs
  • Emplacements par défaut :
  • /var/log/nginx/error.log
  • /var/log/nginx/access.log
# Suivre et filtrer les erreurs récentes
tail -Fn200 /var/log/nginx/error.log | grep -iE 'error|crit|alert'

tail -Fn200 /var/log/nginx/access.log | awk '{print $1, $4, $6, $7, $9, $10}'

Astuce : augmentez temporairement le niveau de détail de l'error log dans un environnement de test :

error_log /var/log/nginx/error.log info;  # ou debug si compilé avec debug
  1. Valider la configuration en toute sécurité
# Toujours tester avant un reload
grep -RIn 'error|warn' /etc/nginx/*.conf /etc/nginx/conf.d || true
nginx -t  # vérifie la syntaxe et une sémantique de base

# Sauvegarde avant changements
cp -a /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak.$(date +%F-%H%M)
  1. Sonder l'upstream et le réseau
  • Si vous utilisez proxy_pass http://app:3000, testez la cible directement depuis l'hôte Nginx :
curl -iv http://127.0.0.1:3000/health || curl -iv http://app:3000/health

# Dans Docker : vérifiez la résolution du nom et l'accessibilité du port
# Depuis le conteneur Nginx :
docker exec -it nginx sh -lc 'getent hosts app && curl -sS http://app:3000/health'
  1. Vérifications TLS essentielles
# Afficher la chaîne de certificats et la prise en charge SNI
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates
  1. Appliquer des correctifs ciblés via les mini runbooks (ci-dessous)
  1. Recharger en toute sécurité et de façon atomique
# Re-tester, puis recharger sans couper les connexions
nginx -t && systemctl reload nginx || service nginx reload
  1. Vérifier et surveiller les régressions
curl -Is http://example.com/ | head -n1
curl -Is https://example.com/ | head -n1

# Smoke test rapide sur des chemins clés
for p in / /health /api/version; do curl -sSfo /dev/null -w '%{http_code} %{url_effective}\n' http://example.com"$p"; done
  1. Durcir pour éviter la récidive
  • Ajoutez des endpoints de santé côté upstream.
  • Réglez timeouts et buffers selon le trafic observé.
  • Centralisez les logs ; alertez sur les pics de 5xx et de 499.

Mini runbooks : erreurs Nginx courantes et correctifs

Chaque sous-section propose symptômes, contrôles de cause racine et correctifs sûrs.

502 Bad Gateway (proxy vers l'app)

Symptômes : 502 sur des routes proxifiées. error.log peut montrer une connexion upstream impossible ou fermée prématurément.

Contrôles :

# L'upstream est-il vivant ?
curl -iv http://127.0.0.1:3000/health

# Résolution DNS si proxy_pass utilise un nom
getent hosts app || dig +short app

# Exemple socket ou PHP-FPM
ls -l /run/php/php-fpm.sock && ss -xl | grep php-fpm

Pièges de configuration et correctifs :

# Vérifiez l'upstream et les en-têtes
location /api/ {
    proxy_pass http://127.0.0.1:3000/;  # attention au slash final
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_connect_timeout 5s;
    proxy_read_timeout 60s;
}
  • Si vous vous appuyez sur le DNS Docker, ajoutez un resolver dans http{} lorsque des noms peuvent changer :
resolver 127.0.0.11 valid=30s;  # DNS embarqué Docker
  • Pour PHP-FPM :
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php-fpm.sock;  # ou 127.0.0.1:9000
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

504 Gateway Timeout

Symptômes : attente longue terminant en 504.

Vérifications et correctifs :

# Augmentez les timeouts pour coller au comportement de l'upstream
proxy_connect_timeout 5s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;

# Gardez l'upstream en keepalive pour réduire la latence d'établissement
upstream app {
    server 127.0.0.1:3000;
    keepalive 16;
}

Examinez aussi les logs de l'upstream pour des requêtes lentes ou des pauses GC.

413 Request Entity Too Large

Symptômes : les uploads échouent ; error.log mentionne un corps trop volumineux.

Correctif :

# À placer dans http, server ou location selon le besoin
client_max_body_size 50m;

Rechargez et re-testez uniquement la route d'upload.

404 Not Found et 403 Forbidden

Causes fréquentes de 404 :

  • Mapping root vs alias incorrect.
  • try_files mal ordonné.
  • Surprises de précédence des location.

Causes fréquentes de 403 :

  • Fichier index manquant.
  • Droits fichiers ou contexte SELinux.

Modèles de correction :

# Fichiers statiques depuis /var/www/site/public
server {
    root /var/www/site/public;
    index index.html index.htm;

    location /images/ {
        alias /mnt/media/img/;  # alias remplace root dans ce bloc
        autoindex off;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Permissions Linux et SELinux :

# Vérifiez que l'utilisateur nginx peut lire les répertoires
namei -l /var/www/site/public/index.html

# Réparer le contexte SELinux (si activé)
sudo restorecon -R /var/www/site || sudo chcon -R -t httpd_sys_content_t /var/www/site

Échecs de handshake TLS

Symptômes : curl -k fonctionne mais les navigateurs échouent ; error.log montre des erreurs SSL ou aucun chiffrement commun.

Modèles de correction :

server {
    listen 443 ssl http2;
    server_name example.com;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    add_header Strict-Transport-Security 'max-age=31536000' always;
}

Vérifiez la chaîne et SNI :

openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates

Si vous voyez le mauvais certificat, contrôlez le server_name et qu'un seul default_server gère le 443.

Problèmes d'en-têtes 400/431 et 499 client closed request

  • En-têtes volumineux : augmentez les buffers.
large_client_header_buffers 4 16k;
underscores_in_headers on;  # si vos clients envoient des underscores
  • 499 indique que le client a fermé la connexion trop tôt. Vérifiez la latence upstream et les timeouts côté client ; réduisez le temps de réponse et la taille des corps.

WebSocket et HTTP upgrade

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

location /ws/ {
    proxy_pass http://127.0.0.1:8080/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
}

Échecs au reload ou au démarrage

Symptômes : nginx -t échoue ou le reload ne fait rien.

Contrôles :

nginx -t
journalctl -u nginx -n 100 --no-pager

# Erreurs courantes : listen dupliqué, directive inconnue, mauvais include

Conflits de ports :

ss -tulpn | grep ':80\|:443' || true
# Arrêtez l'autre processus ou changez les ports d'écoute de Nginx

Docker, Kubernetes Ingress et Linux : points d'attention

  • Docker
  • Montez la config sous /etc/nginx et testez depuis le conteneur :
docker exec -it nginx sh -lc 'nginx -t && nginx -V && ss -tulpn'
  • Assurez-vous que les noms dans proxy_pass se résolvent dans le conteneur. Envisagez d'ajouter :
resolver 127.0.0.11 valid=30s;
  • Kubernetes Ingress (NGINX controller)
  • Inspectez les logs du controller et les events :
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --tail=200
kubectl describe ingress your-ingress -n your-namespace
  • Réglez les timeouts (annotations), la taille des bodies et les proxy headers. Vérifiez que votre Service pointe vers des Pods sains et que les readinessProbes réussissent.
  • Bases Linux
  • Pare-feu : ouvrez 80 et 443 (ufw, firewalld, iptables).
  • SELinux : vérifiez les contextes du contenu et des certificats.
  • systemd : préférez reload à restart pour les changements de config.

Plan pilote local

Démarrez par un petit pilote audit-able en local. Gardez un périmètre réduit et mesurable.

Objectifs

  • Servir du contenu statique sur / et proxifier /api vers une app de démo sur 127.0.0.1:9000.
  • Déclencher à la demande des cas 502, 413 et TLS.
  • Pratiquer les reloads sûrs sans requêtes échouées pendant le changement.

Mise en place

  1. Upstream de démo
# Application de démo simple (ex. Python)
python3 -m http.server 9000 --bind 127.0.0.1 &
  1. Configuration Nginx
# /etc/nginx/conf.d/pilot.conf
server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;

    location /api/ {
        proxy_pass http://127.0.0.1:9000/;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 5m;  # ajustez pour les tests
    }
}
  1. Validation et reload
nginx -t && systemctl reload nginx || service nginx reload
  1. Cas de test
  • Parcours nominal :
curl -sS -w '%{http_code}\n' -o /dev/null http://localhost/
curl -sS -w '%{http_code}\n' -o /dev/null http://localhost/api/
  • Exercice 502 : arrêtez l'upstream, confirmez le comportement de Nginx, puis restaurez.
pkill -f 'http.server 9000' || true
curl -sS -v http://localhost/api/
python3 -m http.server 9000 --bind 127.0.0.1 &
  • Exercice 413 : uploadez un fichier plus grand que client_max_body_size et observez error.log.
head -c 10M </dev/urandom > big.bin
curl -sS -F [email protected] http://localhost/api/upload
  • Exercice TLS (optionnel) : ajoutez un certificat autosigné et un server sur 443, puis vérifiez avec openssl.
  1. Critères de succès
  • 200 pour / et /api lorsque l'upstream est disponible.
  • 502 apparaît quand l'upstream est coupé ; disparaît après restauration.
  • 413 survient pour corps trop gros ; succès après augmentation de client_max_body_size.
  • Aucun échec à nginx -t et reloads propres.
  • error.log montre clairement chaque cas de test.
  1. Retour arrière
cp -a /etc/nginx/nginx.conf.bak.* /etc/nginx/nginx.conf 2>/dev/null || true
# Ou désactivez pilot.conf puis reload
mv /etc/nginx/conf.d/pilot.conf /etc/nginx/conf.d/pilot.conf.off
nginx -t && systemctl reload nginx || service nginx reload

Conclusion

Appliquez la boucle : confirmez le symptôme, contrôlez processus et ports, lisez les logs, validez la config, testez l'upstream et TLS, appliquez un correctif ciblé, rechargez sans interrompre, puis vérifiez. Entraînez-vous avec le pilote local jusqu'à ce que chaque mini runbook devienne un réflexe. Transposez ensuite aux environnements Docker et Kubernetes Ingress : vérifiez la résolution de noms, les endpoints de santé, les timeouts et les en-têtes. Gardez des changements petits, fiez-vous aux logs et à curl pour un feedback rapide, et consignez les commandes efficaces pour que l'équipe puisse les reproduire en toute confiance.

Article Quality Score

Reader usefulness 100%
  • check_circle Reader-ready guide
  • check_circle Practical examples included
  • check_circle Clean SEO article URL