Nginx反向代理指南：如何透传客户端真实IP与协议头-Nginx-PHP中文网

nginx反向代理需透传真实ip和协议：配置proxy_set_header设置x-real-ip、x-forwarded-for、x-forwarded-proto等头；多层代理时用set_real_ip_from+real_ip_header提取真实ip；后端须主动解析对应头而非直接读取远程地址。

nginx反向代理指南：如何透传客户端真实ip与协议头

当Nginx作为反向代理时，后端服务（如应用服务器）默认只能看到Nginx的IP，丢失了客户端真实IP和原始协议（HTTP/HTTPS）。要正确透传这些信息，关键在于两步：Nginx主动设置请求头 + 后端服务信任并解析这些头。

配置Nginx透传真实IP

Nginx需在proxy_pass前显式添加以下头字段：

X-Real-IP：设为客户端真实IP，通常用$remote_addr（直连时有效）；若前端还有CDN或负载均衡，应改用$http_x_forwarded_for并取最左非私有IP
X-Forwarded-For：追加客户端IP，避免覆盖原有链路信息，写法为proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for
X-Forwarded-Proto：透传原始协议，写法为proxy_set_header X-Forwarded-Proto $scheme
X-Forwarded-Host与X-Forwarded-Port：按需补充，便于后端生成正确URL

示例配置片段：

location / {
  proxy_pass http://backend;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
}

处理多层代理场景

若请求经过CDN、WAF或多个Nginx节点，$remote_addr会变成上一跳IP。此时不能直接信任X-Forwarded-For全量内容，需结合set_real_ip_from指令白名单可信代理IP段，并启用real_ip_header X-Forwarded-For让Nginx自动提取最左合法IP赋给$remote_addr。

例如：

set_real_ip_from 10.0.0.0/8;
set_real_ip_from 192.168.0.0/16;
real_ip_header X-Forwarded-For;
real_ip_recursive on;

开启real_ip_recursive on后，Nginx会从右往左逐个剔除已知代理IP，最终把第一个非代理IP作为真实客户端IP。

后端服务需主动读取并信任这些头

Nginx只负责“发”，后端框架必须“收”。常见误区是后端直接调用request.getRemoteAddr()（Java）或request.remote_addr（Python Flask），这返回的是Nginx IP。

Java Spring Boot：配置server.forward-headers-strategy=framework，并确保TomcatServletWebServerFactory启用setRemoteIpHeader("X-Forwarded-For")
Python Flask：使用ProxyFix中间件，指定trusted_hosts或num_proxies
Node.js Express：设置app.set('trust proxy', true)，并确认Nginx已透传X-Forwarded-For和X-Forwarded-Proto