Ce guide concerne NGINX Open Source. Vérifiez la version, les modules compilés ou chargés et les particularités de votre paquet.
Séparer les deux échanges HTTP
NGINX reçoit une requête client puis construit une requête vers un serveur upstream. Le protocole, l’URI et les en-têtes ne sont pas nécessairement identiques entre les deux côtés. Pour expliquer un problème, notez ce que le client demande, ce que NGINX transmet et ce que le serveur reçoit.
proxy_set_header modifie les en-têtes de la requête upstream. add_header concerne les en-têtes de réponse au client, avec son propre comportement selon le statut et l’héritage. Les confondre peut produire une réponse qui semble correcte tout en laissant l’application recevoir un Host inattendu.
Le proxy sélectionne une location, construit une requête upstream puis transmet une réponse. Les en-têtes de requête et de réponse appartiennent à deux opérations différentes.
Télécharger le schéma en SVG · version claireSources : NGINX / F5, Module ngx_http_proxy_module ; NGINX / F5, Module ngx_http_core_module.
Vérifier la transformation de l’URI
Une URI présente dans proxy_pass remplace la partie normalisée qui correspond à la location dans les cas documentés. Sans cette URI, la transmission suit une autre règle. Les regex, locations nommées et réécritures ajoutent des contraintes ; le slash final ne se résume pas à un choix esthétique.
Le fragment pédagogique conserve le préfixe /api/ car proxy_pass ne contient pas d’URI. Les en-têtes de provenance ne sont fiables que si la chaîne de proxies et sa politique de confiance sont définies. Ne transformez pas une valeur fournie par un client en preuve d’identité.
Un upstream peut aussi être joint par un socket Unix dans la syntaxe documentée de proxy_pass. Dans ce cas, le chemin du socket et les permissions de son processus remplacent une partie du diagnostic adresse/port. Précisez toujours quelle frontière transporte la requête avant de chercher une panne réseau.
location /api/ {
proxy_pass http://127.0.0.1:9000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}Sources : NGINX / F5, Module ngx_http_proxy_module.
Chiffrement et authentification upstream
Utiliser une URL HTTPS pour l’upstream chiffre cet échange ; la vérification du certificat doit aussi être configurée. Examinez proxy_ssl_verify, l’autorité de confiance, le nom vérifié et l’envoi du SNI. Le certificat peut être valide mais concerner un autre nom que celui utilisé par le proxy.
Identifiez également les timeouts et le buffering selon le comportement applicatif. Un upload, un flux long ou une réponse volumineuse demande une analyse différente d’un petit fichier. Une augmentation globale du timeout peut retarder la détection d’un serveur défaillant au lieu de corriger le problème.
Sources : NGINX / F5, Module ngx_http_proxy_module ; NGINX / F5, Module ngx_http_ssl_module.
Exercice : une API dont le chemin change
Un backend attend /api/health, mais observe /health. Comparez le couple location/proxy_pass, puis les éventuelles réécritures. Testez une seule URI avec un Host contrôlé et confrontez les logs des deux côtés ; évitez une correction par essai de plusieurs slashs sans expliquer la transformation.
Dans votre compte rendu, distinguez URI, Host, adresse de provenance et certificat upstream. Chacune de ces propriétés répond à une question différente. Pour une répartition entre plusieurs serveurs, continuez avec le guide des upstreams.
Sources : NGINX / F5, Module ngx_http_proxy_module ; NGINX / F5, Module ngx_http_log_module.
Sources et portée
Les dates de consultation et les versions applicables sont précisées pour chaque référence ci-dessous. Les exemples utilisent des noms et adresses de documentation à remplacer. Les commandes de lecture affichent l’existant ; les captures et requêtes de diagnostic sont à limiter au périmètre autorisé.
- NGINX / F5 — Module ngx_http_proxy_module · Référence officielle ; vérifier le périmètre de version · consulté le 3 octobre 2026.
- NGINX / F5 — Module ngx_http_core_module · Référence officielle ; vérifier le périmètre de version · consulté le 3 octobre 2026.
- NGINX / F5 — Module ngx_http_ssl_module · Référence officielle ; vérifier le périmètre de version · consulté le 3 octobre 2026.
- NGINX / F5 — Module ngx_http_log_module · Référence officielle ; vérifier le périmètre de version · consulté le 3 octobre 2026.
Retrouver le parcours de lecture F5 NGINX