Nginx 工程实践 -- 4. 转发头与真实客户端 IP

反向代理后面的后端服务,看到的连接地址是 Nginx,通常是 127.0.0.1。如果什么都不做,访问日志丢失来源、按 IP 限流失效、地域和风控判断失真、后端生成绝对链接时还可能拿到内网地址。本篇把转发头怎么写、变量怎么选、以及怎么把真实 IP "还原"回来讲清楚。

flowchart LR
    C["客户端"] -->|"XFF: 客户端"| CDN["CDN"]
    CDN -->|"XFF 追加"| N["Nginx
real_ip_recursive on"] N -->|"XFF 追加
$proxy_add_x_forwarded_for"| B["后端"]

一、为什么需要转发头

Nginx 与后端建立的是新的 TCP 连接,后端拿到的是 Nginx 的地址。后果很直接:

  • 访问日志里所有请求都来自同一个 IP;
  • 限流、封禁、验证码触发等基于 IP 的策略全部失效;
  • 风控、地域统计、灰度分流失去依据;
  • 后端重定向或生成绝对 URL 时,可能返回内网地址。

解决方式分两层:转发头(把信息"告知"后端)和 realip(把地址"改写"回真实值)。

二、四个关键转发头

1
2
3
4
5
6
7
8
location /api/ {
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;
}

2.1 Host

proxy_set_header 的默认值是 Host $proxy_host;,也就是 proxy_pass 里写的名字(可能是 upstream 名或后端地址),通常不是客户端想要的域名。

变量含义
$host请求行里的主机名,去掉端口;没有则取当前 server_name 的第一个;小写
$http_host客户端原始 Host 头,可能带端口,原样保留
$server_name当前 server 块的 server_name
$proxy_hostproxy_pass 的目标名,默认值

选择建议:后端按域名做虚拟主机或生成链接时用 $host;需要原样透传时用 $http_host;不确定就用 $host。

2.2 X-Real-IP

1
proxy_set_header X-Real-IP $remote_addr;

只放一个地址,实现简单,但不能穿越多级代理(会被上游覆盖)。

2.3 X-Forwarded-For

1
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

$proxy_add_x_forwarded_for = 原请求里的 XFF + , + $remote_addr,是追加而不是覆盖。多级代理时它会形成一条链,后端可以逐跳解析。

2.4 X-Forwarded-Proto / X-Forwarded-Host / X-Forwarded-Port

1
2
3
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;

后端据此判断客户端最初用的是 http 还是 https,避免把 https 请求重定向回 http、或生成错误协议的绝对 URL。

三、变量速查

变量来源
$remote_addr与 Nginx 建立 TCP 连接的地址
$http_x_forwarded_for客户端原始 XFF,可能被伪造
$proxy_add_x_forwarded_for原 XFF + 当前 $remote_addr(追加)
$scheme本跳协议(http/https)
$server_port本跳监听端口

四、Forwarded(RFC 7239)

HTTP 标准定义了 Forwarded: for=...;host=...;proto=...,比 X-Forwarded-* 更规范。但 Nginx 原生不会生成 Forwarded 头,需要第三方模块或自行拼装;X-Forwarded-* 仍是事实标准,绝大多数后端都支持。

五、多层链路下怎么取"入口 IP"

1
客户端 1.2.3.4 → CDN → Nginx → 后端

经过 CDN 时,CDN 会把客户端地址追加进 XFF;Nginx 再追加 CDN 的出口地址。于是后端收到的 XFF 类似:

1
X-Forwarded-For: 1.2.3.4, 10.20.30.40

两种取法:

  • 取最左($http_x_forwarded_for 的第一个):实现简单,但客户端可以在请求里自带 XFF 伪造,不可信;
  • 从可信层数往左数:只信任已知会写 XFF 的上游,跳过固定层数后取第一个,安全性更高。这正是 real_ip_recursive 做的事。

六、用 realip 还原真实地址

转发头只是"告知",ngx_http_realip_module 会把 $remote_addr 改写为头里的地址,让后续所有依赖它的逻辑(访问控制、限流、日志、geo、allow/deny)都基于真实 IP 生效。

1
2
3
4
5
6
7
# http 块或 server 块
set_real_ip_from 10.0.0.0/8;
set_real_ip_from 172.16.0.0/12;
set_real_ip_from 127.0.0.1;

real_ip_header X-Forwarded-For;
real_ip_recursive on;

三个指令:

指令默认说明
set_real_ip_from—声明可信来源地址或网段;只有来自这些地址的请求才会被改写
real_ip_headerX-Real-IP从哪个头取替换地址;用 XFF 就写 X-Forwarded-For
real_ip_recursiveoffon 时从右往左跳过所有可信地址,取第一个不可信地址

off 时,如果直连地址可信,就用头里的最后一个地址;on 时,一直向左找,直到遇到不可信的地址,也就是"入口客户端"。多数代理场景需要 on。

改写后仍可用 $realip_remote_addr、$realip_remote_port 保留改写前的地址。

注意:ngx_http_realip_module 默认不参与编译,需要 --with-http_realip_module。Debian/Ubuntu 的发行版包通常已包含,自建 Nginx 时要显式打开。

七、完整配置模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# ---- http 块 ----
upstream backend {
server 127.0.0.1:3000;
keepalive 32;
}

# 信任来自本机与内网代理的地址
set_real_ip_from 127.0.0.1;
set_real_ip_from 10.0.0.0/8;
real_ip_header X-Forwarded-For;
real_ip_recursive on;

# ---- server 块 ----
server {
listen 80;
server_name example.com;

location /api/ {
proxy_pass http://backend;
proxy_http_version 1.1;

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;
proxy_set_header X-Forwarded-Host $host;

access_log /var/log/nginx/api-access.log combined;
}
}

八、排错

现象原因 / 处理
后端日志全是 127.0.0.1没配 realip,或 set_real_ip_from 没包含真实来源网段
Host 变成了 upstream 名或 IP用了默认的 $proxy_host,改成 $host
XFF 只剩一个地址上游覆盖了 XFF;或后端只取第一个值
后端拿到内网 IPXFF 第一跳是 CDN/LB,需要 real_ip_recursive on
改写后地址没变set_real_ip_from 未覆盖该来源;或模块未编译

验证方式:后端打印 Host、X-Real-IP、X-Forwarded-For,用 curl -H "X-Forwarded-For: 1.2.3.4" 模拟客户端自带的伪造链,确认改写逻辑符合预期。

参考链接

  1. Nginx 官方文档:ngx_http_proxy_module —— proxy_set_header 及内置变量;
  2. Nginx 官方文档:ngx_http_realip_module —— set_real_ip_from / real_ip_header / real_ip_recursive;
  3. RFC 7239:Forwarded HTTP Extension;
  4. Nginx 官方文档:嵌入式变量。

小结

转发头解决"告知",realip 解决"改写"。Host 用 $host,X-Forwarded-For 用 $proxy_add_x_forwarded_for,X-Forwarded-Proto 用 $scheme;多级链路里用 set_real_ip_from + real_ip_recursive on 才能拿到入口地址。别让后端只凭 XFF 的第一个值做安全判断——它可被伪造。

系列导航


Nginx 工程实践 -- 4. 转发头与真实客户端 IP
https://bubao.github.io/posts/a3f1c2d4.html
作者
一念
发布于
2026年11月21日
许可协议