====== 一文讲清楚:XFF ======
''XFF'' 是 **X-Forwarded-For** 的缩写,一个 HTTP **请求头**,用来记录「这个请求最初是从哪个 IP 发出的」。当请求穿过代理、负载均衡或 CDN 之后,服务端看到的连接来源早就不是真实客户端了,XFF 就是用来把真实 IP 捡回来的。
但它同时是**最容易被伪造的请求头之一**:值由客户端和沿途代理共同拼接,谁都能往里塞东西。所以理解 XFF 的重点不是「怎么读」,而是**该信到哪一段为止**。
===== 1. 它要解决什么问题 =====
HTTP 跑在 TCP 之上,而 TCP 连接是**逐跳**建立的:客户端连代理,代理再连后端,后端只知道对面是代理。
客户端 203.0.113.7 --TCP--> Nginx 10.0.0.5 --TCP--> 应用 10.0.0.8
应用看到的 remote_addr = 10.0.0.5 (代理的内网地址,不是用户)
TCP 头里没有「原始来源」这个概念,于是业内约定:**每经过一个代理,就往 ''X-Forwarded-For'' 里追加一个 IP**。后端读这一串,就能把请求路径还原出来。
它最早由 Squid 代理软件引入,后来被 Nginx、HAProxy、各类负载均衡和 CDN 广泛沿用,成为事实标准;真正写入规范的是后来的 RFC 7239(''Forwarded'' 头)。
===== 2. 格式:一串 IP,逗号加空格分隔 =====
X-Forwarded-For: 203.0.113.7, 198.51.100.23
^ 位置 ^ 含义 ^ 可信度 ^
| 最左(第一个) | 声称的原始客户端 IP | **最不可信**,客户端可以自己写 |
| 中间 | 沿途各级代理 | 取决于代理有没有清理、有没有追加 |
| 最右(最后一个) | 直接连着你的那一跳 | **相对可信**,通常与 ''remote\_addr'' 一致 |
顺序按请求经过的次序**从左到右**排列。所以「取第一个 IP 当用户 IP」是最常见的错误写法——它恰好是攻击者唯一能完全控制的位置。
===== 3. 正确取法:从右往左,跳过可信代理 =====
规则一句话:**从最右端开始往左走,跳过所有你信任的代理,遇到的第一个不可信地址才是真实客户端。**
攻击者自己写: X-Forwarded-For: 6.6.6.6
Nginx 追加上游: 203.0.113.7
后端收到: X-Forwarded-For: 6.6.6.6, 203.0.113.7
remote_addr: 10.0.0.5
可信代理列表:10.0.0.0/8
完整链从右往左走:
10.0.0.5 在可信列表内 跳过
203.0.113.7 不在可信列表内 就是真实客户端
6.6.6.6 已经用不到,忽略
关键点:**只有可信列表里的地址才有资格追加,不可信的一律当数据看。** 只要最外层入口是自己可控的,攻击者伪造的那一段就永远落在真实客户端左边,伤害不到结果。
===== 4. 家族里的其他头 =====
^ 头 ^ 内容 ^ 说明 ^
| ''X-Forwarded-For'' | 逗号分隔的 IP 链 | 事实标准,最常见 |
| ''X-Real-IP'' | 单个 IP | Nginx 社区习惯,取值简单,但同样可伪造 |
| ''Forwarded'' | ''for=203.0.113.7;proto=https;by=10.0.0.5'' | RFC 7239 定义的正规写法,含协议与代理身份 |
| ''X-Forwarded-Proto'' | ''http'' / ''https'' | 后端判断原始协议,避免 HTTPS 站点被重定向回 HTTP |
| ''X-Forwarded-Host'' | 原始域名 | 生成绝对 URL 时使用 |
| ''Via'' | 代理链与协议版本 | 由代理自己添加,规范在 RFC 7230 |
| ''CF-Connecting-IP'' | 单个 IP | Cloudflare 专有,官方建议优先于 XFF |
注意:这些**都是普通请求头**,默认谁都能发。它们的可信度完全来自「谁在你的信任边界之内」。
===== 5. 配置示例 =====
Nginx 反向代理,转发时把来源信息带给后端:
location / {
proxy_pass http://127.0.0.1:8080;
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\_add\_x\_forwarded\_for'' = 客户端传来的 XFF **加上** ''$remote\_addr'',也就是**追加**语义。
* 如果这台 Nginx 就是**最外层入口**(前面没有别的代理),更安全的做法是**覆写**(见第 6 节),丢掉客户端传进来的一切:
proxy_set_header X-Forwarded-For $remote_addr;
后端侧要显式声明可信范围:
// Express:必须显式配置信任范围,别用 trust proxy: true
const express = require("express");
const app = express();
app.set("trust proxy", ["loopback", "10.0.0.0/8"]); // 只有这些来源的 XFF 才算数
app.get("/", (req, res) => res.json({ ip: req.ip, chain: req.ips }));
# Spring Boot:交给框架解析转发头
server.forward-headers-strategy=framework
server.tomcat.remoteip.internal-proxies=10\.0\.0\.\d{1,3}
日志里也要带上,方便排查:
log_format main '$remote_addr - $http_x_forwarded_for "$request"';
===== 6. 覆写 XFF:是什么,什么条件下才成立 =====
「覆写」(overwrite / 替换)指的是入口那一跳**不追加、只替换**:把客户端送来的 ''X-Forwarded-For'' 整个丢掉,用自己这条 TCP 连接的对端地址重新写一遍。
# 覆写:丢掉客户端送来的整串,只写自己看到的 TCP 源地址
proxy_set_header X-Forwarded-For $remote_addr;
# 追加:保留客户端送来的值,再补上自己的上游地址
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
^ 做法 ^ 头里剩下什么 ^ 适用位置 ^
| 追加 | 客户端传来的值 + 本跳的上游地址 | 内层代理,真实客户端还要继续往后传 |
| 覆写 | 只有本跳看到的 TCP 源地址 | **唯一入口**,客户端到你就没有别的代理 |
覆写的价值很直接:**被覆写掉的那一段,恰好是攻击者唯一能完全控制的部分**。链里只留下「门卫亲眼看到的地址」,后端不需要再用可信列表猜哪一段能信。
==== 6.1 覆写成立要同时满足的条件 ====
覆写不是写一句配置就算成立。它成立的标准只有一条——**覆写后的值确实等于真实客户端**。这一条要求下面每项同时成立,缺一项就退化成「把一个假 IP 从左边挪到了右边」。
- **① 这一跳直接面对客户端。** 覆写点必须是最外层入口,客户端与它之间没有别的代理、CDN 或网关。否则 ''$remote\_addr'' 取到的是上一跳代理的地址,覆写等于亲手删掉真实 IP。
- **② 后端不可绕行。** 应用只监听内网、只接受来自入口的连接(防火墙、安全组、监听 ''127.0.0.1''、mTLS 任选其一)。否则攻击者可以跳过入口直连后端自己写 XFF,而覆写逻辑根本不会执行。
- **③ 入口唯一且可控。** 它是请求进入信任域的唯一通路,不会被临时开的口子绕过——调试端口、测试域名、旁路负载均衡都算。
- **④ 同类头一起清理。** 客户端能伪造的不止 XFF:''X-Real-IP''、''Forwarded''、''True-Client-IP'' 等必须在同一跳一并重写或删除。只改一个,后端读另一个照样被骗。
- **⑤ 同名与重复头被真正覆盖。** HTTP 头名大小写不敏感,且允许多个同名头。要确认网关是**先删后写**(Nginx 的 ''proxy\_set\_header'' 即为同名覆盖),而不是把客户端的值拼在你的值前后。
- **⑥ 配套头按同一标准处理。** ''X-Forwarded-Proto''、''X-Forwarded-Host'' 同样要覆写,否则攻击者塞一个 ''X-Forwarded-Proto: http'' 就可能造成协议降级或重定向被污染。
- **⑦ 后端只认这一条链路。** 应用或框架的可信代理配置与覆写点对应上;限流、风控、审计日志统一改用覆写后的值,不允许别处继续读原始的 ''http\_x\_forwarded\_for''。
- **⑧ 覆写出来的值仍要校验。** 它终究是字符串:限制长度与段数、校验是否是合法 IP,并规范 IPv6(剥掉方括号与端口)。
- **⑨ 日志留两份。** 同时记录 ''remote\_addr'' 与最终采信的客户端 IP,出争议时能自证覆写确实发生过。
==== 6.2 什么时候不该覆写 ====
- **前面有 CDN 或云负载均衡。** 此时 ''$remote\_addr'' 是 CDN 节点地址,覆写会让所有用户变成同一个 IP。正确做法是**追加**,再从右往左跳过可信代理;或者改用厂商专有头(如 ''CF-Connecting-IP''),并且只在入口处信任它。
- **多层自建代理(Nginx + Ingress + 网关)。** 同理:只有最外层追加,内层一律追加,绝不覆写。
- **需要保留完整路径用于审计。** 覆写会丢掉中间跳的痕迹,合规场景下往往要链式保留,再配合可信列表解析。
==== 6.3 一句话判断 ====
问自己一句:**这一跳是不是客户端到我这里唯一的入口,并且没人能绕过它直连后端?** 是,覆写最干净;不是,就老实追加,再从右往左取。
===== 7. 安全:XFF 能骗过哪些机制 =====
只要后端「看图说话」直接采信 XFF 的值,下面这些机制都会被绕过:
- **IP 白名单 / 内网接口保护**:发一个 ''X-Forwarded-For: 127.0.0.1'' 就自称本机。
- **限流、防刷、验证码、防暴力破解**:换一个假 IP 就是一份全新配额。
- **登录风控与审计日志**:日志里全是伪造 IP,事后追责无从下手。
- **地域限制 / 内容合规**:声称来自允许地区的 IP 即可。
- **头部污染**:中间代理只追加不清理,链会越来越长,最终解析出错误结果。
应对原则:
* **只在信任边界处相信它**,边界之外的 XFF 一律当用户输入处理。
* 后端显式配置可信代理列表,避免 ''trust proxy: true'' 这种「信任所有人」的写法。
* 把 XFF 当**不可信输入**校验:限制总长度、限制段数、每段必须是合法 IP,顺手剥掉端口、方括号和空格。
* **不要把 IP 当成唯一身份**。NAT、运营商出口、IPv6 隐私地址都会让大量用户共用一个 IP,风控要叠加 Cookie、Token、设备指纹等维度。
===== 8. 常见坑速查 =====
^ 现象 ^ 原因 ^ 处理方向 ^
| 日志里全是 ''127.0.0.1'' 或内网 IP | 只记了 ''remote\_addr'',或代理没转发 | 代理配转发,日志同时记录两者 |
| 所有用户 IP 一模一样 | 取到了链最右端的网关 IP | 改成从右往左跳过可信代理 |
| 限流永远不触发 | 按最左的伪造值计数 | 改用可信解析结果 |
| 限流误伤全站 | 所有人被算作 CDN 出口 IP | 换维度限流,或参考厂商专有头 |
| 取到 ''2001:db8::1'' 这类带括号端口的值 | IPv6 会带方括号与端口 | 解析时剥掉括号和端口部分 |
| 请求被网关拒掉 | 攻击者拼接超长 XFF | 在入口限制头部长度与段数 |
===== 9. 一句话总结 =====
XFF 是一串**由多跳共同写成**的 IP 列表:**右端可信,左端可伪造**。用它之前先回答一个问题——**我到底信任哪些代理?**
===== 10. 结构总览 =====
```mdk height=560 color=#4f46e5
# XFF(X-Forwarded-For)
## 是什么
### 一个 HTTP 请求头
- 记录请求最初来自哪个 IP
- 多值用逗号加空格分隔
### 为什么需要
- TCP 连接是逐跳的
- remote_addr 只是最后一跳代理
## 格式与读取
### 顺序
- 最左 = 声称的客户端(可伪造)
- 最右 = 直接连着你的那一跳
### 正确算法
- 从右往左走
- 跳过所有可信代理
- 第一个不可信的才是真实客户端
## 覆写 XFF
### 是什么
- 丢弃客户端送来的整串
- 用本跳 TCP 源地址重写
- 与「追加」相对
### 成立标准
- 本跳直接面对客户端
- 后端不可绕行
- 入口唯一且可控
- 同类头一并清理
- 同名重复头真正覆盖
- proto / host 配套头同样处理
- 后端只认这一条链路
- 值仍要做合法性校验
- 日志留 remote_addr 与结果两份
### 不该覆写
- 前面有 CDN 或云 LB
- 多层自建代理
- 审计需要保留完整路径
## 兄弟头
### 常见
- X-Real-IP
- X-Forwarded-Proto / Host
- Via
### 标准
- Forwarded(RFC 7239)
### 厂商专有
- CF-Connecting-IP
## 配置要点
### Nginx
- $proxy_add_x_forwarded_for 是追加语义
- 最外层入口建议直接覆写
### 后端
- Express 显式设置 trust proxy
- Spring Boot 交给框架解析
### 日志
- 同时记录 remote_addr 与 XFF
## 安全风险
### 可伪造会绕过
- IP 白名单与内网保护
- 限流 / 风控 / 审计
- 地域限制
### 对策
- 只在可信边界相信 XFF
- 当不可信输入做校验
- 不把 IP 当唯一身份
## 常见坑
### 取错位置
- 取最左 → 被伪造
- 取最右 → 全是网关 IP
### 覆写用错地方
- 多层代理下覆写 → 只剩 CDN 节点 IP
### 解析细节
- IPv6 带方括号与端口
- 超长头部被网关拒绝
```
----
返回:[[代码术语]]