Nginx 工程实践 -- 20. map、geo 与 split_clients 运行时分流

有些策略不需要改配置文件、不需要重启:根据请求头、Cookie、来源 IP 动态决定"走哪个上游、给哪个版本、是否放行"。Nginx 的三个映射模块——map、geo、split_clients——就是干这个的。它们都生成变量,再交给 proxy_pass、if、auth_request 等指令消费。

flowchart LR
    A["请求"] --> B["map
按 header / cookie / 参数"] B --> C{"命中规则?"} C -->|"规则 A"| D["变量 = A 组"] C -->|"default"| E["变量 = 默认值"] F["geo"] -->|"按 IP 网段"| C G["split_clients"] -->|"按比例 hash"| C

一、map:通用映射

map 在 http {} 里定义,根据源字段的值计算目标变量:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
map $http_x_version $backend_pool {
default backend_stable;
"v2" backend_canary;
"beta" backend_beta;
}

upstream backend_stable { server 10.0.0.11; }
upstream backend_canary { server 10.0.0.21; }
upstream backend_beta { server 10.0.0.31; }

server {
location /api/ {
proxy_pass http://$backend_pool;
}
}

要点:

  • 匹配方式:精确字符串、hostnames(支持通配/后缀)、~ 正则(区分大小写 ~、不区分 ~*);
  • default 必填思路:源字段为空或无匹配时用 default;
  • 映射表可放独立文件,用 include 引入(配合第 9 篇的配置组织);
  • volatile:标记变量为易失,禁用缓存(用于依赖易变输入的场景)。
1
2
3
4
map $request_uri $is_legacy {
~^/v1/ 1;
default 0;
}

二、geo:按来源 IP 映射

geo 专门处理 IP 网段 → 值 的映射,支持 CIDR:

1
2
3
4
5
6
geo $geo_zone {
default external;
10.0.0.0/8 internal;
192.168.0.0/16 internal;
203.0.113.0/24 partner;
}
  • 可用于"内网免鉴权、外网要口令"、按地区选择上游;
  • geo 支持 proxy/proxies 声明可信代理(与 real_ip 配合,见第 4 篇),从 X-Forwarded-For 取真实 IP 再匹配;
  • 网段匹配是最长前缀,不是顺序匹配。
1
2
3
4
5
geo $country {
default ZZ;
10.0.0.0/8 CN;
198.51.100.0/24 US;
}

三、split_clients:按比例灰度

按一致性哈希把流量切成固定比例,用于灰度发布、A/B:

1
2
3
4
5
6
7
8
9
10
11
12
split_clients "${remote_addr}${http_user_agent}" $variant {
10% "canary";
* "stable";
}

server {
location / {
proxy_pass http://$variant;
}
}
upstream canary { server 10.0.0.21; }
upstream stable { server 10.0.0.11; }
  • 源字符串(通常是用户标识)经 MD5 后映射到百分比;
  • 同一用户每次结果稳定,不会来回跳;
  • 百分比之和应覆盖 100%,用 * 兜底剩余;
  • 调整比例时映射会重新分布,属于预期行为。

四、组合用例

按 Cookie 灰度 + map:map $cookie_canary $pool { "1" canary; default stable; }。

按地区 + geo + map:geo 得到地区码,map 把地区码映射到上游。

内网免口令:geo $internal { 10.0.0.0/8 1; default 0; } + map $internal $auth_off { 1 off; },再配合 auth_basic。

动态 deny:map $http_x_bad $deny { 1 1; } + if ($deny) { return 403; }。

五、常见坑

坑说明
以为 map 能用在 streammap 是 http 上下文指令
匹配顺序写成"先写先生效"字符串是精确/正则匹配,与书写顺序无关
geo 网段顺序敏感最长前缀匹配,不是顺序
split_clients 源字符串为空用 ${remote_addr} 等兜底,避免全落同一桶
百分比不兜底用 * 接住剩余流量
正则里含 }/;整个表达式加引号
映射表过大放独立文件、include,必要时分流

参考链接

  1. Nginx 官方文档:ngx_http_map_module —— 映射与匹配规则;
  2. Nginx 官方文档:ngx_http_geo_module —— IP 网段映射;
  3. Nginx 官方文档:ngx_http_split_clients_module —— 按比例灰度;
  4. Nginx 官方文档:ngx_http_upstream_module —— 上游组定义。

小结

  • map:通用键值映射,支持精确/正则/hostnames;
  • geo:IP 网段映射,最长前缀匹配,可配可信代理;
  • split_clients:一致性哈希按比例分流,同一用户稳定;
  • 三者都产出变量,交给 proxy_pass/if/auth_basic 消费;
  • 映射表放独立文件,配合第 9 篇的配置组织。

系列导航


Nginx 工程实践 -- 20. map、geo 与 split_clients 运行时分流
https://bubao.github.io/posts/e0f1a2b3.html
作者
一念
发布于
2026年11月21日
许可协议