Gin 默认不加 X-Forwarded-For 头，因其无法判断上游代理是否可信，直接信任该头易遭 IP 伪造；仅当显式调用 c.ClientIP() 且配置了 SetTrustedProxies 时，才按可信代理链解析真实客户端 IP。
为什么 Gin 默认不加 X-Forwarded-For 头？
Gin 默认不自动解析或设置 X-Forwarded-For，因为它无法判断上游是否可信——如果 Nginx 没配 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for，或者前端有多个代理层，Gin 直接信任该头就可能被伪造 IP。所以它只在你显式调用 c.ClientIP() 时，才按 TrustedProxies 列表做可信链校验。
常见错误现象：Nginx 已配置反代，但 Gin 日志里全是 127.0.0.1 或容器内网 IP，c.ClientIP() 返回不真实客户端地址。
- 必须在 Gin 启动前设置可信代理列表，例如：
r.SetTrustedProxies([]string{"10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"}) - 若用 Kubernetes Ingress 或云厂商 LB，要填的是 LB 的出口 IP 段（不是 Nginx Pod IP），否则校验失败
- 若 Nginx 和 Gin 在同一 Pod（Sidecar 场景），Nginx 的
proxy_set_header X-Forwarded-For $remote_addr就够用，因为流量不经过外部网络
proxy_pass 路径末尾斜杠怎么影响 Gin 路由匹配？
Nginx 的 proxy_pass 是否带结尾斜杠，直接决定路径是否被重写，而 Gin 对路径是严格匹配的。比如 Gin 注册了 GET /api/v1/users，但 Nginx 配置错，就会 404。
典型错误配置：
location /api/ {
proxy_pass http://localhost:8080; # ← 少了斜杠，/api/ → /api/，Gin 收到 /api/v1/users，找不到路由
}正确写法（保持路径前缀剥离）：
location /api/ {
proxy_pass http://localhost:8080/; # ← 注意末尾斜杠，/api/v1/users → /v1/users
}- 不带斜杠：Nginx 把 location 匹配部分原样拼到后端 URL 后，
/api/+v1/users=/api/v1/users - 带斜杠：Nginx 把
/api/替换为空，只转发剩余路径，/v1/users - 若 Gin 根路径是
/，且你希望保留/api前缀，就别加斜杠，但 Gin 路由必须注册为/api/v1/users
如何让 Gin 正确识别 HTTPS 和 Host？
Gin 本身不感知协议和域名，全靠 Nginx 传来的请求头。如果没配好，c.Request.URL.Scheme 是 http，c.Request.Host 是 Nginx 的监听地址（如 localhost:8080），导致生成的绝对 URL、重定向地址出错。
关键配置项必须出现在 Nginx 的 location 块里：
-
proxy_set_header X-Forwarded-Proto $scheme;—— 让 Gin 知道原始是 http 还是 https -
proxy_set_header Host $host;—— 传递原始 Host，避免 Gin 用反代地址生成链接 -
proxy_set_header X-Real-IP $remote_addr;—— 辅助 IP 识别（配合TrustedProxies）
然后 Gin 里需启用信任头解析：
r.ForwardedByClientIP = true
否则 c.Request.URL.Scheme 始终是 http，c.Request.Host 不会更新。
静态文件被 Nginx 处理还是 Gin 处理？
别让 Gin 处理前端静态资源。Gin 的 StaticFS 或 FileServer 是阻塞式、无缓存、不压缩的，高并发下拖慢整个服务。Nginx 天然支持 gzip、etag、expires 和内存缓存，应该由它接管。
典型分工：
- Nginx 配置
location /static/或location ~* \.(js|css|png|jpg|gif)$，指向本地root /var/www/static; - Gin 只处理 API 路由（如
/api/、/healthz），不挂载任何静态文件中间件 - 若用单页应用（SPA），Nginx 的
try_files必须兜底到index.html，否则前端路由刷新 404
容易踩的坑：开发时用 Gin 内置静态服务没问题，上线后忘记关掉，结果 Nginx 和 Gin 同时响应静态请求，缓存策略冲突、ETag 不一致、甚至返回不同版本文件。
