故障排查
已发行
系统化的故障排查方法论，从问题现象出发，快速定位根因并解决。
系统化排查流程
部署问题
Pod 无法启动
# 检查 Pod 状态
kubectl get pods -n hami-system
# 查看事件
kubectl describe pod <pod-name> -n hami-system
# 常见原因
# - 镜像拉取失败（ImagePullBackOff）
# - 资源不足（Pending）
# - 节点选择器不匹配Webhook 证书错误
# 检查证书
kubectl get secret -n hami-system -l app=hami-webhook
# 检查 Webhook 配置
kubectl get mutatingwebhookconfiguration -l app=hami-webhook -o yaml
# 重新生成证书（使用 cert-manager）
kubectl delete certificate -n hami-system hami-webhook-cert
# cert-manager 会自动重新签发调度器健康检查失败
# 检查健康端点
kubectl exec -n hami-system deployment/hami-scheduler -- wget -qO- http://localhost:8080/healthz
# 查看日志
kubectl logs -n hami-system deployment/hami-scheduler --tail=100设备插件注册失败
# 检查设备插件状态
kubectl get pods -n hami-system -l app=hami-device-plugin
# 查看设备插件日志
kubectl logs -n hami-system daemonset/hami-device-plugin
# 常见原因
# - kubelet socket 不存在或权限不对
# - NVML 初始化失败（驱动问题）
# - 设备路径不存在调度问题
Pod 一直 Pending
# 1. 查看 Pod 事件
kubectl describe pod <pod-name>
# 2. 查看调度器日志
kubectl logs -n hami-system deployment/hami-scheduler | grep <pod-name>
# 3. 增加日志级别（v5 显示设备细节）
kubectl edit deployment -n hami-system hami-scheduler
# 添加 --v=5 参数常见调度失败原因
| 错误信息 | 原因 | 解决方案 |
|---|---|---|
| GPU memory insufficient | 显存不足 | 减少请求量或增加 GPU |
| device type mismatch | 设备类型不匹配 | 检查 hami.io/gpu-type 注解 |
| quota exceeded | 命名空间配额超限 | 增加 ResourceQuota 或减少请求 |
| no healthy device | 设备不健康 | 检查 GPU 状态和驱动 |
| node locked | 节点锁未释放 | 等待或手动清理节点注解 |
节点过滤失败
# 查看节点设备注解
kubectl get node <node-name> -o jsonpath='{.metadata.annotations}' | jq .
# 检查节点 GPU 资源
kubectl describe node <node-name> | grep -A 20 "Allocatable"
# 检查 GPU 健康状态
nvidia-smi -q -d HEALTH资源分配问题
资源请求无法满足
# 查看集群 GPU 资源总量
kubectl get nodes -o json | jq '.items[].status.allocatable'
# 查看已分配资源
kubectl get pods -A -o json | jq '[.items[] | select(.spec.containers[].resources.limits["nvidia.com/gpu"] != null)]'显存/算力分配不正确
# 查看 Pod 注解中的分配信息
kubectl get pod <pod-name> -o jsonpath='{.metadata.annotations}' | jq .
# 检查容器内可见的 GPU
kubectl exec <pod-name> -- nvidia-smi
kubectl exec <pod-name> -- env | grep CUDA设备问题
GPU 不被识别
# 在 GPU 节点上检查
nvidia-smi # 驱动是否正常
nvidia-smi -q -d P2P # GPU 间通信
# 检查设备文件
ls -la /dev/nvidia*
# 检查容器运行时
nvidia-ctk --version设备健康检查失败
# 检查 GPU 健康状态
nvidia-smi -q -d HEALTH
# 查看设备插件健康检查日志
kubectl logs -n hami-system daemonset/hami-device-plugin | grep -i health
# 手动触发节点清理
kubectl annotate node <node-name> hami.io/device-cleanup="true"硬件兼容性
| 问题 | 检查 | 解决 |
|---|---|---|
| 驱动版本过低 | nvidia-smi | 升级到 >= 510.47 |
| CUDA 版本不兼容 | nvcc --version | 升级到 >= 11.6 |
| MIG 模式不匹配 | nvidia-smi -mig | 检查 MIG 配置 |
| NVML 初始化失败 | 设备插件日志 | 检查驱动安装 |
运行时问题
容器内看不到 GPU
# 检查环境变量
kubectl exec <pod-name> -- env | grep -E "CUDA|NVIDIA"
# 检查设备挂载
kubectl exec <pod-name> -- ls -la /dev/nvidia*
# 检查注解
kubectl get pod <pod-name> -o jsonpath='{.metadata.annotations}' | jq .CUDA 错误
# 常见 CUDA 错误
# CUDA_ERROR_OUT_OF_MEMORY → 显存不足，减少 nvidia.com/gpumem
# CUDA_ERROR_NO_DEVICE → 设备不可见，检查设备插件
# CUDA_ERROR_INVALID_DEVICE → 设备 ID 错误，检查 CUDA_VISIBLE_DEVICES调试工具
kubectl 命令集
# 查看所有 HAMi 组件状态
kubectl get all -n hami-system
# 查看调度器日志（带时间戳）
kubectl logs -n hami-system deployment/hami-scheduler --timestamps --tail=200
# 查看设备插件日志
kubectl logs -n hami-system daemonset/hami-device-plugin -c nvidia --tail=200
# 查看 Webhook 日志
kubectl logs -n hami-system deployment/hami-webhook --tail=200
# 查看节点设备注解
kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations.*}{"\n"}{end}'性能分析
# 启用 pprof（需要在启动参数中添加）
kubectl port-forward -n hami-system deployment/hami-scheduler 6060:6060
# 查看 CPU profile
go tool pprof http://localhost:6060/debug/pprof/profile
# 查看内存 profile
go tool pprof http://localhost:6060/debug/pprof/heap标准化错误码
| 错误码 | 含义 | 排查方向 |
|---|---|---|
SCHED_INSUFFICIENT_GPU_MEMORY | 显存不足 | 减少请求或增加 GPU |
SCHED_DEVICE_TYPE_MISMATCH | 设备类型不匹配 | 检查注解 |
SCHED_QUOTA_EXCEEDED | 配额超限 | 调整 ResourceQuota |
SCHED_NO_HEALTHY_DEVICE | 无健康设备 | 检查 GPU 状态 |
SCHED_NODE_LOCKED | 节点锁定 | 等待或清理锁 |
DP_ALLOCATE_FAILED | 设备分配失败 | 检查设备插件日志 |
DP_NVML_INIT_FAILED | NVML 初始化失败 | 检查驱动 |
WH_QUOTA_CHECK_FAILED | 配额检查失败 | 检查 ResourceQuota |
WH_INVALID_RESOURCE | 无效资源请求 | 检查资源字段 |
社区支持
- GitHub Issues：https://github.com/project-hami/hami/issues
- Discord：HAMi 社区 Discord
提交 Issue 时建议附上：
# 收集诊断信息
kubectl cluster-info
kubectl get nodes -o wide
kubectl get pods -n hami-system -o wide
kubectl logs -n hami-system deployment/hami-scheduler --tail=100
kubectl describe pod <problematic-pod>小结
本章介绍了 HAMi 的故障排查体系：
- 系统化流程：从问题现象到根因定位
- 部署问题：Pod 启动失败、证书错误、注册失败
- 调度问题：Pending、过滤失败、评分异常
- 设备问题：GPU 不识别、健康检查失败、兼容性
- 调试工具：kubectl 命令集、pprof 性能分析
- 错误码标准化：错误码辅助快速定位