Nginx 中 proxy_cache_purge 怎样通过 API 清除指定缓存

要让Nginx通过API清除指定缓存，关键是确保purge请求精准命中目标缓存条目，这依赖于cache_key与purge key严格一致、ngx_cache_purge模块静态编译启用、以及IP白名单等可信访问控制。

要让 Nginx 通过 API 清除指定缓存，关键不是“加个 purge 接口”，而是确保每次清除请求都能精准命中目标缓存条目——这依赖于缓存键（cache key）的一致性、模块的正确启用、以及调用来源的可信控制。

必须静态编译并验证 ngx_cache_purge 模块

原生 Nginx 不支持 PURGE 方法，需使用第三方模块 ngx_cache_purge，且仅支持静态编译：

• 编译时添加 --add-module=/path/to/ngx_cache_purge，注意匹配当前 Nginx 版本（推荐 release/v2.5+）
• 上线前执行 nginx -V 2>&1 | grep -o 'cache_purge'，输出含 cache_purge 才表示生效
• 动态加载（.so）不可行；失败时无报错，但 PURGE 请求会直接返回 405

purge location 的 key 必须与 proxy_cache_key 完全一致

清除失败的主因是 key 不匹配。例如：

• 若缓存配置为：proxy_cache_key "$scheme$request_method$host$request_uri";
• 则 purge location 应写为：location ~ ^/purge(/.*)$ { proxy_cache_purge my_cache "$scheme$request_method$host$1"; }
• 如果原始 key 包含查询参数（$args），这里必须补上 $is_args$args
• 建议在测试阶段用 add_header X-Cache-Key "$scheme$request_method$host$request_uri"; 输出实际 key，与 purge 构造值比对

API 调用必须走可信通道，禁止公网暴露

PURGE 是高危操作，不能靠“隐藏路径”防护：

• 只允许内网 IP 访问，如 CI/CD 发布机、运维跳板机：allow 10.20.0.0/16;，结尾必须加 deny all;
• 避免用域名或通配符做白名单，IP 最直接可靠
• 如需增强鉴权，可在 location 内嵌套 auth_request，对接内部 OAuth 或 JWT 校验服务

调用方式与响应状态码含义要准确理解

清除不是删文件，而是标记缓存条目为无效。常用调用方式及状态码语义：

• 发送 curl -X PURGE https://api.example.com/purge/v1/user/1001
• 200：请求已接收并处理成功（无论该 URL 当前是否有缓存）
• 404：该 key 当前无缓存条目（正常情况，非错误）
• 405：方法不被允许 → 检查模块是否启用、location 是否匹配、HTTP 方法是否为大写 PURGE