基于 Cookie 的金丝雀发布是通过读取浏览器中 canary=1 等标识 Cookie，利用 Nginx map 指令将请求动态路由至 canary 或 prod 后端集群，实现可控、可追溯的灰度验证。
什么是基于 Cookie 的金丝雀发布
金丝雀发布的核心是让一小部分真实用户提前访问新版本服务，验证稳定性后再全量上线。用 Cookie 做标识，意味着不依赖客户端 IP、User-Agent 或请求头参数，而是通过用户浏览器中已存在的、可被服务端写入和读取的 cookie 字段（如 canary=1）来打标，实现长期、稳定、可追溯的流量染色。
Nginx map 指令如何完成流量分类
map 是 Nginx 的变量映射模块，它能根据源变量（比如 $cookie_canary）的值，动态生成一个目标变量（比如 $upstream_group），且该过程发生在请求处理早期，开销极低、无状态、高性能。
典型配置示例如下：
map $cookie_canary $upstream_group {
default "prod";
"~^1|true|on|yes" "canary";
}
说明：
- 若请求携带 Cookie: canary=1、canary=true 等匹配正则的值，$upstream_group 被设为 "canary"；
- 其他情况（包括未携带该 cookie）统一走 "prod" 分组；
- 正则开头的 ~^ 表示大小写敏感的前缀匹配，避免误判 canary=10 这类值。
将染色结果路由到不同后端集群
定义好 $upstream_group 后，只需在 location 或 server 块中用 proxy_pass 动态指向对应 upstream：
upstream prod {
server 10.0.1.10:8080;
server 10.0.1.11:8080;
}
<p>upstream canary {
server 10.0.2.10:8080 weight=10; # 可加权控制灰度比例
}</p><p>server {
listen 80;
location / {
proxy_pass <a href="https://www.php.cn/link/db190973a7de5c5c876cba872133442f">https://www.php.cn/link/db190973a7de5c5c876cba872133442f</a>;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
关键点：
- 不需要重写 URL 或判断 location，完全靠变量驱动路由；
- upstream 可独立配置健康检查、负载策略、超时等，与染色逻辑解耦；
- 若需按百分比放量（非 cookie 强制），可结合 $request_id 或 $msec 做哈希分流，但 cookie 方式更可控、可主动触发。
配套动作：前端如何注入 and 后端如何回传 canary cookie
仅靠 Nginx 无法自动写入 cookie，需前后端协同：
- 前端在用户进入灰度通道（如点击“体验新版”按钮）时，执行
document.cookie = "canary=1; path=/; max-age=604800"，设置 7 天有效期； - 后端服务在响应中可选择性透传或刷新该 cookie，例如返回
Set-Cookie: canary=1; Path=/; Max-Age=604800，确保跨页面、跨请求持续生效； - Nginx 默认会把原始 Cookie 透传给后端，无需额外配置；若需过滤或重命名，可用
proxy_set_header Cookie ...手动构造。
注意：Nginx 本身不校验 cookie 签名或时效，安全性依赖业务层——建议后端对 canary cookie 做简单签名或绑定用户 ID，防止恶意篡改。
