洞悉 NGINX ngx_http_access_module基于 IP 的访问控制实战指南

一、模块概述

ngx_http_access_module 是 NGINX 核心模块之一，用于基于客户端 IP 地址或 UNIX 域套接字限制访问。它通过简单的 allow/deny 规则，对请求进行最先匹配原则的过滤。与基于密码（auth_basic）、子请求（auth_request）或 JWT（ngx_http_auth_jwt_module）相结合时，可通过 satisfy 指令灵活配置“与/或”关系。

二、指令语法

allow  address | CIDR | unix: | all;
deny   address | CIDR | unix: | all;

address：单个 IPv4 地址，如 192.168.1.10。
CIDR：IPv4/IPv6 网段，如 10.1.0.0/16、2001:db8::/32。
unix:：匹配 UNIX 域套接字（1.5.1+）。
all：匹配所有客户端。

上下文：http, server, location, limit_except。

规则按出现顺序依次检查，直到命中为止；若无规则，则默认放行。

三、基础配置示例

location /admin/ {# 拒绝单个 IPdeny  192.168.1.1;# 允许同网段访问allow 192.168.1.0/24;allow 10.1.1.0/16;# 允许 IPv6 网段allow 2001:0db8::/32;# 默认拒绝所有其它deny  all;
}

上述配置效果：

192.168.1.1 被拒绝（优先于 192.168.1.0/24）；
192.168.1.2–192.168.1.254 及 10.1.x.x、指定 IPv6 网段被允许；
其余地址返回 403 Forbidden。

四、与 `satisfy` 结合

当既要基于 IP，又要基于认证时，可使用：

location /secure/ {satisfy any;allow  192.168.0.0/24;deny   all;auth_basic           "Restricted";auth_basic_user_file /etc/nginx/htpasswd;
}

satisfy any：IP 白名单或 HTTP 基本认证任一通过即可；
使用 satisfy all（默认）则需同时满足两者。

五、进阶用法

1. 全局与局部规则

在 http 或 server 块定义默认规则，location 内可覆盖或补充。
limit_except 中可只对非 GET/HEAD 等方法应用 IP 控制。

limit_except GET HEAD {allow  10.0.0.0/8;deny   all;
}

2. 与 `ngx_stream_geo_module` 结合

当有大量网段或需动态更新时，推荐用 geo 模块预先匹配变量，再在 access 中引用：

geo $allowed {default        0;192.168.0.0/24 1;include        conf/allowed_geo.conf;
}server {location / {if ($allowed = 0) {return 403;}# 其它配置…}
}

六、性能与维护

顺序匹配：将最常命中的规则放前，减少平均匹配次数。
规则规模：少量时用 allow/deny 足矣；大量网段建议配合 geo 或外部文件 include。
字符处理：CIDR 与单 IP 都会被转换为无符号整数，匹配效率高；
日志监控：可配合 error_log 监控 403 访问，及时调整规则。

七、安全与审计

拒绝 all：应始终在最后一行写 deny all，防止开放未覆盖的 IP。
正则与变量：allow/deny 不支持正则，仅支持 CIDR；灵活场景下可配合 $remote_addr 在 if 中使用正则或自定义变量。
域内安全：使用 unix: 仅允许运行于本机的服务调用，提升安全性。