利用Map模块实现基于Cookie的灰度分流深度解析|Duuu笔记
Nginx 的 map 模块是实现基于 Cookie 灰度发布的轻量原生方案，支持正则匹配与变量映射，需定义在 http 块中，按顺序首匹配生效，可结合 IP 与 Cookie 实现双重灰度控制。
想用 Nginx 实现基于 Cookie 的灰度发布？Map 模块是轻量、高效又原生的方案——无需额外插件，不依赖 Lua，纯配置即可完成用户维度的流量打标与路由分流。
为什么选 map 而不是 if 或 rewrite？
if 在 location 中有诸多限制（比如不能嵌套、部分变量不可用），rewrite 容易引发循环重写或语义不清；而 map 是 Nginx 的变量映射机制，声明式、无副作用、支持正则匹配，且在请求处理早期就完成变量赋值，适合做灰度标识提取。
关键点：
map 必须定义在 http 块中，不能放在 server 或 location 里
匹配逻辑是“从上到下、首个匹配即停止”，顺序很重要
支持 ~（区分大小写正则）、~*（忽略大小写正则）、=（精确匹配）
默认值用 default 指定，未匹配时生效
提取灰度 Cookie 并映射为 upstream 标识
假设业务约定：前端在用户登录后写入 Cookie
gray_user=on
或
gray_user=ab-test-v2
，需将该值映射为后端分组名（如 backend_v1 / backend_v2）。
示例配置：
http {
# 定义灰度标识映射关系
map $cookie_gray_user $backend_group {
default "backend_v1";
"on" "backend_v2";
"ab-test-v2" "backend_v2";
~*^v2 "backend_v2";
~*^canary "backend_v2";
}
upstream backend_v1 {
server 10.0.1.10:8080;
}
upstream backend_v2 {
server 10.0.1.11:8080;
}
server {
listen 80;
location / {
proxy_pass http://$backend_group;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
}
自由画布
百度文库和百度网盘联合开发的AI创作工具类智能体
下载
说明：
$cookie_gray_user
是 Nginx 内置变量，自动提取名为 gray_user 的 Cookie 值
正则
~*^v2
可匹配 v2、V2、v2-beta 等，增强灰度策略灵活性
变量
$backend_group
可直接用于 proxy_pass，Nginx 会动态解析对应 upstream
进阶：结合 IP + Cookie 做双重灰度控制
有时需要“内部员工强制走新版本 + 普通用户按 Cookie 白名单分流”。可在 map 中叠加条件，利用 Nginx 的变量拼接能力：
map "$cookie_gray_user:$remote_addr" $backend_group {
default "backend_v1";
"~*on:.+" "backend_v2"; # Cookie=on → 全部走 v2
"~*ab-test-v2:.+" "backend_v2";
"~*:.+192\.168\.10\.[0-9]+" "backend_v2"; # 匹配内网 IP 段
"~*canary:.+" "backend_v2";
}
注意：
map 的 key 支持字符串拼接
，这里用冒号分隔两个变量，再用正则统一匹配。这样既保留 Cookie 控制，又赋予 IP 层兜底能力。
验证与调试技巧
上线前务必验证映射是否生效：
加临时响应头：
add_header X-Backend-Group $backend_group;
，用 curl 查看返回头
开启 Nginx debug 日志（编译时需含 --with-debug），或使用
error_log /var/log/nginx/debug.log debug;
用
nginx -t
检查语法，
nginx -s reload
平滑重载
测试时清除浏览器 Cookie 或用 curl 指定 Cookie：
curl -H "Cookie: gray_user=ab-test-v2" http://your-domain/
