HTTP 与 Web 标准 / 系统课时

定位 502 503 504

定位 502 503 504

代理链路出现 502、503、504 时,不能只凭状态码猜故障点。有效做法是把状态码、代理错误日志、上游状态和各阶段耗时放在一起,判断失败发生在连接上游、选择可用实例,还是等待上游响应的阶段。

学习目标

  • 区分 502、503、504 在代理链路中的核心含义
  • 结合代理日志和耗时字段判断故障发生阶段
  • 按固定顺序验证上游连接、服务状态和超时配置

先把三个状态码放回代理链路

当客户端经过反向代理、网关或负载均衡器访问后端时,最终状态码可能由代理生成,也可能只是代理把上游返回的状态码原样转发。因此,状态码只能给出调查方向,不能单独证明根因。

502、503、504 在代理链路中的故障位置

状态码 协议层面的重点 排查时优先寻找的证据
502 Bad Gateway 代理作为网关时,从上游得到无效响应 上游连接被拒绝、连接被重置、响应格式异常、上游提前断开
503 Service Unavailable 当前服务暂时无法处理请求 维护、过载、健康实例不足,或上游自身明确返回 503
504 Gateway Timeout 网关等待上游响应超过允许时间 上游连接过慢、首字节过慢、处理时间超过代理超时阈值

不同代理产品对具体故障的状态码映射并不完全一致。例如“没有健康上游”可能被不同实现映射为不同 5xx。因此排查时应以实际代理日志为准,而不是把“503 等于无健康节点”之类经验规则当成协议保证。

用状态码和耗时做第一轮判断

先从客户端记录 HTTP 状态码和总耗时。下面的命令请求代理入口,同时输出建立客户端到代理连接所需时间、收到首字节时间和总时间。将占位符替换为实际地址。

bash
curl -sS -o /dev/null -w 'status=%{http_code} connect=%{time_connect}s starttransfer=%{time_starttransfer}s total=%{time_total}s\n' "http://<HOST>:<PORT>/<PATH>"

预期输出。以下示例表示代理最终返回 504,实际时间值可能不同。

text
status=504 connect=<TIME>s starttransfer=<TIME>s total=<TIME>s

如果 connect 很短而 total 接近固定阈值,例如每次都接近代理配置的读取超时时间,重点检查代理到上游这一段。不过这里的 time_connect 只测量客户端到代理的连接,并不能代替代理内部的上游连接耗时。

502 如果几乎立即返回,常见方向是上游端口无人监听、连接被拒绝、TLS 或协议不匹配;504 如果总是在接近固定秒数后返回,更像代理的连接或读取计时器触发。503 若快速且稳定出现,应进一步判断它究竟由代理生成,还是上游应用主动返回。

把代理日志里的时间轴对上

代理访问日志最好能够关联请求 ID、最终状态码、上游状态以及连接和响应耗时。以常见反向代理日志字段为例,排查时重点观察这些信息:request_time、upstream_status、upstream_connect_time、upstream_header_time 和 upstream_response_time。

下面是经过简化的三类日志示意,字段名和格式会随代理产品及日志配置变化。

text
status=502 request_time=0.003 upstream_status=502 upstream_connect_time=0.001 upstream_response_time=0.001
status=503 request_time=0.002 upstream_status=- upstream_connect_time=- upstream_response_time=-
status=504 request_time=30.001 upstream_status=504 upstream_connect_time=0.004 upstream_response_time=30.000

第一行说明故障很快发生,继续查看同一请求对应的错误日志,常会发现连接拒绝、上游提前关闭或响应解析失败等更具体的原因。第二行没有实际访问上游的时间,更应检查代理自身的路由、健康检查、限流或维护策略,但这只是诊断线索,不能仅凭一个横线字段断定原因。

第三行中连接很快完成,但响应耗时接近固定的 30 秒,说明重点已经从“能否连上”转向“上游为什么迟迟没有返回”。此时应检查应用处理时间、数据库或下游依赖,以及代理的读取超时,而不是盲目增加重试次数。

从代理所在位置直接验证上游

排查代理链路时,应尽量在代理主机或代理容器内部直接访问同一个上游目标。这样可以绕过客户端到代理这一段,验证 DNS、网络路由、目标端口和应用响应是否正常。

bash
curl -sS -o /dev/null -w 'upstream_status=%{http_code} total=%{time_total}s\n' "http://<UPSTREAM_HOST>:<UPSTREAM_PORT>/<PATH>"

预期输出。修复后上游健康接口应返回预期的成功状态,实际耗时可能不同。

text
upstream_status=200 total=<TIME>s

如果直连上游也失败,应先解决上游监听、网络、安全策略或应用自身问题;如果直连稳定成功而代理仍然失败,则重点检查代理使用的目标地址、协议、连接池、健康检查和超时参数。还要确认测试的是代理实际使用的主机名、端口和协议,避免拿另一个入口的成功结果误判链路已经恢复。

用同一请求完成闭环验证

一次可靠排查通常按这个顺序进行:先记录客户端收到的状态码、耗时和请求 ID,再到代理访问日志与错误日志中定位同一请求,确认是否真正访问了上游以及失败发生在哪个计时阶段;随后从代理所在位置直连同一上游,最后再检查上游应用日志和依赖耗时。

修复后不要只验证“5xx 消失”。还应确认代理日志中的上游状态恢复正常、耗时不再贴近超时阈值,并连续请求多次,避免故障只存在于部分实例。502、503、504 的价值不是直接告诉你答案,而是帮助你把调查范围逐步缩小到连接、可用性或响应等待这三个方向。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

定位 502 503 504

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通