502 是什么
502 Bad Gateway 表示作为网关或代理的服务器，从上游服务器收到了无效响应，或者根本无法与上游建立连接。RFC 9110 §15.6.3 的定位很清楚：问题出在网关与上游之间，而不是客户端请求有毛病。最常见的三类根因是后端进程没起来、连到了错误的端口或协议（HTTP 与 HTTPS 混用）、后端崩溃后连接被重置。因此 502 的第一现场永远是网关的错误日志，先读日志再改配置。
基本信息
| 名称 | 502 Bad Gateway |
|---|---|
| 作用 | 网关无法从上游取得有效响应 |
| 规范 | RFC 9110 §15.6.3 |
| 典型根因 | 后端进程退出、端口未监听、协议不匹配、连接被重置 |
| 第一现场 | 网关错误日志中的连接失败与上游相关行 |
典型成因场景
- 后端服务发布重启期间，网关短暂返回 502
- 后端监听在回环地址而网关在另一台机器，根本连不上
- 后端只提供明文 HTTP，网关却配置了加密回源，或相反
- 动态进程池耗尽，或后端套接字路径配置错误
- 容器编排中后端未通过就绪检查就被挂上负载均衡
日志定位与后端探测
日志定位与后端探测
grep -E 'connect|upstream|reset|SSL' /var/log/nginx/error.log | tail -20
tail -100 /var/log/nginx/error.log | grep -oE 'Connection refused|upstream timed out|no live upstreams|invalid response' | sort | uniq -c
ss -lntp | grep -E ':(8000|9000|3000)' # 确认后端进程确实在监听
curl -sv http://127.0.0.1:8000/health # 在网关所在机器上直接访问后端
nginx -T | grep -nE 'proxy_pass|fastcgi_pass' # 核对回源地址与协议日志关键词对应根因
| 日志关键词 | 含义 | 处置方向 |
|---|---|---|
| Connection refused | 端口没人监听 | 拉起后端进程，核对监听地址 |
| upstream sent invalid response | 协议或响应格式不对 | 检查回源协议与后端输出内容 |
| no live upstreams | 健康检查全部失败 | 检查后端健康检查与就绪探针 |
| Connection reset by peer | 后端主动断开或崩溃 | 看后端日志与是否被内存回收 |
| SSL handshake failed | 网关与后端加密配置不匹配 | 统一回源协议与证书配置 |
502 与 503 的区别在责任方：502 是网关代理的上游坏了，503 是服务本身主动或被迫暂时不服务（过载、维护）。看到 502 先修上游，看到 503 先看容量与维护开关。
若把 502 错误页交给 CDN 缓存又没有短 TTL 或缓存标签，后端恢复后用户仍会持续看到错误页，必须手动刷新缓存才能恢复。
恢复与预防
- 发布采用滚动或蓝绿方式，保证任一时刻都有健康实例在承接流量
- 给网关到上游的连接与读取都设合理超时，避免慢实例把连接池占满
- 就绪检查与存活检查分开配置，未就绪的实例绝不接入流量
- 后端监听地址与端口由配置管理统一下发，避免改动之后两边不一致
- 为错误码建立告警与自定义错误页，不要把网关默认页直接暴露给用户
与相邻错误码的分工
| 错误码 | 责任方 | 典型动作 |
|---|---|---|
| 502 | 网关与上游之间的连接或响应 | 拉起后端，核对端口与协议 |
| 503 | 服务自身过载或处于维护 | 扩容、限流、返回维护页 |
| 504 | 上游处理太慢 | 优化慢点，长任务改异步 |
| 500 | 应用内部抛出未处理异常 | 修代码，查依赖与配置 |
502 的排查顺序是先证明上游是否收到请求，再看上游自己的日志与资源占用。跳过这一步直接调大超时或重启网关，只会让故障在更长时间里反复出现。
如何缩短影响时间
- 把后端启动与预热时间纳入发布流程，实例真正就绪后再切流量，避免发布窗口内的固定报错
- 错误页与监控告警同时上线：用户看到友好提示，值班同学第一时间收到通知
- 让网关把状态码与上游地址写进访问日志并保留摘要，事后分析不必重新复现现场