如何使用 proxy_set_header 透传客户端IP与Host至后端服务？

本文共计622个文字，预计阅读时间需要3分钟。

请提供需要改写的原文，我将根据您的要求进行修改。

透传真实 IP 的两个核心 header

必须同时配置以下两项，才能覆盖多级代理场景：

• X-Real-IP：直接设为 $remote_addr，它代表与 Nginx 建立 TCP 连接的上一级客户端（通常是直连用户或可信代理）
• X-Forwarded-For：用 $proxy_add_x_forwarded_for，它会自动在原有值末尾追加当前请求的真实 IP，适合多层 CDN 或负载均衡链路

示例配置：

  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

保留原始 Host 头的三种写法

Host 头决定后端如何生成 URL、做虚拟主机路由。不设置或设错，容易导致 400 错误或跳转到内部地址：

• proxy_set_header Host $host; —— 最常用，取客户端请求里的 Host（含端口，如 example.com:8080）
• proxy_set_header Host $http_host; —— 更严谨，优先使用请求头中已有的 Host 字段（若为空则不传）
• proxy_set_header Host $server_name; —— 强制固定为 Nginx server 块配置的域名，适合后端只认一个入口域名的场景

后端必须自己解析，Nginx 不会自动“替换” remote_addr

Nginx 只负责把 IP 写进 header，后端代码仍需手动提取：

• Node.js/Express：用 req.headers['x-real-ip'] 或 req.headers['x-forwarded-for'].split(',')[0].trim()
• Next.js Pages Router API Route：req.headers['x-real-ip']
• Next.js App Router 中间件：request.headers.get('x-real-ip')
• Java Servlet：request.getHeader("X-Real-IP")，而非 getRemoteAddr()

注意：X-Forwarded-For 可能是逗号分隔的多个 IP（如 203.0.113.1, 198.51.100.2），最左边才是用户真实 IP，右边是各级代理节点。

额外建议：配合 real_ip_module 提升日志准确性

如果还希望 Nginx 自己的日志（access_log）也记录真实 IP，需启用 real_ip_module 并配置：

  set_real_ip_from 127.0.0.1;   # 仅信任本机反向代理
  real_ip_header X-Real-IP;
  real_ip_recursive on;

这样 $remote_addr 在日志里就变成真实 IP，无需再从 header 解析。