proxy_set_header 是 nginx 反向代理中用于设置发往后端请求头的指令，需置于 location 或 server 块内，支持传递真实 ip（x-real-ip、x-forwarded-for）、协议（x-forwarded-proto）、自定义业务头等，并可删除头或使用变量，但仅作用于 upstream 请求且以最内层配置为准。
在 Nginx 中，proxy_set_header 是反向代理场景下控制上游请求头的关键指令，它允许你添加、修改或覆盖发往后端服务的 HTTP 请求头。正确使用它，能解决鉴权传递、客户端真实信息透传、调试标识注入等常见需求。
基本语法与生效位置
proxy_set_header 必须写在 location 或 server 块中，且仅对启用代理的请求（如用了 proxy_pass）生效。每条指令定义一个请求头名和值，格式为：
proxy_set_header Header-Name value;
注意：Nginx 默认会清除部分原始请求头（如 Connection、Keep-Alive），并自动设置 Host 和 Content-Length；若显式设置这些头，会覆盖默认行为。
传递客户端真实信息
后端常需知道用户真实 IP 和协议类型，但经 Nginx 代理后，Remote-Addr 变成 Nginx 自身 IP。可通过以下方式补全：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
-
proxy_set_header X-Real-IP $remote_addr;—— 传递最外层客户端 IP（适用于无多级代理） -
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;—— 追加 IP 到已有的X-Forwarded-For头，支持链式代理 -
proxy_set_header X-Forwarded-Proto $scheme;—— 传递http或https，便于后端生成正确跳转链接
注入自定义业务头
可用于灰度路由、内部追踪、租户识别等场景。例如：
-
proxy_set_header X-Env "prod";—— 标明当前是生产环境 -
proxy_set_header X-Request-ID $request_id;—— 使用 Nginx 内置变量传递唯一请求 ID（需先启用ngx_http_random_index_module或用map定义$request_id） -
proxy_set_header Authorization "Bearer xyz123";—— 向后端透传固定令牌（慎用，避免泄露敏感凭据）
值中可使用变量（如 $arg_token 获取 URL 参数）、字符串或空格分隔的组合，但不能包含换行或未转义的双引号。
注意事项与常见陷阱
容易出错的地方往往不在语法，而在上下文逻辑：
- 该指令不会影响 Nginx 自身接收的请求头，只作用于发给 upstream 的请求
- 如果在多个嵌套块中重复设置同一 header，**以最内层 location 的定义为准**
- 设为空字符串（
proxy_set_header X-Custom "";）会**删除**该头，而非发送空值 - 若后端是 gRPC 服务，需额外配置
grpc_set_header，普通proxy_set_header对其无效
