因为ctx.RemoteAddr()返回的是反向代理(如Nginx、Cloudflare)的连接地址,而非真实客户端IP;必须解析X-Forwarded-For头并校验可信代理链,否则黑白名单将完全失效。

为什么 ctx.RemoteAddr() 拿不到真实客户端 IP
直接用 ctx.RemoteAddr() 获取 IP 做黑白名单,基本等于封自己。它返回的是反向代理(如 Nginx、Cloudflare)的连接地址,不是用户真实出口 IP。你看到的 10.0.0.5 或 127.0.0.1 很可能来自负载均衡器本身。
必须手动解析 X-Forwarded-For 头,并做可信链校验:
- 读取
ctx.GetHeader("X-Forwarded-For"),按逗号分割,取第一个非空、非私有网段的 IP - 私有网段要严格匹配:
127.0.0.0/8、10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、::1/128、fc00::/7 - 别用
strings.Contains(ip, "192.168.")这种字符串匹配——CIDR 判断必须用net.IPNet.Contains() - 若
X-Forwarded-For为空或全为私有 IP,再 fallback 到ctx.RemoteAddr()(仅限直连调试环境)
怎么在中间件里查 IP 黑白名单并立即拦截
黑名单命中后不能调 ctx.Next(),必须终止请求流;白名单则应跳过后续校验逻辑。推荐把名单存在内存 map[string]bool 或 Redis 中,避免每次读文件或查 DB。
示例逻辑片段:
ip := getRealIP(ctx) // 上面提到的解析函数
if ip == "" {
ctx.StatusCode(400)
ctx.WriteString("invalid ip")
ctx.StopExecution()
return
}
if blacklist[ip] {
ctx.StatusCode(403)
ctx.WriteString("forbidden by ip blacklist")
ctx.StopExecution()
return
}
if len(whitelist) > 0 && !whitelist[ip] {
ctx.StatusCode(403)
ctx.WriteString("access denied: ip not in whitelist")
ctx.StopExecution()
return
}
- 注意:白名单优先级高于黑名单,二者共存时建议先查白名单再查黑名单
- 黑名单建议支持 CIDR 表达式(如
"192.168.1.0/24"),需预编译为*net.IPNet存入 map - 不要在每次请求里重复解析 CIDR,初始化阶段就做好
常见错误:Nginx 配置漏传 X-Forwarded-For
即使代码写对了,如果 Nginx 没透传头,ctx.GetHeader("X-Forwarded-For") 就永远是空。这是线上最常被忽略的配置断点。
Nginx 必须显式设置:
location / {
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
proxy_pass http://backend;
}
-
$proxy_add_x_forwarded_for会追加而非覆盖,避免丢失原始链路 - 别只写
proxy_set_header X-Forwarded-For $remote_addr—— 这会丢掉上游已有的值 - 若用了 Cloudflare、AWS ALB 等托管 LB,确认它们是否默认透传该头(ALB 默认不传,需额外配置 listener rule)
IP 校验容易被绕过的边界情况
攻击者会伪造 X-Forwarded-For,所以不能无条件信任。关键判断逻辑必须结合「可信代理列表」:
- 只接受来自已知可信代理(如内网 Nginx IP、K8s Ingress Controller IP)发来的
X-Forwarded-For - 检查
ctx.RemoteAddr()是否在可信代理网段内,不在就直接忽略该头,强制用RemoteAddr - 禁用
X-Forwarded-For的客户端伪造能力:Nginx 加underscores_in_headers on;并拒绝带下划线的 header(防X_Forwarded_For绕过) - 测试时用
curl -H "X-Forwarded-For: 1.2.3.4" http://your-api/验证是否真被拦截,而不是只靠日志“看起来生效”
真正起作用的 IP 拦截,从来不是单点代码逻辑,而是 Nginx 配置 + 中间件解析 + 可信源校验三者咬合的结果。少一环,黑名单就形同虚设。


















