Architecture de Nginx expliquée : du flux de données au durcissement en production

Introduction

Lorsqu'une requête web atteint Nginx, elle traverse une série de composants soigneusement conçus avant qu'une réponse ne soit renvoyée. Comprendre ce parcours, de la connexion initiale au dernier octet, distingue une configuration fonctionnelle d'un déploiement résilient et performant.

Ce guide explore l'architecture de Nginx avec des exemples pratiques. Vous apprendrez comment les processus maître et worker coopèrent, comment Nginx gère des milliers de connexions sans créer de threads, et comment vérifier, optimiser et récupérer votre configuration en toute sécurité. Chaque paramètre et commande est limité à une version et testé avec Nginx 1.24.x, la version stable au moment de la rédaction, avec des notes sur la compatibilité ascendante lorsque cela est pertinent.

Nous passerons de l'observation à l'intervention : d'abord inspecter sans rien modifier, puis effectuer la plus petite modification justifiée, vérifier le succès et planifier la récupération en cas de problème. Cette approche minimise les risques tout en vous offrant un modèle mental solide du fonctionnement interne de Nginx.

Inventaire de la version et de l'environnement

Avant de modifier un paramètre Nginx, vous devez avoir une vision claire de votre environnement actuel : version installée, options de compilation, chemins de configuration et modèle de processus à l'exécution. Cette section couvre les commandes en lecture seule qui établissent cette base de référence.

Pourquoi inventorier d'abord

Un Nginx mal configuré peut entraîner des temps d'arrêt, des failles de sécurité ou des régressions de performance. Connaître votre état initial vous permet de :

• Identifier si une fonctionnalité est disponible dans votre version installée
• Détecter une dérive entre le processus en cours et la configuration sur disque
• Revenir à un état connu et fonctionnel si une modification échoue
• Cloner la configuration pour des tests en environnement de préproduction sans incertitude

Inspecter la version installée et les options de compilation

Exécutez la commande suivante pour afficher la version et les options de compilation non par défaut :

sudo nginx -V 2>&1 | tr ' ' '\n' | grep -E 'nginx/|--with|--without'

Sortie attendue sur Ubuntu 24.04 avec le dépôt officiel Nginx :

nginx/1.24.0
--with-http_ssl_module
--with-http_v2_module
--with-http_realip_module
--with-stream

La sortie complète inclut tous les modules compilés. Comparez cette liste aux modules requis par votre configuration. Par exemple, si vous utilisez la compression gzip, assurez-vous que --with-http_gzip_static_module apparaît ; sinon, gzip_static on échouera silencieusement.

Localiser les fichiers de configuration

Nginx utilise un fichier de configuration principal et des fichiers inclus facultatifs. Déterminez les chemins avec :

sudo nginx -t 2>&1 | grep 'configuration file'

Sortie typique :

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

La commande de test lit la configuration et indique l'ordre d'inclusion. Pour voir chaque fichier chargé, utilisez :

sudo nginx -T 2>&1 | grep '# configuration file'

La sortie attendue liste chaque fichier dans l'ordre où Nginx les inclut :

# configuration file /etc/nginx/nginx.conf:
# configuration file /etc/nginx/mime.types:
# configuration file /etc/nginx/conf.d/default.conf:

Cela est précieux lorsque vous avez plusieurs directives include et devez savoir quel fichier en remplace un autre.

Examiner les processus en cours d'exécution

Nginx s'exécute sous deux types de processus : un processus maître unique et un ou plusieurs processus worker. Le maître s'exécute en tant que root et gère le chargement de la configuration et le cycle de vie des workers. Les workers s'exécutent en tant qu'utilisateur non privilégié (souvent www-data ou nginx) et gèrent le trafic réseau.

Utilisez ps pour voir la hiérarchie des processus :

ps -eo pid,ppid,user,cmd --forest | grep nginx

Sortie attendue sur une installation minimale :

root       1234     1  0  10:05 ?        00:00:00 nginx: master process /usr/sbin/nginx
www-data   1235  1234  0  10:05 ?        00:00:00 nginx: worker process
www-data   1236  1234  0  10:05 ?        00:00:00 nginx: worker process

Si votre sortie ne montre que le processus maître ou aucun worker, Nginx a peut-être échoué à démarrer les workers en raison d'une erreur de configuration ou d'un problème de permission. Consultez le journal des erreurs pour plus de détails.

Liste de vérification de l'inventaire

Utilisez cette liste avant toute modification :

• [ ] Enregistrer la version et les options de compilation de Nginx avec nginx -V
• [ ] Confirmer le chemin du fichier de configuration principal avec nginx -t
• [ ] Lister tous les fichiers de configuration inclus avec nginx -T
• [ ] Vérifier le modèle de processus avec ps -eo pid,ppid,user,cmd --forest | grep nginx
• [ ] Copier horodatée de /etc/nginx/ vers un répertoire de sauvegarde

Chemin de configuration sécurisé

Une fois que vous connaissez votre environnement, vous pouvez effectuer des modifications en toute sécurité. La règle d'or : tester avant de recharger, recharger avant de redémarrer, et conserver une copie de restauration.

Validation de la syntaxe de configuration

Exécutez toujours le contrôle de syntaxe avant d'appliquer une modification :

sudo nginx -t

Sortie de succès attendue :

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

En cas d'erreur, Nginx affiche le fichier et le numéro de ligne :

nginx: [emerg] unknown directive "sever_name" in /etc/nginx/conf.d/example.conf:5
nginx: configuration file /etc/nginx/nginx.conf test failed

Cela empêche l'application d'une mauvaise configuration au serveur en cours d'exécution.

Effectuer une modification minimale : exemple du nombre de workers

Supposons que vous souhaitiez ajuster le nombre de processus worker pour correspondre aux cœurs CPU. Tout d'abord, trouvez le paramètre actuel :

grep -E 'worker_processes' /etc/nginx/nginx.conf

Sortie attendue :

worker_processes auto;

Si vous vous attendez à ce que auto crée un worker par cœur, vérifiez avec nproc :

nproc

Sortie attendue sur une VM à 4 cœurs :

4

Maintenant, changez la directive en un nombre fixe, par exemple 2, à l'aide d'un éditeur de texte :

sudo nano /etc/nginx/nginx.conf

Remplacez worker_processes auto; par worker_processes 2;, puis enregistrez et quittez.

Avant de recharger, testez la configuration :

sudo nginx -t

Si le test réussit, rechargez avec :

sudo systemctl reload nginx

Vérifiez que le nouveau nombre de workers est actif :

ps -eo pid,ppid,user,cmd --forest | grep nginx

La sortie attendue montre maintenant deux processus worker.

Pour revenir en arrière, inversez la modification et exécutez à nouveau les commandes de test et de rechargement.

Rayon d'impact et planification de la récupération

Chaque modification a un rayon d'impact : l'ensemble des processus, connexions ou comportements qui peuvent être affectés. Pour worker_processes, sa modification nécessite un rechargement, qui redémarre gracieusement les workers. Les connexions existantes sont gérées par les anciens workers jusqu'à leur fermeture, mais les nouvelles connexions utilisent les nouveaux workers.

Si un rechargement échoue, Nginx continue de fonctionner avec l'ancienne configuration. Cependant, si vous redémarrez au lieu de recharger, tous les workers sont arrêtés et les connexions sont interrompues. Préférez reload pour les modifications de configuration et restart uniquement lorsque le processus lui-même ne répond plus.

Conservez toujours une sauvegarde horodatée de la configuration avant de modifier :

sudo cp -r /etc/nginx /etc/nginx.backup.$(date +%Y%m%d_%H%M%S)

Cela vous donne un chemin de retour direct : copiez la sauvegarde sur la configuration active et rechargez.

Extrait de configuration : ajustement du bloc events

Le bloc events contrôle le nombre de connexions simultanées que chaque worker peut gérer. Un ajustement courant :

events {
    worker_connections 1024;
}

Pour augmenter à 2048, modifiez le fichier et exécutez nginx -t. Le nombre total maximal de connexions devient worker_processes * worker_connections. Avec 2 workers et 1024 connexions chacun, Nginx peut gérer 2048 connexions simultanées. Ajustez les deux paramètres ensemble pour atteindre votre capacité cible.

Vérification et diagnostics

Après avoir appliqué une configuration, vous devez vérifier que Nginx se comporte comme prévu dans des conditions de trafic réelles. Cette section couvre les outils de diagnostic disponibles sans surveillance externe.

Vérification des journaux d'accès et d'erreurs

Nginx enregistre chaque requête dans le journal d'accès et chaque problème dans le journal d'erreurs. Localisez leurs chemins :

grep -rE 'access_log|error_log' /etc/nginx/nginx.conf /etc/nginx/conf.d/

Sortie typique :

access_log /var/log/nginx/access.log;
error_log /var/log/nginx/error.log;

Suivez les journaux en direct tout en envoyant des requêtes de test :

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

Envoyez ensuite une requête avec curl :

curl -I http://localhost

L'entrée de journal d'accès attendue inclut la ligne de requête et le code d'état :

127.0.0.1 - - [25/Jul/2025:10:15:23 +0000] "HEAD / HTTP/1.1" 200 0 "-" "curl/8.5.0"

Le code d'état 200 indique un succès. Pour les erreurs, cherchez dans le journal d'erreurs avec grep :

sudo grep 'error' /var/log/nginx/error.log

La sortie attendue est vide si aucune erreur récente ne s'est produite.

Surveillance des connexions actives et de l'état

Nginx peut exposer une page d'état pour les métriques en temps réel. Activez-la dans un bloc serveur ou une location :

location /nginx_status {
    stub_status on;
    access_log off;
    allow 127.0.0.1;
    deny all;
}

Après rechargement, demandez la page d'état :

curl http://localhost/nginx_status

Sortie attendue :

Active connections: 3
server accepts handled requests
 1234 1234 5678
Reading: 0 Writing: 1 Waiting: 2

Cela montre trois connexions actuelles, une en cours de traitement et deux connexions keep-alive inactives. Si Active connections est systématiquement proche de votre limite de connexions worker, vous devrez peut-être augmenter worker_connections ou ajouter des workers.

Test du comportement de proxy inverse

Si Nginx agit comme proxy inverse, vérifiez qu'il transmet correctement les requêtes. Exemple de configuration de proxy :

location /app/ {
    proxy_pass http://127.0.0.1:8080/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Testez avec une requête incluant des en-têtes :

curl -v http://localhost/app/

La sortie attendue montre une réponse du backend. Pour inspecter les en-têtes que Nginx envoie au backend, enregistrez-les temporairement sur le backend ou utilisez tcpdump :

sudo tcpdump -i lo -A -s 0 'tcp port 8080 and (((ip[2:2] - ((ip[0]&0xf)<<2)) - ((tcp[12]&0xf0)>>2)) != 0)'

Cela capture la requête HTTP telle qu'envoyée par Nginx. Cherchez Host: yourdomain.com et X-Real-IP: client-ip pour confirmer la transmission correcte des en-têtes.

Liste de vérification des diagnostics

Après chaque modification, parcourez cette liste :

• [ ] Vérifier le journal d'erreurs Nginx pour de nouvelles entrées
• [ ] Envoyer une requête de test et confirmer le code d'état attendu
• [ ] Surveiller /nginx_status si activé et comparer les tendances
• [ ] Vérifier que les en-têtes de proxy atteignent correctement le backend
• [ ] Exécuter à nouveau nginx -t après toute modification supplémentaire

Modes de défaillance et récupération

Malgré une planification minutieuse, des problèmes peuvent survenir. Cette section couvre les scénarios de défaillance courants et comment récupérer avec un minimum de temps d'arrêt.

Scénario 1 : Erreur de syntaxe de configuration

Défaillance : Vous modifiez la configuration et exécutez nginx -t, mais obtenez une erreur de syntaxe.

Pourquoi cela arrive : Un point-virgule manquant, une directive mal orthographiée ou des accolades déséquilibrées sont introduits.

Récupération : Le message d'erreur indique le fichier et la ligne. Ouvrez cet emplacement, corrigez l'erreur et exécutez à nouveau nginx -t. N'appliquez pas la configuration tant que le test ne réussit pas.

Si vous avez déjà rechargé avec la mauvaise configuration (ce qui ne devrait pas arriver si vous testez d'abord), Nginx aurait rejeté le rechargement et continué à fonctionner avec l'ancienne configuration. Vous pouvez simplement corriger l'erreur et recharger à nouveau.

Scénario 2 : Crash des processus worker

Défaillance : Un ou plusieurs processus worker meurent de manière inattendue.

Pourquoi cela arrive : Épuisement de la mémoire, erreur de segmentation due à un module bogué, ou arrêt intentionnel.

Récupération : Le processus maître réapparaît automatiquement les workers. Vérifiez le journal d'erreurs pour des indices :

sudo grep 'worker process' /var/log/nginx/error.log

Sortie attendue (si un crash s'est produit) :

2025/07/25 11:20:00 [alert] 1234#1234: worker process 1236 exited on signal 11

Le signal 11 est une erreur de segmentation. Enquêtez sur le module ou la configuration qui l'a déclenchée. Si un module personnalisé a causé le problème, envisagez de revenir à une version connue comme fonctionnelle.

Scénario 3 : Backend indisponible

Défaillance : Nginx renvoie 502 Bad Gateway pour les requêtes de proxy inverse.

Pourquoi cela arrive : Le serveur en amont est en panne, ne répond pas, ou l'URL proxy_pass est incorrecte.

Récupération : Vérifiez le journal d'erreurs :

sudo grep 'upstream' /var/log/nginx/error.log

Sortie attendue :

2025/07/25 11:30:00 [error] 1235#1235: *1 connect() failed (111: Connection refused) while connecting to upstream, client: 192.168.1.10, server: example.com, request: "GET /app/ HTTP/1.1", upstream: "http://127.0.0.1:8080/app/"

Cela vous indique que le backend à 127.0.0.1:8080 a refusé la connexion. Démarrez le service backend, puis réessayez la requête. Pour éviter des temps d'arrêt prolongés, configurez Nginx avec un serveur de secours :

upstream backend {
    server 127.0.0.1:8080;
    server 127.0.0.1:8081 backup;
}

location /app/ {
    proxy_pass http://backend;
}

Lorsque le serveur principal est en panne, Nginx utilise le serveur de secours.

Scénario 4 : Disque plein pour les journaux

Défaillance : Nginx ne peut pas écrire les journaux et le trafic est affecté.

Pourquoi cela arrive : Les fichiers journaux consomment tout l'espace disque disponible.

Récupération : Tout d'abord, libérez de l'espace :

sudo truncate -s 0 /var/log/nginx/access.log
sudo truncate -s 0 /var/log/nginx/error.log

Ensuite, configurez la rotation des journaux si elle n'est pas déjà en place :

sudo logrotate -vf /etc/logrotate.d/nginx

Pour éviter la récurrence, surveillez l'utilisation du disque et configurez une tâche cron pour alerter lorsque l'utilisation dépasse 80 %.

Vérification de la récupération

Après avoir récupéré d'une défaillance, vérifiez que Nginx sert correctement le trafic :

curl -I http://localhost

La sortie attendue inclut HTTP/1.1 200 OK. De plus, vérifiez le journal d'erreurs pour toute nouvelle entrée depuis la récupération.

Liste de vérification opérationnelle

Cette liste condense les pratiques opérationnelles essentielles pour Nginx. Utilisez-la avant, pendant et après toute modification.

Liste de vérification avant modification

• [ ] Enregistrer la version et la compilation actuelles avec nginx -V
• [ ] Sauvegarder le répertoire de configuration avec horodatage
• [ ] Identifier la directive spécifique à modifier et sa valeur actuelle
• [ ] Vérifier la documentation pour le contexte pris en charge et les valeurs possibles de la directive dans votre version de Nginx
• [ ] Planifier la commande de vérification et la sortie attendue

Liste de vérification de l'exécution des modifications

• [ ] Modifier le fichier de configuration avec un éditeur de texte
• [ ] Exécuter nginx -t pour valider la syntaxe
• [ ] Si le test échoue, corriger les erreurs et retester
• [ ] Si le test réussit, recharger avec systemctl reload nginx
• [ ] Surveiller le journal d'erreurs pour des messages inattendus pendant le rechargement

Liste de vérification après modification

• [ ] Confirmer que la modification est active en inspectant la sortie pertinente (par exemple, liste des processus, page d'état ou en-têtes de réponse)
• [ ] Envoyer des requêtes de test à tous les hôtes virtuels affectés
• [ ] Vérifier les journaux d'accès et d'erreurs pour des anomalies
• [ ] Si la performance est affectée, comparer les métriques avant et après
• [ ] Documenter la modification dans votre système de gestion des changements avec le propriétaire et la date de révision

Attribuez un responsable unique pour chaque élément de la liste lorsque vous travaillez en équipe. Par exemple :

• Sauvegardes de configuration : Ingénieur DevOps, Priya Shah
• Test de syntaxe : Développeur d'application, Marco Rossi
• Rechargement en production : Administrateur système, Lena Fischer
• Surveillance des journaux : SRE, Alex Johnson

Révisez cette liste mensuellement pour l'ajuster aux nouvelles versions, aux changements de rôles d'équipe ou à l'évolution des modèles de trafic.

Pièges courants et comment les éviter

Même les administrateurs expérimentés tombent dans ces pièges. Reconnaissez-les tôt pour garder votre déploiement Nginx stable.

Piège 1 : Ignorer nginx -t

Pourquoi cela arrive : Se précipiter pour déployer un correctif sans tester.

Conséquence : Un rechargement échoue et laisse le serveur fonctionner avec l'ancienne configuration, ou pire, un redémarrage applique une configuration cassée et tout le trafic s'arrête.

Évitement : Faites de nginx -t une étape obligatoire dans votre script de déploiement. Appliquez-le avec un hook de pré-commit ou un pipeline CI qui rejette les configurations invalides.

Piège 2 : Surcharger les connexions worker

Pourquoi cela arrive : Définir worker_connections trop bas par rapport au trafic attendu.

Conséquence : Nginx met en file d'attente ou abandonne les connexions lorsque la limite est atteinte, provoquant des délais d'attente et des erreurs.

Évitement : Calculez la capacité en utilisant worker_processes * worker_connections. Surveillez les Active connections via stub_status. Augmentez les limites lors des tests de charge et vérifiez avec ab ou wrk.

Piège 3 : Coder en dur les IP en amont sans contrôles de santé

Pourquoi cela arrive : Utiliser des IP directes dans proxy_pass sans bloc upstream.

Conséquence : Si l'IP du backend change ou si le serveur tombe en panne, Nginx continue d'y envoyer des requêtes jusqu'à une mise à jour manuelle.

Évitement : Définissez un bloc upstream avec plusieurs serveurs et activez les contrôles de santé actifs :

upstream backend {
    server 192.168.1.10:8080 max_fails=3 fail_timeout=30s;
    server 192.168.1.11:8080 max_fails=3 fail_timeout=30s;
}

Nginx marque temporairement un serveur comme hors service après trois échecs, dirigeant le trafic vers le serveur sain.

Piège 4 : Stocker des secrets dans les fichiers de configuration sans protection

Pourquoi cela arrive : Commodité ou manque de sensibilisation.

Conséquence : Les mots de passe ou clés API dans /etc/nginx/ peuvent être lisibles par des utilisateurs non privilégiés ou exposés dans les sauvegardes.

Évitement : Définissez des permissions restrictives :

sudo chmod 600 /etc/nginx/sites-available/private.conf
sudo chown root:root /etc/nginx/sites-available/private.conf

Utilisez des variables d'environnement ou des outils de gestion des secrets lorsque c'est possible, et ne commitez jamais de secrets dans le contrôle de version.

Piège 5 : Oublier de faire tourner les journaux

Pourquoi cela arrive : Supposer que la configuration logrotate par défaut est adéquate.

Conséquence : Le disque se remplit, Nginx ne parvient pas à écrire les journaux et les performances du système se dégradent.

Évitement : Vérifiez les paramètres logrotate et exécutez un test à blanc :

sudo logrotate -d /etc/logrotate.d/nginx

La sortie attendue montre les actions sans modifier réellement les fichiers. Ajustez la taille et la rétention en fonction de votre trafic.

Conclusion

L'architecture de Nginx, un processus maître avec des workers pilotés par événements, lui permet de gérer des milliers de connexions simultanées avec une faible empreinte mémoire. Comprendre comment ces pièces s'assemblent vous permet de configurer, vérifier et récupérer en toute confiance.

Vous disposez maintenant d'un flux de travail complet :

1. Inventoriez votre environnement avec des commandes en lecture seule
2. Effectuez des modifications minimales, limitées à une version, après test
3. Vérifiez le comportement avec les journaux, les pages d'état et les requêtes en direct
4. Récupérez rapidement des modes de défaillance courants
5. Évitez les pièges typiques grâce à des pratiques proactives

Comme prochaine étape, choisissez une amélioration à faible risque de ce guide, comme activer stub_status ou ajuster worker_connections, et appliquez la liste de vérification complète. Enregistrez l'état actuel, effectuez la modification, vérifiez le résultat et documentez le chemin de retour. Cette approche disciplinée transforme Nginx d'une boîte noire en un composant transparent et contrôlable de votre infrastructure.

Pour une exploration plus approfondie, consultez la documentation officielle de Nginx pour votre version, en particulier les sections sur les directives de base, le proxy inverse et l'équilibrage de charge.