proxy_set_header 是修复代理链路信息失真的关键控制点，通过透传 x-real-ip、x-forwarded-for、host、x-forwarded-proto 等头，确保后端获取真实客户端ip、原始域名、协议等信息，避免重定向错误、cors拦截、https跳转失败等问题。
proxy_set_header 不是“增强性能”的开关，而是修复代理链路信息失真的关键控制点。它让后端真正看清谁在访问、从哪来、用什么协议、走的哪个域名——这些信息一旦错位，就会引发重定向错误、IP日志混乱、HTTPS跳转失败、CORS拦截等看似随机实则可预测的问题。
确保后端拿到真实的客户端身份
默认情况下，后端看到的 IP 往往是 Nginx 本机（127.0.0.1）或上一级代理节点，无法做风控、限流或地域分析。正确透传需组合使用：
- X-Real-IP $remote_addr：直接传递最外层真实客户端 IP（单层代理适用）
- X-Forwarded-For $proxy_add_x_forwarded_for：自动拼接已有 X-Forwarded-For 值 + 当前客户端 IP，支持多级代理链（如 CDN → Nginx → 后端）
- 避免写成
X-Forwarded-For $remote_addr：会覆盖上游已有的 IP 链，丢失中间代理信息
让后端生成正确的跳转与资源链接
后端框架（如 Spring Boot、Django、Express）常根据 Host 和协议头拼接绝对 URL。若 Nginx 不修正，就会返回 http://localhost:8080/login 这类内部地址，导致浏览器拒绝加载或混合内容报错：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- Host $host：把用户请求的原始域名（如 app.example.com）传给后端，而非 proxy_pass 目标地址
- X-Forwarded-Proto $scheme：告诉后端原始请求是 http 还是 https，避免生成 http 跳转链接
- X-Forwarded-Host $host 和 X-Forwarded-Port $server_port：辅助后端还原完整请求入口
支撑 WebSocket 与跨域等协议级功能
某些协议升级和安全校验依赖特定请求头，Nginx 默认不转发，必须显式声明：
- Upgrade $http_upgrade：透传 Upgrade 头（值为 websocket），触发后端协议切换
- Connection "upgrade"：固定值，配合 Upgrade 头完成 WebSocket 握手
-
Origin $http_origin：原样传递 Origin，供后端做 CORS 白名单校验；若需强制改写（如统一代理到测试环境），可用
Origin "https://test-api.example.com"
规避常见配置陷阱
proxy_set_header 行为受作用域和继承规则影响，容易因疏忽引入隐性故障：
- 指令在 location 中定义时，会覆盖 server 或 http 块中的同名设置——建议统一放在 location 内，避免跨层级冲突
- 字符串值必须加引号（如
"upgrade"），否则含空格或特殊字符会解析失败 - 不要遗漏
proxy_set_header Host $host：这是多数重定向问题的根源，也是最容易被忽略的一行 - 禁用不必要的头（如
User-Agent ""）可减少信息泄露，但需确认后端不依赖该字段
