Nginx访问控制模块怎么用？ngx_http_access_module配置详解

Nginx的强大很大程度上来自其模块化设计，ngx_http_access_module就是其中一个默认内置的基础安全模块。它的作用很直接：根据客户端IP地址决定请求是被放行还是被拒绝。相比在应用层做鉴权，这种在网络入口处的拦截消耗极小、生效极快，是保护管理后台、内部接口时最常用的手段之一。本文将从指令用法、匹配规则、典型场景和常见坑几个方面，把这个模块的用法讲透。

一、模块原理与基本指令

ngx_http_access_module在Nginx构建时默认编译进来，不需要额外的安装步骤。它只提供两个核心指令：allow和deny，二者可以出现在http、server、location以及stream模块对应的层级中，还支持放在limit_except块内针对特定HTTP方法做限制。

每条指令后面跟一个地址规则，支持四种写法：完整IPv4或IPv6地址、CIDR格式的网段（如192.168.1.0/24）、关键字all（表示所有地址），以及在使用了ngx_http_geo_module定义变量后可配合的间接方式。基本用法如下：

location /admin/ {
    allow 192.168.1.0/24;   # 允许内网网段访问
    allow 10.0.0.5;         # 允许单个IP访问
    deny  all;              # 拒绝其他所有来源
}

需要理解的是，这个模块的处理顺序是自上而下逐条匹配，命中第一条匹配的规则后立即停止，不会继续往下检查。也就是说规则的先后顺序非常关键，把deny all写在前面会让后面的allow永远不生效。当请求被拒绝时，Nginx默认返回403状态码，客户端看到的就是一个Forbidden页面。

二、匹配规则与作用范围的细节

很多人以为allow和deny是各管各的，实际上它们共享同一条匹配链。Nginx会按照配置文件中出现的先后顺序依次比对客户端地址，第一条命中的规则决定最终结果。举个例子，如果配置写成先deny 192.168.1.1再allow 192.168.1.0/24，那么192.168.1.1这个地址会被拒绝，网段内其他地址则放行。这种精细控制正是顺序匹配带来的灵活性。

作用范围的继承规则也值得注意。子级配置会整体覆盖父级配置，而不是合并。比如在server层写了allow 10.0.0.1，而在某个location里写了deny all，那么该location会完全忽略server层的allow规则，所有请求一律拒绝。这一点和很多人直觉中的叠加式继承不同，配置时容易踩坑。

server {
    allow 10.0.0.1;          # server层规则
    location /internal/ {
        deny all;            # 此处覆盖server层，10.0.0.1也会被拒
    }
    location /public/ {
        # 没有access规则，继承server层，10.0.0.1可访问
    }
}

另外，如果同一层级中所有的allow和deny规则都没有命中（既没有deny all兜底），请求默认会被放行。因此安全敏感的场景一定要记得在规则末尾加上deny all，形成默认拒绝的白名单模式，而不是依赖默认放行。

三、反向代理场景下的真实IP问题

这个模块有一个非常经典的坑：当Nginx前面还有一层负载均衡或CDN时，access模块看到的是直接对端地址，也就是代理服务器的IP，而不是真实访客的IP。此时基于公网客户端IP做黑白名单会完全失效，所有请求看起来都来自同一个或少数几个代理地址。

解决办法是配合set_real_ip_from和real_ip_header指令，让Nginx信任前置代理并在指定头部中提取真实地址。这样access模块判断时使用的就是还原后的客户端IP：

# 前置了一层代理，真实IP放在X-Forwarded-For头中
set_real_ip_from 172.16.0.0/16;    # 信任的代理网段
real_ip_header X-Forwarded-For;

location /api/ {
    allow 203.0.113.0/24;          # 此时匹配的是真实客户端IP
    deny all;
}

这里务必注意只把可信的代理网段加入set_real_ip_from，因为X-Forwarded-For头是可以被客户端伪造的。如果无差别信任该头部，攻击者可以随意伪造IP绕过黑名单，访问控制形同虚设。

四、典型应用场景与配置示例

场景一：保护管理后台。只允许公司出口IP或运维办公网段访问后台路径，其余一律拒绝，配合自定义错误页提升体验：

location /admin/ {
    allow 203.0.113.10;
    allow 198.51.100.0/24;
    deny all;
    error_page 403 /403.html;
    location = /403.html {
        root /usr/share/nginx/html;
        internal;
    }
}

场景二：封禁恶意IP。针对频繁扫描或攻击的来源做黑名单，其余正常放行。当恶意IP较多时，可以把列表拆分到独立文件中用include引入，方便维护：

# blocklist.conf 内容为多行 deny x.x.x.x;
location / {
    include /etc/nginx/conf.d/blocklist.conf;
    allow all;
}

场景三：按HTTP方法限制。把规则放在limit_except块内，例如只允许内网发起DELETE请求：

location /data/ {
    limit_except DELETE {
        allow 192.168.0.0/16;
        deny all;
    }
}

五、模块局限与替代方案

ngx_http_access_module虽然好用，但能力边界也很明显。它只认IP，不能基于域名、请求头、时间等条件做判断；静态配置意味着每次增删规则都要reload Nginx，面对大规模动态封禁会力不从心。

当需求更复杂时，可以考虑这些替代或互补方案：一是ngx_http_geo_module配合map，可以根据IP生成变量实现更灵活的分类控制；二是ngx_http_geoip_module或njs脚本，基于地理位置或自定义逻辑判断；三是结合fail2ban实现自动化的动态封禁；四是使用limit_req和limit_conn模块做请求频率维度的防护。对于简单的黑白名单需求，access模块依然是首选，毕竟它足够轻量、语义清晰、几乎零学习成本。

总结一下，用好这个模块的关键在于三点：牢记规则自上而下顺序匹配、理解子级覆盖父级的继承机制、在代理环境下正确还原真实IP。掌握这些之后，一条清晰的allow加deny all配置就能为你的服务筑起第一道可靠的访问防线。

Nginxngx_http_access_module访问控制修改时间：2026-09-15 21:10:41