如何基于查询参数配置Nginx条件allow IP白名单？

要实现「仅当请求携带key=123查询参数时才启用IP白名单」的需求，由于Nginx不支持在include中使用变量，可通过**geo模块定义白名单IP** + map模块组合条件 + 安全的if指令完成，具体配置如下：

1. 定义IP白名单（geo块） #

在http块下添加geo配置，标记符合条件的白名单IP：

geo $is_whitelisted_ip {
    default 0;  # 默认不属于白名单
    192.168.1.0/24 1;  # 替换成你的目标IP范围，匹配的IP会被标记为1
    10.0.0.5 1;  # 单个IP也可直接配置
}

2. 组合查询参数与IP白名单条件（map块） #

同样在http块下添加map，根据查询参数key的值，决定是否启用IP白名单校验：

map $arg_key $allow_access {
    # 当key=123时，是否允许访问由IP白名单的标记值决定
    123 $is_whitelisted_ip;
    # 其他情况（key≠123或无key参数），直接允许所有访问
    default 1;
}

3. 在目标location中添加访问控制 #

在/some/path的location块内，通过if指令判断$allow_access的值，若为0则返回403拒绝访问：

location /some/path {
    set $backend        http://localhost:8080;
    proxy_pass          $backend;

    proxy_set_header    Host $http_host;
    proxy_buffering     off;
    proxy_read_timeout  15m;
    expires             -1;

    # 仅当$allow_access为0时拒绝访问，此用法属于Nginx官方认可的安全场景
    if ($allow_access = 0) {
        return 403;
    }
}

补充说明 #

• geo是Nginx核心模块，无需额外安装，专门用于根据客户端IP设置变量，执行效率高。
• 此处if仅用于return指令，不属于「if is evil」文档中提到的危险场景（如在if内修改proxy_pass、设置root等），可安全使用。
• 若需支持多个key值对应不同白名单，可直接扩展map的规则配置。

内容的提问来源于stack exchange，提问作者Roman Rastiehaiev