proxy_cache_bypass用于让满足条件的请求跳过缓存直连后端，需与proxy_cache同location启用，并配合proxy_cache_skip防止响应被缓存；变量非空且不为"0"即触发，支持请求头、cookie、参数等组合判断，生效时$upstream_cache_status为bypass。
开发人员可以通过配置 proxy_cache_bypass，让特定请求（比如带特定 header 或参数的请求）跳过 Nginx 缓存，直接回源获取最新数据，而普通用户仍走缓存——这是调试和验证后端变更最常用的方式。
设置 bypass 条件：基于请求头或参数
该指令接收一个或多个变量，只要其中任一变量值为非空字符串（且不为 "0"），Nginx 就不查找缓存、直接转发请求到上游。常用组合如下：
- 用自定义请求头识别开发请求：
proxy_cache_bypass $http_x_bypass_cache;
前端或 curl 加上-H "X-Bypass-Cache: 1"即可绕过 - 用 cookie 区分内部人员：
proxy_cache_bypass $cookie_dev_mode;
登录态中设置dev_mode=1的 cookie 即生效 - 用查询参数快速测试：
proxy_cache_bypass $arg_nocache;
访问/api/data?nocache=1即跳过缓存
配合 proxy_cache_skip 避免缓存 bypass 请求
仅靠 proxy_cache_bypass 不足以保证“绕过缓存”，还需防止这类请求被意外缓存。建议同步配置：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
-
proxy_cache_skip $http_x_bypass_cache;—— 若 header 存在，不缓存响应 -
proxy_cache_skip $arg_nocache;—— 若参数存在，响应不写入缓存 - 两者搭配，既跳过读缓存，也跳过写缓存，避免污染缓存池
验证是否生效：看响应头和日志
绕过成功时，响应头中不应出现 X-Cache: HIT 或类似字段（取决于你自定义的缓存标识），而应是 X-Cache: MISS 或无该头；同时可通过开启 log_format 记录 $upstream_cache_status 变量确认：
-
HIT：命中缓存 -
MISS：未命中，但已缓存响应 -
BYPASS：触发了proxy_cache_bypass，未查缓存、未写缓存
安全提醒：限制 bypass 权限范围
绕过缓存可能暴露未发布接口或增加后端压力，务必做好访问控制：
- 不要对所有 IP 开放 bypass，例如只允许内网或特定 IP 段：
set $bypass "0";<br>if ($remote_addr ~ ^(192\.168\.|10\.) ) { set $bypass "1"; }<br>proxy_cache_bypass $bypass $http_x_bypass_cache; - 避免使用易被构造的公开参数（如
?debug=1），优先选需鉴权的 header 或 cookie - 上线前移除或注释掉开发专用配置，防止误用
