ENGINEERING PLAYBOOK

HTTP 500 内部错误排查

500 表示服务器在处理请求时没有给出更具体的成功响应，但错误可能发生在代理、应用、模板、数据库或外部依赖。排查应冻结一个失败请求，以同一时区和请求标识串联全部证据。

适用人群：需要用请求标识串联代理、应用和下游证据的服务维护人员

排查路径

  1. 确认 500 由哪一层生成，避免只看浏览器错误页。
  2. 锁定一个失败样本并保存完整请求条件。
  3. 按最近变更、异常栈、下游状态与资源告警排序假设。
  4. 在可控环境复现并验证最小修复。

执行步骤

  1. 记录失败请求的时间、路径、方法与 request id。
  2. 检查 Nginx error log 和应用异常栈是否对应。
  3. 核对数据库、缓存和外部 API 的状态与超时。
  4. 检查磁盘、内存、文件句柄和连接池上限。
  5. 回滚最近变更后比较相同请求的结果。

可复制命令与示例

检查响应与请求标识

curl -sS -D - -o /tmp/body https://example.test/api | sed -n '1,30p'

按时间查看服务日志

journalctl -u app.service --since "10 minutes ago" --no-pager

可复现任务记录

具体错误或任务

单个 API 请求返回 500，需要确认错误由 Nginx、应用、数据库还是外部依赖生成。

失败信号：状态行为 500，响应含 request id；同一时间窗的应用日志存在异常或上游超时。

最小输入

固定方法、路径、脱敏请求体、失败时间、request id 和最近变更摘要。

验证命令或步骤

curl -sS -D /tmp/headers -o /tmp/body 'https://example.test/api'; sed -n '1,20p' /tmp/headers

预期输出

修复后同一输入返回预期 2xx/4xx，并可用 request id 在日志中定位完整处理链。

失败输出

仍返回 500，或重启后暂时成功但没有对应异常、根因和回归证据。

成功判据

最小修复解释原异常，同输入回归通过，反向错误样本仍按预期失败，5xx 比例不反弹。

本任务常见错误

  • 只靠重启清除现象
  • 时间窗与日志时区不一致
  • 把所有 500 归因于应用代码

资料与适用边界

状态码语义依据 RFC 9110；具体异常必须由目标服务日志、依赖状态和同一请求标识共同证明。

证据块复核日期：2026-09-04

相关站内页面

资料依据与复核边界

资料复核日期：2026-08-29