核心在于有来源、有命名、有范围、有校验地安全透传可信上下文：需从客户端头、域名/路径或参数动态取值，规范命名（短横线优先或启用underscores_in_headers），按location显式声明透传范围，敏感字段脱敏，并由后端主动读取校验。

`proxy_set_header` 透传元数据，核心不是简单复制头，而是**有来源、有命名、有范围、有校验地把可信上下文安全送给后端**。它不自动识别或过滤，所有逻辑都要你显式定义。

从哪儿取值：必须动态、可溯源

写死的值只适合全站统一场景（比如固定灰度标签），多数业务需要从请求中提取变量：

• 客户端自带头：如 proxy_set_header X-Tenant-ID $http_x_tenant_id; —— 直接取前端已携带的租户标识
• 域名/路径映射：用 map 指令归一化，例如根据 $host 区分环境：
  

  map $host $env_tag {<br>  ~^staging\.example\.com$ "staging";<br>  ~^prod\.example\.com$ "prod";<br>}

  
  再在 location 中：proxy_set_header X-Env $env_tag;
• 请求参数：支持简单 query 参数，如 proxy_set_header X-Trace-ID $arg_trace_id;（注意：纯 Nginx 不解析 cookie 或复杂 body）

怎么命名与传递：避免被静默丢弃

名字不对，header 就传不到后端：

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

• 推荐用短横线命名（如 X-User-ID），天然兼容，无需额外配置
• 若必须用下划线（如 X_User_ID），需在 http 或 server 块中启用：underscores_in_headers on;，且确认上级没设为 off
• 不要依赖 proxy_pass_request_headers on —— 它会把所有原始头都传过去，容易污染或越权；始终显式声明要透传的头

控制透传边界：按路径或租户隔离

一个 header 配错，可能让 A 租户的数据跑到 B 租户的服务里：

• 在具体 location 块中设置，而不是写在 http 全局块 —— 变量如 $scheme、$host 在全局无效
• 多租户场景建议按路径分流，例如：location /t/abc/ { proxy_set_header X-Tenant-ID "abc"; }
• 敏感字段脱敏后再传，比如用哈希代替明文用户 ID：proxy_set_header X-User-Key $user_key_hash;（需提前用 map 或 env 设置好该变量）

后端必须主动读取并信任

Nginx 只负责“递话”，后端不接、不验、不认，元数据就等于没传：

• Spring Boot：配置 server.forward-headers-strategy=framework，代码中调用 request.getHeader("X-Tenant-ID")
• Node.js（Express）：设置 app.set('trust proxy', true)，再用 req.get('X-Tenant-ID')
• Django：设 SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')，并启用 USE_X_FORWARDED_HOST = True