NVIDIA驱动、CUDA与容器环境逐层排错手册

适用目标

解决nvidia-smi正常但容器看不到GPU、CUDA版本不匹配和框架启动失败。本文面向已经能够使用Linux命令行、但需要把环境做成可重复交付的工程人员。操作前先备份现有配置，并记录硬件型号、系统内核和当前软件版本。

准备工作

确认宿主机内核、驱动版本、Docker与NVIDIA Container Toolkit。建议建立独立测试目录和变更记录，所有命令、镜像标签、配置文件与测试结果都写入同一份实施日志。生产机器不要边排错边无记录升级。

实施步骤

先在宿主机运行nvidia-smi并记录驱动版本。

检查docker info与容器运行时。

用官方CUDA基础镜像执行nvidia-smi。

在容器中核对libcuda.so与框架CUDA版本。

运行最小矩阵乘法而不是直接启动大模型。每完成一步立即保存输出，出现异常时只回退最近一项变更。

常见误区

不要把宿主机CUDA Toolkit版本等同于驱动能力。

不要在容器里安装另一套内核驱动。

避免未经记录同时升级驱动、框架和镜像。如果现象与预期不符，应缩小到最小复现环境，不要直接在完整业务栈中猜测原因。

验证与验收

容器可识别全部GPU，PyTorch返回正确设备数量，矩阵计算通过，重启后配置仍有效。除一次性功能验证外，至少重复三次并进行重启复测。性能类任务必须固定输入、输出和并发口径，同时记录P50、P95和失败率。

交付清单

交付物应包含版本清单、配置文件、启动与停止命令、监控入口、已知限制、故障处理步骤和回滚方法。只有其他工程师能够依据文档重新完成部署，教程才算真正可执行。