可通过 proxy_cache_bypass 指令配合 x-refresh-cache 请求头实现边缘节点缓存秒级强制刷新，无需重启服务或修改配置；配置 proxy_cache_bypass $http_x_refresh_cache 后，非空/非0/非"0"/非"off"/非"false" 的该请求头即触发回源，响应自动缓存，但不清理旧缓存。
可以通过 proxy_cache_bypass 指令配合自定义请求头（如 X-Refresh-Cache），让运维人员在不重启服务、不修改配置的前提下，对特定边缘节点的缓存进行秒级强制刷新。
配置 proxy_cache_bypass 触发条件
该指令的作用是：当满足指定条件时，Nginx 不使用已缓存的响应，而是直接向后端发起新请求。关键是让它识别运维人员发出的“刷新信号”：
- 在
location块中设置proxy_cache_bypass $http_x_refresh_cache; - 只要请求头中存在
X-Refresh-Cache（值非空、非0、非"0"、非"off"、非"false"），Nginx 就跳过缓存，回源拉取最新内容 - 建议同时配
proxy_cache_purge或proxy_cache_lock避免并发回源，但 bypass 本身不清理旧缓存，只绕过它
让刷新行为精准作用于边缘节点
边缘节点缓存是否刷新，取决于该节点上 Nginx 的配置是否生效，而非中心节点。因此需确保：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- 所有边缘节点统一部署含
proxy_cache_bypass的配置，并 reload（或热更）生效 - 运维请求必须直连目标边缘节点（例如通过节点 IP + Host 头），避免被负载均衡打散到其他节点
- 若用域名访问，可临时在 hosts 绑定某边缘 IP，或利用
curl -H "Host: example.com" http://edge-ip/path精准命中
运维人员执行刷新的操作方式
无需改代码、不依赖发布系统，一条 curl 即可触发：
curl -H "X-Refresh-Cache: 1" https://example.com/api/data- 响应体即为最新后端结果，且该响应会自动进入缓存（除非后端返回 no-cache/no-store）
- 后续普通请求仍走缓存，直到下次带该头请求再次 bypass
- 可结合脚本批量刷多个路径，或封装成内部运维工具按钮
安全与灰度控制建议
避免误刷或被恶意利用，推荐加一层轻量校验：
- 限制 header 值为特定令牌，如
proxy_cache_bypass $token;+map $http_x_refresh_cache $token { "sec-abc123" 1; default ""; } - 仅允许内网 IP 或指定运维出口 IP 发起该请求（用
if ($remote_addr !~ ^(10\.0\.0|192\.168)) { return 403; }） - 记录日志：
log_format cache_bypass '$remote_addr - $request_time "$request" $status $upstream_cache_status $http_x_refresh_cache';
不复杂但容易忽略：bypass 只影响本次请求是否读缓存，不会主动删除旧缓存；若要彻底清旧快照，需搭配 purge 模块或后端主动失效机制。
