Nginx反向代理时自定义请求头为何在后端服务中丢失？

Question

在Nginx反向代理场景中，常遇到自定义请求头（如 `X-Request-ID`、`X-User-Token`）在后端服务（如Spring Boot、Node.js）中不可见的问题。根本原因在于：**Nginx默认会忽略下划线（`_`）命名的请求头**（为防止与内部变量冲突，受 `underscores_in_headers off` 默认配置限制），且对含特殊字符或非标准名称的头字段可能直接丢弃；此外，若未显式使用 `proxy_set_header` 指令重传，Nginx不会自动透传原始请求头（仅传递部分安全白名单头，如 `Host`、`Connection` 等）；最后，若后端服务运行在Tomcat等容器中，还需确认其是否启用 `relaxedQueryChars`/`relaxedPathChars` 或禁用 `rejectIllegalHeader` 以兼容非常规头名。排查需三步：检查Nginx配置中 `underscores_in_headers on`、`proxy_set_header` 是否覆盖目标头、后端框架日志是否接收原始头字段。

Answer 1

```html

一、现象层：自定义请求头“消失”的典型表现

运维或开发人员常观察到：前端通过 X-Request-ID: abc123 或 X-User-Token: eyJhbGciOi... 发起请求，Nginx 日志（$http_x_request_id）可正常记录，但 Spring Boot 的 @RequestHeader("X-Request-ID") 返回 null，Node.js 的 req.headers['x-request-id'] 为 undefined。此非网络丢包，亦非客户端未发送，而是请求头在代理链中被静默过滤。

二、配置层：Nginx 的三大隐式拦截机制

• 下划线屏蔽机制：Nginx 默认启用 underscores_in_headers off，所有含 _ 的 Header（如 X_User_ID）被直接忽略——这是最易被忽视的“默认安全策略”；
• 透传白名单机制：Nginx 不会自动转发原始请求头，仅透传有限安全头（Host, Connection, User-Agent 等），其余需显式声明；
• 大小写归一化陷阱：Nginx 内部将 Header 名转为小写存储，若后端严格匹配 X-Request-ID（带连字符大写），而 Nginx 透传为 x-request-id，部分旧版框架解析失败。

三、协议层：HTTP/1.1 头字段合规性与容器兼容性

组件	关键配置项	影响范围	推荐值
Tomcat 9+	rejectIllegalHeader=false	拒绝含下划线/空格/控制字符的 Header	true → false
Spring Boot 3.x	server.tomcat.relaxed-query-chars=_	扩展允许字符集（默认不含 _）	显式追加 _
Node.js (Express)	app.set('trust proxy', true)	启用 X-Forwarded-* 解析，但不影响自定义头	必须配合 proxy_set_header

四、诊断层：三步精准定位法（附验证命令）

1. 查 Nginx 配置：
   grep -n "underscores_in_headers\|proxy_set_header.*X-" /etc/nginx/conf.d/*.conf
   确认存在 underscores_in_headers on; 且每条 location 块含：
   proxy_set_header X-Request-ID $http_x_request_id;
2. 抓包比对：在 Nginx 入口侧（tcpdump -i lo port 80）与后端服务入口侧（tcpdump -i lo port 8080）分别捕获，用 Wireshark 比对 HTTP 头字段完整性；
3. 后端日志埋点：Spring Boot 中添加 @EventListener 监听 RequestHandledEvent，打印 request.getHeaderNames() 全量枚举；Node.js 使用 console.log(Object.keys(req.headers))。

五、解决层：生产环境黄金配置模板

upstream backend {
    server 127.0.0.1:8080;
}

server {
    listen 80;
    underscores_in_headers on;  # ✅ 关键：启用下划线支持

    location / {
        proxy_pass http://backend;

        # ✅ 显式透传标准与自定义头（注意变量名大小写）
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Request-ID $http_x_request_id;
        proxy_set_header X-User-Token $http_x_user_token;

        # ✅ 强制保留原始大小写（Nginx 1.19.4+ 支持）
        proxy_pass_request_headers on;
    }
}

六、进阶层：自动化检测与可观测性增强

graph LR
A[客户端发起请求] --> B{Nginx 接收}
B --> C[检查 underscores_in_headers]
C -->|off| D[丢弃含_的Header]
C -->|on| E[进入Header处理链]
E --> F[proxy_set_header 是否覆盖?]
F -->|否| G[使用$http_x_foo变量透传]
F -->|是| H[按指令值赋值]
H --> I[转发至后端]
I --> J[后端容器校验rejectIllegalHeader]
J -->|true| K[拒绝非法Header]
J -->|false| L[成功注入Servlet/Express上下文]

七、避坑层：高频错误模式清单

• ❌ 在 http{} 块设 underscores_in_headers on，却在 server{} 块未继承（该指令不继承，须在 server 或 location 级重申）；
• ❌ 使用 $sent_http_x_request_id（响应头变量）替代 $http_x_request_id（请求头变量）；
• ❌ Spring Boot 中误用 @RequestHeader(value = "x-request-id", required = false) 但未开启 spring.mvc.ignore-default-model-on-redirect=true 导致 header 被框架过滤；
• ❌ Nginx reload 成功但未验证 worker 进程是否已加载新配置（nginx -t && kill -HUP $(cat /var/run/nginx.pid)）。

八、演进层：云原生场景下的替代方案

在 Service Mesh（如 Istio）中，可通过 EnvoyFilter 统一注入/透传 Header，规避 Nginx 配置碎片化；Kubernetes Ingress Controller（如 NGINX Ingress）支持 configuration-snippet 注入 underscores_in_headers on，实现声明式治理。对于 Serverless 场景（AWS ALB + Lambda），需依赖 ALB 的 custom request headers 白名单机制，而非 Nginx。

```