Web 服务器与网关 / 系统课时
传递请求追踪标识
传递请求追踪标识
本课学习如何在 Nginx 网关层生成、复用并传递请求追踪标识,使客户端请求能够与后端服务日志建立关联。完成配置后,可以通过一个 ID 快速检索同一次请求经过的完整链路。
学习目标
- 理解请求追踪标识在网关中的作用。
- 配置 Nginx 生成或转发请求 ID。
- 将请求 ID 同时写入上游请求、响应头和访问日志。
认识请求追踪标识流程
在微服务架构中,一个请求可能经过网关、多个业务服务和数据库访问层。如果每个组件只记录自己的日志,很难确认这些日志是否属于同一次请求。
请求追踪标识通常由入口网关创建。如果客户端已经提供合法标识,网关可以复用;如果没有,则生成新的唯一值,并通过请求头传递给后端。

配置请求 ID 传递
Nginx 可以使用 $request_id 变量生成唯一请求标识,并通过 proxy_set_header 传递给上游。
nginx
http {
log_format trace '$request_id $remote_addr $request_uri';
server {
listen <PORT>;
location /api/ {
proxy_set_header X-Request-ID $request_id;
add_header X-Request-ID $request_id always;
proxy_pass http://backend;
}
}
}预期结果
text
客户端响应头:
X-Request-ID: 7f2c8d4e8a9b
上游请求头:
X-Request-ID: 7f2c8d4e8a9b实际生成的 ID 会随请求变化,示例值仅用于说明传递关系。
复用客户端已有标识
部分系统由前端、API 网关或链路追踪组件提前生成 ID。此时需要避免无条件覆盖已有值,可以使用 map 判断是否存在请求头。
nginx
http {
map $http_x_request_id $trace_id {
default $http_x_request_id;
"" $request_id;
}
server {
location / {
proxy_set_header X-Request-ID $trace_id;
}
}
}预期结果
text
已有请求头:
X-Request-ID: client-id-001
转发结果:
X-Request-ID: client-id-001没有请求头时,Nginx 会使用自身生成的请求标识。
验证追踪链路
验证时应同时检查客户端响应、Nginx 访问日志和上游服务日志,确认同一个 ID 在多个位置保持一致。
bash
curl -i http://example.com/api/test预期结果
text
HTTP/1.1 200 OK
X-Request-ID: 7f2c8d4e8a9b如果响应没有返回标识,应检查 add_header 是否配置在正确上下文,以及请求是否经过目标 location。
按自己的节奏,确认真正理解。