api network_error ai_generated true

502 错误网关：上游服务器不可达

502 Bad Gateway: upstream server unreachable

ID: api/http-502-bad-gateway-upstream-unreachable

其他格式: JSON · Markdown 中文 · English
85%修复率
88%置信度
1证据数
2023-06-10首次发现

版本兼容性

版本状态引入弃用备注
Nginx 1.24+ active — — —
HAProxy 2.8+ active — — —
AWS ALB (2024) active — — —

根因分析

API 网关或反向代理从上游服务器收到无效响应，通常是由于上游服务器宕机、过载或负载均衡器配置错误。

English

The API gateway or reverse proxy received an invalid response from the upstream server, often due to the upstream being down, overloaded, or misconfigured in the load balancer.

generic

官方文档

https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass

解决方案

  1. 通过健康检查端点（例如 `/health`）检查上游服务器健康状态。示例：`curl -I http://upstream-service:8080/health`。如果失败，重启上游服务或检查其日志。
  2. 验证负载均衡器配置，确保上游服务器正确列出且端口匹配。示例：`nginx -t` 测试 Nginx 配置，然后 `systemctl reload nginx`。
  3. 临时绕过网关直接访问上游（如果网络允许）以隔离问题。示例：`curl http://10.0.1.5:8080/api/v1/resource`。

无效尝试

常见但无效的做法:

  1. 90% 失败

    The upstream server itself is unhealthy; restarting the gateway does not fix the upstream issue.

  2. 75% 失败

    If the upstream is down, timeouts only delay failure detection; the root cause (e.g., crashed service) remains.

  3. 60% 失败

    While DNS can cause this, the error often stems from upstream service failure (e.g., port 8080 not listening), not DNS resolution.