doc_processer/docs/NVIDIA_DOCKER_REMOTE_TROUBLESHOOTING.md

NVIDIA Docker 驱动版本不匹配 - 远程排查与修复指南

问题说明

错误信息：

nvidia-container-cli: initialization error: nvml error: driver/library version mismatch

这表示 NVIDIA 驱动的用户空间库和内核模块版本不一致。

---

📋 步骤 1：远程诊断

在目标机器上运行诊断脚本：

# 1. 将诊断脚本复制到目标机器
scp diagnose-nvidia-docker.sh user@remote-host:~/

# 2. SSH 登录到目标机器
ssh user@remote-host

# 3. 运行诊断脚本
bash diagnose-nvidia-docker.sh

# 4. 查看生成的诊断报告
cat nvidia-docker-diagnostic-*.txt

# 5. 将报告复制回本地分析（可选）
# 在本地机器运行：
scp user@remote-host:~/nvidia-docker-diagnostic-*.txt ./

诊断脚本会检查：

• ✅ NVIDIA 驱动版本（用户空间）
• ✅ NVIDIA 内核模块版本
• ✅ Docker 状态和配置
• ✅ NVIDIA Container Toolkit 状态
• ✅ 正在使用 GPU 的进程
• ✅ 系统日志中的错误

---

🔧 步骤 2：根据诊断结果修复

场景 A：驱动版本不匹配（最常见）

症状：

用户空间驱动版本: 550.90.07
内核模块版本: 550.54.15

修复方案（按优先级）：

方案 1：重启 Docker 服务 ⚡（最简单，80% 有效）

# SSH 到目标机器
ssh user@remote-host

# 停止所有容器
sudo docker stop $(sudo docker ps -aq)

# 重启 Docker
sudo systemctl restart docker

# 测试
sudo docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi

如果成功：问题解决，跳到步骤 3 启动应用。

如果失败：继续下一个方案。

---

方案 2：重新加载 NVIDIA 内核模块 💪（95% 有效）

# SSH 到目标机器
ssh user@remote-host

# 使用修复脚本（推荐）
sudo bash fix-nvidia-docker.sh

# 或手动执行：
# 1. 停止 Docker 和所有使用 GPU 的进程
sudo systemctl stop docker
sudo killall -9 python python3 nvidia-smi 2>/dev/null || true

# 2. 卸载 NVIDIA 内核模块
sudo rmmod nvidia_uvm 2>/dev/null || true
sudo rmmod nvidia_drm 2>/dev/null || true
sudo rmmod nvidia_modeset 2>/dev/null || true
sudo rmmod nvidia 2>/dev/null || true

# 3. 重新加载模块
sudo modprobe nvidia
sudo modprobe nvidia_uvm
sudo modprobe nvidia_drm
sudo modprobe nvidia_modeset

# 4. 重启 Docker
sudo systemctl restart docker

# 5. 测试
sudo docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi

如果成功：问题解决。

如果失败：内核模块可能被某些进程占用，继续下一个方案。

---

方案 3：重启系统 🔄（99% 有效）

# SSH 到目标机器
ssh user@remote-host

# 重启
sudo reboot

# 等待系统重启（约 1-2 分钟）
sleep 120

# 重新连接并测试
ssh user@remote-host
sudo docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi

注意：重启会中断所有服务，请确认可以接受短暂停机。

---

场景 B：NVIDIA Container Toolkit 问题

症状：

❌ nvidia-container-cli 未安装
或
nvidia-container-cli 版本过旧

修复：

# SSH 到目标机器
ssh user@remote-host

# 更新 NVIDIA Container Toolkit
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)

# 添加仓库（如果未添加）
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# 安装/更新
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# 配置 Docker
sudo nvidia-ctk runtime configure --runtime=docker

# 重启 Docker
sudo systemctl restart docker

# 测试
sudo docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi

---

场景 C：Docker 配置问题

症状：

/etc/docker/daemon.json 不存在
或缺少 nvidia runtime 配置

修复：

# SSH 到目标机器
ssh user@remote-host

# 创建/更新 Docker 配置
sudo tee /etc/docker/daemon.json <<EOF
{
  "runtimes": {
    "nvidia": {
      "path": "nvidia-container-runtime",
      "runtimeArgs": []
    }
  },
  "default-runtime": "nvidia"
}
EOF

# 重启 Docker
sudo systemctl restart docker

# 测试
sudo docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi

---

🚀 步骤 3：启动应用

修复成功后，启动 doc_processer 容器：

# SSH 到目标机器
ssh user@remote-host

# 确保旧容器已停止
sudo docker rm -f doc_processer 2>/dev/null || true

# 启动容器
sudo docker run -d --gpus all --network host \
  --name doc_processer \
  --restart unless-stopped \
  -v /home/yoge/.paddlex:/root/.paddlex:ro \
  -v /home/yoge/.cache/modelscope:/root/.cache/modelscope:ro \
  -v /home/yoge/.cache/huggingface:/root/.cache/huggingface:ro \
  doc_processer:latest

# 检查容器状态
sudo docker ps | grep doc_processer

# 查看日志
sudo docker logs -f doc_processer

---

📊 验证和监控

验证 GPU 访问

# 检查容器内的 GPU
sudo docker exec doc_processer nvidia-smi

# 测试 API
curl http://localhost:8053/health

监控日志

# 实时日志
sudo docker logs -f doc_processer

# 查看最近 100 行
sudo docker logs --tail 100 doc_processer

---

🛠️ 常用远程命令

一键诊断并尝试修复

# 在目标机器创建这个脚本
cat > quick-fix.sh <<'EOF'
#!/bin/bash
set -e

echo "🔧 快速修复脚本"
echo "================"

# 方案 1: 重启 Docker
echo "尝试重启 Docker..."
sudo docker stop $(sudo docker ps -aq) 2>/dev/null || true
sudo systemctl restart docker
sleep 3

if sudo docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi &>/dev/null; then
    echo "✅ 修复成功（重启 Docker）"
    exit 0
fi

# 方案 2: 重载模块
echo "尝试重载 NVIDIA 模块..."
sudo rmmod nvidia_uvm nvidia_drm nvidia_modeset nvidia 2>/dev/null || true
sudo modprobe nvidia nvidia_uvm nvidia_drm nvidia_modeset
sudo systemctl restart docker
sleep 3

if sudo docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi &>/dev/null; then
    echo "✅ 修复成功（重载模块）"
    exit 0
fi

# 方案 3: 需要重启
echo "❌ 自动修复失败，需要重启系统"
echo "执行: sudo reboot"
exit 1
EOF

chmod +x quick-fix.sh
sudo bash quick-fix.sh

SSH 隧道（如果需要本地访问远程服务）

# 在本地机器运行
ssh -L 8053:localhost:8053 user@remote-host

# 现在可以在本地访问
curl http://localhost:8053/health

---

📝 故障排除检查清单

• 运行 diagnose-nvidia-docker.sh 生成完整诊断报告
• 检查驱动版本是否一致（用户空间 vs 内核模块）
• 检查 NVIDIA Container Toolkit 是否安装
• 检查 /etc/docker/daemon.json 配置
• 尝试重启 Docker 服务
• 尝试重新加载 NVIDIA 内核模块
• 检查是否有进程占用 GPU
• 查看 Docker 日志：journalctl -u docker -n 100
• 最后手段：重启系统

---

💡 预防措施

1. 固定 NVIDIA 驱动版本

# 锁定当前驱动版本
sudo apt-mark hold nvidia-driver-*

# 查看已锁定的包
apt-mark showhold

2. 自动重启 Docker（驱动更新后）

# 创建 systemd 服务
sudo tee /etc/systemd/system/nvidia-docker-restart.service <<EOF
[Unit]
Description=Restart Docker after NVIDIA driver update
After=nvidia-persistenced.service

[Service]
Type=oneshot
ExecStart=/bin/systemctl restart docker

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable nvidia-docker-restart.service

3. 监控脚本

# 创建监控脚本
cat > /usr/local/bin/check-nvidia-docker.sh <<'EOF'
#!/bin/bash
if ! docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi &>/dev/null; then
    echo "$(date): NVIDIA Docker 访问失败" >> /var/log/nvidia-docker-check.log
    systemctl restart docker
fi
EOF

chmod +x /usr/local/bin/check-nvidia-docker.sh

# 添加到 crontab（每 5 分钟检查）
echo "*/5 * * * * /usr/local/bin/check-nvidia-docker.sh" | sudo crontab -

---

📞 需要帮助？

如果以上方案都无法解决，请提供：

1. 诊断报告：nvidia-docker-diagnostic-*.txt 的完整内容
2. 错误日志：sudo docker logs doc_processer
3. 系统信息：

   nvidia-smi
   docker --version
   nvidia-container-cli --version
   uname -a
   

---

快速参考

命令	说明
bash diagnose-nvidia-docker.sh	生成诊断报告
sudo bash fix-nvidia-docker.sh	自动修复脚本
sudo systemctl restart docker	重启 Docker
sudo reboot	重启系统
docker logs -f doc_processer	查看应用日志
docker exec doc_processer nvidia-smi	检查容器内 GPU