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 | |
要点:
- 匹配方式:精确字符串、
hostnames(支持通配/后缀)、~正则(区分大小写~、不区分~*); default必填思路:源字段为空或无匹配时用 default;- 映射表可放独立文件,用
include引入(配合第 9 篇的配置组织); volatile:标记变量为易失,禁用缓存(用于依赖易变输入的场景)。
1 | |
二、geo:按来源 IP 映射
geo 专门处理 IP 网段 → 值 的映射,支持 CIDR:
1 | |
- 可用于"内网免鉴权、外网要口令"、按地区选择上游;
geo支持proxy/proxies声明可信代理(与real_ip配合,见第 4 篇),从X-Forwarded-For取真实 IP 再匹配;- 网段匹配是最长前缀,不是顺序匹配。
1 | |
三、split_clients:按比例灰度
按一致性哈希把流量切成固定比例,用于灰度发布、A/B:
1 | |
- 源字符串(通常是用户标识)经 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 能用在 stream | map 是 http 上下文指令 |
| 匹配顺序写成"先写先生效" | 字符串是精确/正则匹配,与书写顺序无关 |
geo 网段顺序敏感 | 最长前缀匹配,不是顺序 |
split_clients 源字符串为空 | 用 ${remote_addr} 等兜底,避免全落同一桶 |
| 百分比不兜底 | 用 * 接住剩余流量 |
正则里含 }/; | 整个表达式加引号 |
| 映射表过大 | 放独立文件、include,必要时分流 |
参考链接
- Nginx 官方文档:ngx_http_map_module —— 映射与匹配规则;
- Nginx 官方文档:ngx_http_geo_module —— IP 网段映射;
- Nginx 官方文档:ngx_http_split_clients_module —— 按比例灰度;
- 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
