Saltar a contenido

cache-purge: módulo de purga de caché e invalidación de etiquetas para NGINX

Requiere el plan Pro (o superior) de la suscripción GetPageSpeed NGINX Extras.

Instalación

Puede instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero sin limitarse a:

  • RedHat Enterprise Linux 7, 8, 9 y 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 y 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

Habilite el módulo añadiendo lo siguiente al inicio de /etc/nginx/nginx.conf:

load_module modules/ngx_http_cache_purge_module.so;

Este documento describe nginx-module-cache-purge v2.6.0 publicado el 23 de agosto de 2026.

Purga selectiva de contenido de las cachés FastCGI, proxy, SCGI y uWSGI de NGINX mediante solicitudes HTTP PURGE — sin trucos con el sistema de archivos, sin dolores de cabeza con permisos.

Esta es una funcionalidad presente en NGINX Plus, pero ngx_cache_purge la trae a NGINX de código abierto.

Características principales

  • Purga en la misma ubicación — añada soporte PURGE directamente a las ubicaciones de caché existentes, sin necesidad de bloques location adicionales
  • Purga con comodines — purgue múltiples entradas de caché con una sola solicitud usando *
  • Etiquetas de caché / claves sustitutas — invalide solo los objetos cuyas etiquetas de respuesta en caché coincidan con un patrón PURGE de confianza
  • Purga masiva — borre todo el contenido en caché de una vez con purge_all
  • Control de acceso basado en IP — restrinja quién puede emitir solicitudes de purga
  • Sustitución del método de clave de caché — purgue contenido almacenado en caché con GET incluso cuando $request_method está en su clave de caché
  • Formato de respuesta configurable — obtenga resultados de purga en HTML, JSON, XML o texto plano
  • Todos los tipos de caché — funciona con FastCGI, proxy, SCGI y uWSGI

Inicio rápido

Añada soporte PURGE a cualquier ubicación en caché:

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;
        }
    }
}

Purgue una página en caché:

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

Eso es todo. Sin ubicación /purge separada, sin permisos del sistema de archivos que gestionar.

Directivas de configuración

Sintaxis de misma ubicación (recomendada)

Habilita la purga directamente en la ubicación que sirve contenido en caché.

fastcgi_cache_purge

  • sintaxis: fastcgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • predeterminado: none
  • contexto: http, server, location

proxy_cache_purge

  • sintaxis: proxy_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • predeterminado: none
  • contexto: http, server, location

scgi_cache_purge

  • sintaxis: scgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • predeterminado: none
  • contexto: http, server, location

uwsgi_cache_purge

  • sintaxis: uwsgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • predeterminado: none
  • contexto: http, server, location

Sintaxis de ubicación separada

Use una ubicación dedicada para solicitudes de purga. Útil cuando necesita reglas de acceso diferentes para la purga.

fastcgi_cache_purge

  • sintaxis: fastcgi_cache_purge zone_name key
  • contexto: location

proxy_cache_purge

  • sintaxis: proxy_cache_purge zone_name key
  • contexto: location

scgi_cache_purge

  • sintaxis: scgi_cache_purge zone_name key
  • contexto: location

uwsgi_cache_purge

  • sintaxis: uwsgi_cache_purge zone_name key
  • contexto: location

Formato de respuesta

cache_purge_response_type

  • sintaxis: cache_purge_response_type html|json|xml|text
  • predeterminado: html
  • contexto: http, server, location

Ejemplo con respuestas 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/"}

Sustitución del método de clave de caché

Cuando $request_method es parte de su clave de caché, las solicitudes de purga generan una clave diferente (PURGE vs GET) y no encontrarán la entrada en caché. Estas directivas resuelven ese problema:

*_cache_purge_key_method

  • sintaxis: fastcgi_cache_purge_key_method <method> [<method> ...]
  • contexto: http, server, location

Disponible para todos los tipos de caché: 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;  # Sustituye GET por PURGE en la búsqueda de clave
}

Puede especificar múltiples métodos:

fastcgi_cache_purge_key_method GET HEAD;

Integración con WordPress

Caché FastCGI + Purga

Una configuración completa de WordPress con caché y soporte de purga automática:

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;
        }
    }
}

¿Por qué fastcgi_cache_purge en ambas ubicaciones? La URL raíz / es un caso especial. Cuando try_files verifica $uri/, encuentra el directorio raíz del documento. Para solicitudes GET, la directiva index enruta a index.php — pero para solicitudes PURGE, index no se aplica y NGINX se detiene en location /. Añadir fastcgi_cache_purge allí garantiza que PURGE / funcione.

Plugin de purga de caché proxy

Instale el plugin Proxy Cache Purge para purgar automáticamente la caché cuando se actualice el contenido:

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

El plugin envía solicitudes PURGE a NGINX cada vez que se modifican publicaciones, comentarios o páginas — sin necesidad de gestión manual de caché.

Mejores prácticas para claves de caché

Manténgalo simple — evite $request_method en las claves

## Recomendado
fastcgi_cache_key "$scheme$host$request_uri";

## Evitar — las solicitudes de purga no coincidirán con las entradas GET en caché
fastcgi_cache_key "$scheme$request_method$host$request_uri";

Si debe incluir $request_method, use *_cache_purge_key_method GET para corregir las búsquedas de clave de purga.

Purga con comodines

Purgue múltiples entradas que coincidan con un patrón añadiendo *:

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

El asterisco debe ser el último carácter. Para que esto funcione, $uri debe estar al final de su clave de caché.

Etiquetas de caché / claves sustitutas

cache_purge_tags conecta una cabecera de etiqueta almacenada en las respuestas de upstream en caché con una cabecera regex en una solicitud PURGE autorizada:

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;
}
  • sintaxis: cache_purge_tags <cached-response-header> <purge-pattern-header>
  • predeterminado: off
  • contexto: http, server, location

Para Magento Open Source y Adobe Commerce, no se necesita ningún cambio en la aplicación. Magento ya añade X-Magento-Tags a las respuestas almacenables en caché y envía solicitudes PURGE de localhost de confianza con X-Magento-Tags-Pattern. El módulo escanea la misma zona de caché y elimina solo los objetos coincidentes. Un patrón de etiqueta tiene prioridad sobre el comportamiento de clave exacta, comodín y purge_all para esa solicitud.

La cabecera de etiqueta de respuesta puede ocultarse a los clientes con proxy_hide_header. Permanece disponible en los metadatos de caché en disco de NGINX para invalidación. Una regex inválida devuelve HTTP 400; un patrón válido sin coincidencias devuelve HTTP 200, coincidiendo con el VCL de Varnish generado por Magento.

La invalidación por etiquetas escanea los metadatos de cabecera en caché solo cuando llega una solicitud PURGE. Los aciertos de caché normales no pagan sobrecarga de índice de etiquetas, pero el tiempo de purga crece con el número de archivos en la zona de caché. Esto intercambia la lista de baneo persistente de Varnish por la eliminación inmediata de objetos NGINX coincidentes.

Las integraciones de etiquetas de caché de WordPress pueden usar la misma directiva con sus nombres de cabecera:

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

Purga masiva

Borre todos los archivos en caché de una vez:

proxy_cache_purge PURGE purge_all from 127.0.0.1;

Esto puede ser lento con cachés grandes o almacenamiento lento. Use rutas de caché respaldadas por RAM para un mejor rendimiento.

Control de acceso basado en IP

Restrinja las solicitudes de purga a fuentes de confianza:

fastcgi_cache_purge PURGE from 127.0.0.1 192.168.1.0/24;

Solución de problemas

Respuesta Causa Solución
405 Not Allowed PURGE alcanzó una ubicación sin *_cache_purge Añada *_cache_purge a todas las ubicaciones relevantes
412 Precondition Failed Entrada de caché no encontrada (nunca almacenada, ya expirada o clave no coincide) Verifique la clave de caché — busque problemas con $request_method
403 Forbidden IP del cliente no está en la lista from Añada su IP a from
200 OK pero la caché persiste $request_method en la clave de caché crea claves no coincidentes Elimine $request_method de la clave, o añada *_cache_purge_key_method GET

Interacción con gzip_vary: Habilitar gzip_vary puede interferir con la purga de caché. Si experimenta un comportamiento de purga inconsistente, deshabilite gzip_vary dentro de la ubicación en caché.

Pruebas

ngx_cache_purge incluye un conjunto de pruebas basado en Test::Nginx:

prove

Véase también