灰度发布可通过Nginx的proxy_cache_bypass与proxy_no_cache实现请求级缓存绕过，或通过动态proxy_cache_key（如嵌入$is_gray）实现缓存逻辑隔离，并需配合map变量与upstream路由完成端到端灰度闭环，同时注意权限控制与安全防护。
灰度发布期间，既要让部分用户看到新版本，又要避免缓存污染或误命中旧内容，Nginx 的 proxy_cache 本身不直接支持“按版本隔离缓存”，但可通过组合 proxy_cache_bypass、proxy_no_cache 和缓存 key 动态构造，实现请求级绕过或逻辑隔离。
让灰度流量完全跳过缓存读写
这是最常用也最稳妥的做法：灰度用户请求不查缓存、也不存缓存，确保始终回源获取最新响应。
- 在 location 块中启用 bypass 和 no-cache 指令，例如：
proxy_cache_bypass $http_x_gray $arg_gray $cookie_is_gray;
proxy_no_cache $http_x_gray $arg_gray $cookie_is_gray;
- 只要任一变量非空且不为 "0"（如请求头
X-Gray: 1、参数?gray=1或 Cookie 中is_gray=1），Nginx 就跳过缓存查找，并禁止将该响应写入缓存 - 此时
$upstream_cache_status值为 BYPASS，响应头中不应出现X-Cache: HIT类标识
用动态 cache_key 实现缓存逻辑隔离
若需保留灰度内容的缓存（比如新版本接口响应稳定、想提升性能），可让灰度与非灰度请求使用不同缓存 key，物理上互不干扰。
- 修改
proxy_cache_key，嵌入灰度标识：
proxy_cache_key "$scheme$proxy_host$request_uri$is_gray";
- 当
$is_gray为空时，key 是普通形式；当为"1"时，key 多出后缀，形成独立缓存槽位 - 需配合
map提前定义变量（必须放在 http 块顶层）：
map $http_x_gray $is_gray {
default "";
"1" "1";
}
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- 这样灰度请求命中的是专属缓存，旧版用户仍走原有缓存，互不影响
配合 upstream 路由实现端到端灰度闭环
缓存只是链路一环，完整灰度需与后端路由联动。例如：灰度请求既走新后端，又进专属缓存区。
- 先用
map提取灰度标识并映射后端组名：
map $cookie_uid $backend {
default "old";
~^(u1001|u1002)$ "gray";
}
- 再在 location 中同时控制路由和缓存：
proxy_pass http://backend_$backend;
proxy_cache_key "$scheme$proxy_host$request_uri$backend";
- 这样 uid 匹配的请求不仅转发到
backend_gray，还使用带"gray"后缀的 cache_key，天然隔离
安全与运维注意事项
绕过或隔离缓存不是功能开关，而是线上敏感操作，需限制影响面。
- 避免用公开参数（如
?nocache=1）开放 bypass，优先选用需鉴权的 header 或登录态 cookie - 内网调试可加 IP 白名单，例如：
set $bypass 0;
if ($remote_addr ~ ^(192\.168\.|10\.) ) { set $bypass 1; }
proxy_cache_bypass $bypass;
- 上线前务必注释或删除开发专用配置，防止被恶意利用导致缓存雪崩或后端压垮
