Nginx 中 proxy_cache_purge 清理过期动态缓存内容-Nginx-PHP中文网

nginx proxy_cache_purge 只支持精准键值删除，不感知缓存过期；清理动态缓存需确保后端响应可缓存、cache_key稳定可复现，且purge请求的key与缓存时完全一致，否则无法命中删除。

nginx 中 proxy_cache_purge 清理过期动态缓存内容

Nginx 的 proxy_cache_purge 模块不能直接清理“过期”的动态缓存内容，它只做精准键值删除，不感知缓存是否过期。所谓“清理过期动态缓存”，实际是两件事的配合：让动态内容可缓存 + 主动触发 purge 清除旧版本。关键不在“过期”本身，而在“如何让 purge 命中你要删的那条缓存”。

proxy_cache_purge 对动态内容的适用前提

动态内容（如 PHP、Node.js 接口）必须被 Nginx 显式缓存，即配置了 proxy_cache 且响应未被 Cache-Control: no-cache 或 Vary 头完全绕过；
缓存 key 必须稳定、可复现，不能含随机值（如 session_id、timestamp、CSRF token）；
purge 请求构造的 key，必须与缓存时 proxy_cache_key 完全一致，否则查无此键，删无可删。

常见失败原因：

后端返回 Vary: Cookie，导致同一 URL 缓存多个变体，而 purge 只删默认变体；
proxy_cache_key 包含 $cookie_xxx 或 $arg_token，但 purge 请求没带对应 cookie 或参数；
使用了 fastcgi_cache 却误配 proxy_cache_purge（应配 fastcgi_cache_purge）。

如何让动态接口支持 purge 清理

统一缓存 key 规范
显式定义 proxy_cache_key，剥离不可控变量：
```
proxy_cache_key "$scheme$request_method$host$uri$is_args$args";
```
若需区分用户角色（如 admin/user），可加入可控标识：

aperture: the L402 aware reverse proxy
安装并运行 Aperture（Lightning Labs 的 L402 闪电反向代理），用于创建 L402 付费墙、配置付费 API 端点、为其他代理托管付费内容或测试 L402 认证流程。

下载
```
proxy_cache_key "$scheme$request_method$host$uri$is_args$args|$http_x_user_role";
```

控制缓存粒度与有效期
避免一刀切缓存全部动态接口，按状态码和路径分级：

proxy_cache_valid 200 302 5m;   # 成功响应缓存5分钟
proxy_cache_valid 404 1m;       # 错误页缓存1分钟
proxy_cache_use_stale error timeout updating;

为 purge 接口匹配动态路径
location 需捕获完整路径及参数，确保 $1$is_args$args 与缓存 key 中的 $uri$is_args$args 对齐：
```
location ~ ^/purge(/.*)$ {
    allow 127.0.0.1;
    allow 10.10.5.0/24;
    deny all;
    proxy_cache_purge my_cache "$scheme$request_method$host$1$is_args$args";
}
```
✅ 正确调用示例：
curl -X PURGE 'https://api.example.com/purge/user/profile?id=123'
❌ 错误调用（少参数）：
curl -X PURGE 'https://api.example.com/purge/user/profile' → 不匹配，返回 200 但实际未删。

动态内容 purge 的典型落地方式

发布后自动清理
在 CI/CD 流程末尾，调用 purge 接口清除对应 API 路径：

curl -X PURGE "https://api.example.com/purge/v1/articles"
curl -X PURGE "https://api.example.com/purge/v1/articles/1001"

业务逻辑触发清理
用户编辑文章后，后端主动发请求：

PURGE /v1/articles/1001 HTTP/1.1
Host: api.example.com
X-Purge-Token: abc123

配合 map 和鉴权头校验：

map $http_x_purge_token $valid_purge {
    "abc123" 1;
    default 0;
}
location ~ ^/purge(/.*)$ {
    if ($valid_purge = 0) { return 403; }
    proxy_cache_purge my_cache "$scheme$request_method$host$1$is_args$args";
}

批量清理某类动态资源
用脚本生成 key 列表并逐个 purge（不推荐高频执行）：

for id in $(seq 1 100); do
    curl -s -o /dev/null -X PURGE "https://api.example.com/purge/v1/items/$id"
done

真正“过期”的缓存由 Nginx 自动淘汰（靠 inactive 和 proxy_cache_valid），purge 是人工干预手段——它解决的是“不该再用，但还没到 inactive 时间”的问题。只要 key 设计得当、调用方式匹配，动态内容一样可以精准清理。