在 linux 中实现 nginx 请求头转发以透传微服务链路追踪 id，核心做法是在 nginx 配置文件中利用 $http_x_request_id 变量获取客户端传入的 id，并通过 proxy_set_header 指令将其传递给后端服务。如果客户端未提供该 id，nginx 应使用内置的 $request_id 生成一个新的唯一标识符，确保链路连续性。这样做能确保每个请求在整个调用链中拥有唯一的追踪上下文。
Nginx 如何获取并设置 X-Request-ID 请求头
Nginx 通过 $http_<header_name></header_name> 的命名规则自动提取 HTTP 请求头。对于 X-Request-ID，对应的变量是 $http_x_request_id。若该值为空，则回退到 $request_id。使用 proxy_set_header 可以覆盖或添加发送给上游服务器的头部。这种机制允许 Nginx 作为入口网关，无缝衔接前端与后端服务的追踪体系。
server {
listen 80;
server_name api.example.com;
location / {
# 如果客户端没传 X-Request-ID，则使用 Nginx 生成的 $request_id
set $my_request_id $http_x_request_id;
if ($my_request_id = "") {
set $my_request_id $request_id;
}
proxy_pass http://backend_service;
proxy_set_header X-Request-ID $my_request_id;
proxy_set_header Host $host;
}
}
如何处理跨域预检请求中的追踪 ID 透传
在处理跨域请求时，浏览器会先发送 OPTIONS 预检请求。此时后端可能尚未建立完整连接，但 Nginx 仍需处理这些请求以确保 CORS 策略生效。虽然预检请求通常不携带业务负载，但为了保持日志一致性，Nginx 依然可以对 OPTIONS 请求应用相同的 ID 透传逻辑。这有助于在访问日志中区分正常的业务请求和预检请求，便于排查跨域问题。
server {
listen 80;
server_name api.example.com;
location / {
# 统一设置追踪 ID
set $my_request_id $http_x_request_id;
if ($my_request_id = "") {
set $my_request_id $request_id;
}
# 处理 CORS 预检
if ($request_method = 'OPTIONS') {
add_header 'Access-Control-Allow-Origin' '*';
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
add_header 'Access-Control-Allow-Headers' 'X-Request-ID, Content-Type';
add_header 'Content-Length' 0;
return 204;
}
proxy_pass http://backend_service;
proxy_set_header X-Request-ID $my_request_id;
proxy_set_header Host $host;
}
}
基于 $request_id 生成的 UUID 格式验证
Nginx 内置的 $request_id 变量默认生成符合 RFC 4122 标准的 v4 UUID 字符串。当客户端未提供 X-Request-ID 时，Nginx 会自动生成一个类似 5c7b8d9e-1a2b-4c3d-8e9f-0a1b2c3d4e5f 格式的 ID。开发者可以通过查看 Nginx 访问日志中的 $request_id 字段来验证这一行为。确保后端服务能够正确解析这种标准 UUID 格式，是实现链路追踪兼容性的关键。
