Nginx通过map指令结合upstream可实现基于Header、Cookie、IP等请求特征的轻量级灰度路由，核心是用map将请求特征映射为upstream变量，proxy_pass动态转发，需设default防502，upstream名须合法且预定义。
利用 Nginx 的 map 指令结合 upstream，可以实现基于请求特征（如 Header、Cookie、IP、域名等）的轻量级、无侵入、毫秒级灰度路由，无需改业务代码，也不依赖外部服务发现组件。
核心思路：用 map 动态映射 upstream 名称
map 指令在 Nginx 配置加载时构建键值映射表，运行时仅做 O(1) 查找，几乎零开销。关键在于把“灰度判定逻辑”编译为静态映射关系，再将结果作为变量传给 proxy_pass 后的 upstream 名称。
- 不支持在
map中写复杂脚本或调用外部接口，但可组合内置变量（$http_x_gray、$cookie_uid、$remote_addr等）和正则匹配 - 每个
map块必须定义默认值（default），否则未匹配时变量为空，会导致 502 - upstream 名称必须是合法标识符（不能含下划线以外的特殊字符，建议全小写+短横线）
典型配置示例：按自定义 Header 切流量
以下配置将 10% 的灰度用户（携带 X-Gray: on）路由到新版本集群，其余走老集群：
http {
# 定义灰度策略：根据请求头决定使用哪个 upstream
map $http_x_gray $backend_upstream {
default backend-v1; # 默认走老版本
~^[oO][nN] backend-v2; # 匹配 X-Gray: on/on/ON 等
}
<pre class="brush:php;toolbar:false;">upstream backend-v1 {
server 192.168.1.10:8080;
server 192.168.1.11:8080;
}
upstream backend-v2 {
server 192.168.1.20:8080 weight=3; # 可加权控制新版本承接比例
server 192.168.1.21:8080;
}
server {
listen 80;
location / {
proxy_pass http://$backend_upstream;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
}
进阶技巧：多维度组合与平滑降级
单个 map 支持嵌套判断逻辑，通过变量链式引用实现“优先级灰度”（例如：先看 Header → 再看 Cookie → 最后看 IP 段）：
- 用
map提取用户 ID 或设备指纹（如$cookie_uid的哈希前两位），做一致性哈希分流 - 结合
$request_uri或$args对特定接口（如/api/v2/）强制走新版本 - 设置 fallback 机制：当
backend-v2全部不可用时，自动切回backend-v1（需配合proxy_next_upstream和健康检查） - 上线前用
log_format记录$backend_upstream，验证路由是否符合预期
注意事项与避坑点
该方案极致轻量，但也受限于 Nginx 配置热加载能力：
- 修改
map或upstream后需执行nginx -s reload，不中断连接，但会新建 worker 进程，旧进程处理完请求后退出 - 避免在
map中使用过于宽泛的正则（如.*），可能影响性能；优先用前缀匹配（^/admin）或精确字符串 - 若需动态更新灰度名单（如运营后台开关），可用 Lua + shared_dict 或 OpenResty 的
lua_shared_dict替代纯静态 map - 确保 upstream 中各 server 的
max_fails和fail_timeout设置合理，防止短暂抖动引发误切
