proxy_cache_bypass生效需同时满足：同location内配置proxy_cache；变量名严格小写且短横转下划线；值非空且不为"0"/"off"；多变量任意一真即绕过；响应头无X-Cache:HIT、日志显示BYP或MISS。

要在 location 块中用 proxy_cache_bypass 跳过特定请求的缓存，核心是让该指令“生效”且“精准触发”——它本身不自动起作用，必须满足前提、写对变量、值符合判断逻辑。

必须共存：proxy_cache 和 proxy_cache_bypass 同在 location 中

只写 proxy_cache_bypass $http_x_refresh 没用。Nginx 忽略它，除非同一 location 里明确启用了缓存：

• 必须有 proxy_cache mycache;（名称需与 proxy_cache_path 中定义的 keys_zone 一致）
• 不能只在 http 块里全局写 proxy_cache_bypass，它不会向下继承到未启用缓存的 location
• 常见错误：把 proxy_cache_bypass 放在 server 块却漏了 location 里的 proxy_cache

变量要写对：HTTP 头 → $http_ 开头 + 短横变下划线

客户端带 X-Refresh: 1，Nginx 内部对应变量是 $http_x_refresh，不是 $http_X_Refresh 或 $http_xrefresh：

CPA Update - Secure CLI Proxy API Maintenance

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

下载

• 大小写敏感：必须全小写
• 短横（-）一律转为下划线（_）
• 值只要非空、且不等于 "0" 或 "off"（不区分大小写），就触发 bypass
• 例如这些都有效：X-Refresh: true、X-Refresh: T、X-Refresh: 123

支持多条件组合：用多个变量实现精细控制

可以同时传入多个变量，任意一个为真即绕过：

• proxy_cache_bypass $http_x_preview $arg_debug $remote_addr;
• 比如仅允许内网管理员预览：proxy_cache_bypass $http_x_preview $remote_addr ~^(192\.168\.10\.);
• 或结合自定义 map 变量：proxy_cache_bypass $skip_cache;，再用 map 规则统一计算是否跳过

验证是否真正生效：看响应头和日志

上线后务必检查实际行为，不能只看配置：

• 发起带头请求：curl -H "X-Refresh: 1" https://yoursite.com/api/data
• 响应头中不应出现 X-Cache: HIT；理想是 X-Cache: MISS 或无此头
• 日志中 $upstream_cache_status 应显示 BYP（bypass）或 MISS，而非 HIT
• 若仍命中缓存，先确认 location 是否真走了你写的那段配置（可用 error_log 打印调试变量）