Aller au contenu

cache-purge : module de purge de cache et d'invalidation par tags pour NGINX

Nécessite le plan Pro (ou supérieur) de l'abonnement GetPageSpeed NGINX Extras.

Installation

Vous pouvez installer ce module sur toute distribution basée sur RHEL, y compris, sans s'y limiter :

  • RedHat Enterprise Linux 7, 8, 9 et 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 et Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-cache-purge

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-cache-purge

Activez le module en ajoutant la ligne suivante en haut de /etc/nginx/nginx.conf :

load_module modules/ngx_http_cache_purge_module.so;

Ce document décrit nginx-module-cache-purge v2.6.0 publié le 23 août 2026.

Purgez sélectivement le contenu des caches FastCGI, proxy, SCGI et uWSGI de NGINX à l'aide de requêtes HTTP PURGE — sans bidouilles sur le système de fichiers, sans problèmes de permissions.

Cette fonctionnalité est présente dans NGINX Plus, mais ngx_cache_purge l'apporte à NGINX open source.

Principales fonctionnalités

  • Purge dans le même emplacement — ajoutez la prise en charge de PURGE directement dans les emplacements de cache existants, sans blocs location supplémentaires
  • Purge par wildcard — purgez plusieurs entrées de cache avec une seule requête en utilisant *
  • Tags de cache / clés de substitution (surrogate keys) — invalidez uniquement les objets dont les tags de réponse en cache correspondent à un modèle PURGE de confiance
  • Purge en masse — videz tout le contenu mis en cache d'un coup avec purge_all
  • Contrôle d'accès par IP — restreignez qui peut émettre des requêtes de purge
  • Substitution de méthode dans la clé de cache — purgez le contenu mis en cache pour GET même lorsque $request_method fait partie de votre clé de cache
  • Format de réponse configurable — obtenez les résultats de purge en HTML, JSON, XML ou texte brut
  • Tous les types de cache — fonctionne avec FastCGI, proxy, SCGI et uWSGI

Démarrage rapide

Ajoutez la prise en charge de PURGE à n'importe quel emplacement mis en cache :

http {
    proxy_cache_path /var/cache/nginx keys_zone=my_cache:10m max_size=1g;

    server {
        location / {
            proxy_pass        http://127.0.0.1:8000;
            proxy_cache       my_cache;
            proxy_cache_key   "$scheme$host$request_uri";
            proxy_cache_purge PURGE from 127.0.0.1;
        }
    }
}

Purgez une page mise en cache :

curl -X PURGE https://example.com/page-to-purge

C'est tout. Pas d'emplacement /purge séparé, pas de permissions système à gérer.

Directives de configuration

Syntaxe dans le même emplacement (recommandée)

Active la purge directement dans l'emplacement qui sert le contenu mis en cache.

fastcgi_cache_purge

  • syntaxe : fastcgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • défaut : none
  • contexte : http, server, location

proxy_cache_purge

  • syntaxe : proxy_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • défaut : none
  • contexte : http, server, location

scgi_cache_purge

  • syntaxe : scgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • défaut : none
  • contexte : http, server, location

uwsgi_cache_purge

  • syntaxe : uwsgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • défaut : none
  • contexte : http, server, location

Syntaxe avec emplacement séparé

Utilisez un emplacement dédié pour les requêtes de purge. Utile lorsque vous avez besoin de règles d'accès différentes pour la purge.

fastcgi_cache_purge

  • syntaxe : fastcgi_cache_purge zone_name key
  • contexte : location

proxy_cache_purge

  • syntaxe : proxy_cache_purge zone_name key
  • contexte : location

scgi_cache_purge

  • syntaxe : scgi_cache_purge zone_name key
  • contexte : location

uwsgi_cache_purge

  • syntaxe : uwsgi_cache_purge zone_name key
  • contexte : location

Format de réponse

cache_purge_response_type

  • syntaxe : cache_purge_response_type html|json|xml|text
  • défaut : html
  • contexte : http, server, location

Exemple avec des réponses JSON :

location / {
    proxy_pass        http://backend;
    proxy_cache       my_cache;
    proxy_cache_key   "$uri$is_args$args";
    proxy_cache_purge PURGE from 127.0.0.1;

    cache_purge_response_type json;
}

{"Key": "httplocalhost/"}

Substitution de méthode dans la clé de cache

Lorsque $request_method fait partie de votre clé de cache, les requêtes de purge génèrent une clé différente (PURGE vs GET) et ne trouveront pas l'entrée mise en cache. Ces directives résolvent ce problème :

*_cache_purge_key_method

  • syntaxe : fastcgi_cache_purge_key_method <method> [<method> ...]
  • contexte : http, server, location

Disponible pour tous les types de cache : fastcgi_cache_purge_key_method, proxy_cache_purge_key_method, scgi_cache_purge_key_method, uwsgi_cache_purge_key_method.

location ~ \.php$ {
    fastcgi_cache           WORDPRESS;
    fastcgi_cache_key       "$scheme$request_method$host$request_uri";
    fastcgi_cache_purge     PURGE from 127.0.0.1;
    fastcgi_cache_purge_key_method GET;  # Remplace GET par PURGE dans la recherche de clé
}

Vous pouvez spécifier plusieurs méthodes :

fastcgi_cache_purge_key_method GET HEAD;

Intégration WordPress

Cache FastCGI + Purge

Une configuration WordPress complète avec mise en cache et purge automatique :

http {
    fastcgi_cache_path /var/cache/nginx levels=1:2
        keys_zone=WORDPRESS:100m max_size=1g
        inactive=60m use_temp_path=off;
    fastcgi_cache_key "$scheme$host$request_uri";

    server {
        listen 80;
        server_name example.com;
        root /var/www/wordpress;
        index index.php;

        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot|webp|avif)$ {
            expires max;
            log_not_found off;
        }

        location / {
            try_files $uri $uri/ /index.php?$args;
            fastcgi_cache_purge PURGE from 127.0.0.1;
        }

        location ~ \.php$ {
            try_files $uri =404;
            fastcgi_pass unix:/run/php-fpm/www.sock;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            include fastcgi_params;

            fastcgi_cache WORDPRESS;
            fastcgi_cache_valid 200 60m;
            fastcgi_cache_use_stale error timeout updating;
            fastcgi_cache_lock on;
            fastcgi_cache_purge PURGE from 127.0.0.1;

            add_header X-Cache-Status $upstream_cache_status always;
        }
    }
}

Pourquoi fastcgi_cache_purge dans les deux emplacements ? L'URL racine / est un cas particulier. Lorsque try_files vérifie $uri/, il trouve le répertoire racine du document. Pour les requêtes GET, la directive index route vers index.php — mais pour les requêtes PURGE, index ne s'applique pas et NGINX s'arrête à location /. Ajouter fastcgi_cache_purge ici garantit que PURGE / fonctionne.

Plugin de purge de cache proxy

Installez le plugin Proxy Cache Purge pour purger automatiquement le cache lorsque le contenu est mis à jour :

wp plugin install varnish-http-purge --activate
wp option update vhp_varnish_ip '127.0.0.1'

Le plugin envoie des requêtes PURGE à NGINX à chaque modification d'articles, de commentaires ou de pages — aucune gestion manuelle du cache nécessaire.

Bonnes pratiques pour les clés de cache

Restez simple — évitez $request_method dans les clés

## Recommandé
fastcgi_cache_key "$scheme$host$request_uri";

## À éviter — les requêtes de purge ne correspondront pas aux entrées GET mises en cache
fastcgi_cache_key "$scheme$request_method$host$request_uri";

Si vous devez inclure $request_method, utilisez *_cache_purge_key_method GET pour corriger les recherches de clés de purge.

Purge par wildcard

Purgez plusieurs entrées correspondant à un modèle en ajoutant * :

curl -X PURGE https://example.com/blog/*

L'astérisque doit être le dernier caractère. Pour que cela fonctionne, $uri doit être à la fin de votre clé de cache.

Tags de cache / clés de substitution (surrogate keys)

cache_purge_tags relie un en-tête de tag stocké dans les réponses en amont mises en cache à un en-tête regex sur une requête PURGE autorisée :

location / {
    proxy_pass         http://backend;
    proxy_cache        app_cache;
    proxy_cache_key    "$scheme$host$request_uri";

    proxy_cache_purge  PURGE from 127.0.0.1;
    cache_purge_tags   X-Magento-Tags X-Magento-Tags-Pattern;
}
  • syntaxe : cache_purge_tags <cached-response-header> <purge-pattern-header>
  • défaut : off
  • contexte : http, server, location

Pour Magento Open Source et Adobe Commerce, aucune modification de l'application n'est nécessaire. Magento ajoute déjà X-Magento-Tags aux réponses cacheables et envoie des requêtes PURGE de confiance depuis localhost avec X-Magento-Tags-Pattern. Le module analyse la même zone de cache et supprime uniquement les objets correspondants. Un modèle de tag a priorité sur le comportement par clé exacte, wildcard et purge_all pour cette requête.

L'en-tête de tag de réponse peut être masqué aux clients avec proxy_hide_header. Il reste disponible dans les métadonnées du cache sur disque de NGINX pour l'invalidation. Une regex invalide renvoie HTTP 400 ; un modèle valide sans correspondance renvoie HTTP 200, conformément au VCL Varnish généré par Magento.

L'invalidation par tag analyse les métadonnées d'en-tête mises en cache uniquement lorsqu'une requête PURGE arrive. Les hits de cache normaux ne subissent aucun surcoût d'index de tags, mais le temps de purge augmente avec le nombre de fichiers dans la zone de cache. Cela échange la liste de bannissement persistante de Varnish contre une suppression immédiate des objets NGINX correspondants.

Les intégrations de tags de cache WordPress peuvent utiliser la même directive avec leurs propres noms d'en-têtes :

cache_purge_tags X-Cache-Tags X-Cache-Tags-Pattern;

Purge en masse

Videz tous les fichiers mis en cache d'un coup :

proxy_cache_purge PURGE purge_all from 127.0.0.1;

Cela peut être lent avec de grands caches ou un stockage lent. Utilisez des chemins de cache adossés à la RAM pour de meilleures performances.

Contrôle d'accès par IP

Restreignez les requêtes de purge aux sources de confiance :

fastcgi_cache_purge PURGE from 127.0.0.1 192.168.1.0/24;

Dépannage

Réponse Cause Correctif
405 Not Allowed PURGE a atteint un emplacement sans *_cache_purge Ajoutez *_cache_purge à tous les emplacements concernés
412 Precondition Failed Entrée de cache introuvable (jamais mise en cache, déjà expirée ou clé non correspondante) Vérifiez la clé de cache — recherchez les problèmes de $request_method
403 Forbidden IP du client absente de la liste from Ajoutez votre IP à from
200 OK mais le cache persiste $request_method dans la clé de cache crée des clés non correspondantes Supprimez $request_method de la clé, ou ajoutez *_cache_purge_key_method GET

Interaction avec gzip_vary : L'activation de gzip_vary peut interférer avec la purge du cache. Si vous rencontrez un comportement de purge incohérent, désactivez gzip_vary dans l'emplacement mis en cache.

Tests

ngx_cache_purge inclut une suite de tests basée sur Test::Nginx :

prove

Voir aussi