proxy_pass末尾斜杠决定路径处理方式：带/则剥离location前缀后拼接，不带/则原样转发完整uri；正则location需配合rewrite+break重写路径，不可在proxy_pass后带路径。

写好 proxy_pass 映射规则，核心不是堆参数，而是理清“请求路径怎么来、又怎么走”。Nginx 不是简单转发，它会在 location 匹配后，按固定逻辑裁剪和拼接 URI —— 这个逻辑一旦理解偏差，后端就收不到预期路径，接口 404 或返回错内容。

location 前缀 + proxy_pass 斜杠决定路径是否剥离

这是最常踩坑的点。关键看 proxy_pass URL 结尾有没有 /：

• proxy_pass 后带 /（如 http://backend/）：Nginx 自动去掉 location 匹配的前缀，只把剩余路径拼到目标地址后
• proxy_pass 后不带 /（如 http://backend）：Nginx 把原始请求路径（含匹配前缀）整个作为新路径发给后端

例如：location /api/v1/ { proxy_pass http://svc:8080/; } → 访问 /api/v1/users 实际发给后端的是 /users；而改成 proxy_pass http://svc:8080，就会发 /api/v1/users，后端若没挂载在该路径下就 404。

正则 location 必须配合 rewrite 或 break 使用

当 location 用 ~ 或 ~* 写正则时，proxy_pass 后面不能带任何路径（包括结尾 /），否则配置校验失败。此时路径重写要靠 rewrite 完成：

• 用 rewrite ^/old/(.*)$ /new/$1 break; 改写 URI，再由 proxy_pass 转发
• break 表示改写后不再重新匹配 location，直接走当前块的 proxy_pass
• 避免用 last，否则会触发新一轮 location 匹配，可能陷入循环或误匹配

典型场景：把 /v2/user/* 映射为 /api/user/*，必须先 rewrite，再 proxy_pass 到无路径的后端地址。

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

用 upstream + 多级 location 实现服务弹性与路径隔离

单个 proxy_pass 很难应对灰度、降级或路径拆分需求。推荐组合使用：

• 定义 upstream 块，支持健康检查、权重、备用节点：upstream api_main { server 10.0.1.10:8000 max_fails=3 fail_timeout=30s; server 10.0.1.11:8000 backup; }
• 用不同 location 分流路径：location /api/auth/ { proxy_pass http://api_main; } 和 location /api/data/ { proxy_pass http://api_data; }
• 对关键路径加限流或缓存：location ~ ^/api/v1/(user|order)/.*$ { limit_req zone=api burst=10 nodelay; proxy_pass http://api_main; }

这样既解耦了路由策略和服务实例，也便于按路径做精细化治理。

跨域与 Cookie 适配不能只靠 proxy_pass

proxy_pass 只管转发，但前端看到的仍是原域名，而后端 Set-Cookie 的 domain 往往不匹配。必须显式补全头信息：

• proxy_set_header Host $host:$server_port; —— 传递原始 Host，避免后端依赖错误域名
• proxy_set_header X-Forwarded-For $remote_addr; —— 透传真实客户端 IP
• proxy_cookie_domain ~\.example\.com$ example.com; —— 把后端设的 cookie domain 统一替换为当前主站域名
• 如果后端返回 Secure 或 HttpOnly cookie，确保 Nginx 与后端协议一致（HTTPS 环境下 proxy_pass 用 https://）

漏掉这些，登录态无法保持、接口报 CORS 错误、用户反复登录等问题就会反复出现。