From k8s-networking
基础设施故障排错指南。当用户提到故障排查、排错、troubleshoot、debug、问题诊断、服务异常、系统故障、网络故障、存储故障、K8s 故障、Pod 异常、节点故障、容器问题时使用此 skill。即使用户没有明确说"排错"或"故障",只要涉及系统异常、服务不可用、性能问题、错误排查等相关问题都应该触发此 skill。
How this skill is triggered — by the user, by Claude, or both
Slash command
/k8s-networking:troubleshoot-guideThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
帮助用户系统化地排查和解决基础设施故障。提供常见故障分类、排错思路、诊断命令和解决方案,覆盖 Kubernetes、网络、存储、系统等多个领域。
帮助用户系统化地排查和解决基础设施故障。提供常见故障分类、排错思路、诊断命令和解决方案,覆盖 Kubernetes、网络、存储、系统等多个领域。
| 类别 | 常见症状 | 排查优先级 |
|---|---|---|
| Kubernetes | Pod 异常、调度失败、服务不通、资源不足 | 高 |
| 网络 | 连通性问题、DNS 解析失败、延迟高、丢包 | 高 |
| 存储 | IO 性能差、挂载失败、空间不足、数据损坏 | 高 |
| 系统 | 负载高、OOM、磁盘满、内核异常 | 中 |
| 应用 | 进程崩溃、性能瓶颈、连接池耗尽、配置错误 | 中 |
journalctl、kubectl logs、/var/log/ 是第一手信息现象:Pod 反复重启,状态显示 CrashLoopBackOff
排错思路:
# 1. 查看 Pod 状态和事件
kubectl describe pod <pod-name> -n <namespace>
# 2. 查看当前容器日志
kubectl logs <pod-name> -n <namespace>
# 3. 查看上一次崩溃的日志
kubectl logs <pod-name> -n <namespace> --previous
# 4. 如果容器有多个,指定容器名
kubectl logs <pod-name> -n <namespace> -c <container-name> --previous
常见原因及解决方案:
| 原因 | 特征 | 解决方案 |
|---|---|---|
| 应用启动失败 | 日志中有启动错误 | 检查配置文件、环境变量、依赖服务 |
| OOMKilled | Last State: OOMKilled | 增加 resources.limits.memory |
| 健康检查失败 | Liveness probe failed | 调整 probe 参数或修复健康检查端点 |
| 配置错误 | ConfigMap/Secret 引用错误 | 验证 ConfigMap/Secret 是否存在且正确 |
| 镜像问题 | exec format error | 确认镜像架构匹配节点架构 (amd64/arm64) |
现象:Pod 无法拉取镜像
排错思路:
# 1. 查看事件中的具体错误
kubectl describe pod <pod-name> -n <namespace> | grep -A 10 Events
# 2. 检查镜像是否存在
# 3. 检查 imagePullSecrets 配置
kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.spec.imagePullSecrets}'
# 4. 验证 Secret 是否正确
kubectl get secret <secret-name> -n <namespace> -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d
常见原因:
现象:Pod 一直处于 Pending 状态
排错思路:
# 1. 查看调度事件
kubectl describe pod <pod-name> -n <namespace> | grep -A 20 Events
# 2. 查看节点资源使用情况
kubectl top nodes
kubectl describe nodes | grep -A 5 "Allocated resources"
# 3. 检查节点污点和 Pod 容忍度
kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints
kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.spec.tolerations}'
# 4. 检查 PVC 绑定状态(如果使用 PV)
kubectl get pvc -n <namespace>
常见原因:
现象:服务之间无法通信、外部无法访问服务
排错思路:
# 1. 确认 Pod 是否运行且 Ready
kubectl get pods -n <namespace> -l <label-selector>
# 2. 检查 Service 配置和 Endpoints
kubectl get svc <service-name> -n <namespace>
kubectl get endpoints <service-name> -n <namespace>
# 3. 从集群内部测试连通性
kubectl run debug --image=nicolaka/netshoot --rm -it -- bash
# 在 debug pod 中:
nslookup <service-name>.<namespace>.svc.cluster.local
curl -v <service-name>.<namespace>.svc.cluster.local:<port>
# 4. 检查 NetworkPolicy
kubectl get networkpolicy -n <namespace>
# 5. 检查 Ingress/Gateway 配置
kubectl get ingress -n <namespace>
kubectl describe ingress <ingress-name> -n <namespace>
常见原因:
现象:节点 NotReady 或不可调度
排错思路:
# 1. 查看节点状态和条件
kubectl get nodes
kubectl describe node <node-name>
# 2. 检查 kubelet 状态
ssh <node> systemctl status kubelet
ssh <node> journalctl -u kubelet --since "10 minutes ago"
# 3. 检查系统资源
ssh <node> df -h # 磁盘空间
ssh <node> free -h # 内存
ssh <node> top -bn1 # CPU 和负载
# 4. 检查容器运行时
ssh <node> systemctl status containerd # 或 docker
ssh <node> crictl ps # 容器状态
常见原因:
排错思路:
# 查看集群资源总览
kubectl top nodes
kubectl top pods -n <namespace> --sort-by=memory
# 查看资源配额
kubectl get resourcequota -n <namespace>
kubectl describe resourcequota -n <namespace>
# 查看 LimitRange
kubectl get limitrange -n <namespace>
# 查看 PDB(Pod Disruption Budget)
kubectl get pdb -n <namespace>
排错思路:
# 1. 检查 etcd 集群健康状态
ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \
--cacert=/etc/kubernetes/pki/etcd/ca.crt \
--cert=/etc/kubernetes/pki/etcd/server.crt \
--key=/etc/kubernetes/pki/etcd/server.key \
endpoint health
# 2. 检查 etcd 成员列表
ETCDCTL_API=3 etcdctl member list --write-out=table
# 3. 检查 etcd 性能(磁盘延迟)
ETCDCTL_API=3 etcdctl check perf
# 4. 查看 etcd 日志
journalctl -u etcd --since "30 minutes ago"
# 或 kubeadm 部署方式
kubectl logs -n kube-system etcd-<node-name>
常见问题:
排错思路:
# 1. 基础连通性
ping <target-ip>
traceroute <target-ip>
mtr <target-ip>
# 2. 端口连通性
nc -zv <target-ip> <port>
curl -v telnet://<target-ip>:<port>
# 3. DNS 解析
dig <domain>
nslookup <domain>
dig @<dns-server> <domain>
# 4. 路由检查
ip route show
ip route get <target-ip>
# 5. 防火墙规则
iptables -L -n -v
nft list ruleset
排错思路:
# 1. 检查本地 DNS 配置
cat /etc/resolv.conf
# 2. 测试 DNS 解析
dig <domain> +trace
dig <domain> @8.8.8.8
# 3. K8s 内 CoreDNS 排查
kubectl get pods -n kube-system -l k8s-app=kube-dns
kubectl logs -n kube-system -l k8s-app=kube-dns
kubectl get configmap coredns -n kube-system -o yaml
常见原因:
排错思路:
# 1. 带宽测试
iperf3 -s # 服务端
iperf3 -c <server-ip> # 客户端
# 2. 网络延迟
ping -c 100 <target> # 查看 avg/max/mdev
# 3. 丢包分析
mtr -r -c 100 <target>
# 4. 网卡状态
ethtool <interface>
ip -s link show <interface>
# 5. TCP 连接分析
ss -tunapo
ss -s # 连接统计
排错思路:
# 1. 查看磁盘使用
df -h
df -ih # inode 使用情况
# 2. 找出大文件
du -sh /* | sort -rh | head -20
find / -xdev -type f -size +1G -exec ls -lh {} \;
# 3. 检查已删除但仍被占用的文件
lsof +L1
# 4. 清理方案
journalctl --vacuum-size=500M # 清理 journal 日志
docker system prune -af # 清理 Docker
crictl rmi --prune # 清理未使用的镜像
排错思路:
# 1. 查看 IO 状态
iostat -xz 1 5
# 2. 查看 IO 延迟
ioping -c 10 /dev/sda
# 3. 查看 IO 等待进程
iotop -o
# 4. 磁盘健康检查
smartctl -a /dev/sda
# 5. 文件系统检查
xfs_info /dev/sda1 # XFS
tune2fs -l /dev/sda1 # ext4
排错思路:
# 1. 检查 PVC 状态
kubectl get pvc -n <namespace>
kubectl describe pvc <pvc-name> -n <namespace>
# 2. 检查 PV 状态
kubectl get pv
kubectl describe pv <pv-name>
# 3. 检查 StorageClass
kubectl get sc
kubectl describe sc <sc-name>
# 4. 检查 CSI 驱动
kubectl get pods -n kube-system | grep csi
kubectl logs -n kube-system <csi-pod>
# 5. 检查节点上的挂载
ssh <node> mount | grep <pv-name>
ssh <node> dmesg | tail -50
常见原因:
排错思路:
# 1. 查看系统负载
uptime
top -bn1 | head -20
vmstat 1 5
# 2. 找出 CPU 消耗最高的进程
ps aux --sort=-%cpu | head -20
# 3. 查看中断和上下文切换
mpstat -P ALL 1 5
vmstat 1 5 # 关注 cs 列
# 4. perf 分析(深入排查)
perf top
perf record -g -p <pid> -- sleep 10
perf report
排错思路:
# 1. 查看内存使用
free -h
cat /proc/meminfo
# 2. 检查 OOM 历史
dmesg | grep -i "oom\|out of memory"
journalctl -k | grep -i oom
# 3. 找出内存消耗最高的进程
ps aux --sort=-%mem | head -20
# 4. 查看 swap 使用
swapon --show
vmstat 1 5 # 关注 si/so 列
# 5. 查看 cgroup 内存限制
cat /sys/fs/cgroup/memory/memory.limit_in_bytes
cat /sys/fs/cgroup/memory/memory.usage_in_bytes
排错思路:
# 1. 内核消息
dmesg -T | tail -50
dmesg -T --level=err,warn
# 2. 系统日志
journalctl --since "1 hour ago" --priority=err
journalctl -u <service-name> --since "30 minutes ago"
# 3. 审计日志
ausearch -m avc --start recent # SELinux 拒绝
journalctl _TRANSPORT=audit --since "1 hour ago"
排错思路:
# 1. 查看进程状态
systemctl status <service>
ps aux | grep <process>
# 2. 查看 coredump
coredumpctl list
coredumpctl info <pid>
# 3. 检查文件描述符限制
ulimit -a
cat /proc/<pid>/limits
ls /proc/<pid>/fd | wc -l
# 4. 检查 systemd 资源限制
systemctl show <service> | grep -i limit
排错思路:
# 1. 查看连接状态
ss -tunapo | awk '{print $2}' | sort | uniq -c | sort -rn
# 2. 查看 TIME_WAIT 连接数
ss -tan state time-wait | wc -l
# 3. 查看端口使用
ss -tlnp
# 4. 检查系统端口范围
sysctl net.ipv4.ip_local_port_range
sysctl net.ipv4.tcp_tw_reuse
根据用户描述的故障现象,判断故障所属类别:
如果无法判断,先引导用户描述具体现象。
询问用户:
根据故障类别,按照上述对应章节的排错思路引导用户:
解决方案应包含:
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub wutz/infra-skills --plugin storage-skills