Nginx通过proxy_pass调用upstream需满足四点：必须在http块提前定义、名称严格匹配且仅含小写字母数字和短横线、proxy_pass后不拼路径（/决定是否剥离前缀）、必须配置proxy_set_header透传真实Host/IP/协议。
要让 Nginx 正确通过 proxy_pass 调用自定义的 upstream 集群，核心是“先声明、再引用、路径对齐、头信息补全”。名称必须提前定义、大小写敏感、不带非法字符，转发时末尾斜杠决定路径是否剥离——这四点没做对，90% 的 502 或路径错乱问题就出在这儿。
upstream 名称必须在 http 块中提前定义且严格匹配
upstream 不是 location 内的局部变量，它必须出现在全局 http 块里，且所有 proxy_pass 引用的名称必须与之完全一致（区分大小写）：
- 合法定义位置：只能在
http { ... }区域内，不能放在server或location中 - 名称限制：仅支持小写字母、数字、短横线（
-），不支持下划线（_）和空格，例如api-v1✅，api_v1❌ - 引用检查：若 upstream 名为
user-service，则proxy_pass http://user-service;才有效；写成userservice或User-Service都会报no resolver defined或 502
proxy_pass 指向 upstream 时不能拼接路径
当目标是 upstream 名称时，proxy_pass 后面只允许写 http://集群名 或 http://集群名/，加任何路径（如 /v1）都会触发强制重写，导致后端收不到原始 URI：
FastAPI Flask Proxy
下载
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
-
proxy_pass http://backend-cluster;→ 原样转发完整请求路径，比如/api/users到后端仍是/api/users -
proxy_pass http://backend-cluster/;→ 剥离 location 匹配前缀，比如location /api/ { ... }下的/api/users会变成/users发给后端 -
proxy_pass http://backend-cluster/v1;→ 强制重写为/v1/users，原始语义丢失，多数 REST 接口会 404
必须设置关键 proxy_set_header 传递真实信息
Nginx 作为代理层，默认会覆盖 Host、客户端 IP 等字段。后端若依赖这些信息（如鉴权、日志、跳转），必须显式透传：
-
proxy_set_header Host $host;—— 否则后端收到的是 upstream 地址（如192.168.1.10），无法识别虚拟主机或 HTTPS 协议 -
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，避免混合内容或跳转错误
配合健康检查与负载策略提升可用性
单纯转发不够稳定，建议 upstream 块中加入基础容错配置：
- 用
max_fails=2 fail_timeout=30s自动剔除连续失败节点 - 按业务选算法：需会话保持用
ip_hash；流量不均用weight=3；长连接多用least_conn - 加
backup标记备用节点，主集群异常时自动切换 - 启用
keepalive 32复用连接，减少后端握手开销
