X-Forwarded-For链路追踪需每级代理继承并追加IP，格式为“客户端IP,一级代理IP,...”，Nginx须用"$http_x_forwarded_for, $remote_addr"避免覆盖，后端依可信代理列表逆序剔除后取真实IP，并结合日志与监控实现全链路可观测。
通过 proxy_set_header X-Forwarded-For 实现请求链路追踪，核心不是简单地覆盖或添加一个 IP，而是**在每一级代理中正确继承并追加客户端真实 IP 和沿途代理节点信息**，从而构建可回溯的完整路径。关键在于理解其行为逻辑、避免常见污染，并配合日志与后端协同解析。
理解 X-Forwarded-For 的标准格式与追加规则
X-Forwarded-For 是一个由逗号分隔的 IP 列表，格式为：
客户端真实IP, 一级代理IP, 二级代理IP, ...
Nginx 默认行为是：若上游未设置该头，它会用 $remote_addr（即直连它的客户端 IP）作为第一个值；若上游已带该头，Nginx 不会自动追加，除非你显式用 proxy_set_header X-Forwarded-For "$http_x_forwarded_for, $remote_addr" —— 这才是构建链路的关键操作。
- 错误写法：
proxy_set_header X-Forwarded-For $remote_addr→ 每层都覆盖，只留最后一跳，链路断裂 - 正确写法：
proxy_set_header X-Forwarded-For "$http_x_forwarded_for, $remote_addr"→ 继承上游 + 追加自己 - 首次入口（如最外层 CDN 或负载均衡）若无上游，需确保它设了初始值（如
$remote_addr），否则整个链路开头为空
多级代理场景下的配置要点
假设请求路径为：用户 → CDN → Nginx LB → 应用网关 → 后端服务，每层都需严格遵循“继承+追加”原则：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- CDN 层（如 Cloudflare）：默认已设
X-Forwarded-For为用户真实 IP，无需额外配置（但需确认开启） - Nginx LB 层：配置
proxy_set_header X-Forwarded-For "$http_x_forwarded_for, $remote_addr"，且确保$http_x_forwarded_for可读（不被清空） - 应用网关（如另一台 Nginx 或 Envoy）：同样使用继承+追加，不可用
$remote_addr单独覆盖 - 特别注意：所有中间层必须禁用
underscores_in_headers on等可能导致 header 被丢弃的配置
后端服务如何安全、准确提取原始客户端 IP
仅靠 X-Forwarded-For 列表还不够——你得知道哪一节可信。不能直接取第一个，因为可能被伪造；也不能盲目取最后一个，那是最近一跳的 IP。
- 定义可信代理列表（如 CDN IP 段、LB 内网地址），在后端代码中按逆序从右往左剔除可信跳数
- 例如：XFF =
"203.0.113.5, 192.0.2.10, 10.1.1.100"，若你信任最后两个 IP（192.0.2.10和10.1.1.100）是内部代理，则客户端真实 IP 是203.0.113.5 - 推荐用成熟库处理（如 Python 的
django.utils.http.get_client_ip、Go 的realip.FromHeaders），它们内置可信段校验逻辑 - 同时记录完整 XFF 字符串到访问日志，用于审计和问题排查
配合日志与监控完善链路可视化
仅有 header 不等于可观测。要真正实现“追踪”，需打通日志上下文：
- 在 Nginx access_log 中加入
$http_x_forwarded_for变量，例如：log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$http_x_forwarded_for"'; - 后端服务将解析出的原始 IP、全部 XFF 值、自身服务名、请求 ID 打入结构化日志（如 JSON）
- 用 ELK 或 Loki 聚合各层日志，通过请求 ID 或客户端 IP 关联多跳记录
- 对异常链路（如 XFF 长度突增、出现私有 IP 在非预期位置）设置告警
