Zum Inhalt

cache-purge: NGINX Cache Purge Modul

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 an den 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.5.10, veröffentlicht am 25. März 2026.

Inhalt selektiv aus den FastCGI-, Proxy-, SCGI- und uWSGI-Caches von NGINX mit HTTP PURGE-Anfragen löschen — keine Hacks im Dateisystem, keine Berechtigungsprobleme.

Dies ist eine Funktion, die in NGINX Plus vorhanden ist, aber ngx_cache_purge bringt sie zu open-source NGINX.

Hauptmerkmale

  • Same-location purging — fügen Sie PURGE-Unterstützung direkt zu bestehenden Cache-Standorten hinzu, keine zusätzlichen location-Blöcke erforderlich
  • Wildcard purging — mehrere Cache-Einträge mit einer einzigen Anfrage unter Verwendung von * löschen
  • Bulk purge — alle zwischengespeicherten Inhalte auf einmal mit purge_all löschen
  • IP-basiertes Zugriffssteuerung — beschränken Sie, wer Löschanfragen stellen kann
  • Cache-Schlüssel-Methode Substitution — löschen Sie GET-zwischengespeicherte Inhalte, selbst wenn $request_method in Ihrem Cache-Schlüssel enthalten ist
  • Konfigurierbares Antwortformat — erhalten Sie Löschresultate in HTML, JSON, XML oder einfachem Text
  • Alle Cache-Typen — funktioniert mit FastCGI, Proxy, SCGI und uWSGI

Schnellstart

Fügen Sie PURGE-Unterstützung zu jedem zwischengespeicherten Standort 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 war's. Kein separates /purge-Verzeichnis, keine Dateisystemberechtigungen zu verwalten.

Konfigurationsanweisungen

Same-Location-Syntax (Empfohlen)

Aktiviert das Löschen direkt im Standort, der zwischengespeicherte Inhalte bereitstellt.

fastcgi_cache_purge

  • syntax: fastcgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • default: none
  • context: http, server, location

proxy_cache_purge

  • syntax: proxy_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • default: none
  • context: http, server, location

scgi_cache_purge

  • syntax: scgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • default: none
  • context: http, server, location

uwsgi_cache_purge

  • syntax: uwsgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • default: none
  • context: http, server, location

Separate-Location-Syntax

Verwenden Sie einen speziellen Standort für Löschanfragen. Nützlich, wenn Sie unterschiedliche Zugriffsregeln für das Löschen benötigen.

fastcgi_cache_purge

  • syntax: fastcgi_cache_purge zone_name key
  • context: location

proxy_cache_purge

  • syntax: proxy_cache_purge zone_name key
  • context: location

scgi_cache_purge

  • syntax: scgi_cache_purge zone_name key
  • context: location

uwsgi_cache_purge

  • syntax: uwsgi_cache_purge zone_name key
  • context: location

Antwortformat

cache_purge_response_type

  • syntax: cache_purge_response_type html|json|xml|text
  • default: html
  • context: 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-Schlüssel-Methode Substitution

Wenn $request_method Teil Ihres Cache-Schlüssels ist, erzeugen Löschanfragen einen anderen Schlüssel (PURGE vs GET) und finden den zwischengespeicherten Eintrag nicht. Diese Anweisungen lösen das Problem:

*_cache_purge_key_method

  • syntax: fastcgi_cache_purge_key_method <method> [<method> ...]
  • context: 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 durch PURGE bei der Schlüsselabfrage
}

Sie können mehrere Methoden angeben:

fastcgi_cache_purge_key_method GET HEAD;

WordPress-Integration

FastCGI Cache + Purge

Eine vollständige WordPress-Installation mit Caching und automatischer Löschunterstü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 Standorten? Die Root-URL / ist ein Sonderfall. Wenn try_files $uri/ überprüft, findet es das Dokumentstammverzeichnis. Für GET-Anfragen leitet die index-Anweisung zu index.php — aber für PURGE-Anfragen gilt 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.

Cache-Schlüssel Best Practices

Halten Sie es einfach — vermeiden Sie $request_method in Schlüsseln

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

# Vermeiden — Löschanfragen 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 Löschschlüsselabfragen zu beheben.

Wildcard-Löschen

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

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

Der Stern muss das letzte Zeichen sein. Damit dies funktioniert, muss $uri am Ende Ihres Cache-Schlüssels stehen.

Bulk Purge

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 langsamen Speichern langsam sein. Verwenden Sie RAM-unterstützte Cache-Pfade für die beste Leistung.

IP-basierte Zugriffssteuerung

Beschränken Sie Löschanfragen auf vertrauenswürdige Quellen:

fastcgi_cache_purge PURGE from 127.0.0.1 192.168.1.0/24;

Fehlersuche

Antwort Ursache Lösung
405 Not Allowed PURGE traf einen Standort ohne *_cache_purge Fügen Sie *_cache_purge zu allen relevanten Standorten hinzu
412 Precondition Failed Cache-Eintrag nicht gefunden (nie zwischengespeichert, bereits abgelaufen oder Schlüssel-Mismatch) Überprüfen Sie den Cache-Schlüssel — suchen Sie nach Problemen mit $request_method
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-Schlüssel erzeugt nicht übereinstimmende Schlüssel Entfernen Sie $request_method aus dem Schlüssel oder fügen Sie *_cache_purge_key_method GET hinzu

gzip_vary Interaktion: Die Aktivierung von gzip_vary kann das Löschen des Caches beeinträchtigen. Wenn Sie inkonsistentes Löschverhalten feststellen, deaktivieren Sie gzip_vary im zwischengespeicherten Standort.

Testen

ngx_cache_purge enthält eine Test-Suite basierend auf Test::Nginx:

prove

Siehe auch