Nginx通过proxy_set_header透传X-B3-*等追踪头实现链路追踪ID向下传递，需识别上游头并标准化（如map映射），同时确保下游服务SDK正确解析；无上游trace-id时可用$request_id作fallback。
要在 Nginx 中通过 proxy_pass 实现分布式链路追踪 ID（如 trace-id、span-id、parent-id）的向下传递，核心是：**识别上游传入的追踪头，并原样或标准化后透传给下游服务**。Nginx 本身不生成或解析链路 ID，但可作为“透明搬运工”确保上下文不丢失。
识别并透传标准追踪请求头
主流链路追踪系统（如 Jaeger、Zipkin、SkyWalking）通常使用如下 HTTP 头传递上下文：
-
trace-id或X-B3-TraceId（Zipkin） -
span-id或X-B3-SpanId -
parent-id或X-B3-ParentSpanId -
sampled或X-B3-Sampled（是否采样） -
flags或X-B3-Flags（调试标记）
在 location 或 server 块中，用 proxy_set_header 显式转发这些头：
location /api/ {
proxy_pass http://backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
<pre class="brush:php;toolbar:false;"># 透传 Zipkin 标准头（推荐，兼容性好）
proxy_set_header X-B3-TraceId $http_x_b3_traceid;
proxy_set_header X-B3-SpanId $http_x_b3_spanid;
proxy_set_header X-B3-ParentSpanId $http_x_b3_parentspanid;
proxy_set_header X-B3-Sampled $http_x_b3_sampled;
proxy_set_header X-B3-Flags $http_x_b3_flags;
# 同时兼容 SkyWalking 的 SW8 头（可选）
proxy_set_header sw8 $http_sw8;}
处理大小写与头名标准化
HTTP 头名在传输中不区分大小写，但 Nginx 变量 $http_* 默认转为小写（如 X-B3-TraceId → $http_x_b3_traceid）。若上游用驼峰（TraceId）或下划线（trace_id），需统一映射：
- 用
map指令预定义兼容映射（推荐，避免重复判断） - 或直接在
proxy_set_header中多写几行，覆盖常见变体
示例（在 http 块中）：
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
map $http_trace_id $trace_id {
"" $http_x_b3_traceid;
default $http_trace_id;
}
map $http_x_trace_id $trace_id {
"" $trace_id;
default $http_x_trace_id;
}
<h1>然后在 location 中使用</h1><p>proxy_set_header X-B3-TraceId $trace_id;确保下游服务能接收并使用这些头
Nginx 透传只是第一步。下游服务（如 Spring Cloud、Go Gin、Node.js Express）需配置对应 SDK 主动读取这些头并注入到当前 span 中：
- Spring Boot + Sleuth/Brave：默认支持
X-B3-*和trace-id等头 - Java Agent（SkyWalking）：需开启
ignore_suffix避免拦截 Nginx 转发头 - 自研服务：检查是否从
X-B3-TraceId或trace-id字段读取，而非只认某一种
⚠️ 注意：若下游服务未正确初始化 trace context，即使头传过去了，也不会形成完整链路。
可选：Nginx 自动注入 trace-id（仅限无上游 trace 时）
若入口请求无 trace-id（如浏览器直连），且你希望 Nginx 自动生成一个用于链路起始，可用 ngx_http_random_index_module 不适用，应改用 lua-resty-random 或更简单方式：
- 用
set_by_lua_block（需启用 lua 模块）生成 UUID 或时间戳+随机数 - 或用
map+$request_id（Nginx 内置唯一 ID，格式类似1234567890abcdef1234567890abcdef）作为 fallback trace-id
示例（fallback 方案）：
map $http_x_b3_traceid $pass_trace_id {
"" $request_id; # 无上游 trace-id 时用 request_id 替代
default $http_x_b3_traceid;
}
proxy_set_header X-B3-TraceId $pass_trace_id;注意：$request_id 并非标准 trace-id 格式（如 32 位 hex），部分 SDK 可能拒绝解析，建议仅作调试或内部链路使用。
