Zum Inhalt

cache-purge: NGINX-Cache-Purge- und Tag-Invalidierungsmodul

Erfordert den Pro-Plan (oder höher) des GetPageSpeed NGINX Extras-Abonnements.

Installation

Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:

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

Aktivieren Sie das Modul, indem Sie Folgendes am Anfang von /etc/nginx/nginx.conf hinzufügen:

load_module modules/ngx_http_cache_purge_module.so;

Dieses Dokument beschreibt nginx-module-cache-purge v2.6.0, veröffentlicht am 23. August 2026.

Selektives Löschen von Inhalten aus den FastCGI-, Proxy-, SCGI- und uWSGI-Caches von NGINX mithilfe von HTTP-PURGE-Anfragen – keine Dateisystem-Hacks, keine Berechtigungsprobleme.

Dies ist eine Funktion, die in NGINX Plus vorhanden ist, aber ngx_cache_purge bringt sie in Open-Source-NGINX.

Hauptfunktionen

  • Löschung am selben Ort – fügen Sie PURGE-Unterstützung direkt zu vorhandenen Cache-Locations hinzu, keine zusätzlichen location-Blöcke erforderlich
  • Wildcard-Löschung – löschen Sie mehrere Cache-Einträge mit einer einzigen Anfrage mit *
  • Cache-Tags / Surrogate Keys – invalidieren Sie nur Objekte, deren zwischengespeicherte Antwort-Tags einem vertrauenswürdigen PURGE-Muster entsprechen
  • Massenlöschung – löschen Sie alle zwischengespeicherten Inhalte auf einmal mit purge_all
  • IP-basierte Zugriffskontrolle – beschränken Sie, wer Lösch-Anfragen senden darf
  • Cache-Key-Methoden-Substitution – löschen Sie GET-zwischengespeicherte Inhalte, auch wenn $request_method Teil Ihres Cache-Keys ist
  • Konfigurierbares Antwortformat – erhalten Sie Lösch-Ergebnisse in HTML, JSON, XML oder Klartext
  • Alle Cache-Typen – funktioniert mit FastCGI, Proxy, SCGI und uWSGI

Schnellstart

Fügen Sie PURGE-Unterstützung zu jeder zwischengespeicherten Location hinzu:

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

Löschen Sie eine zwischengespeicherte Seite:

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

Das ist alles. Keine separate /purge-Location, keine Dateisystem-Berechtigungen zu verwalten.

Konfigurationsdirektiven

Syntax für dieselbe Location (empfohlen)

Ermöglicht das Löschen direkt in der Location, die zwischengespeicherte Inhalte ausliefert.

fastcgi_cache_purge

  • Syntax: fastcgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • Standard: none
  • Kontext: http, server, location

proxy_cache_purge

  • Syntax: proxy_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • Standard: none
  • Kontext: http, server, location

scgi_cache_purge

  • Syntax: scgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • Standard: none
  • Kontext: http, server, location

uwsgi_cache_purge

  • Syntax: uwsgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • Standard: none
  • Kontext: http, server, location

Syntax für separate Location

Verwenden Sie eine dedizierte Location für Lösch-Anfragen. Nützlich, wenn Sie unterschiedliche Zugriffsregeln für das Löschen benötigen.

fastcgi_cache_purge

  • Syntax: fastcgi_cache_purge zone_name key
  • Kontext: location

proxy_cache_purge

  • Syntax: proxy_cache_purge zone_name key
  • Kontext: location

scgi_cache_purge

  • Syntax: scgi_cache_purge zone_name key
  • Kontext: location

uwsgi_cache_purge

  • Syntax: uwsgi_cache_purge zone_name key
  • Kontext: location

Antwortformat

cache_purge_response_type

  • Syntax: cache_purge_response_type html|json|xml|text
  • Standard: html
  • Kontext: http, server, location

Beispiel mit JSON-Antworten:

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/"}

Cache-Key-Methoden-Substitution

Wenn $request_method Teil Ihres Cache-Keys ist, erzeugen Lösch-Anfragen einen anderen Key (PURGE vs. GET) und finden den zwischengespeicherten Eintrag nicht. Diese Direktiven lösen das Problem:

*_cache_purge_key_method

  • Syntax: fastcgi_cache_purge_key_method <method> [<method> ...]
  • Kontext: http, server, location

Verfügbar für alle Cache-Typen: 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;  # Ersetzt GET für PURGE bei der Key-Suche
}

Sie können mehrere Methoden angeben:

fastcgi_cache_purge_key_method GET HEAD;

WordPress-Integration

FastCGI-Cache + Löschung

Ein vollständiges WordPress-Setup mit Caching und automatischer Lösch-Unterstützung:

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

Warum fastcgi_cache_purge in beiden Locations? Die Root-URL / ist ein Sonderfall. Wenn try_files $uri/ prüft, findet es das Dokument-Root-Verzeichnis. Bei GET-Anfragen leitet die index-Direktive zu index.php weiter – aber bei PURGE-Anfragen greift index nicht und NGINX stoppt bei location /. Das Hinzufügen von fastcgi_cache_purge dort stellt sicher, dass PURGE / funktioniert.

Proxy-Cache-Purge-Plugin

Installieren Sie das Proxy Cache Purge-Plugin, um den Cache automatisch zu löschen, wenn Inhalte aktualisiert werden:

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

Das Plugin sendet PURGE-Anfragen an NGINX, wann immer Beiträge, Kommentare oder Seiten geändert werden – keine manuelle Cache-Verwaltung erforderlich.

Best Practices für Cache-Keys

Halten Sie es einfach – vermeiden Sie $request_method in Keys

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

## Vermeiden – Lösch-Anfragen stimmen nicht mit zwischengespeicherten GET-Einträgen überein
fastcgi_cache_key "$scheme$request_method$host$request_uri";

Wenn Sie $request_method unbedingt einbeziehen müssen, verwenden Sie *_cache_purge_key_method GET, um die Lösch-Key-Suche zu korrigieren.

Wildcard-Löschung

Löschen Sie mehrere Einträge, die einem Muster entsprechen, indem Sie * anhängen:

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

Das Sternchen muss das letzte Zeichen sein. Damit dies funktioniert, muss $uri am Ende Ihres Cache-Keys stehen.

Cache-Tags / Surrogate Keys

cache_purge_tags verbindet einen Tag-Header, der in zwischengespeicherten Upstream-Antworten gespeichert ist, mit einem Regex-Header auf einer autorisierten PURGE-Anfrage:

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;
}
  • Syntax: cache_purge_tags <cached-response-header> <purge-pattern-header>
  • Standard: off
  • Kontext: http, server, location

Für Magento Open Source und Adobe Commerce ist keine Anwendungsänderung erforderlich. Magento fügt bereits X-Magento-Tags zu cachebaren Antworten hinzu und sendet vertrauenswürdige lokale PURGE-Anfragen mit X-Magento-Tags-Pattern. Das Modul durchsucht dieselbe Cache-Zone und entfernt nur übereinstimmende Objekte. Ein Tag-Muster hat Vorrang vor Exakt-Key-, Wildcard- und purge_all-Verhalten für diese Anfrage.

Der Antwort-Tag-Header kann mit proxy_hide_header vor Clients verborgen werden. Er bleibt in den On-Disk-Cache-Metadaten von NGINX für die Invalidierung verfügbar. Ein ungültiger Regex gibt HTTP 400 zurück; ein gültiges Muster ohne Übereinstimmungen gibt HTTP 200 zurück, entsprechend dem von Magento generierten Varnish-VCL.

Die Tag-Invalidierung durchsucht zwischengespeicherte Header-Metadaten nur, wenn eine PURGE-Anfrage eintrifft. Normale Cache-Treffer zahlen keinen Tag-Index-Overhead, aber die Löschzeit wächst mit der Anzahl der Dateien in der Cache-Zone. Dies tauscht die persistente Ban-Liste von Varnish gegen sofortiges Löschen übereinstimmender NGINX-Objekte.

WordPress-Cache-Tag-Integrationen können dieselbe Direktive mit ihren Header-Namen verwenden:

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

Massenlöschung

Löschen Sie alle zwischengespeicherten Dateien auf einmal:

proxy_cache_purge PURGE purge_all from 127.0.0.1;

Dies kann bei großen Caches oder langsamem Speicher langsam sein. Verwenden Sie RAM-gestützte Cache-Pfade für beste Leistung.

IP-basierte Zugriffskontrolle

Beschränken Sie Lösch-Anfragen auf vertrauenswürdige Quellen:

fastcgi_cache_purge PURGE from 127.0.0.1 192.168.1.0/24;

Fehlerbehebung

Antwort Ursache Lösung
405 Not Allowed PURGE traf eine Location ohne *_cache_purge Fügen Sie *_cache_purge zu allen relevanten Locations hinzu
412 Precondition Failed Cache-Eintrag nicht gefunden (nie gecacht, bereits abgelaufen oder Key-Mismatch) Prüfen Sie den Cache-Key – achten Sie auf $request_method-Probleme
403 Forbidden Client-IP nicht in der from-Liste Fügen Sie Ihre IP zu from hinzu
200 OK, aber Cache bleibt bestehen $request_method im Cache-Key erzeugt nicht übereinstimmende Keys Entfernen Sie $request_method aus dem Key oder fügen Sie *_cache_purge_key_method GET hinzu

gzip_vary-Interaktion: Das Aktivieren von gzip_vary kann das Cache-Löschen beeinträchtigen. Wenn Sie inkonsistentes Lösch-Verhalten feststellen, deaktivieren Sie gzip_vary innerhalb der zwischengespeicherten Location.

Testen

ngx_cache_purge enthält eine Testsuite basierend auf Test::Nginx:

prove

Siehe auch