跳转至

cache-purge: NGINX 缓存清除模块

安装

您可以在任何基于 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
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.8，于 2026 年 1 月 29 日发布。

ngx_cache_purge 是 nginx 模块，增加了从 FastCGI、proxy、SCGI 和 uWSGI 缓存中清除内容的能力。清除操作会删除与清除请求具有相同缓存键的内容。

赞助商

原始补丁的工作完全由 yo.se 资助。

配置指令（相同位置语法）

fastcgi_cache_purge

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

允许从 FastCGI 的缓存中清除选定页面。

proxy_cache_purge

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

允许从 proxy 的缓存中清除选定页面。

scgi_cache_purge

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

允许从 SCGI 的缓存中清除选定页面。

uwsgi_cache_purge

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

允许从 uWSGI 的缓存中清除选定页面。

配置指令（单独位置语法）

fastcgi_cache_purge

  • 语法: fastcgi_cache_purge zone_name key
  • 默认: none
  • 上下文: location

设置用于从 FastCGI 的缓存中清除选定页面的区域和键。

proxy_cache_purge

  • 语法: proxy_cache_purge zone_name key
  • 默认: none
  • 上下文: location

设置用于从 proxy 的缓存中清除选定页面的区域和键。

scgi_cache_purge

  • 语法: scgi_cache_purge zone_name key
  • 默认: none
  • 上下文: location

设置用于从 SCGI 的缓存中清除选定页面的区域和键。

uwsgi_cache_purge

  • 语法: uwsgi_cache_purge zone_name key
  • 默认: none
  • 上下文: location

设置用于从 uWSGI 的缓存中清除选定页面的区域和键。

配置指令（可选）

cache_purge_response_type

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

设置清除结果的响应类型。

部分键

有时无法传递确切的键来清除页面。例如，当 cookie 的内容或参数是键的一部分时。您可以通过在 URL 末尾添加星号来指定部分键。

curl -X PURGE /page*

星号必须是键的最后一个字符，因此您 必须 将 $uri 变量放在末尾。

示例配置（相同位置语法）

http {
    proxy_cache_path  /tmp/cache  keys_zone=tmpcache:10m;

    server {
        location / {
            proxy_pass         http://127.0.0.1:8000;
            proxy_cache        tmpcache;
            proxy_cache_key    "$uri$is_args$args";
            proxy_cache_purge  PURGE from 127.0.0.1;
        }
    }
}

示例配置（相同位置语法 - 清除所有缓存文件）

http {
    proxy_cache_path  /tmp/cache  keys_zone=tmpcache:10m;

    server {
        location / {
            proxy_pass         http://127.0.0.1:8000;
            proxy_cache        tmpcache;
            proxy_cache_key    "$uri$is_args$args";
            proxy_cache_purge  PURGE purge_all from 127.0.0.1 192.168.0.0/8;
        }
    }
}

示例配置（单独位置语法）

http {
    proxy_cache_path  /tmp/cache  keys_zone=tmpcache:10m;

    server {
        location / {
            proxy_pass         http://127.0.0.1:8000;
            proxy_cache        tmpcache;
            proxy_cache_key    "$uri$is_args$args";
        }

        location ~ /purge(/.*) {
            allow              127.0.0.1;
            deny               all;
            proxy_cache        tmpcache;
            proxy_cache_key    "$1$is_args$args";
        }
    }
}

示例配置（可选）

http {
    proxy_cache_path  /tmp/cache  keys_zone=tmpcache:10m;

    cache_purge_response_type text;

    server {

        cache_purge_response_type json;

        location / { #json
            proxy_pass         http://127.0.0.1:8000;
            proxy_cache        tmpcache;
            proxy_cache_key    "$uri$is_args$args";
        }

        location ~ /purge(/.*) { #xml
            allow              127.0.0.1;
            deny               all;
            proxy_cache        tmpcache;
            proxy_cache_key    "$1$is_args$args";
            cache_purge_response_type xml;
        }

        location ~ /purge2(/.*) { # json
            allow              127.0.0.1;
            deny               all;
            proxy_cache        tmpcache;
            proxy_cache_key    "$1$is_args$args";
        }
    }

    server {

        location / { #text
            proxy_pass         http://127.0.0.1:8000;
            proxy_cache        tmpcache;
            proxy_cache_key    "$uri$is_args$args";
        }

        location ~ /purge(/.*) { #text
            allow              127.0.0.1;
            deny               all;
            proxy_cache        tmpcache;
            proxy_cache_key    "$1$is_args$args";
        }

        location ~ /purge2(/.*) { #html
            allow              127.0.0.1;
            deny               all;
            proxy_cache        tmpcache;
            proxy_cache_key    "$1$is_args$args";
            cache_purge_response_type html;
        }
    }
}

解决问题

  • 启用 gzip_vary 可能会导致清除时出现不同的结果，启用它时，您可能会遇到清除缓存的问题。为了可靠的操作，您可以在位置中禁用 gzip_vary #20。

测试

ngx_cache_purge 附带了基于 Test::Nginx 的完整测试套件。

您可以通过运行以下命令进行测试：

$ prove

另见

GitHub

您可以在 nginx-module-cache-purge 的 GitHub 仓库中找到此模块的其他配置提示和文档。