计算机网络 / 系统课时

排查 5xx 服务端错误

排查 5xx 服务端错误

5xx 表示请求已经到达服务器侧,但网关、应用或下游依赖未能正常完成处理。本课给出一条可复现的排查顺序:先确认状态码与请求标识,再串联网关和应用日志,最后按 500、502、503、504 的典型边界修复并复测。

学习目标

  • 能根据 500、502、503、504 的响应特征先划定故障层级。
  • 能用请求 ID 将客户端响应、网关日志和应用日志关联到同一次请求。
  • 能用同一条复现请求验证修复是否真正生效。

先从状态码和响应头定界

先保留原始响应,不要只看前端弹窗。下面的命令会打印状态行和响应头,并把响应体保存到文件;把 <PORT> 替换为实际监听端口,动态请求标识以 <ID> 表示。

bash
curl -sS -D headers.txt -o body.txt \
  -H 'X-Request-ID: debug-<ID>' \
  --max-time 10 \
  http://127.0.0.1:<PORT>/api/orders
cat headers.txt

预期输出示例:

text
HTTP/1.1 502 Bad Gateway
Content-Type: text/html
X-Request-ID: debug-<ID>

500 通常表示应用已经接到请求但内部执行失败;502 常见于反向代理无法从上游获得有效响应;503 常见于服务不可用、实例摘除或过载保护;504 表示代理等待上游响应超过超时阈值。状态码只能用于定界,不能直接当作根因。

5xx 从客户端响应到网关、应用和下游依赖的排查路径

沿请求标识串起三层日志

优先使用响应中的 X-Request-ID、traceparent 或网关生成的关联 ID。若系统还没有统一请求标识,临时排障时至少让入口代理保留一个 ID,并让应用日志打印它。时间窗口控制在故障前后 2~5 分钟,避免在海量日志里只凭关键词猜测。

Linux/systemd 环境可先按请求 ID 查应用日志:

bash
journalctl -u myapp --since '<TIME>' --until '<TIME>' \
  | grep 'debug-<ID>'

预期输出示例:

text
<TIME> myapp[<ID>]: request_id=debug-<ID> route=/api/orders status=500
<TIME> myapp[<ID>]: request_id=debug-<ID> error="database connection timeout"

如果入口是 Nginx,还应检查同一时间点的 access log 与 error log。真正有价值的是把 status、upstream_status、request_time、upstream_response_time 与同一个请求 ID 对齐:例如总耗时 5.01 秒、上游耗时 5.00 秒后返回 504,说明等待时间主要消耗在上游,而不是客户端到网关这段链路。

按 500/502/503/504 分别修复

500 要先找到应用异常栈、未处理异常或依赖调用错误,修复代码或配置后再验证;不要用代理层把 500 改写成 200。502 先检查上游地址、端口、进程是否监听、连接是否被拒绝,以及上游是否过早关闭连接。503 要检查健康检查、实例数量、连接池和限流状态,确认是否真的还有可服务实例。

504 的处理顺序是先找出哪一段超过预算,再决定是否调大超时。例如网关超时为 5 秒,而应用通常 200 毫秒、偶发数据库查询达到 8 秒,应优先优化查询或下游,而不是把网关直接改成 60 秒。只有业务确实允许长请求时,才同步调整网关、应用服务器和下游客户端的超时。

用复现请求完成闭环

修复后必须使用和故障时相同的方法、路径、关键请求头和负载重新请求,并同时观察状态码、耗时和日志。对于间歇性 5xx,至少连续请求 20~50 次;如果故障只在高并发出现,再用现有压测工具按生产流量模型复测,而不是只验证一次 200。

下面用 curl 连续请求 20 次并输出状态码与总耗时;把 <PORT> 替换为实际端口。

bash
for i in $(seq 1 20); do
  curl -sS -o /dev/null \
    -w '%{http_code} %{time_total}\n' \
    --max-time 10 \
    http://127.0.0.1:<PORT>/api/orders
done

预期输出示例:

text
200 <TIME>
200 <TIME>
200 <TIME>
...

应连续 20 次返回业务预期的 2xx 状态,且总耗时不再出现原故障特征;例如原先每次约 5 秒后 504,修复后应回到业务基线附近。若仍出现 5xx,就用新的请求 ID 重新走同一条日志链路,不要跳过定界步骤。

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

目录与阅读设置

阅读设置

17

记录一个想法

排查 5xx 服务端错误

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

登录哪都通