proxy_cache_bypass在灰度中起作用需同时配置bypass与no_cache、缓存key包含灰度标识、后端识别灰度语义；常用信号源为X-Gray-Preview头、preview参数、gray_id Cookie。
要让 proxy_cache_bypass 在灰度环境中真正起作用，关键不是“加个变量就行”，而是构建一套可识别、可控制、不影响主流量的穿透机制。它必须和缓存策略、路由逻辑、后端协作对齐，否则只是形同虚设。
明确 bypass 的触发条件与变量来源
proxy_cache_bypass 本身不定义“谁该绕过”，只响应你给它的变量值。灰度穿透常用三类信号源：
-
自定义请求头：如
X-Gray-Preview: 1，对应 Nginx 变量$http_x_gray_preview（注意短横变下划线、全小写）；值为非空且不等于"0"或"off"即触发 -
查询参数：如
?preview=1，对应$arg_preview；适合前端临时链接调试，但不宜用于生产长期灰度 -
Cookie 字段：如
Cookie: gray_id=abc123，对应$cookie_gray_id；适合用户级灰度，需配合 map 指令做更精细分流
配置必须成对出现：bypass + no_cache
仅配 proxy_cache_bypass 是不够的——它只跳过读缓存，但后端返回的新响应仍可能被存入缓存（尤其当响应头含 Cache-Control: public）。灰度穿透要求“彻底隔离”，所以务必同步配置：
-
proxy_cache_bypass $http_x_gray_preview;→ 不查旧缓存 -
proxy_no_cache $http_x_gray_preview;→ 不存新响应
两个指令变量名必须完全一致，否则逻辑断裂。若漏掉 proxy_no_cache，一次 preview 请求可能把未验证的数据污染整个缓存键空间。
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
灰度穿透需与缓存 key 设计协同
如果 proxy_cache_key 没包含灰度标识，那即使 bypass 成功，后续普通请求仍可能命中被 preview “污染”过的缓存条目。稳妥做法是让灰度流量生成独立缓存索引：
- 基础方案：在 key 中加入灰度标识变量，例如：
proxy_cache_key "$scheme$request_method$host$request_uri$is_args$args$cookie_gray_id"; - 进阶方案：用
map指令预生成灰度前缀，再拼入 key，确保灰度请求 key 始终与常规请求错开
后端必须识别并响应灰度语义
proxy_cache_bypass 只解决“Nginx 层不走缓存”，不代表后端会返回灰度内容。若后端没读取 X-Gray-Preview 或忽略 preview=1，那穿透回来的仍是线上数据。必须做到：
- 后端中间件统一解析该 header 或参数，并切换数据源、模板或功能开关
- 避免日志误报：后端应静默处理该 header，不记录为异常或告警
- 建议响应头中添加
X-Gray: active，便于前端或监控快速确认路径正确性
不复杂但容易忽略
