Pular para conteúdo

cache-purge: Módulo de Purga de Cache 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

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_cache_purge_module.so;

Este documento descreve nginx-module-cache-purge v2.5.10 lançado em 25 de março de 2026.

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

Este é um recurso presente no NGINX Plus, mas ngx_cache_purge o traz 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 necessidade de blocos location extras
  • Purga com curinga — purgue várias entradas de cache com uma única requisição usando *
  • Purga em massa — limpe todo o conteúdo em cache de uma vez com purge_all
  • Controle de acesso baseado em IP — restrinja quem pode emitir requisições de purga
  • Substituição do método da chave de cache — purgue conteúdo em cache de 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 a 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;
        }
    }
}

Purge uma página em cache:

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

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

Diretrizes de Configuração

Sintaxe de Mesma Localização (Recomendado)

Habilita a purga diretamente na localização que serve 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 de Localização Separada

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

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 do Método da Chave de Cache

Quando $request_method é 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. Essas diretrizes 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

FastCGI Cache + Purga

Uma configuração completa do WordPress com suporte a cache e 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 que fastcgi_cache_purge em ambas as localizações? A URL raiz / é um caso especial. Quando try_files verifica $uri/, encontra o diretório raiz do documento. Para requisições GET, a diretiva index direciona 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 de Purga de Cache Proxy

Instale o Proxy Cache Purge para purgar automaticamente o cache quando o conteúdo é 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.

Melhores Práticas para Chaves 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 a 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 de purga.

Purga com Curiga

Purge múltiplas entradas que correspondem a um padrão anexando *:

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.

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 em RAM para melhor desempenho.

Controle de Acesso Baseado em IP

Restringa 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 em cache, já expirou ou incompatibilidade de chave) 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 à lista 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ê experimentar um comportamento inconsistente de purga, desative gzip_vary dentro da localização em cache.

Testando

ngx_cache_purge inclui um conjunto de testes baseado em Test::Nginx:

prove

Veja Também