nginx 主动缓存失效需通过静态编译 ngx_cache_purge 模块实现，依赖完全一致的 cache_key 和严格访问控制的 purge 接口，请求返回 200 表示已处理、404 表示无缓存、405 表示配置错误。

要让 Nginx 实现主动缓存失效，核心是用 proxy_cache_purge 模块精准“点名删除”某条缓存，而不是等它自然过期。它不依赖时间，而是靠一次 HTTP 请求立即让指定 URL 的缓存失效。

必须静态编译模块并验证启用

原生 Nginx 不带 purge 功能，需集成第三方模块 ngx_cache_purge：

• 从 GitHub 获取稳定分支（如 release/v2.5+），执行 git clone --depth 1 https://github.com/FRiCKLE/ngx_cache_purge.git
• 编译 Nginx 时显式加入： ./configure --add-module=/path/to/ngx_cache_purge [其他参数]
• 安装后运行 nginx -V 2>&1 | grep cache_purge，有输出即表示模块已生效
• 注意：该模块不支持动态加载（.so），失败时无报错但 PURGE 请求会返回 405

缓存 key 必须完全一致

purge 是否成功，90% 取决于 key 是否一字不差。Nginx 不做模糊匹配，只比对哈希值：

CPA Update - Secure CLI Proxy API Maintenance

安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

下载

• 在 location 中显式定义 proxy_cache_key，例如：proxy_cache_key "$scheme$request_method$host$request_uri";
• 对应的 purge location 中，key 构造必须复用相同变量，且顺序、大小写、是否含参数都要一致
• 若原始 key 含查询参数（$args），purge 里就得补上 $is_args$args；若用 $request_uri，就别误写成 $uri（后者不含参数）
• 建议临时加 add_header X-Cache-Key "$scheme$request_method$host$request_uri"; 输出 key，用于调试比对

配置安全的 purge 接口

/purge 路径是高危入口，绝不能暴露在公网或开放给任意 IP：

• 用正则匹配路径，例如：location ~ ^/purge(/.*)$ { ... }，其中 $1 捕获待清理的路径部分
• 仅允许可信来源，如 CI/CD 服务器、运维跳板机：allow 10.20.1.50;、allow 127.0.0.1;，结尾必须加 deny all;
• 避免使用域名白名单或注释掉 deny 规则——IP 是最直接可靠的控制方式
• 如需增强鉴权，可在 location 内嵌套 auth_request，对接内部 JWT 或 OAuth 校验服务

触发清理与响应状态解读

发送一个 PURGE 请求即可完成秒级失效：

• 清除首页：curl -X PURGE http://example.com/purge/
• 清除带参接口：curl -X PURGE "http://example.com/purge/api/user?id=123"
• 状态码含义要清楚：
  200：请求已接收并处理（无论该 key 当前是否存在缓存）
  404：当前无对应缓存条目（正常，不是错误）
  405：方法不被允许 → 检查模块是否启用、location 是否匹配、是否用了 PURGE 方法
• purge 删除的是共享内存中的元数据，磁盘文件由 cache manager 异步回收；下次请求立刻回源，X-Cache-Status 立即变为 MISS