如何使用Nginx geo模块根据客户端IP返回不同的配置值？

当业务系统进行多机房部署或灰度发布时，常常需要根据用户的来源IP地址引导到不同的后端服务，或者向特定区域的用户展示不同的内容。面对这一需求，直接在应用代码中硬编码IP段不仅维护成本高昂，而且缺乏灵活性。此时，借助Nginx自带的geo模块可以优雅地解决这一痛点。该模块允许管理员在配置文件中定义IP地址范围，并将其映射到自定义的变量值上。当请求到达时，Nginx会自动根据客户端真实IP匹配预设规则，并将结果存入变量供后续逻辑使用。这种方式不仅将网络层判断与应用层逻辑解耦，还大幅提升了请求处理的效率。

Nginx geo模块的工作原理与基础语法

Nginx的geo模块是一个内置的标准模块，默认随Nginx主程序一起编译，不需要在编译时额外添加参数。它的核心作用是根据客户端的IP地址创建带有指定值的变量。在默认情况下，geo模块会读取$remote_addr变量的值，也就是直接与Nginx建立TCP连接的那个客户端IP地址。通过在http上下文中定义geo块，我们可以建立IP地址与特定字符串值之间的映射关系。

geo模块的基础语法结构非常直观。它通常以geo [$ip_address] $variable { ... }的形式出现在配置文件中。如果不指定$ip_address参数，模块会自动使用$remote_addr。在大括号内部，我们可以使用CIDR格式定义IP范围，并为它们分配对应的值。同时，还可以使用default关键字来指定当客户端IP不匹配任何已定义范围时的默认值。这种配置方式使得IP管理变得集中且清晰。

该模块在性能方面具有显著优势。当Nginx启动并解析配置文件时，geo模块会将所有定义的IP网段构建成一棵高效的基数树。在请求处理阶段，当需要判断客户端IP属于哪个区间时，Nginx会在这棵基数树中进行快速查找。这种数据结构使得IP匹配的时间复杂度极低，几乎不会对请求处理速度产生负面影响，因此非常适合用于处理高并发场景下的IP识别与流量调度需求。

根据客户端IP返回不同变量值的实战配置

让我们通过一个具体的业务场景来演示geo模块的用法。假设我们有一个内部测试环境，希望只有特定办公网络的IP（例如192.168.1.0/24）能够访问测试接口，而其他所有外部IP的请求都需要被重定向到维护提示页面。为了实现这个目标，我们可以使用geo模块定义一个名为$is_internal的变量，用于标识请求是否来自内部网络。

下面是具体的Nginx配置代码示例。我们在http块中定义geo块，将默认值设为0，并将内部网段的值设为1。随后在对应的location块中，利用if指令判断$is_internal变量的值。如果为0，则返回特定的HTTP状态码或重定向。这种基于变量的判断方式使得流量控制逻辑非常清晰。

http {
    # 定义geo变量，默认为0，内部网段为1
    geo $is_internal {
        default 0;
        192.168.1.0/24 1;
    }

    server {
        listen 80;
        server_name test.ipipp.com;

        location /api/ {
            # 如果不是内部IP，则返回403禁止访问
            if ($is_internal = 0) {
                return 403;
            }
            proxy_pass http://backend_test;
        }
    }
}

在复杂的网络拓扑中，Nginx前面可能还部署了CDN或者四层负载均衡器。在这种情况下，$remote_addr获取到的将是上一跳代理服务器的IP，而不是真实客户端的IP。为了让geo模块正确工作，必须结合ngx_http_realip_module模块。通过配置set_real_ip_from指令信任代理服务器，并使用real_ip_header指令从X-Forwarded-For请求头中提取真实客户端IP，这样geo模块才能基于真实IP进行准确匹配。

结合map指令实现复杂业务逻辑的动态分发

虽然geo模块能够根据IP返回不同的值，但在实际应用中，我们往往需要根据这个值进一步映射到不同的后端服务器地址、根目录路径或上游服务组。如果仅仅依赖if指令进行多重判断，不仅配置语法繁琐，而且在Nginx中过多使用if指令容易引发意外行为。此时，将geo模块与map指令结合使用是业界公认的最佳实践。

我们可以先用geo模块将不同省份或国家的IP段映射为简单的区域代号，然后再使用map指令将这些区域代号映射为具体的后端服务器组名。下面是一个结合使用的配置示例。这种链式映射的方式极大地增强了配置的灵活性和可读性。

http {
    # 第一步：根据IP获取区域代号
    geo $region_code {
        default other;
        10.0.0.0/8 beijing;
        192.168.0.0/16 shanghai;
    }

    # 第二步：根据区域代号映射后端服务组
    map $region_code $backend_pool {
        default default_backend;
        beijing bj_backend;
        shanghai sh_backend;
        other default_backend;
    }

    upstream bj_backend {
        server 192.168.10.1:8080;
    }

    upstream sh_backend {
        server 192.168.20.1:8080;
    }

    upstream default_backend {
        server 192.168.30.1:8080;
    }

    server {
        listen 80;
        location / {
            # 直接使用映射后的变量进行代理
            proxy_pass http://$backend_pool;
        }
    }
}

通过geo和map的组合，我们将网络层的IP识别与业务层的路由分发完全解耦。Nginx配置文件变得模块化且非常清晰易读。后续如果需要增加新的IP段或修改路由规则，只需在相应的配置块中增删一行即可，无需修改复杂的逻辑判断代码。这种架构设计不仅极大地降低了运维成本和出错概率，还使得Nginx能够胜任更加复杂的流量调度与灰度发布任务，充分发挥了其在网络边缘的计算与路由能力。

Nginx geo模块IP地理位置负载均衡修改时间：2026-08-21 15:15:54