代码术语:一文讲清楚什么是xff

一文讲清楚:XFF

XFF 是 X-Forwarded-For 的缩写,一个 HTTP 请求头,用来记录「这个请求最初是从哪个 IP 发出的」。当请求穿过代理、负载均衡或 CDN 之后,服务端看到的连接来源早就不是真实客户端了,XFF 就是用来把真实 IP 捡回来的。

但它同时是最容易被伪造的请求头之一:值由客户端和沿途代理共同拼接,谁都能往里塞东西。所以理解 XFF 的重点不是「怎么读」,而是该信到哪一段为止。

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 头)。

X-Forwarded-For: 203.0.113.7, 198.51.100.23
位置 含义 可信度
最左(第一个) 声称的原始客户端 IP 最不可信,客户端可以自己写
中间 沿途各级代理 取决于代理有没有清理、有没有追加
最右(最后一个) 直接连着你的那一跳 相对可信,通常与 remote_addr 一致

顺序按请求经过的次序从左到右排列。所以「取第一个 IP 当用户 IP」是最常见的错误写法——它恰好是攻击者唯一能完全控制的位置。

规则一句话:从最右端开始往左走,跳过所有你信任的代理,遇到的第一个不可信地址才是真实客户端。

攻击者自己写:   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       已经用不到,忽略

关键点:只有可信列表里的地址才有资格追加,不可信的一律当数据看。 只要最外层入口是自己可控的,攻击者伪造的那一段就永远落在真实客户端左边,伤害不到结果。

头 内容 说明
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

注意:这些都是普通请求头,默认谁都能发。它们的可信度完全来自「谁在你的信任边界之内」。

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"';

「覆写」(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 源地址 唯一入口,客户端到你就没有别的代理

覆写的价值很直接:被覆写掉的那一段,恰好是攻击者唯一能完全控制的部分。链里只留下「门卫亲眼看到的地址」,后端不需要再用可信列表猜哪一段能信。

覆写不是写一句配置就算成立。它成立的标准只有一条——覆写后的值确实等于真实客户端。这一条要求下面每项同时成立,缺一项就退化成「把一个假 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,出争议时能自证覆写确实发生过。
  • 前面有 CDN 或云负载均衡。 此时 $remote_addr 是 CDN 节点地址,覆写会让所有用户变成同一个 IP。正确做法是追加,再从右往左跳过可信代理;或者改用厂商专有头(如 CF-Connecting-IP),并且只在入口处信任它。
  • 多层自建代理(Nginx + Ingress + 网关)。 同理:只有最外层追加,内层一律追加,绝不覆写。
  • 需要保留完整路径用于审计。 覆写会丢掉中间跳的痕迹,合规场景下往往要链式保留,再配合可信列表解析。

问自己一句:这一跳是不是客户端到我这里唯一的入口,并且没人能绕过它直连后端? 是,覆写最干净;不是,就老实追加,再从右往左取。

只要后端「看图说话」直接采信 XFF 的值,下面这些机制都会被绕过:

  • IP 白名单 / 内网接口保护:发一个 X-Forwarded-For: 127.0.0.1 就自称本机。
  • 限流、防刷、验证码、防暴力破解:换一个假 IP 就是一份全新配额。
  • 登录风控与审计日志:日志里全是伪造 IP,事后追责无从下手。
  • 地域限制 / 内容合规:声称来自允许地区的 IP 即可。
  • 头部污染:中间代理只追加不清理,链会越来越长,最终解析出错误结果。

应对原则:

  • 只在信任边界处相信它,边界之外的 XFF 一律当用户输入处理。
  • 后端显式配置可信代理列表,避免 trust proxy: true 这种「信任所有人」的写法。
  • 把 XFF 当不可信输入校验:限制总长度、限制段数、每段必须是合法 IP,顺手剥掉端口、方括号和空格。
  • 不要把 IP 当成唯一身份。NAT、运营商出口、IPv6 隐私地址都会让大量用户共用一个 IP,风控要叠加 Cookie、Token、设备指纹等维度。
现象 原因 处理方向
日志里全是 127.0.0.1 或内网 IP 只记了 remote_addr,或代理没转发 代理配转发,日志同时记录两者
所有用户 IP 一模一样 取到了链最右端的网关 IP 改成从右往左跳过可信代理
限流永远不触发 按最左的伪造值计数 改用可信解析结果
限流误伤全站 所有人被算作 CDN 出口 IP 换维度限流,或参考厂商专有头
取到 2001:db8::1 这类带括号端口的值 IPv6 会带方括号与端口 解析时剥掉括号和端口部分
请求被网关拒掉 攻击者拼接超长 XFF 在入口限制头部长度与段数

XFF 是一串由多跳共同写成的 IP 列表:右端可信,左端可伪造。用它之前先回答一个问题——我到底信任哪些代理?

# 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 带方括号与端口
- 超长头部被网关拒绝

返回:代码术语

该主题尚不存在

您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。

  • 代码术语/一文讲清楚什么是xff.txt
  • 最后更改: 2026/10/12 17:17
  • 由 张叶安