错误码与故障现象反查：从报错文本、HTTP 状态码或 K8s 状态找到第一条排查路径

使用方式

先在上面的分组里找到最接近的报错或状态，再进入排障页按“现象 → 假设 → 验证 → 修复”推进。报错文本只是入口，不要只凭一个状态码下结论；同一种 502 可能来自上游端口、进程崩溃、DNS 或超时。

• HTTP/网关：先确认错误由谁产生，再看上游日志和超时。
• 连接/TLS：先分清拒绝、重置、超时和证书失败，四者的排查顺序不同。
• K8s 状态：先看 kubectl describe 的 Events 和容器退出码，再看日志。
• 系统/存储：先确认资源是否真的耗尽，再判断是否只读或权限问题。

HTTP 与网关

• 502-bad-gateway — 上游端口、进程、DNS 或协议不匹配。
• 504-gateway-timeout — 上游处理超时、连接池耗尽或网络延迟。
• nginx-499 — 客户端提前断开，先看上游耗时和客户端超时。
• nginx-413 — 请求体超过 client_max_body_size 或上游限制。
• nginx-404 — 路由、root/alias、重写规则或静态文件缺失。
• nginx-401 — 认证缺失或认证头未透传。
• nginx-403 — 文件权限、目录索引或访问规则拒绝。
• nginx-503 — 上游全部不可用、限流或维护模式。
• http-429 — 限流触发，先区分网关、应用和依赖限流。
• cloud-lb-502 — 云负载均衡健康检查、后端端口和安全组。
• k8s-ingress-502 — Ingress 到 Service/Endpoint 的链路。
• k8s-ingress-503 — 无可用 Endpoint 或 Service 选择器错误。

连接、超时与 TLS

• connection-refused — 端口未监听、防火墙拒绝或地址错误。
• connection-reset-by-peer — 对端进程退出、协议不匹配或中间设备重置。
• connection-timeout — 丢包、路由、ACL、DNS 或后端过载。
• context-deadline-exceeded — Go 调用超时，先看上游耗时和重试。
• grpc-deadline-exceeded — gRPC deadline、负载均衡和连接复用。
• io-timeout — 存储或网络 IO 超时，先区分设备、NFS 和云盘。
• tls-handshake-timeout — TCP 可达但握手不完成，查 MTU、防火墙和证书链。
• tls-handshake-failed — 协议版本、SNI、证书或客户端证书不匹配。
• keepalive-timeout — 长连接被中间设备或服务端回收。
• unexpected-eof — 对端提前关闭，常见于代理、超时和进程崩溃。
• websocket-disconnect — 代理超时、心跳缺失或后端重启。
• x509-unknown-authority — CA 未被信任、链不完整或系统信任库缺失。
• certificate-expired — 证书过期、时区错误或轮换未生效。
• certificate-untrusted — 自签证书、主机名不匹配或中间证书缺失。
• nginx-ssl-error — Nginx 证书、协议和密码套件配置。

Kubernetes 状态与事件

• crashloopbackoff — 容器反复退出，先看退出码和 previous 日志。
• oom-killed — 容器内存超限，区分应用泄漏、堆外内存和 limit 过小。
• imagepullbackoff — 镜像 tag、认证、仓库连通性或拉取限流。
• pod-pending — 资源不足、亲和性、污点、PVC 或调度器问题。
• k8s-pvc-pending — StorageClass、容量、拓扑和绑定模式。
• node-notready — kubelet、运行时、网络或节点压力。
• kubelet-not-ready — kubelet 停止、证书过期或容器运行时异常。
• terminating-stuck — finalizer、卡住的卷卸载或 kubelet 无响应。
• probe-failed — 探针路径、端口、超时和启动时间。
• k8s-job-failed — Job 退出码、重试策略和依赖失败。
• pod-evicted — 节点磁盘、内存压力或临时存储超限。
• k8s-webhook-timeout — 准入 Webhook 超时、证书或服务不可用。

存储与文件系统

• no-space-left — 空间耗尽，先查已删除但仍被占用的文件。
• inode-exhausted — inode 用完，常见于大量小文件和缓存。
• read-only-filesystem — 文件系统错误、云盘掉线或挂载选项。
• disk-readonly — 磁盘或块设备进入只读，先保护现场。
• mount-failed — 设备、文件系统类型、权限和挂载点冲突。
• nfs-stale-file-handle — NFS 服务端导出变化或连接中断。
• too-many-open-files — 文件描述符泄漏或 limit 过低。

数据库、缓存与消息队列

• mysql-deadlock — InnoDB 死锁，先看 SHOW ENGINE INNODB STATUS。
• mysql-too-many-connections — 连接泄漏、连接池或 max_connections。
• postgres-connection-exhausted — 连接泄漏、池配置或空闲事务。
• postgres-deadlock — 锁顺序、长事务和等待图。
• postgres-lock-wait — 锁等待、阻塞链和 pg_stat_activity。
• redis-memory-full — maxmemory、淘汰策略和大 Key。
• redis-connection-failed — 地址、认证、TLS 或连接池。
• redis-cluster-failover — 槽位、主从切换和客户端重定向。
• kafka-under-replicated — ISR 收缩、broker 离线或磁盘问题。
• kafka-consumer-lag — 总 lag、分区倾斜和消费能力。

系统、权限与运行时

• kernel-panic — 内核崩溃，先保留转储和启动日志。
• boot-failure — 引导、fstab、initramfs 或根文件系统问题。
• systemd-start-limit — 服务反复重启触发启动限制。
• systemd-timeout — 服务启动或停止超时，先看依赖和 ExecStop。
• permission-denied — 权限位、ACL、SELinux 或挂载选项。
• selinux-denied — SELinux 拒绝，先看 audit 日志再调整策略。
• sudo-failed — sudoers、TTY、密码或命令权限。
• time-drift — NTP/chrony、虚拟化时钟和证书校验。
• zombie-process — 僵尸进程与父进程回收。

退出码速查

• 137：进程被 SIGKILL，常见于容器 OOM 或 docker stop 超时；先看 oom-killed。
• 143：进程收到 SIGTERM，通常是正常停止或编排系统终止；检查优雅退出和 terminationGracePeriodSeconds。
• 126/127：命令不可执行或找不到；检查路径、权限、shebang 和镜像内工具是否存在。
• 130：收到 SIGINT，多为人工中断；脚本要清理临时文件和子进程。
• 1：通用失败，必须结合 stderr、日志和业务断言定位，不能只看退出码。

常见误区

1. 只凭 HTTP 状态码判断根因；502 可能来自 DNS、端口、进程或协议，必须看上游日志。
2. 把 OOMKilled 当成应用内存泄漏的唯一结论；也可能是 limit 过低、堆外内存或 page cache。
3. 看到 READONLY 就重启 Redis；要先确认副本角色、Sentinel 主节点和客户端连接地址。

参考链接

• HTTP: Semantics and Content
• Kubernetes: Pod lifecycle
• NGINX: Troubleshooting

读完自测

1. 502 和 504 的第一排查顺序有什么不同？
2. 容器退出码 137 一定代表应用内存泄漏吗？
3. 为什么 READONLY 错误要先确认客户端连接的是主节点还是副本？

更多排障入口

• incident-kubelet-hang — 一次网络存储挂起导致 kubelet 与容器运行时同时卡死的复盘（匿名化合成案例）。
• macos-launchd-failed — macOS 的 launchd 代理或守护进程无法启动、反复退出时的定位与修复。
• macos-softwareupdate-failed — macOS 软件更新检查、下载或安装失败时的定位与修复。
• ruby-gc — Ruby（MRI）服务 GC 时间上升、内存不回落，Puma worker 被重启或 OOMKilled。
• slow-ssh-login — SSH 登录缓慢的定位与修复。

相关条目

• troubleshoot-learning-path — 按症状组织的排障学习路径
• linux-command-map — Linux 命令地图
• glossary-index — 术语与缩写索引
• lab-learning-path — 用故障演练验证排查结论