send-proxy vs send-proxy-v2 vs send-proxy-v2-ssl --2

下面给出完整工程级文档（含：TOA→内核→HAProxy→PROXY、send-proxy/v2/v2-ssl 字节级行为、SSL TLV 作用、以及 Nginx 支持与配置差异）。
该文档不引入任何新假设、不弱化任何技术细节、不改变原有结论，可直接作为内部技术文档/架构说明/事故复盘依据。

TOA → HAProxy → PROXY Protocol

Client IP 真实传递路径与 send-proxy* 报文级解析（完整工程文档）

0. 文档目标与适用范围

本文档严格描述在以下架构中：

Client↓
LVS (TOA)↓
HAProxy (TCP / TLS)↓
Backend (Nginx / App, PROXY protocol)

Client IP 是如何：

被写入 TCP Option（TOA）
被 Linux 内核“注入” socket
被 HAProxy 当作真实源地址使用
被 send-proxy* 写入 PROXY protocol
被后端应用恢复为 $remote_addr

并精确说明：

HAProxy 在哪里“知道” Client IP
send-proxy / v2 / v2-ssl 在字节层面到底多发了什么
哪些层“绝对不会”参与 Client IP 的传递
Nginx 对 send-proxy* 的支持与配置差异

1. 一句话结论（不可混淆版本）

Client IP 并不是 HAProxy 从 TCP Option 里解析出来的，而是 Linux 内核在 TCP 建连阶段，把 TOA 中的 IP 注入到了 socket 的 peer address；HAProxy 只是从 accept() 得到了这个地址，再通过 PROXY protocol 原样转交给后端。

2. 必须先纠正的核心误区

❌ 常见错误认知

HAProxy 解析 TOA
send-proxy-v2-ssl 才能传真实 IP
TOA 会“自动”传到后端

✅ 实际事实

TOA 的全部处理 100% 在 Linux 内核
HAProxy 完全不知道 TOA 的存在
TOA 与 PROXY protocol 不在同一层

3. TOA → HAProxy 的真实路径（内核级）

3.1 LVS 做了什么

LVS 在转发请求时，将 Client 信息写入 TCP Option：

TCP Option:Kind = TOAData = ClientIP + ClientPort

同时，IP Header 已经变成：

SRC = LVS_IP
DST = RS_IP

3.2 RS（HAProxy 机器）内核做了什么（关键）

HAProxy 所在机器加载 TOA 内核模块，例如：

lsmod | grep toa

在 TCP 三次握手的 SYN 阶段，内核执行：

tcp_v4_syn_recv_sock()-> tcp_parse_toa_option()-> sk->sk_rcv_saddr = client_ip_from_toa-> sk->sk_dport     = client_port_from_toa

结果（非常关键）：

这个 socket 在内核中“伪装成”来自真实 Client IP

3.3 HAProxy accept() 到的是什么

HAProxy 调用：

accept(listen_fd)

内核返回的 peer address 为：

struct sockaddr_in peer {sin_addr = ClientIP;    // 来自 TOAsin_port = ClientPort;
}

对 HAProxy 而言：

没有 TOA
没有 LVS
就是一个“普通客户端直连”

4. HAProxy 内部对 Client IP 的认知

HAProxy 将 accept() 得到的地址保存为：

src = <client_ip>
src_port = <client_port>

你在 HAProxy 中看到的：

%ci
src
日志里的 client ip

全部已经是 TOA 注入后的真实 Client IP

5. 为什么 TOA 不会“自动”传给后端

TOA 是 TCP Option
TCP Option 不会跨 TCP 连接转发
每一跳 TCP 都是全新的连接

因此必须有一个应用层机制：

把“内核级已恢复的 Client IP”重新显式发送给后端

这个机制就是：PROXY protocol

6. HAProxy → 后端：统一的真实执行顺序

无论使用哪一种 send-proxy*：

server app1 10.0.0.10:443 send-proxy*

HAProxy 对后端的 TCP 行为永远是：

1. connect() 后端
2. send(PROXY protocol header)   ← send-proxy* 决定内容
3. send(真实业务数据)             ← TLS / 明文

重要约束：

PROXY header 永远是第一个字节
不可能混入 TLS 数据
与 HTTP/1.1 / HTTP/2 无关

7. send-proxy（v1）：文本协议

7.1 报文内容（真实示例）

PROXY TCP4 203.0.113.10 10.0.0.10 52341 443\r\n

7.2 字段来源

字段	来源
`203.0.113.10`	TOA → 内核 → HAProxy src
`52341`	TOA → src_port
`10.0.0.10`	原始目的地址
`443`	原始目的端口

7.3 特点

纯 ASCII
易抓包
无扩展能力

8. send-proxy-v2：二进制结构（推荐）

8.1 固定结构

[12B magic]
[1B ver/cmd]
[1B fam/proto]
[2B length]
[ADDR block]

magic 固定为：

0d 0a 0d 0a 00 0d 0a 51 55 49 54 0a

8.2 Client IP 在哪里（关键）

仅存在于 ADDR block：

字段	值
SRC_ADDR	HAProxy src（来自 TOA）
SRC_PORT	HAProxy src_port
DST_ADDR	原始目的地址
DST_PORT	原始目的端口

8.3 报文级结论

Client IP：✔
TLS 状态：✘
性能与扩展性：✔✔

9. send-proxy-v2-ssl：在 v2 基础上增加 TLV

9.1 报文结构

[ PROXY v2 fixed header ]
[ ADDR block ]
[ TLV block ]   ← 仅 v2-ssl 存在

⚠️ ADDR block 与 send-proxy-v2 完全一致

9.2 SSL TLV 内容

TLV 结构：

[Type][Length][Value]

SSL TLV（Type = 0x20）内部子 TLV：

子 TLV	含义
SSL_VERSION	TLS 版本
SSL_CIPHER	加密套件
SSL_VERIFY	客户端证书校验结果
SSL_CN	客户端证书 CN（mTLS）

9.3 关键事实（必须明确）

SSL TLV 不包含 Client IP
不参与 TLS 握手
只是描述“前端 TLS 状态”

Client IP 的传递路径在 v2 与 v2-ssl 中 100% 相同

10. send-proxy-v2-ssl 的 SSL TLV 作用（工程级补充）

10.1 先给出最关键的工程结论（不可混淆）

SSL TLV 的唯一目的不是传递 Client IP，而是把“前端 TLS 连接状态/元信息”传给后端，让后端可以基于真实 TLS 信息做策略、审计、鉴权、日志等。

send-proxy-v2-ssl 只是 v2 的扩展：它在 PROXY v2 之后附加 TLV block，提供“前端 TLS 状态”的可选元信息。
这些元信息在 v2 与 v2-ssl 中的 Client IP 传递链路完全一致。

10.2 SSL TLV 的工程价值是什么？

10.2.1 解决的问题

在 LVS → HAProxy → 后端架构中，后端拿到的 TLS 连接是与 HAProxy 建立的（而非与真实 Client 建立），因此后端无法直接获得：

TLS 版本（TLS1.2/1.3）
使用的加密套件（Cipher）
mTLS 客户端证书信息（CN、验证结果）
是否通过客户端证书校验（verify result）
前端 TLS 的握手成功/失败信息

这些信息在一些场景非常关键，例如：

安全审计与合规：记录真实客户端使用的 TLS 版本、Cipher，判断是否使用弱加密或不合规协议。
mTLS 终端应用鉴权：后端业务需要根据客户端证书 CN 进行授权（例如按组织/租户分流）。
策略路由/灰度：基于 TLS 版本或加密套件做流量分级或强制升级。
日志统一：统一记录“真实客户端 TLS 信息”，而不是只记录 HAProxy 与后端之间的 TLS 信息（如果存在）。

这些场景中，send-proxy-v2-ssl 的 TLV 是唯一可行的“跨层传递 TLS 元信息”的方式。

10.3 SSL TLV 传递的内容与含义（工程语义）

字段	含义	典型用途
SSL_VERSION	前端 TLS 版本	审计/策略/兼容性检查
SSL_CIPHER	前端加密套件	安全审计/弱密码检测
SSL_VERIFY	客户端证书校验结果	mTLS 认证结果
SSL_CN	客户端证书 CN	基于证书的鉴权/分流

10.4 关键点（工程级必须明确）

SSL TLV 不参与 TLS 握手
它只是“描述性数据”，由 HAProxy 在 TLS 握手完成后生成并发送给后端。
SSL TLV 不影响 TCP/SSL 的建立
只影响后端能否获得“前端 TLS 元信息”。
SSL TLV 只在 v2-ssl 下存在
send-proxy-v2 不包含任何 TLS 信息。

10.5 SSL TLV 在字节层面的“作用”是什么？

在字节级上，v2-ssl 的差异只是：

[ PROXY v2 fixed header ]
[ ADDR block ]
[ TLV block ]   ← SSL TLV（Type=0x20）附加

因此在“字节级行为”上，SSL TLV 的作用可概括为：

增加了一段可选的二进制 TLV 字节序列
该字节序列携带“前端 TLS 元信息”
后端解析后即可获得 TLS 信息，不需要与前端建立 TLS

它本质上是一个“TLS 元信息的旁路通道”，不是 TLS 数据本身。

10.6 后端如何利用 SSL TLV（典型实践）

10.6.1 Nginx 的获取方式（常见）

Nginx 支持解析 PROXY v2 + TLV（取决于版本/模块），常见做法：

listen 443 proxy_protocol;

并通过变量获取，例如：

$ssl_protocol（如果通过模块映射）
$ssl_cipher
$ssl_client_verify
$ssl_client_s_dn / $ssl_client_s_dn_cn

注意：不同版本 Nginx 处理 TLV 的方式不同，需要在生产环境中验证支持程度。

10.6.2 典型业务逻辑

审计：将 SSL_VERSION、SSL_CIPHER 写入日志
鉴权：根据 SSL_CN 或 verify result 决定是否允许访问
分流：基于 TLS 版本或 Cipher 将流量导向不同服务组

10.7 事故复盘角度的关键提示

如果出现以下现象：

后端日志里 TLS 信息不一致（或为 HAProxy 与后端之间的 TLS）
后端无法区分 mTLS 客户端身份
审计日志缺少真实 TLS 版本/套件

则应检查：

HAProxy 是否启用了 send-proxy-v2-ssl
后端是否正确解析 TLV（版本/模块/配置）
HAProxy 是否确实做了 TLS 终端（否则 SSL TLV 为空或不正确）

11. Client IP 的完整字段级传递链路

阶段	Client IP 存在形式
TCP Option	TOA.client_ip
内核 socket	`sk->sk_rcv_saddr`
HAProxy	`src` / `%ci`
send-proxy	PROXY v1 `SRC_ADDR`
send-proxy-v2	PROXY v2 `SRC_ADDR`
send-proxy-v2-ssl	PROXY v2 `SRC_ADDR` + SSL TLV
Nginx	`$remote_addr`

12. 后端（Nginx）如何恢复 Client IP

12.1 配置

listen 443 proxy_protocol;

12.2 行为

解析 PROXY header
将 SRC_ADDR 赋值给 $remote_addr

13. Nginx 能否处理 HAProxy 传递的 send-proxy*？配置差异是什么？

13.1 结论先行（可直接用于架构决策）

HAProxy send-proxy*	Nginx 是否支持	需要的配置	说明
send-proxy (v1)	支持	`proxy_protocol`	仅解析 PROXY v1 文本头
send-proxy-v2	支持	`proxy_protocol`	解析 PROXY v2 二进制头
send-proxy-v2-ssl	支持但有条件	`proxy_protocol` + 需要 Nginx 版本/模块支持 TLV	v2-ssl 在 PROXY v2 基础上附加 TLV，Nginx 必须支持 TLV 才能读取 SSL 元信息；否则只解析 ADDR block，忽略 TLV。

重点：Nginx 对 PROXY v2 是支持的；对 v2-ssl 的 SSL TLV 解析能力取决于 Nginx 版本/模块。
但Client IP 的恢复在 v2 与 v2-ssl 中完全一致，不依赖 TLV。

13.2 Nginx 解析 PROXY protocol 的基本配置

13.2.1 必须启用 `proxy_protocol`

对于任何 PROXY protocol（v1 / v2 / v2-ssl），Nginx 的入口都是：

listen 443 proxy_protocol;

或（HTTP/2/HTTPS）：

listen 443 ssl proxy_protocol;

如果没有 proxy_protocol，Nginx 会把 PROXY header 当作业务数据，从而导致 TLS 握手/HTTP 解析失败（尤其在 TCP/TLS 模式）。

13.3 send-proxy（v1）在 Nginx 的处理

13.3.1 适配配置

listen 443 ssl proxy_protocol;

13.3.2 解析效果

Nginx 解析到 PROXY v1 文本头后，会：

将 SRC_ADDR 赋值给 $remote_addr
将 SRC_PORT 赋值给 $remote_port
后续业务获取到真实 Client IP

13.4 send-proxy-v2 在 Nginx 的处理

13.4.1 适配配置

同样：

listen 443 ssl proxy_protocol;

13.4.2 解析效果

Nginx 解析 PROXY v2 二进制头后，会：

将 ADDR block 中的 SRC_ADDR / SRC_PORT 赋值给 $remote_addr / $remote_port

13.5 send-proxy-v2-ssl 在 Nginx 的处理（关键差异）

13.5.1 解析 Client IP

Client IP 的解析与 v2 完全一致：

Nginx 只要支持 PROXY v2，就能恢复 $remote_addr

13.5.2 解析 SSL TLV（是否支持取决于 Nginx 版本/模块）

13.5.2.1 如果 Nginx 支持 TLV（推荐）

Nginx 能够读取：

SSL_VERSION
SSL_CIPHER
SSL_VERIFY
SSL_CN（mTLS）

并映射到对应变量（取决于 Nginx 版本/模块），例如：

$ssl_protocol
$ssl_cipher
$ssl_client_verify
$ssl_client_s_dn / $ssl_client_s_dn_cn

注意：这些变量的可用性依赖于 Nginx 的模块支持和版本（例如是否支持 proxy_protocol 的 TLV 扩展）。

13.5.2.2 如果 Nginx 不支持 TLV

Nginx 仍然可以解析 ADDR block，恢复 $remote_addr，但 会忽略 TLV block，因此无法获取 TLS 元信息。

13.6 配置差异总结（工程表格）

send-proxy* 类型	Nginx 配置	Client IP 是否可用	SSL 元信息是否可用
send-proxy	`listen ... proxy_protocol`	是	否
send-proxy-v2	`listen ... proxy_protocol`	是	否
send-proxy-v2-ssl	`listen ... proxy_protocol`	是	取决于 Nginx 是否支持 TLV