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