nginx反向代理中proxy_set_header是控制请求头转发的关键指令，必须显式配置host、x-real-ip、x-forwarded-for三项基础头以确保后端正确识别客户端ip、协议和域名；还需补充x-forwarded-proto等头支持https终止场景，并通过$变量透传自定义头，未显式声明的头默认被丢弃。

proxy_set_header 是 Nginx 反向代理中控制请求头转发行为的关键指令，它决定客户端原始请求头如何被修改或补充后发往后端服务器。配置不当会导致后端服务无法正确识别真实客户端 IP、协议类型或 Host 信息，进而引发登录异常、重定向错误、HTTPS 混合内容等问题。

必须设置的三项基础头字段

默认情况下，Nginx 会覆盖或丢弃部分原始请求头。为保障后端服务正常运行，以下三项通常需显式配置：

• Host：用 proxy_set_header Host $host; 或更稳妥的 proxy_set_header Host $http_host;，确保后端收到与客户端请求一致的 Host 值（含端口），避免因 Host 缺失导致 404 或路由错乱；
• X-Real-IP：用 proxy_set_header X-Real-IP $remote_addr;，将客户端真实 IP 传递给后端，供日志记录或访问控制使用；
• X-Forwarded-For：用 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;，该变量自动追加客户端 IP 到已有的 X-Forwarded-For 链中（若上游已有值），适合多层代理场景。

HTTPS 和协议感知相关头

当 Nginx 终止 HTTPS 并以 HTTP 转发至后端时，后端可能误判请求为非安全连接，需主动告知真实协议：

CPA Update - Secure CLI Proxy API Maintenance

安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

下载

• proxy_set_header X-Forwarded-Proto $scheme; —— 传递原始请求协议（http 或 https），后端据此生成正确跳转链接；
• proxy_set_header X-Forwarded-Port $server_port; —— 显式传递原始端口（如 443），尤其在非标准端口部署时有用；
• 若后端依赖 HTTPS=on 环境变量判断协议，可配合 fastcgi_param HTTPS on;（FastCGI）或应用层逻辑适配，但更推荐统一使用 X-Forwarded-* 头。

哪些头会被自动清除？如何保留自定义头？

Nginx 默认不转发以下头字段：Connection、Keep-Alive、Proxy-Authenticate、Proxy-Authorization、Te、Trailers、Upgrade、Content-Encoding（除非启用 gzip off）。若需透传特定头（如认证 Token、内部标识），必须显式设置：

• proxy_set_header Authorization $http_authorization; —— 注意变量名格式为 $http_*，下划线替换横线，全小写；
• proxy_set_header X-Request-ID $request_id; —— 需先启用 ngx_http_realip_module 或通过 map 定义变量；
• 未显式声明的自定义头一律被丢弃，不可依赖“默认透传”。

location 块内配置优先级与作用域

proxy_set_header 支持在 http、server、location 任意层级使用，遵循就近覆盖原则：

• 全局设置写在 http 块中，作为默认值；
• 某类接口（如 API）需额外头，可在对应 location /api/ 中追加或覆盖；
• WebSocket 代理需特别添加：proxy_set_header Upgrade $http_upgrade; 和 proxy_set_header Connection "upgrade";，否则连接无法升级；
• 重复设置同一名字的头，以最后出现的为准，不会合并。