Nginx proxy_pass 实现前后端分离接口转发需正确匹配路径、处理末尾斜杠、透传请求头并配置超时与前端路由回退；location /api/ 配 proxy_pass http://backend/（带斜杠）可去除前缀，配合 try_files $uri $uri/ /index.html 解决 History 模式 404。

Nginx 的 proxy_pass 是实现前后端分离项目中接口转发的核心配置，关键在于正确匹配请求路径、改写 URI、透传必要头信息，并避免跨域问题。下面从常用场景出发，讲清楚怎么配才不踩坑。

明确区分静态资源和 API 请求

前端通常打包成静态文件（如 /index.html），后端提供接口（如 /api/users）。Nginx 需把带 /api/ 前缀的请求转发给后端服务，其余请求直接返回前端资源。

• 前端资源走 root 或 alias，比如 root /var/www/dist;
• API 请求用 location /api/ { proxy_pass http://backend; }，注意末尾斜杠的作用

理解 proxy_pass 末尾斜杠的含义

这是最容易出错的地方：

• proxy_pass http://127.0.0.1:3000/;（带斜杠）：会删除匹配的 location 前缀，再拼接。例如 location /api/ 匹配 /api/users，实际转发为 http://127.0.0.1:3000/users
• proxy_pass http://127.0.0.1:3000;（不带斜杠）：会保留完整原始 URI，转发为 http://127.0.0.1:3000/api/users

多数后端服务期望接收不带 /api 前缀的路径，所以推荐第一种写法，配合 location /api/ 使用。

CPA Update - Secure CLI Proxy API Maintenance

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

下载

补充必要的代理头和超时设置

只写 proxy_pass 不够，后端可能拿不到真实 IP、协议或 Host，导致重定向异常或鉴权失败。

• 加 proxy_set_header Host $host; 保证后端看到原始 Host
• 加 proxy_set_header X-Real-IP $remote_addr; 和 X-Forwarded-For 传递客户端 IP
• 加 proxy_set_header X-Forwarded-Proto $scheme; 让后端知道是 HTTP 还是 HTTPS
• 设置 proxy_connect_timeout、proxy_send_timeout、proxy_read_timeout（如 60s），避免长接口被中断

处理前端路由（History 模式）和 404

Vue Router 或 React Router 的 History 模式下，刷新 /user/123 会 404，因为 Nginx 找不到对应文件。

• 在 location / 块中加 try_files $uri $uri/ /index.html;
• 确保该配置放在 location /api/ 等 API 规则之后（Nginx 优先匹配最长前缀），避免把 API 请求也 fallback 到 index.html

配完记得 nginx -t 检查语法，再 nginx -s reload 生效。只要路径匹配逻辑清晰、斜杠用对、头信息传全，接口转发就基本稳了。