cache-purge: NGINX 缓存清除模块

需要 GetPageSpeed NGINX Extras 订阅的 Pro 计划（或更高版本）。

安装

您可以在任何基于 RHEL 的发行版中安装此模块，包括但不限于：

• RedHat Enterprise Linux 7、8、9 和 10
• CentOS 7、8、9
• AlmaLinux 8、9
• Rocky Linux 8、9
• Amazon Linux 2 和 Amazon Linux 2023

CentOS/RHEL 8+、Fedora Linux、Amazon Linux 2023+CentOS/RHEL 7 和 Amazon Linux 2

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

通过在 /etc/nginx/nginx.conf 的顶部添加以下内容来启用模块：

load_module modules/ngx_http_cache_purge_module.so;

本文档描述了 nginx-module-cache-purge v2.5.10，于 2026 年 3 月 25 日发布。

---

通过 HTTP PURGE 请求选择性地从 NGINX 的 FastCGI、代理、SCGI 和 uWSGI 缓存中清除内容——无需文件系统黑客，无需权限头痛。

这是 NGINX Plus 中的一个功能，但 ngx_cache_purge 将其带入开源 NGINX。

主要特性

• 同一位置清除 — 直接向现有缓存位置添加 PURGE 支持，无需额外的 location 块
• 通配符清除 — 使用 * 一次性清除多个缓存条目
• 批量清除 — 使用 purge_all 一次性清除所有缓存内容
• 基于 IP 的访问控制 — 限制可以发出清除请求的用户
• 缓存键方法替代 — 即使 $request_method 在您的缓存键中，也能清除 GET 缓存的内容
• 可配置的响应格式 — 以 HTML、JSON、XML 或纯文本格式获取清除结果
• 所有缓存类型 — 适用于 FastCGI、代理、SCGI 和 uWSGI

快速开始

向任何缓存位置添加 PURGE 支持：

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

清除缓存页面：

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

就这样。没有单独的 /purge 位置，也没有需要管理的文件系统权限。

配置指令

同一位置语法（推荐）

允许在提供缓存内容的位置直接进行清除。

fastcgi_cache_purge

• 语法: fastcgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
• 默认: none
• 上下文: http、server、location

proxy_cache_purge

• 语法: proxy_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
• 默认: none
• 上下文: http、server、location

scgi_cache_purge

• 语法: scgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
• 默认: none
• 上下文: http、server、location

uwsgi_cache_purge

• 语法: uwsgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
• 默认: none
• 上下文: http、server、location

单独位置语法

为清除请求使用专用位置。当您需要不同的访问规则进行清除时非常有用。

fastcgi_cache_purge

• 语法: fastcgi_cache_purge zone_name key
• 上下文: location

proxy_cache_purge

• 语法: proxy_cache_purge zone_name key
• 上下文: location

scgi_cache_purge

• 语法: scgi_cache_purge zone_name key
• 上下文: location

uwsgi_cache_purge

• 语法: uwsgi_cache_purge zone_name key
• 上下文: location

响应格式

cache_purge_response_type

• 语法: cache_purge_response_type html|json|xml|text
• 默认: html
• 上下文: http、server、location

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

缓存键方法替代

当 $request_method 是您缓存键的一部分时，清除请求会生成不同的键（PURGE 与 GET），并且找不到缓存条目。这些指令解决了这个问题：

*_cache_purge_key_method

• 语法: fastcgi_cache_purge_key_method <method> [<method> ...]
• 上下文: http、server、location

适用于所有缓存类型：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;  # 在键查找中将 GET 替代 PURGE
}

您可以指定多个方法：

fastcgi_cache_purge_key_method GET HEAD;

WordPress 集成

FastCGI 缓存 + 清除

一个完整的 WordPress 设置，具有缓存和自动清除支持：

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

为什么在两个位置都使用 fastcgi_cache_purge？ 根 URL / 是一个特殊情况。当 try_files 检查 $uri/ 时，它会找到文档根目录。对于 GET 请求，index 指令会路由到 index.php — 但对于 PURGE 请求，index 不适用，NGINX 会停在 location /。在这里添加 fastcgi_cache_purge 确保 PURGE / 有效。

代理缓存清除插件

安装 Proxy Cache Purge 插件，以在内容更新时自动清除缓存：

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

该插件会在每次修改帖子、评论或页面时向 NGINX 发送 PURGE 请求——无需手动管理缓存。

缓存键最佳实践

保持简单 — 避免在键中使用 $request_method

# 推荐
fastcgi_cache_key "$scheme$host$request_uri";

# 避免 — 清除请求将无法匹配缓存的 GET 条目
fastcgi_cache_key "$scheme$request_method$host$request_uri";

如果您必须包含 $request_method，请使用 *_cache_purge_key_method GET 来修复清除键查找。

通配符清除

通过附加 * 清除匹配模式的多个条目：

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

星号必须是最后一个字符。为了使其工作，$uri 必须位于您的缓存键的末尾。

批量清除

一次性清除所有缓存文件：

proxy_cache_purge PURGE purge_all from 127.0.0.1;

对于大型缓存或慢速存储，这可能会很慢。使用基于 RAM 的缓存路径以获得最佳性能。

基于 IP 的访问控制

限制清除请求仅来自受信任的来源：

fastcgi_cache_purge PURGE from 127.0.0.1 192.168.1.0/24;

故障排除

响应	原因	修复
405 Not Allowed	PURGE 命中没有 *_cache_purge 的位置	在所有相关位置添加 *_cache_purge
412 Precondition Failed	找不到缓存条目（从未缓存、已过期或键不匹配）	检查缓存键 — 查找 $request_method 问题
403 Forbidden	客户端 IP 不在 from 列表中	将您的 IP 添加到 from
200 OK 但缓存仍然存在	缓存键中的 $request_method 创建了不匹配的键	从键中删除 $request_method，或添加 *_cache_purge_key_method GET

gzip_vary 交互: 启用 gzip_vary 可能会干扰缓存清除。如果您遇到不一致的清除行为，请在缓存位置内禁用 gzip_vary。

测试

ngx_cache_purge 包含基于 Test::Nginx 的测试套件：

prove

另见

• 使用 NGINX 缓存清除增强 WordPress — 完整设置指南
• NGINX 代理缓存与微缓存 — 代理缓存基础
• NGINX fastcgi_cache_purge 文档 — NGINX Plus 参考