Dépannage de Nginx : Solutions courantes en ligne de commande pour les problèmes de serveur Web

Lorsque Nginx tombe en panne, les premières minutes consistent généralement à cerner le problème. Le service est-il arrêté ? Une modification de configuration a-t-elle échoué ? Un autre processus utilise-t-il déjà le port 80 ? Nginx est-il sain mais l'application en amont est-elle hors service ? La ligne de commande vous donne des réponses rapides si vous effectuez les vérifications dans le bon ordre.

J'aime commencer par les commandes les moins destructrices : inspecter l'état, tester la configuration, lire les journaux, et seulement ensuite recharger ou redémarrer. Un redémarrage peut masquer des preuves utiles, alors traitez-le comme une solution uniquement après avoir su ce que vous corrigez.

Commandes essentielles de gestion de Nginx

La première étape du dépannage consiste souvent à vérifier l'état du service Nginx lui-même. Selon votre système d'exploitation, vous interagirez généralement avec systemd ou service (SysVinit).

1. Vérification de l'état du service Nginx

Savoir si Nginx est en cours d'exécution, arrêté ou en échec est crucial. La commande status fournit cette vue d'ensemble.

Avec systemd (Courant sur les distributions Linux modernes comme Ubuntu 16.04+, CentOS 7+) :

sudo systemctl status nginx

Sortie attendue (Actif/En cours d'exécution) :

● nginx.service - A high performance web server and a reverse proxy server
   Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2023-10-24 10:00:00 UTC; 1h ago
     Docs: man:nginx(8)
 Main PID: 1234 (nginx)
    Tasks: 2 (limit: 4915)
   CGroup: /system.slice/nginx.service
           ├─1234 nginx: master process /usr/sbin/nginx -g daemon on;
           └─1235 nginx: worker process 

Si la sortie affiche Active: inactive (dead) ou Active: failed, vous savez que Nginx ne sert pas actuellement le trafic. Cela ne vous dit pas pourquoi. L'indice suivant est généralement un test de configuration ou le journal système.

sudo journalctl -u nginx -n 80 --no-pager

Cela montre les journaux de service récents, y compris les échecs de démarrage de systemd. Recherchez des messages concernant des directives inconnues, des fichiers de certificat manquants, des échecs de liaison ou des erreurs de permission.

2. Démarrer, arrêter et recharger Nginx

Une fois que vous avez identifié l'état, vous devez le gérer. Utilisez les commandes suivantes selon les besoins :

Action	Commande (avec systemctl)
Arrêter le service	sudo systemctl stop nginx
Démarrer le service	sudo systemctl start nginx
Redémarrer le service	sudo systemctl restart nginx (Arrête puis redémarre)
Recharger la configuration	sudo systemctl reload nginx (Applique les nouvelles configurations sans interrompre les connexions)

Meilleure pratique : Utilisez reload plutôt que restart Lorsque vous apportez des modifications de configuration (comme la mise à jour d'hôtes virtuels ou de certificats SSL), utilisez toujours reload. Cela applique les modifications en douceur tandis que les connexions existantes se poursuivent sans interruption. Utilisez restart uniquement si reload échoue ou si vous devez réinitialiser complètement les processus de travail.

Avant tout rechargement, exécutez :

sudo nginx -t && sudo systemctl reload nginx

Ce modèle en une ligne évite l'erreur la plus courante : recharger une configuration cassée et faire tomber un serveur en fonctionnement. Si nginx -t échoue, la commande de rechargement ne s'exécutera pas.

Validation des fichiers de configuration

La cause la plus courante d'échec de démarrage ou de comportement inattendu dans Nginx est une erreur de syntaxe dans les fichiers de configuration (nginx.conf ou les fichiers inclus dans /etc/nginx/sites-available/). Nginx fournit un excellent utilitaire de test intégré.

3. Test de la syntaxe de configuration

Le drapeau -t teste les fichiers de configuration pour les erreurs de syntaxe et vérifie si les chemins des fichiers de configuration sont valides.

sudo nginx -t

Exemple de sortie réussie :

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Exemple de sortie d'erreur :

Si une erreur existe, Nginx vous indiquera le fichier et le numéro de ligne exacts. Par exemple, un point-virgule manquant :

nginx: [emerg] unknown directive "server_name example.com" in /etc/nginx/sites-enabled/default:15
nginx: configuration file /etc/nginx/nginx.conf test failed

Ce retour immédiat vous permet d'aller directement à la ligne 15 du fichier spécifié pour corriger la faute de frappe.

Parfois, la ligne signalée est seulement l'endroit où Nginx a finalement remarqué le problème. Un } ou ; manquant peut être quelques lignes plus tôt. Si l'erreur pointe vers une directive qui semble normale, inspectez le bloc au-dessus.

4. Affichage de la configuration active

Pour voir exactement ce que Nginx exécute actuellement (particulièrement utile après plusieurs fusions de configuration ou inclusions complexes), utilisez le drapeau -T (T majuscule) :

sudo nginx -T

Cela affiche toute la configuration active, qui peut être redirigée vers un fichier pour comparaison ou révision détaillée :

sudo nginx -T > current_nginx_config.txt

Soyez prudent lorsque vous partagez la sortie de nginx -T. Elle peut inclure des noms d'hôte internes, des chemins de certificats, des en-têtes de proxy, et parfois des secrets passés comme en-têtes. Pour le travail d'incident, c'est excellent. Pour les tickets ou les discussions, anonymisez d'abord.

Vérification des ports et des écouteurs

Si Nginx ne démarre pas et que les journaux mentionnent bind() to 0.0.0.0:80 failed, un autre processus écoute peut-être déjà sur le port.

sudo ss -ltnp | grep -E ':80|:443'

La sortie typique montre l'adresse locale, le port et le nom du processus. Si Apache, Caddy, un proxy de conteneur ou un ancien processus Nginx détient le port, Nginx ne peut pas s'y lier.

Vous pouvez également confirmer le comportement public depuis le serveur lui-même :

curl -I http://127.0.0.1
curl -Ik https://127.0.0.1

-I récupère uniquement les en-têtes. -k ignore la validation du certificat, ce qui est utile lors du test de localhost avec un certificat émis pour un nom de domaine. Depuis une autre machine, testez également le nom d'hôte réel :

curl -I https://example.com

Si localhost fonctionne mais que le nom d'hôte public échoue, examinez les règles de pare-feu, les groupes de sécurité cloud, le DNS, les équilibreurs de charge ou la configuration du CDN.

Le DNS mérite d'être vérifié séparément car il peut donner l'impression qu'un serveur Nginx sain est cassé de l'extérieur :

dig +short example.com
dig +short www.example.com

Assurez-vous que l'adresse renvoyée est le serveur ou l'équilibreur de charge que vous attendez. Si vous avez récemment déplacé le site, un DNS obsolète peut envoyer certains utilisateurs vers l'ancien hôte tandis que vos propres tests atteignent le nouveau.

Surveillance et analyse des journaux

Si Nginx démarre avec succès mais sert des pages incorrectes ou renvoie des erreurs 5xx, les journaux deviennent la source principale de vérité.

5. Localisation des fichiers journaux clés

Par défaut, les journaux Nginx se trouvent généralement dans /var/log/nginx/. Les deux fichiers essentiels sont :

• access.log : Enregistre chaque requête traitée par le serveur, y compris l'IP, l'heure de la requête, le code d'état et la ressource demandée.
• error.log : Enregistre les avertissements, les notifications et les erreurs critiques rencontrés lors du fonctionnement ou du traitement des requêtes.

6. Surveillance des journaux en temps réel avec tail

Pour surveiller les erreurs en temps réel, utilisez la commande tail avec l'option de suivi (-f) sur le journal des erreurs.

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

Ceci est inestimable lors du test d'un point de terminaison d'application nouvellement déployé, car vous pouvez immédiatement voir si Nginx ou l'application en amont génère des erreurs.

Pour un serveur plus occupé, suivez uniquement les nouvelles lignes d'erreur et gardez les horodatages visibles :

sudo tail -n 50 -f /var/log/nginx/error.log

Ensuite, reproduisez la requête défaillante dans un autre terminal :

curl -I https://example.com/failing/path

Ce simple flux de travail à deux terminaux est souvent plus rapide que de cliquer dans un navigateur car chaque requête et entrée de journal peuvent être directement mises en correspondance.

7. Analyse des codes d'état du journal d'accès

Pour les problèmes de trafic élevé, une analyse rapide du journal d'accès pour les codes d'état peut révéler des problèmes :

• Codes 4xx (Erreurs client) : Indiquent souvent des liens brisés, des fichiers manquants (404) ou des problèmes de permissions.
• Codes 5xx (Erreurs serveur) : Indiquent que Nginx lui-même n'a pas pu répondre à la requête, souvent en raison de délais d'attente de connexion en amont (502/504) ou d'échecs de traitement interne du serveur (500).

Utilisez grep pour filtrer des codes spécifiques. Par exemple, trouver toutes les erreurs 502 Bad Gateway :

sudo grep ' 502 ' /var/log/nginx/access.log | tail -n 20

Un comptage rapide des codes d'état peut montrer si vous avez affaire à une seule mauvaise URL ou à un incident plus large :

sudo awk '{print $9}' /var/log/nginx/access.log | sort | uniq -c | sort -nr | head

Modèles courants :

• Les pics 404 signifient souvent un mauvais chemin de déploiement, des fichiers statiques manquants ou des routes modifiées.
• 403 pointe souvent vers des permissions de fichiers, des permissions de répertoire ou une règle d'accès intentionnelle.
• 502 signifie généralement que Nginx n'a pas pu obtenir une réponse valide du service en amont.
• 504 signifie généralement que le service en amont a accepté la connexion mais n'a pas répondu à temps.

Pour les échecs en amont, vérifiez également le service d'application :

sudo systemctl status myapp
sudo journalctl -u myapp -n 100 --no-pager

Remplacez myapp par le nom réel du service. Nginx ne peut proxyfier que ce qui est vivant et accessible.

Diagnostics avancés : Verbosité et ID de processus

8. Forcer la journalisation de débogage (Prudence conseillée)

Dans des situations très délicates, augmenter le niveau de journalisation peut révéler des informations plus détaillées sur le traitement des requêtes. Cela se fait en modifiant la directive error_log dans votre configuration en debug.

Avertissement : La journalisation de débogage génère des quantités massives de données très rapidement et ne doit être utilisée que temporairement pour un dépannage actif, car elle impacte gravement les performances.

Après avoir modifié la directive, vous devez utiliser reload ou restart Nginx pour que le changement prenne effet.

9. Trouver l'ID du processus maître Nginx (PID)

L'ID de processus (PID) est utile pour envoyer des signaux spécifiques au processus maître en cours d'exécution (par exemple, pour un arrêt gracieux ou un rechargement gracieux en dehors de systemctl). Le PID est généralement stocké dans un fichier, généralement /var/run/nginx.pid.

cat /var/run/nginx.pid
# Exemple de sortie : 1234

Vous pouvez ensuite utiliser la commande kill si nécessaire (par exemple, sudo kill -HUP 1234 pour forcer un rechargement en utilisant le PID) :

La plupart des opérateurs devraient préférer systemctl reload nginx car cela passe par le gestionnaire de services et est plus facile à auditer. Les signaux sont toujours utiles sur les systèmes minimalistes, les conteneurs ou les hôtes plus anciens où systemd ne gère pas le processus.

Corrections courantes en ligne de commande par symptôme

Si Nginx échoue après une modification de configuration :

sudo nginx -t
sudo journalctl -u nginx -n 80 --no-pager

Corrigez le fichier et la ligne signalés, puis testez à nouveau avant de recharger.

Si HTTPS échoue après le renouvellement du certificat :

sudo nginx -t
sudo ls -l /etc/letsencrypt/live/example.com/
sudo openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -noout -dates -subject

Cela confirme que le fichier de certificat existe et affiche le sujet et les dates de validité.

Si les fichiers statiques renvoient 403 :

namei -l /var/www/example.com/index.html

namei -l affiche les permissions pour chaque répertoire dans le chemin. Nginx a besoin de la permission d'exécution sur les répertoires parents et de la permission de lecture sur les fichiers.

Si un proxy inverse renvoie 502 :

sudo grep 'connect() failed' /var/log/nginx/error.log | tail
sudo ss -ltnp | grep 3000
curl -I http://127.0.0.1:3000

Cela vérifie si l'amont écoute et s'il répond localement.

Si l'amont est un socket Unix au lieu d'un port TCP, vérifiez le chemin du socket et les permissions :

sudo ls -l /run/myapp/myapp.sock
sudo grep -R "proxy_pass" /etc/nginx/sites-enabled /etc/nginx/conf.d

L'utilisateur du processus de travail Nginx a besoin de la permission d'accéder au socket. Sur de nombreux systèmes, cet utilisateur est www-data ou nginx, mais confirmez-le dans nginx.conf avant de modifier la propriété ou les groupes.

Pour les échecs intermittents, comparez les requêtes réussies et échouées dans le journal d'accès. Un petit échantillon est souvent suffisant :

sudo grep ' 504 ' /var/log/nginx/access.log | tail -n 20
sudo grep ' 200 ' /var/log/nginx/access.log | tail -n 20

Recherchez des modèles dans les chemins, les champs de temps de réponse en amont si votre format de journal les inclut, ou une IP client spécifique qui déclenche des requêtes lourdes.

Flux de travail de dépannage

Face à un problème Nginx, suivez cette séquence :

1. Vérifier l'état : sudo systemctl status nginx.
2. Tester la configuration : En cas d'échec au démarrage, exécutez sudo nginx -t. Corrigez les erreurs signalées.
3. Redémarrer/Recharger : Si la configuration a été modifiée, utilisez sudo systemctl reload nginx.
4. Surveiller les journaux : Si le service fonctionne mais est cassé, utilisez sudo tail -f /var/log/nginx/error.log tout en reproduisant le problème.
5. Analyser l'accès : Examinez access.log pour les codes d'état indiquant la nature de l'échec (4xx vs 5xx).

Cet ordre vous évite de deviner. L'état vous indique si Nginx est en cours d'exécution, les tests de configuration vous indiquent s'il peut se charger, les journaux vous indiquent ce qui s'est passé lors des requêtes réelles, et les vérifications curl locales séparent les problèmes Nginx des problèmes en amont ou réseau.

Gardez une courte note d'incident pendant que vous travaillez : commande exécutée, résultat observé et modification effectuée. Cela évite les vérifications répétées et facilite grandement le transfert.