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

- **ID:** `api/http-502-bad-gateway-upstream-unreachable`
- **领域:** api
- **类别:** network_error
- **验证级别:** ai_generated
- **修复率:** 85%

## 根因

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

## 版本兼容性

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

## 解决方案

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`。
   ```

## 无效尝试

- **** — The upstream server itself is unhealthy; restarting the gateway does not fix the upstream issue. (90% 失败率)
- **** — If the upstream is down, timeouts only delay failure detection; the root cause (e.g., crashed service) remains. (75% 失败率)
- **** — While DNS can cause this, the error often stems from upstream service failure (e.g., port 8080 not listening), not DNS resolution. (60% 失败率)