容器用不了 GPU 的排查逻辑
容器里的 GPU 访问是三层拼起来的：宿主机驱动正常、容器工具链已安装并配置为 Docker 运行时、启动命令显式申请了设备。任一层缺失都会失败，而且报错文案各不相同。固定从上到下的顺序排查，比随手改容器参数快得多：先证明宿主机能用卡，再证明 Docker 认识运行时，最后证明容器拿得到设备。
四步排查
四步排查
# 1) 宿主机驱动是否正常
nvidia-smi
# 2) 容器工具链是否安装
nvidia-container-cli --version
dpkg -l | grep -i nvidia-container-toolkit
# 3) Docker 运行时是否配置生效
docker info | grep -i nvidia
# 4) 用最小镜像验证透传（不涉及业务镜像与权重）
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi -L典型报错与原因
| 报错或现象 | 常见原因 |
|---|---|
| 找不到设备驱动选择器 | 未安装容器工具链，或安装后未配置运行时 |
| 运行时未知或守护进程启动失败 | 运行时配置文件写错，Docker 起不来 |
| 容器内驱动版本不足 | 镜像内 CUDA 运行时高于宿主驱动支持上限 |
| 容器能跑但看不到卡 | 启动命令没带设备申请参数，或编排里没声明设备 |
| 只有部分卡可见 | 显式限制了设备列表，与预期不一致 |
典型使用场景
- 新装机器首次跑容器：按顺序验证透传，避免一次引入多个变量
- 升级驱动或 Docker 之后：重新验证运行时配置是否仍然生效
- 业务容器起不来：先用基础镜像排除业务镜像自身的问题
- CI 环境准备：把四步检查写进流水线脚本，提前失败在环境层
- 多人共用机器：确认设备数量与占用情况，避免请求了被占着的卡
核对顺序与判据
| 第一步 | 宿主机能看到卡且版本正常 |
|---|---|
| 第二步 | 工具链已安装，配置文件存在 |
| 第三步 | Docker 信息里能看到运行时已注册 |
| 第四步 | 最小镜像在容器内能列出设备 |
用基础 CUDA 镜像做验证能排除业务镜像的干扰：业务镜像体积大、构建时间久，环境问题在它上面排查成本更高。
用特权模式当临时方案会掩盖真正问题，并带来额外权限风险：只在明确知道后果时使用，且不要写进长期配置。