Nginx proxy_cache条件绕过需三要素协同：启用缓存（proxy_cache+proxy_cache_valid）、定义绕过条件（proxy_cache_bypass）、阻止写入（proxy_no_cache），且必须同location内共存，缺一不可。

要让 Nginx 的 proxy_cache 支持条件绕过，关键不是“加一条 bypass 指令”就完事，而是构建一套协同生效的缓存控制链：启用缓存、定义绕过条件、阻止响应写入——三者缺一不可。

必须共存的基础配置

单独写 proxy_cache_bypass 不起作用。它只在已启用缓存的 location 中才被识别：

• location 块内必须有 proxy_cache mycache（名称需与 proxy_cache_path 中的 keys_zone 一致）
• 必须设置 proxy_cache_valid，例如 proxy_cache_valid 200 302 5m，否则 Nginx 不认为该响应可缓存，整个缓存流程不启动
• proxy_cache_bypass 和 proxy_no_cache 必须写在同一 location 块内，不能放在 http 或 server 级别

常用 bypass 条件写法

指令接收一个或多个变量，任意一个变量值为非空字符串且不等于 "0" 或 "off"（不区分大小写），即触发绕过：

CPA Update - Secure CLI Proxy API Maintenance

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

下载

• 用自定义请求头：proxy_cache_bypass $http_x_bypass_cache → 客户端加 -H "X-Bypass-Cache: 1"
• 用查询参数：proxy_cache_bypass $arg_nocache → 访问 /api/data?nocache=1
• 用 Cookie：proxy_cache_bypass $cookie_dev_mode → 浏览器含 dev_mode=1 的 Cookie
• 用 Authorization 头：proxy_cache_bypass $http_authorization → 适用于带 Token 的管理接口
• 组合多个条件：proxy_cache_bypass $arg_debug $http_x_preview $cookie_admin → 满足任一即绕过

必须配对 proxy_no_cache 防污染

proxy_cache_bypass 只跳过读缓存，但默认仍会把后端返回的响应写入缓存。若管理员请求返回敏感数据，可能被普通用户误命中：

• 务必添加 proxy_no_cache $http_x_bypass_cache（变量名和值判断逻辑必须与 bypass 完全一致）
• 也可用不同变量，如 proxy_no_cache $arg_nocache，但推荐统一使用同一变量，确保“不读 + 不存”原子生效
• 生效后响应头中 X-Cache-Status 显示 BYP，日志中 $upstream_cache_status 字段为 BYP

复杂场景建议用 map 预处理

当需要按路径、角色、登录态等多维度判断时，直接拼变量易出错。推荐先用 map 构建语义化布尔变量：

• 按路径绕过：map $request_uri $skip_cache_by_path { ~*^/admin/ 1; ~*^/api/debug 1; default 0; }
• 按用户角色：map $http_x_user_role $skip_cache_by_role { "admin" 1; "dev" 1; default 0; }
• 在 location 中统一调用：proxy_cache_bypass $skip_cache_by_path $skip_cache_by_role; 和 proxy_no_cache $skip_cache_by_path $skip_cache_by_role;