proxy_pass 是 Nginx 反向代理核心指令，末尾斜杠决定路径拼接规则：无斜杠保留完整 URI，有斜杠则剥离 location 前缀；需配合 Host、X-Real-IP、X-Forwarded-Proto 等 header 透传，并可拦截 OPTIONS 预检请求返回 CORS 头。
proxy_pass 是 Nginx 实现反向代理最核心的指令，它决定请求最终被转发到哪个后端服务。配置是否正确，直接影响接口可达性、路径行为、跨域处理和负载均衡效果。
proxy_pass 的基本写法与路径映射逻辑
关键在于末尾斜杠（/）的存在与否，会触发完全不同的路径拼接规则：
-
不带尾部斜杠：如
proxy_pass http://127.0.0.1:8080;，Nginx 将完整保留原始请求 URI 并追加到目标地址后。例如请求/api/v1/user，实际转发为http://127.0.0.1:8080/api/v1/user。 -
带尾部斜杠：如
proxy_pass http://127.0.0.1:8080/;，Nginx 会先截掉 location 匹配的部分，再拼接到目标地址。例如location /api/ { proxy_pass http://127.0.0.1:8080/; }，请求/api/v1/user将转发为http://127.0.0.1:8080/v1/user。
常见代理场景下的典型配置
针对不同部署结构，需匹配对应写法：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- 后端服务根路径即 API 入口（如 Spring Boot 默认）：用
proxy_pass http://backend:8080/;+location /api/，实现路径剥离。 - 后端已自带统一前缀（如
/v1/），前端也按此调用：可直接proxy_pass http://backend:8080;，不做路径改写。 - 需代理多个子路径且指向不同服务：配合多个
location块，分别定义proxy_pass，注意避免正则 location 中使用变量导致缓存失效问题。
必须配套的代理头设置
仅靠 proxy_pass 不足以让后端正确识别原始请求信息。以下 header 设置几乎总是必需：
-
proxy_set_header Host $host;：透传原始 Host，避免后端因 Host 错误返回 404 或重定向异常。 -
proxy_set_header X-Real-IP $remote_addr;和X-Forwarded-For $proxy_add_x_forwarded_for;：传递真实客户端 IP，供日志或限流使用。 -
proxy_set_header X-Forwarded-Proto $scheme;：标识原始协议（http/https），影响后端生成跳转链接的 scheme。 - 若后端依赖 Referer 或 User-Agent 做校验，也建议显式透传：
proxy_set_header Referer $http_referer;
处理跨域预检（OPTIONS）请求
当浏览器发起跨域请求时，会先发一个 OPTIONS 预检。若后端未处理，Nginx 可在 location 中拦截并响应：
- 添加
if ($request_method = 'OPTIONS') { add_header Access-Control-Allow-Origin '*'; add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS'; add_header Access-Control-Allow-Headers 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization'; add_header Access-Control-Max-Age 1728000; add_header Content-Type 'text/plain; charset=utf-8'; add_header Content-Length 0; return 204; } - 注意：该写法需放在
proxy_pass之前，且不要与 rewrite 指令混用，否则可能被跳过。
