Saltar a contenido

cache-purge: Módulo de Purga de Caché de NGINX

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

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado 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

Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:

load_module modules/ngx_http_cache_purge_module.so;

Este documento describe nginx-module-cache-purge v2.5.10 lanzado el 25 de marzo de 2026.

Purga selectivamente contenido de los cachés FastCGI, proxy, SCGI y uWSGI de NGINX utilizando solicitudes HTTP PURGE — sin trucos de sistema de archivos, sin dolores de cabeza por permisos.

Esta es una característica presente en NGINX Plus, pero ngx_cache_purge la lleva a NGINX de código abierto.

Características Clave

  • Purga en la misma ubicación — añade soporte para PURGE directamente a las ubicaciones de caché existentes, sin bloques de location adicionales necesarios
  • Purga con comodines — purga múltiples entradas de caché con una sola solicitud utilizando *
  • Purga masiva — limpia todo el contenido en caché de una vez con purge_all
  • Control de acceso basado en IP — restringe quién puede emitir solicitudes de purga
  • Sustitución de método de clave de caché — purga contenido en caché por GET incluso cuando $request_method está en tu clave de caché
  • Formato de respuesta configurable — recibe 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ñade soporte para 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;
        }
    }
}

Purga una página en caché:

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

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

Directivas de Configuración

Sintaxis de la 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

Usa una ubicación dedicada para solicitudes de purga. Útil cuando necesitas diferentes reglas de acceso 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 de Método de Clave de Caché

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

*_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
}

Puedes 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 soporte de caché y 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 las solicitudes GET, la directiva index redirige a index.php — pero para las solicitudes PURGE, index no se aplica y NGINX se detiene en location /. Añadir fastcgi_cache_purge allí asegura que PURGE / funcione.

Plugin de Purga de Caché Proxy

Instala el Proxy Cache Purge para purgar automáticamente la caché cuando se actualiza 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 — no se necesita gestión manual de la caché.

Mejores Prácticas de Clave de Caché

Mantenlo simple — evita $request_method en 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 debes incluir $request_method, usa *_cache_purge_key_method GET para corregir las búsquedas de clave de purga.

Purga con Comodines

Purga 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 tu clave de caché.

Purga Masiva

Limpia 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. Usa rutas de caché respaldadas por RAM para obtener el mejor rendimiento.

Control de Acceso Basado en IP

Restringe las solicitudes de purga a fuentes confiables:

fastcgi_cache_purge PURGE from 127.0.0.1 192.168.1.0/24;

Solución de Problemas

Respuesta Causa Solución
405 No Permitido PURGE alcanzó una ubicación sin *_cache_purge Añade *_cache_purge a todas las ubicaciones relevantes
412 Fallo de Precondición Entrada de caché no encontrada (nunca en caché, ya expiró o desajuste de clave) Verifica la clave de caché — busca problemas con $request_method
403 Prohibido IP del cliente no está en la lista de from Añade tu IP a from
200 OK pero la caché persiste $request_method en la clave de caché crea claves desajustadas Elimina $request_method de la clave, o añade *_cache_purge_key_method GET

Interacción con gzip_vary: Habilitar gzip_vary puede interferir con la purga de caché. Si experimentas un comportamiento de purga inconsistente, desactiva 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