---
tags: [kubernetes, troubleshooting, diagnostics, ops-checklist]
create time: 2026-05-18 00:30
---

# K8s 运维排查 — Checklist 与诊断速查

## 概述

每次上线前过一遍清单，遇到问题时有系统化的排查思路。本章整理了实战中最常用的诊断命令、高频问题对照表和有价值的调试技巧。更多 SRE 理念（错误预算、MTTR）参见 [[../04-SRE实践]]。

## 上线前 Checklist

| # | 检查项 | 说明 |
|---|--------|------|
| 1 | **Probe 已配置** | liveness/readiness/startup 都设定了阈值 |
| 2 | **Resources Limits** | 防止单个 Pod OOMKill 拖垮整台机器 |
| 3 | **日志输出到 stdout/stderr** | 可被采集器解析为 JSON |
| 4 | **trace_id 透传** | 跨服务调用链 trace_id 不丢失 |
| 5 | **回滚预案** | `kubectl rollout undo deployment/order-service` 能用 |
| 6 | **告警已配置** | 关键指标异常时有人收到通知 |
| 7 | **镜像 Tag** | 不用 latest，用语义化版本或 commit SHA |

## 常用诊断命令

```bash
# 1. 查看 Pod 状态（为什么起不来？）
kubectl get pods -n production

# 2. 看单个 Pod 的详细事件
kubectl describe pod <pod-name> -n production
# ↑ 重点看 Events 区域的 LastState / State / Reason

# 3. 看容器日志（含重启前的上一次输出）
kubectl logs <pod-name> -n production --previous   # 上次崩溃容器的日志
kubectl logs <pod-name> -n production -c sidecar    # 多容器指定 sidecar 名

# 4. 进入运行中的容器调试
kubectl exec -it <pod-name> -n production -- /bin/sh

# 5. 查看滚动更新进度
kubectl rollout status deployment/order-service -n production

# 6. 回滚到上一个版本
kubectl rollout undo deployment/order-service -n production

# 7. 查看资源占用
kubectl top pods -n production          # Pod CPU/Memory
kubectl top nodes                       # 节点级别
```

## 高频问题对照表

| 症状 | 可能原因 | 排查步骤 |
|------|---------|---------|
| `ImagePullBackOff` | 镜像不存在、仓库认证失败、拼写错误 | `kubectl describe pod` 看 Normal Events；确认 registry 凭证 Secret |
| `ErrImagePull` | 镜像 tag 不存在 | 检查 CI 是否成功 push；`docker pull` 在本地复现 |
| `CrashLoopBackOff` | Liveness Probe 误杀、代码异常启动 | `kubectl logs --previous`；检查 `/healthz` 健康端点逻辑 |
| `Pending` (调度中) | 资源不足、Affinity/Toleration 不满足 | `kubectl describe pod` 看 Warning 事件；检查节点可用资源 |
| `OOMKilled` | memory limit 过小或内存泄漏 | 增大 limits；检查应用堆dump；JVM 需设 `-Xmx` |
| Service 不通 | Selector 标签不匹配、端口配置错 | `kubectl get ep <svc>` 看 Endpoint 列表；curl ClusterIP 验证 |
| ConfigMap/Secret 未生效 | 重建了 Pod 但环境变量没更新 | 删除 Pod 让 Deployment 重建；ConfigMap volume 挂载会热更新 |
| Ingress 无响应 | Ingress Controller 未安装、Backend 配置错 | `kubectl get pods -n ingress-nginx`；检查 annotation 语法 |
| DNS 解析失败 | CoreDNS Pod 异常或 NetworkPolicy 限制 DNS egress | `nslookup kubernetes.default`；确保 DNS egress 端口 53 放行 |
| Pod 被频繁驱逐 | Node 资源不足触发 Eviction | `kubectl describe node <node>` 看 MemoryPressure/DiskPressure |

## 调试技巧：优雅地抓包与断点

```bash
# ========== Debugging Sidecar 模式 ==========
# 给故障 Pod 附加一个临时调试容器，共享网络命名空间
kubectl debug <pod-name> -it --image=nicolaka/netshoot --share-network

# 进来了之后可以直接:
# curl, nslookup, tcpdump, ping, tshark — 全套网络诊断工具

# ========== 动态调整日志级别（无需重建 Pod）==========
# 通过 port-forward 访问 kube-apiserver 的 debug endpoint
kubectl port-forward svc/kube-apiserver 6443:443 -n default
```

> [!tip] 快速判断 K8s 问题的层级
> 
> ```
> Pod 起不来 → 查 Images / Resources / Probes
> Pod 起来了但服务不通 → 查 Service Selector / Endpoints / Ingress
> 服务通但有报错 → 查 App Logs / Metrics / Traces
> 性能差 → 查 CPU Throttling / Disk IO / 连接池
> ```
> 
> 按这个顺序一层层定位，避免在日志里大海捞针。

## 补充：kubectl 高阶用法

```bash
# 根据表达式筛选（比如只看处于 CrashLoop 的 Pod）
kubectl get pods --field-selector=status.phase==Failed -A

# 批量执行命令（在每个 Pod 中同时运行）
kubectl exec deploy/api-server -- sh -c 'uptime; free -m'

# 导出资源配置用于备份或审计
kubectl get deployment -n production -o yaml > deploy-backup.yaml

# 模拟变更效果（dry-run，不做实际修改）
kubectl apply -f new-deployment.yaml --dry-run=server -o yaml

# 查看哪个节点承载了某个 Pod
kubectl get pods -o wide -n production | grep my-app

# 持续监控 Pod 事件（实时流）
kubectl get events -n production --sort-by=.lastTimestamp -w
```

> [!info] 理解 kubectl verbosity 级别
> 
> `-v=6` 显示 HTTP 请求 headers；`-v=8` 额外返回响应 body；`-v=9` 逐行展开。调试 API 交互时通常 `-v=6` 就足够了，`-v=8` 以上会产生大量输出。

## 补充：集群层面的健康检查

```bash
# 查看所有控制面组件状态
kubectl get componentstatuses       # K8s 1.19+ 已废弃，改用：
kubectl get endpoints etcd -n kube-system

# 检查 CoreDNS 健康（DNS 异常的起点）
kubectl get pods -n kube-system -l k8s-app=kube-dns
kubectl logs -n kube-system <coredns-pod-name>

# 检查存储插件正常
kubectl get storageclass

# 查看当前活跃的资源配额使用情况
kubectl describe quota -n production
```

## 关联笔记

- [[../01-核心概念与Deployment]] — Deployment 回滚操作
- [[../03-网络与服务发现]] — Service / Ingress 的调试方法
- [[../05-调度控制]] — Pending Pod 与 Affinity/Toleration 的关系
- [[../hhs/MS/05-部署运维/04-SRE实践]] — MTTR 指标与故障恢复
- [[../hhs/MS/04-可观测性]] — Prometheus + Grafana 可视化排查