洞悉 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/ {
    # 拒绝单个 IP
    deny  192.168.1.1;
    # 允许同网段访问
    allow 192.168.1.0/24;
    allow 10.1.1.0/16;
    # 允许 IPv6 网段
    allow 2001:0db8::/32;
    # 默认拒绝所有其它
    deny  all;
}

上述配置效果：

1. 192.168.1.1 被拒绝（优先于 192.168.1.0/24）；
2. 192.168.1.2--192.168.1.254 及 10.1.x.x、指定 IPv6 网段被允许；
3. 其余地址返回 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: 仅允许运行于本机的服务调用，提升安全性。

八、常见陷阱

1. 位置错误 ：allow/deny 必须在可见的上下文（server、location），否则无效。
2. 未写 deny all ：若只有 allow，但无默认 deny all，其他客户端仍然可访问。
3. 与 auth_basic 冲突 ：若既有密码又有 IP 控制，未设置 satisfy 时默认"与"关系，可能导致意外拒绝。

九、总结

ngx_http_access_module 提供了简单高效的基于地址访问控制，配合 satisfy、geo、auth_basic 等模块，可实现精细化安全策略。制作规则时要注意顺序与默认策略，针对不同场景合理拆分到全局 vs 局部，既能保障性能，也能提升可维护性。