Aller au contenu

cache-purge: Module de purge de cache NGINX

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

Installation

Vous pouvez installer ce module dans toute distribution basée sur RHEL, y compris, mais 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 ce qui suit 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.5.10 publié le 25 mars 2026.

Purge sélectivement le contenu des caches FastCGI, proxy, SCGI et uWSGI de NGINX en utilisant des requêtes HTTP PURGE — pas de hacks de système de fichiers, pas de maux de tête liés aux permissions.

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

Caractéristiques clés

  • Purge au même emplacement — ajoutez le support PURGE directement aux emplacements de cache existants, aucun bloc location supplémentaire n'est nécessaire
  • Purge par wildcard — purgez plusieurs entrées de cache avec une seule requête en utilisant *
  • Purge en masse — effacez tout le contenu mis en cache d'un coup avec purge_all
  • Contrôle d'accès basé sur l'IP — restreignez qui peut émettre des requêtes de purge
  • Substitution de méthode de clé de cache — purgez le contenu mis en cache par GET même lorsque $request_method est dans votre clé de cache
  • Format de réponse configurable — obtenez les résultats de purge en HTML, JSON, XML ou texte brut
  • Tous types de cache — fonctionne avec FastCGI, proxy, SCGI et uWSGI

Démarrage rapide

Ajoutez le support 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;
        }
    }
}

Purge une page mise en cache :

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

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

Directives de configuration

Syntaxe Same-Location (Recommandée)

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

fastcgi_cache_purge

  • syntax: fastcgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • default: none
  • context: http, server, location

proxy_cache_purge

  • syntax: proxy_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • default: none
  • context: http, server, location

scgi_cache_purge

  • syntax: scgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • default: none
  • context: http, server, location

uwsgi_cache_purge

  • syntax: uwsgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • default: none
  • context: http, server, location

Syntaxe Separate-Location

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

  • syntax: fastcgi_cache_purge zone_name key
  • context: location

proxy_cache_purge

  • syntax: proxy_cache_purge zone_name key
  • context: location

scgi_cache_purge

  • syntax: scgi_cache_purge zone_name key
  • context: location

uwsgi_cache_purge

  • syntax: uwsgi_cache_purge zone_name key
  • context: location

Format de réponse

cache_purge_response_type

  • syntax: cache_purge_response_type html|json|xml|text
  • default: html
  • context: 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 de 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 cela :

*_cache_purge_key_method

  • syntax: fastcgi_cache_purge_key_method <method> [<method> ...]
  • context: 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;  # Substitue GET pour 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 support de 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 spécial. Lorsque try_files vérifie $uri/, il trouve le répertoire racine du document. Pour les requêtes GET, la directive index dirige vers index.php — mais pour les requêtes PURGE, index ne s'applique pas et NGINX s'arrête à location /. Ajouter fastcgi_cache_purge là garantit que PURGE / fonctionne.

Plugin de purge de cache proxy

Installez le 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 fois que des articles, des commentaires ou des pages sont modifiés — aucune gestion manuelle du cache n'est nécessaire.

Meilleures pratiques pour la clé de cache

Gardez-le 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é de purge.

Purge par wildcard

Purge plusieurs entrées correspondant à un motif 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.

Purge en masse

Effacez 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 en RAM pour de meilleures performances.

Contrôle d'accès basé sur l'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 Solution
405 Not Allowed PURGE a touché un emplacement sans *_cache_purge Ajoutez *_cache_purge à tous les emplacements pertinents
412 Precondition Failed Entrée de cache non trouvée (jamais mise en cache, déjà expirée ou clé non correspondante) Vérifiez la clé de cache — recherchez des problèmes avec $request_method
403 Forbidden IP du client non dans 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 : Activer gzip_vary peut interférer avec la purge de cache. Si vous rencontrez un comportement de purge incohérent, désactivez gzip_vary à l'intérieur de l'emplacement mis en cache.

Tests

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

prove

Voir aussi