proxy_pass是nginx反向代理核心指令，用于转发请求至后端服务；末尾有/可截断路径前缀，需配置proxy_set_header传递真实请求头，并处理重定向、websocket及超时等常见问题。
在 Nginx 中，proxy_pass 是实现反向代理的核心指令，用于把客户端请求转发到后端服务（如 Node.js、Python Flask、Java Spring Boot 等）。关键在于路径匹配、URL 重写和请求头控制，稍不注意就容易出现 404、重复路径或静态资源加载失败等问题。
基础用法：直接转发到后端地址
最简单的配置是将某个 location 下的所有请求，原样转发到后端服务：
location /api/ {
proxy_pass http://127.0.0.1:3000;
}
注意：proxy_pass 末尾不加 / 时，Nginx 会把匹配的前缀（这里是 /api/）一起转发过去。比如请求 /api/users，后端实际收到的是 /api/users。
去掉前缀：末尾加斜杠实现路径截断
如果后端服务本身不处理 /api 前缀（例如它只监听 /users），就需要去掉前缀：
location /api/ {
proxy_pass http://127.0.0.1:3000/; # 注意末尾的 /
}
这时请求 /api/users 会被改写为 /users 再发给后端。这是最常用也最容易出错的地方。
FastAPI Flask Proxy
下载
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
补充必要代理头，避免后端取不到真实信息
默认情况下，后端看到的 Host、客户端 IP 都是 Nginx 的，需手动设置请求头：
-
proxy_set_header Host $host;—— 透传原始 Host -
proxy_set_header X-Real-IP $remote_addr;—— 传递真实客户端 IP -
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;—— 支持多层代理链 -
proxy_set_header X-Forwarded-Proto $scheme;—— 告诉后端是 http 还是 https
建议把这些头统一写在 location 或 server 块里，避免遗漏。
常见问题与应对
以下情况容易导致转发异常：
- 后端返回 302 重定向时跳转到内部地址（如
http://127.0.0.1:3000/login）→ 加上proxy_redirect http://127.0.0.1:3000/ /api/;重写跳转地址 - WebSocket 连接失败 → 在
location中添加proxy_http_version 1.1;和proxy_set_header Upgrade $http_upgrade;等支持升级头 - 大文件上传超时 → 增加
proxy_read_timeout、proxy_send_timeout和client_max_body_size
配置生效后记得运行 nginx -t 检查语法，再 nginx -s reload 重载。
