Pular para conteúdo

cache-purge: Módulo de purga de cache e invalidação por tags do NGINX

Requer o plano Pro (ou superior) da assinatura GetPageSpeed NGINX Extras.

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

  • RedHat Enterprise Linux 7, 8, 9 e 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 e 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 o módulo adicionando o seguinte no topo do /etc/nginx/nginx.conf:

load_module modules/ngx_http_cache_purge_module.so;

Este documento descreve o nginx-module-cache-purge v2.6.0 lançado em 23 de agosto de 2026.

Purgue seletivamente conteúdo dos caches FastCGI, proxy, SCGI e uWSGI do NGINX usando requisições HTTP PURGE — sem truques no sistema de arquivos, sem dores de cabeça com permissões.

Este é um recurso presente no NGINX Plus, mas o ngx_cache_purge traz essa funcionalidade para o NGINX de código aberto.

Principais Recursos

  • Purga na mesma localização — adicione suporte a PURGE diretamente nas localizações de cache existentes, sem blocos location extras
  • Purga com curinga — purgue múltiplas entradas de cache com uma única requisição usando *
  • Tags de cache / chaves substitutas — invalide apenas objetos cujas tags de resposta em cache correspondam a um padrão PURGE confiável
  • Purga em massa — limpe todo o conteúdo em cache de uma vez com purge_all
  • Controle de acesso por IP — restrinja quem pode emitir requisições de purga
  • Substituição de método na chave de cache — purgue conteúdo em cache via GET mesmo quando $request_method está na sua chave de cache
  • Formato de resposta configurável — obtenha resultados de purga em HTML, JSON, XML ou texto simples
  • Todos os tipos de cache — funciona com FastCGI, proxy, SCGI e uWSGI

Início Rápido

Adicione suporte a PURGE em qualquer localização em 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;
        }
    }
}

Purgue uma página em cache:

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

Pronto. Sem localização /purge separada, sem permissões de sistema de arquivos para gerenciar.

Diretivas de Configuração

Sintaxe na Mesma Localização (Recomendada)

Habilita a purga diretamente na localização que serve o conteúdo em cache.

fastcgi_cache_purge

  • sintaxe: fastcgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • padrão: none
  • contexto: http, server, location

proxy_cache_purge

  • sintaxe: proxy_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • padrão: none
  • contexto: http, server, location

scgi_cache_purge

  • sintaxe: scgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • padrão: none
  • contexto: http, server, location

uwsgi_cache_purge

  • sintaxe: uwsgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • padrão: none
  • contexto: http, server, location

Sintaxe em Localização Separada

Use uma localização dedicada para requisições de purga. Útil quando você precisa de regras de acesso diferentes para purga.

fastcgi_cache_purge

  • sintaxe: fastcgi_cache_purge zone_name key
  • contexto: location

proxy_cache_purge

  • sintaxe: proxy_cache_purge zone_name key
  • contexto: location

scgi_cache_purge

  • sintaxe: scgi_cache_purge zone_name key
  • contexto: location

uwsgi_cache_purge

  • sintaxe: uwsgi_cache_purge zone_name key
  • contexto: location

Formato de Resposta

cache_purge_response_type

  • sintaxe: cache_purge_response_type html|json|xml|text
  • padrão: html
  • contexto: http, server, location

Exemplo com respostas 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/"}

Substituição de Método na Chave de Cache

Quando $request_method faz parte da sua chave de cache, requisições de purga geram uma chave diferente (PURGE vs GET) e não encontrarão a entrada em cache. Estas diretivas resolvem isso:

*_cache_purge_key_method

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

Disponível para todos os tipos 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;  # Substitui GET por PURGE na busca da chave
}

Você pode especificar múltiplos métodos:

fastcgi_cache_purge_key_method GET HEAD;

Integração com WordPress

Cache FastCGI + Purga

Uma configuração completa de WordPress com cache e suporte automático a purga:

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 que fastcgi_cache_purge em ambas as localizações? A URL raiz / é um caso especial. Quando try_files verifica $uri/, ele encontra o diretório raiz do documento. Para requisições GET, a diretiva index roteia para index.php — mas para requisições PURGE, index não se aplica e o NGINX para em location /. Adicionar fastcgi_cache_purge lá garante que PURGE / funcione.

Plugin Proxy Cache Purge

Instale o plugin Proxy Cache Purge para purgar o cache automaticamente quando o conteúdo for atualizado:

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

O plugin envia requisições PURGE para o NGINX sempre que posts, comentários ou páginas são modificados — sem necessidade de gerenciamento manual de cache.

Boas Práticas para Chave de Cache

Mantenha simples — evite $request_method nas chaves

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

## Evite — requisições de purga não corresponderão às entradas GET em cache
fastcgi_cache_key "$scheme$request_method$host$request_uri";

Se você precisar incluir $request_method, use *_cache_purge_key_method GET para corrigir as buscas de chave na purga.

Purga com Curinga

Purgue múltiplas entradas que correspondam a um padrão adicionando *:

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

O asterisco deve ser o último caractere. Para que isso funcione, $uri deve estar no final da sua chave de cache.

Tags de Cache / Chaves Substitutas

cache_purge_tags conecta um cabeçalho de tag armazenado nas respostas upstream em cache a um cabeçalho regex em uma requisição 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;
}
  • sintaxe: cache_purge_tags <cabeçalho-resposta-em-cache> <cabeçalho-padrão-purga>
  • padrão: off
  • contexto: http, server, location

Para Magento Open Source e Adobe Commerce, nenhuma alteração na aplicação é necessária. O Magento já adiciona X-Magento-Tags às respostas armazenáveis em cache e envia requisições PURGE confiáveis de localhost com X-Magento-Tags-Pattern. O módulo varre a mesma zona de cache e remove apenas os objetos correspondentes. Um padrão de tag tem precedência sobre o comportamento de chave exata, curinga e purge_all para aquela requisição.

O cabeçalho de tag de resposta pode ser ocultado dos clientes com proxy_hide_header. Ele permanece disponível nos metadados de cache em disco do NGINX para invalidação. Um regex inválido retorna HTTP 400; um padrão válido sem correspondências retorna HTTP 200, correspondendo ao VCL Varnish gerado pelo Magento.

A invalidação por tag varre os metadados de cabeçalho em cache apenas quando uma requisição PURGE chega. Acessos normais ao cache não pagam sobrecarga de índice de tags, mas o tempo de purga cresce com o número de arquivos na zona de cache. Isso troca a lista persistente de bans do Varnish pela exclusão imediata dos objetos NGINX correspondentes.

Integrações de tags de cache do WordPress podem usar a mesma diretiva com seus nomes de cabeçalho:

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

Purga em Massa

Limpe todos os arquivos em cache de uma vez:

proxy_cache_purge PURGE purge_all from 127.0.0.1;

Isso pode ser lento com caches grandes ou armazenamento lento. Use caminhos de cache com suporte a RAM para melhor desempenho.

Controle de Acesso por IP

Restrinja requisições de purga a fontes confiáveis:

fastcgi_cache_purge PURGE from 127.0.0.1 192.168.1.0/24;

Solução de Problemas

Resposta Causa Correção
405 Not Allowed PURGE atingiu uma localização sem *_cache_purge Adicione *_cache_purge a todas as localizações relevantes
412 Precondition Failed Entrada de cache não encontrada (nunca armazenada, já expirada ou chave incompatível) Verifique a chave de cache — procure por problemas com $request_method
403 Forbidden IP do cliente não está na lista from Adicione seu IP ao from
200 OK mas o cache persiste $request_method na chave de cache cria chaves incompatíveis Remova $request_method da chave, ou adicione *_cache_purge_key_method GET

Interação com gzip_vary: Habilitar gzip_vary pode interferir na purga de cache. Se você tiver comportamento inconsistente de purga, desabilite gzip_vary dentro da localização em cache.

Testes

O ngx_cache_purge inclui uma suíte de testes baseada em Test::Nginx:

prove

Veja Também