Nginx 通过 $request_id 变量生成并透传唯一请求 ID，需 Nginx ≥1.11.0，在 proxy_set_header 中使用 $request_id 可自动创建 UUID，配合 log_format 记录日志，并优先信任客户端传入的 X-Request-ID 以保证重试一致性。
在 Nginx 中为代理请求设置唯一标识 ID，核心是利用 $request_id 变量（需启用 ngx_http_core_module，Nginx 1.11.0+ 默认内置），并将其透传给后端服务，便于全链路日志追踪与问题定位。
启用并生成 request_id
Nginx 本身不自动创建 $request_id，但支持通过 map 指令配合 $binary_remote_addr、$time_iso8601 等变量构造，更推荐直接使用内置的 random 模块或第三方模块。不过最稳妥、原生支持的方式是：
- 确保 Nginx ≥ 1.11.0（推荐 ≥ 1.19.0）；
- 在
http块中定义：map $request_id $req_id { default $request_id; "" $request_id; }
（该 map 实际是“兜底”，真正触发生成靠后续的proxy_set_header使用）； - 实际生效的关键操作：在
location或server块中使用proxy_set_header X-Request-ID $request_id;—— 此时若$request_id为空，Nginx 会自动生成一个 UUID 格式的值（如2a4e7c9d-1b3f-4e8a-9c1f-5a6b7c8d9e0f）。
透传 ID 到上游服务
仅生成还不够，必须让后端能收到这个 ID：
- 在代理配置中添加：
proxy_set_header X-Request-ID $request_id; - 如后端也遵循 OpenTracing 或需要统一字段，可同步设置：
proxy_set_header X-Correlation-ID $request_id; - 若需记录到 Nginx 访问日志以便关联排查，修改 log_format：
log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$request_id"';
并在access_log中引用该格式。
保持 ID 在重试/子请求中一致
默认情况下，Nginx 在 upstream 重试或内部子请求（如 auth_request）中会生成新的 $request_id，导致 ID 不一致。解决方法：
- 用
map提前捕获初始 ID（适用于简单场景）：map $http_x_request_id $req_id_for_upstream { ~. $http_x_request_id; default $request_id; }
然后在 proxy 段用$req_id_for_upstream替代$request_id； - 更可靠的做法：客户端首次发起请求时带上
X-Request-ID，Nginx 优先信任它：proxy_set_header X-Request-ID $http_x_request_id;
这样即使重试，只要客户端没换 ID，上游看到的就是同一个。
验证是否生效
快速确认配置是否起作用：
- 重启 Nginx 后，用 curl 发起请求：
curl -H "X-Request-ID: abc123" http://your-domain/api/test - 检查后端日志或响应头，确认收到
X-Request-ID: abc123； - 不带 header 再试一次，观察后端是否收到类似
9f3a2b1c-...的自动生成值； - 查 Nginx access.log，确认每行末尾有非空的 request_id 字段。
