proxy_pass 是 Nginx 实现反向代理的核心指令，其末尾斜杠决定路径重写方式：无斜杠则完整拼接路径，有斜杠则截去 location 匹配部分；必须配合 proxy_set_header 设置 Host、X-Real-IP 等请求头，并针对重定向、Cookie、WebSocket、大文件上传等场景做专项配置。
在 Nginx 的 server 块中配置 proxy_pass，是实现反向代理最核心的操作。它不只是一条转发指令，还牵涉到请求头重写、协议适配、路径映射等关键细节，稍有疏忽就可能导致 404、502 或后端服务无法识别原始路径。
proxy_pass 的基本写法与路径处理逻辑
proxy_pass 后面跟的 URL 地址决定了请求如何被重写并转发。重点在于末尾是否带斜杠（/）：
- 写成
proxy_pass http://127.0.0.1:8000;（无尾部/）：Nginx 会把匹配 location 的完整 URI 路径原样拼接到目标地址后。例如location /api/匹配到/api/user，则实际发给后端的是http://127.0.0.1:8000/api/user。 - 写成
proxy_pass http://127.0.0.1:8000/;（有尾部/）：Nginx 会把 location 中匹配的部分“截掉”，只转发剩余路径。例如location /api/+proxy_pass http://127.0.0.1:8000/;，对/api/user的请求，实际发往http://127.0.0.1:8000/user。
必须配合的请求头设置
后端服务通常依赖 Host、X-Real-IP、X-Forwarded-For 等头信息判断来源和路由。默认情况下 Nginx 不会透传这些字段，需显式配置：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
-
proxy_set_header Host $host;—— 保留原始 Host，避免后端因 Host 不匹配返回 404； -
proxy_set_header X-Real-IP $remote_addr;—— 让后端拿到真实客户端 IP； -
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;—— 支持多层代理时链式记录 IP； -
proxy_set_header X-Forwarded-Proto $scheme;—— 显式告知后端当前是 http 还是 https，对重定向逻辑很重要。
常见问题与对应修复点
很多 502 错误或静态资源加载失败，并非后端挂了，而是代理配置没对齐：
- 后端返回 302 重定向时跳转地址错误 → 检查是否设置了
proxy_redirect，例如proxy_redirect http://localhost:8000/ /;； - Cookie 的
Domain或Path不生效 → 加上proxy_cookie_domain和proxy_cookie_path修正； - WebSocket 连接被断开 → 必须添加
proxy_http_version 1.1;和proxy_set_header Upgrade $http_upgrade;、proxy_set_header Connection "upgrade";； - 大文件上传失败 → 需调大
client_max_body_size、proxy_buffering off;（视情况）、proxy_read_timeout等超时与缓冲参数。
一个可直接参考的典型配置片段
以下是一个兼顾安全性、兼容性和调试性的 location 示例：
location /api/ {
proxy_pass http://backend_servers/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_redirect off;
proxy_buffering on;
client_max_body_size 100m;
proxy_read_timeout 300;
}
其中 backend_servers 是定义在 upstream 块中的服务器组名，便于后续扩展负载均衡。
