allow和deny仅在http、server、location及limit_except块中生效,不可用于events或顶层;按自上而下顺序匹配,首个匹配即终止,deny优先级高于allow,须以deny all收尾并配合set_real_ip_from才能基于真实IP控制访问。

nginx 中 allow 和 deny 的作用范围必须明确
这两个指令只在 http、server、location 和 limit_except 块中生效,不能写在 upstream 或全局配置顶层。最常见错误是把它们丢进 events 块或随便一个没作用域的上下文里,Nginx 启动时会直接报错:unknown directive "allow"。
实际生效顺序是“自上而下匹配 + 最具体优先”,比如 location /admin/ 里的 deny 会覆盖 server 块中的 allow;但要注意:所有 allow/deny 必须成对出现,且以 deny all 收尾才安全,否则默认放行。
正确写法:用 allow/deny 实现白名单模式
想只允许某几个 IP 访问某个接口,典型做法是先全拒,再逐个放行:
location /api/internal/ {
deny all;
allow 192.168.1.100;
allow 2001:db8::1;
allow 10.0.0.0/8;
}
注意点:
-
deny all必须写在最前面,否则后续allow无效(Nginx 按顺序匹配,遇到第一个匹配就终止) - IPv4 和 IPv6 可混用,但每行只能写一个地址或 CIDR 段
- 不支持域名(如
allow example.com会报错),DNS 解析需在 upstream 或应用层处理 - 如果用了反向代理(如用户真实 IP 在
X-Forwarded-For),allow/deny默认仍检查remote_addr—— 这是 Nginx 接收到连接的直接 IP,不是客户端原始 IP
当用户走 CDN 或代理时,allow/deny 为什么总失效
因为 Nginx 默认只识别 TCP 连接来源,CDN 回源请求的 remote_addr 是 CDN 节点 IP,不是用户真实 IP。要基于真实 IP 控制访问,必须:
- 确认上游已设置
X-Real-IP或X-Forwarded-For头 - 在
http块中加:set_real_ip_from 203.208.60.0/24;(填你所用 CDN 的 IP 段) - 再加:
real_ip_header X-Real-IP;或real_ip_header X-Forwarded-For; - 之后
allow/deny才真正作用于用户原始 IP
漏掉 set_real_ip_from 就算写了 real_ip_header 也没用 —— Nginx 会忽略未授权来源的头信息。
allow/deny 与 geo + map 的性能差异
少量 IP(几十个以内)用 allow/deny 简单直接;但若要管理几百个 IP 或动态更新,硬编码在配置里会导致频繁 reload,影响稳定性。这时更适合用 geo 指令预生成变量,再配合 map 转为布尔值:
geo $blocked_ip {
default 0;
192.168.5.5 1;
2001:db8::2 1;
}
map $blocked_ip $allowed {
1 "";
0 "ok";
}
server {
if ($allowed = "") { return 403; }
}
这种写法 reload 开销小,也方便脚本自动更新 geo 块内容。但注意:if 在 location 外使用有局限,且不能嵌套,复杂逻辑建议移至应用层或用 OpenResty。
真实环境中,IP 黑白名单常需联动日志分析和自动封禁,靠纯 Nginx 静态规则很难闭环。别指望靠几行 deny 挡住扫描器或 CC 攻击 —— 它们只是第一道筛子,后面还得有速率限制、WAF 和行为分析兜底。











