c.clientip() 在生产环境常返回 127.0.0.1 或内网地址，因其默认不信任任何代理，跳过 x-forwarded-for/x-real-ip 而直接使用 remoteaddr；需显式调用 settrustedproxies 配置可信网段（cidr 格式），并确保 nginx 正确设置 proxy_set_header x-forwarded-for $proxy_add_x_forwarded_for 和 x-real-ip $remote_addr。
为什么 c.ClientIP() 在生产环境经常返回 127.0.0.1 或内网地址
c.ClientIP() 不是“直接读 IP”，而是依赖 c.RemoteIP() 判断是否为可信代理，再决定是否解析请求头。默认情况下，Gin 的 SetTrustedProxies 未配置，它会把所有代理都当成不可信——结果就是跳过 X-Forwarded-For / X-Real-IP，直接返回 c.Request.RemoteAddr 解析出的地址（通常是 Nginx 的 127.0.0.1:42183 或 10.0.1.5:33291）。这不是函数 bug，是安全默认行为。
常见错误现象：
– 本地开发时 c.ClientIP() 看似正常（直连无代理）
– 上线后突然全变成 127.0.0.1、10.0.0.x、172.16.x.x
– 黑白名单中间件完全失效，风控形同虚设
- 必须显式调用
r.SetTrustedProxies([]string{"10.0.0.0/8", "192.168.0.0/16", "172.16.0.0/12"})，不能留空或传nil - 网段写法必须是 CIDR 格式（如
"10.0.0.0/8"），不能写成"10.0.0.1"单 IP（Gin 内部用net.IPNet.Contains判断） - 如果用云厂商 SLB（如阿里云、AWS ALB），需查清其出口 IP 段并加入信任列表，否则 X-Forwarded-For 被丢弃
Gin 中正确提取真实 IP 的三步校验逻辑
别依赖单一 header，Gin 的 c.ClientIP() 底层其实已按顺序尝试：X-Forwarded-For → X-Real-IP → RemoteAddr，但前提是代理 IP 先被信任。真正要自己控制的，是 header 解析细节和 fallback 顺序。
- 优先检查
X-Real-IP：它只存一个 IP，Nginx 配置proxy_set_header X-Real-IP $remote_addr;后可靠，且无需切分 - 再 fallback 到
X-Forwarded-For：取逗号分隔后的最左非私有 IP，但必须strings.TrimSpace后再net.ParseIP，否则空格导致解析失败 - 最后才用
c.RemoteIP()：仅当以上全为空或全是私有地址（127.0.0.1、10.0.0.0/8等）时兜底，生产环境不应触发 - 注意
X-Forwarded-For可伪造，所以必须配合SetTrustedProxies—— 如果请求来源不在信任列表里，Gin 会直接忽略该 header
Nginx 配置不匹配会导致 Gin 提取逻辑完全失效
Gin 是否能拿到真实 IP，一半取决于 Go 代码，另一半取决于 Nginx 是否把原始 IP 正确注入 header。常见错配场景：
-
proxy_set_header X-Forwarded-For $remote_addr;❌ —— 这会覆盖上游链路，后端永远只看到最后一跳 IP -
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;✅ —— 它会追加而非覆盖，保留原始客户端 IP 在最左 -
proxy_set_header X-Real-IP $remote_addr;必须存在，否则X-Real-IPheader 为空，Gin 就少一个可靠 fallback - 多层代理（CDN → Nginx → Go）时，CDN 通常也设了
X-Forwarded-For，Nginx 的$proxy_add_x_forwarded_for会把它原样带上，Gin 解析时需信任 CDN 出口网段
自定义 IP 提取函数比直接用 c.ClientIP() 更可控
当需要精确控制解析逻辑（比如豁免健康检查路径、记录原始 XFF 值、做日志脱敏），建议绕过 c.ClientIP()，手写提取函数。核心就三点：确认代理可信 → 解析 XFF → 过滤私有 IP。
示例关键片段：
func realIP(c *gin.Context) string {
ip, _, _ := net.SplitHostPort(c.Request.RemoteAddr)
if isTrustedProxy(net.ParseIP(ip)) {
if xff := c.Request.Header.Get("X-Forwarded-For"); xff != "" {
for _, ip = range strings.Split(xff, ",") {
ip = strings.TrimSpace(ip)
if ip := net.ParseIP(ip); ip != nil && !ip.IsPrivate() {
return ip.String()
}
}
}
if realIP := c.Request.Header.Get("X-Real-IP"); realIP != "" {
if ip := net.ParseIP(realIP); ip != nil && !ip.IsPrivate() {
return ip.String()
}
}
}
if ip := net.ParseIP(ip); ip != nil && !ip.IsPrivate() {
return ip.String()
}
return "0.0.0.0"
}
-
isTrustedProxy必须用net.IPNet.Contains做网段判断，不能字符串匹配 - 不要用正则或手动 trim 空格，
strings.TrimSpace+net.ParseIP足够健壮 - 返回
"0.0.0.0"比 panic 更安全，便于上层做降级处理
复杂点不在代码长度，而在信任边界的定义：你得清楚每一层代理（CDN、SLB、Nginx）的出口 IP 段，并确保它们全在 SetTrustedProxies 列表里——漏掉任意一层，真实 IP 就断在那一环。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
