在 nginx 中配置 `proxy_pass` 传递客户端真实 ip，核心做法是在反向代理的 `location` 块中添加 `proxy_set_header` 指令，将 `x-real-ip` 和 `x-forwarded-for` 头设置为 `$remote_addr`。这样做后，后端应用（如 node.js、java 或 python）就能从请求头中读取到用户的真实公网 ip，而不是 nginx 服务器的内网 ip。
如何配置 proxy_pass 传递 X-Real-IP
要获取客户端的真实 IP，必须在 Nginx 的配置文件中显式设置 `X-Real-IP` 请求头。默认情况下，Nginx 不会自动转发这个头部，因此需要手动添加指令。具体操作是找到负责代理的 `server` 或 `location` 块，在其中加入 `proxy_set_header X-Real-IP $remote_addr;`。这样，当请求被转发给后端服务时，后端就能通过读取该头部获得发起请求的客户端地址。
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://backend_server;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
上述配置中，`$remote_addr` 变量代表直接连接 Nginx 的客户端 IP。如果客户端使用了代理，`$remote_addr` 可能显示的是上一级代理的 IP。为了更准确地追踪来源，通常还会配合 `X-Forwarded-For` 使用。`$proxy_add_x_forwarded_for` 会在原有列表后追加当前客户端 IP，形成完整的跳转链。后端程序解析这两个头部时，`X-Real-IP` 通常取第一个值，而 `X-Forwarded-For` 则是一个逗号分隔的字符串，需按规则截取。
如何处理多层代理下的 IP 信任问题
当 Nginx 位于负载均衡器或 CDN 之后时，`$remote_addr` 获取到的将是上一层代理的内网 IP，而非最终用户 IP。此时需要配置 Nginx 信任特定的上游代理 IP，并正确解析 `X-Forwarded-For` 头部。这可以通过 `set_real_ip_from` 和 `real_ip_header` 指令实现。Nginx 会检查请求中的指定头部，如果源 IP 在信任列表中，则用头部中的 IP 替换 `$remote_addr`。
# 信任来自 192.168.1.0/24 网段的负载均衡器 set_real_ip_from 192.168.1.0/24; # 告诉 Nginx 从 X-Forwarded-For 中提取真实 IP real_ip_header X-Forwarded-For; # 可选：设置递归查找，确保获取最末端的真实 IP real_ip_recursive on;
启用 `real_ip_recursive on` 后，Nginx 会从 `X-Forwarded-For` 列表的最右侧开始向左查找，直到遇到一个不在 `set_real_ip_from` 信任列表中的 IP，将其作为真实的 `$remote_addr`。这对于复杂的网络架构非常关键，能确保即使经过多级代理，后端依然能拿到最终用户的公网 IP。如果不配置信任列表，Nginx 会忽略上游传来的头部，导致 `$remote_addr` 始终指向最近的代理节点。
基于 proxy_set_header 缺失导致的 IP 错误排查
如果在后端应用中始终只能看到 Nginx 自身的 IP 或内网地址，最常见的原因是遗漏了 `proxy_set_header` 配置。开发者在调试时，应检查 Nginx 配置文件中对应的 `location` 块是否包含 `X-Real-IP` 和 `X-Forwarded-For` 的设置。此外，还需确认后端代码是否正确读取了这些头部，而不是错误地读取了 `REMOTE_ADDR` 环境变量（在某些 CGI 模式下可能映射不同）。
验证方法很简单：在后端打印出接收到的所有 HTTP 头部，或者编写一个简单的测试接口返回 `$_SERVER['HTTP_X_REAL_IP']` (PHP) 或 `req.headers['x-real-ip']` (Node.js)。如果返回为空或为 Nginx IP，则说明 Nginx 未正确转发。修改配置后，务必执行 `nginx -s reload` 使更改生效，否则新请求仍会使用旧配置。
