实战讲解 Nginx map 指令实现基于客户端 IP 段的动态后端路由-Nginx-PHP中文网

Nginx通过map指令按客户端IP段动态路由，核心是将$remote_addr或$realip_remote_addr映射为后端地址变量并在proxy_pass中引用，需在http块定义、支持CIDR/正则/精确匹配、必须设default防502，且proxy_pass末尾不可加路径。

实战讲解 nginx map 指令实现基于客户端 ip 段的动态后端路由

用 Nginx 的 map 指令按客户端 IP 段动态路由，核心是把 $remote_addr 或 $realip_remote_addr 映射为后端地址变量，再在 proxy_pass 中引用。它不依赖第三方模块，配置简洁，适合做地域分流、内网灰度、白名单透传等场景。

IP 段匹配要写在 http 块里，不能放 server 里

map 必须定义在 http{} 全局块中，Nginx 启动时就完成变量注册，运行时只查表，无性能损耗。匹配依据用 $remote_addr（直连时）或 $realip_remote_addr（经可信代理后）。若用了 real_ip 模块，记得先配置 set_real_ip_from 和 real_ip_header。

支持三种匹配方式：

精确 IP："192.168.1.100" "10.0.1.10:8080";
IP 段（CIDR）："192.168.1.0/24" "10.0.1.20:8080";（需 Nginx ≥ 1.19.0）
正则表达式：~^10\.0\.2\.[0-9]{1,3}$ "10.0.2.50:8080";（注意转义点号）

务必加 default 分支，否则未匹配的请求会因变量为空导致 502 错误。

典型配置：按办公网、测试网、默认集群分发

例如公司内网 192.168.10.0/24 走预发布环境，测试团队网段 172.16.5.0/24 走 canary 集群，其余走生产集群：

http {
    map $remote_addr $backend_ip {
        default "10.0.4.100:8080";  # 生产
        "192.168.10.0/24" "10.0.2.10:8080";  # 办公网 → 预发布
        "172.16.5.0/24" "10.0.3.20:8080";   # 测试网 → canary
        ~^127\.0\.0\.1$ "127.0.0.1:8000";    # 本地调试
    }
<pre class="brush:php;toolbar:false;">server {
    listen 80;
    location /api/ {
        proxy_pass http://$backend_ip;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

}

Nginx Reverse Proxy

配置 Nginx 反向代理，实现域名绑定。用户说“绑定域名”“配置 Nginx”“反向代理”时触发，将域名绑定到指定 IP:端口。

下载

注意：proxy_pass 后不能带路径（如 http://$backend_ip/），否则原始 URI 会被丢弃；正确写法是末尾不加 /，让后端自己处理完整路径。

进阶技巧：组合 IP + 请求头做双重决策

单一 IP 匹配有时不够灵活，可叠加一层逻辑。比如优先看 X-Forwarded-For 中的真实 IP，缺失时回退到 $remote_addr：

map $http_x_forwarded_for $client_ip {
    "" $remote_addr;
    default $http_x_forwarded_for;
}
<p>map $client_ip $backend_group {
default "prod";
"192.168.1.0/24" "staging";
"~^10.10." "canary";
}</p>

再配合 upstream 分组使用，就能对不同 IP 段启用差异化策略——比如 staging 组开启详细日志，canary 组加权重控制流量比例。