Français

English
Русский
Deutsch

Français

English
Русский
Deutsch

Thème

Nginx. Configurer les règles (location) d’un hôte virtuel ​

Les règles (blocs location) définissent la façon dont Nginx traite les requêtes selon les chemins d’URL d’un hôte virtuel. Elles permettent d’activer PHP, de configurer un proxy vers un autre service, de limiter l’accès par IP, de redéfinir le dossier racine d’un sous-chemin et de régler d’autres paramètres. Cet article vous concerne si vous avez déjà créé un hôte virtuel en suivant l’article Nginx. Hôtes virtuels en mode constructeur et souhaitez configurer le bloc « Options supplémentaires » du formulaire. Si le formulaire ne couvre pas votre cas (par exemple les directives rewrite, if ou map), utilisez le mode expert.

Où se trouvent les règles ​

Sur la page de création ou de modification d’un hôte virtuel, sous les champs principaux, déroulez le bloc « Options supplémentaires » et cliquez sur « Ajouter une règle » : le panneau vous propose de choisir un modèle et crée une fiche. L’ordre des fiches dans le formulaire correspond à l’ordre des blocs dans server.

Modèles de règles ​

Lorsque vous ajoutez une règle, vous choisissez l’un des modèles. Le modèle détermine quels champs spécifiques apparaissent dans la fiche et quelles directives Nginx se retrouvent dans le bloc location final. La règle racine est toujours présente dans l’hôte et se crée automatiquement : son modèle ne peut pas être changé ; pour les autres, le modèle se choisit à la main.

Règle racine ​

La règle racine correspond au bloc location / de la configuration Nginx. Toutes les requêtes qui ne correspondent à aucune règle plus spécifique passent par elle. Sa fiche est toujours la première du formulaire ; le chemin est fixé à /, le sélecteur de modèle n’est pas affiché et il n’y a pas de bouton de suppression. Seuls le commutateur « Activée / Désactivée » et les paramètres universels sont disponibles.

Par défaut, la règle racine a déjà ces paramètres :

  • « Fichiers (try_files) » = $uri $uri/ =404 — le schéma standard pour servir des fichiers statiques : Nginx cherche d’abord le fichier demandé, puis le dossier, sinon il répond par une erreur 404.
  • « Taille max. de la requête » = 10m — limite de taille du corps de la requête.

Chacun de ces paramètres par défaut peut être modifié ou supprimé ; les autres paramètres universels s’ajoutent de la manière habituelle. Vous pouvez aussi désactiver la règle racine elle-même avec le commutateur (voir Activer et désactiver une règle), par exemple pour décrire entièrement le traitement de la racine avec des règles distinctes ou des paramètres universels.

Simple ​

Le modèle « Simple » est un bloc location vide, avec un « chemin » libre et un ensemble de paramètres universels. Il n’a aucun champ spécifique : son comportement se configure en ajoutant des paramètres. Cas d’usage typiques :

  • limiter l’accès par IP au répertoire /admin/ ;
  • redéfinir le dossier racine pour /static/ ;
  • définir un expires long pour les ressources statiques ;
  • bloquer l’accès aux fichiers de service comme .git.
Exemple détaillé : une règle pour un répertoire de fichiers statiques

Supposons que, dans le formulaire d’une règle « Simple », le chemin soit /static/ et que vous ayez ajouté avec « Ajouter un paramètre » les paramètres « Durée du cache (expires) » = 30d, « Taille max. de la requête » = 10m et « Autoriser l’accès (allow) » = all. Le fichier *.conf obtenu contiendra à peu près ce bloc :

nginx
location /static/ {
    expires 30d;
    client_max_body_size 10m;
    allow all;
}

Le modèle « Simple » n’ajoute lui-même aucune directive au bloc : on y retrouve uniquement ce que vous avez défini dans les paramètres.

PHP (FastCGI) ​

Le modèle « PHP (FastCGI) » configure la transmission des requêtes à PHP-FPM — le scénario habituel pour WordPress, Laravel et les autres applications PHP. Lorsque vous choisissez ce modèle, le champ « Chemin » se remplit automatiquement avec l’expression régulière ~ \.php$, qui correspond à toutes les requêtes se terminant par .php. Dans la plupart des cas, il n’est pas nécessaire de la modifier.

Si au moins une règle de l’hôte utilise le modèle PHP (FastCGI), BeAdmin place automatiquement index.php en tête de la liste des fichiers d’index de l’hôte. Quand cette règle est supprimée, index.php est retiré de la liste, lui aussi automatiquement.

Version de PHP ​

La version de PHP est un champ propre à ce modèle. Selon la version choisie, BeAdmin insère dans la configuration le chemin du socket FPM correspondant : unix:/var/run/php/php<X.Y>-fpm.sock. Si la version choisie n’est pas encore installée sur le système, vous pouvez l’installer directement depuis ce champ : inutile d’aller dans la section PHP.

💡 Ce que le panneau ajoute en plus de vos paramètres

Outre fastcgi_pass pour la version de PHP choisie, BeAdmin ajoute au bloc un jeu standard de directives FastCGI : fastcgi_split_path_info, try_files $fastcgi_script_name =404, include fastcgi_params et les fastcgi_param de base. Comme try_files est fixé, le paramètre « Fichiers (try_files) » que vous ajoutez est ignoré dans le modèle PHP : inutile de le définir.

Exemple détaillé : une règle PHP dans la configuration finale

Supposons que, dans le formulaire d’une règle PHP, le chemin soit ~ \.php$, que PHP 8.3 soit sélectionné et que vous ayez ajouté avec « Ajouter un paramètre » les paramètres « Taille max. de la requête » = 64m et « Durée du cache (expires) » = 1h. Le fichier *.conf obtenu contiendra à peu près ce bloc :

nginx
location ~ \.php$ {
    # Paramètres du formulaire
    client_max_body_size 64m;
    expires 1h;

    # Socket PHP-FPM de la version choisie
    fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;

    # Habillage FastCGI standard ajouté par BeAdmin
    fastcgi_split_path_info ^(.+?\.php)(/.*)$;
    try_files $fastcgi_script_name =404;
    set $path_info $fastcgi_path_info;
    include fastcgi_params;

    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO       $path_info;
    fastcgi_param PATH_TRANSLATED $document_root$path_info;
    fastcgi_param HTTP_PROXY      "";
}

Les deux premières directives sont les paramètres que vous avez ajoutés dans le formulaire. Tout le reste, BeAdmin l’insère d’après la version de PHP choisie et le modèle standard de traitement FastCGI.

Proxy inverse ​

Le modèle « Proxy inverse » transforme le bloc location en proxy inverse : les requêtes du chemin choisi sont envoyées vers un backend interne (un autre Nginx, Apache sur 127.0.0.1:8808, une application Node, un conteneur Docker). Le champ « Chemin » est vidé lorsque vous choisissez ce modèle : renseignez-le vous-même. Le plus souvent, il s’agit de /, /api ou ^~ /api/.

Proxy vers (proxy_pass) ​

Dans le champ « Proxy vers (proxy_pass) », indiquez l’URL du backend — par exemple http://127.0.0.1:8080 ou https://api.internal.example.com/v2. Cette valeur est reprise dans la directive proxy_pass. Le champ est obligatoire : sans lui, la règle ne s’enregistre pas.

En-têtes ​

Dans la sous-section « En-têtes », vous définissez des en-têtes HTTP supplémentaires que Nginx transmet au backend via proxy_set_header. Le bouton « Ajouter un en-tête » ajoute une paire « nom — valeur ». Le nom se choisit dans une liste prédéfinie : Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, Connection, Upgrade, Accept-Encoding, Accept-Language, Authorization, Content-Type, Content-Length, User-Agent, Referer, Origin, Cache-Control, Cookie, Set-Cookie. Si l’en-tête voulu ne figure pas dans la liste, la seule solution est le mode expert.

Jeu typique pour l’association Nginx + Apache : Host = $host, X-Real-IP = $remote_addr, X-Forwarded-For = $proxy_add_x_forwarded_for, X-Forwarded-Proto = $scheme.

Exemple détaillé : proxy vers une application Node locale

Supposons que, dans le formulaire d’une règle « Proxy inverse », le chemin soit /, que « Proxy vers (proxy_pass) » vaille http://127.0.0.1:8080 et que vous ayez ajouté avec « Ajouter un en-tête » les paires Host = $host et X-Real-IP = $remote_addr. Le fichier *.conf obtenu contiendra à peu près ce bloc :

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

Le modèle « Proxy inverse » n’ajoute au bloc que proxy_pass et les proxy_set_header des en-têtes listés ; tout le reste se configure avec les paramètres universels ou le mode expert.

Paramètres universels ​

Tous les modèles ont une sous-section commune « Paramètres » avec le même ensemble de clés. Le bouton « Ajouter un paramètre » permet de choisir une clé dans la liste ; une même clé ne peut pas être ajoutée deux fois à une même fiche. Le tableau indique ce que chaque paramètre signifie dans la configuration Nginx et comment le formulaire le vérifie.

Paramètre du formulaireDans *.confRôle et contrôles appliqués
« Autoriser l’accès (allow) »allow <valeur>;Liste des adresses autorisées. Chaque valeur est une adresse IPv4 (192.168.1.100), un réseau CIDR (192.168.1.0/24, masque de 0 à 32) ou le mot-clé all. Plusieurs valeurs se saisissent à la suite dans la liste déroulante.
« Refuser l’accès (deny) »deny <valeur>;Même principe, mais pour refuser l’accès. L’usage habituel : plusieurs allow pour vos propres réseaux et un deny all à la fin.
« Taille max. de la requête »client_max_body_size <valeur>;Limite de taille du corps de la requête. Le format est un nombre suivi d’un suffixe facultatif k, m ou g : 100m, 10k, 1g, 0.
« Durée du cache (expires) »expires <valeur>;En-tête Expires pour le cache côté navigateur. La liste déroulante propose les préréglages off, 1m, 30m, 1h, 24h, 7d, 30d, 1y ; vous pouvez saisir votre propre valeur, par exemple -1h ou max.
« Journaliser les erreurs 404 »log_not_found on/off;Commutateur : indique s’il faut consigner dans le journal de Nginx les messages sur les fichiers introuvables.
« Dossier racine (root_dir) »root <valeur>;Dossier racine de cette règle : il remplace le root général de l’hôte par un chemin précis. Le champ ne doit pas être vide.
« Fichiers (try_files) »try_files <valeur>;Chaîne complète des arguments de la directive try_files, par exemple $uri $uri/ =404 ou $uri /index.php?$query_string. Dans le modèle PHP (FastCGI), ce paramètre est ignoré : try_files y est fixé.

⚠️ IPv6 dans « Autoriser l’accès (allow) » et « Refuser l’accès (deny) »

Le formulaire n’accepte que les adresses IPv4 et les réseaux CIDR IPv4. Pour restreindre l’accès par IPv6, il faut passer par le mode expert : allow et deny y sont écrits directement dans la configuration et acceptent toute la syntaxe de Nginx.

Activer et désactiver une règle ​

Chaque règle, y compris la règle racine, peut être désactivée temporairement avec le commutateur « Activée / Désactivée ». Les paramètres d’une règle désactivée restent dans le formulaire, mais la règle n’est pas reprise dans le fichier *.conf final de Nginx : c’est pratique pour mettre de côté une partie de la configuration sans la perdre. Par ailleurs, une règle désactivée n’est plus soumise à la vérification des chemins en double : vous pouvez désactiver une ancienne règle de chemin /api et en créer une nouvelle avec le même chemin, l’enregistrement passera.

Pour aller plus loin ​

BeAdmin © 2025. Tous droits réservés.