服务器Docker实例化容器 -- 踩坑大全

Ubuntu 22.04 + Docker + PyTorch + Jupyter + GPU 环境搭建踩坑总结

一、背景

在服务器上使用 Docker 部署 PyTorch 环境，并通过 Jupyter Notebook 进行开发，目标是：

1. 使用 pytorch/pytorch:2.1.0-cuda12.1-cudnn8-devel
2. 支持 GPU 加速
3. 挂载本地项目目录
4. 浏览器访问 Jupyter

二、基础环境确认

1. Docker 是否安装

docker-v

2. NVIDIA 驱动是否正常

nvidia-smi

✅ 正常应显示 GPU 信息
❌ 报错说明驱动未安装或异常

三、Docker 容器运行（基础版）

dockerrun-d\--namemy_pytorch_jupyter\-p8888:8888\-v/home/youruser/my_pytorch:/workspace\-w/workspace\pytorch/pytorch:2.1.0-cuda12.1-cudnn8-devel\jupyter notebook--ip=0.0.0.0--port=8888--no-browser --allow-root

解释：

• –gpus all：如果服务器有 GPU
• -it：交互式终端
• -p 8888:8888：将容器 8888 端口映射到宿主机 8888 端口（Jupyter 默认端口）
• -v /home/youruser/my_pytorch:/workspace：挂载目录
• –name my_pytorch_container：给容器起名字
• –ip=0.0.0.0：允许外部访问
• –no-browser：容器里没有浏览器
• –allow-root：以 root 运行

命令执行后会输出一个 URL，类似：

http://127.0.0.1:8888/?token=xxxx

你可以把 127.0.0.1 换成服务器 IP，在浏览器访问：

http://服务器IP:8888/?token=xxxx

✅ 小贴士
下次启动容器，可以用

dockerstart-aimy_pytorch_container

数据都保存在 /home/youruser/my_pytorch 下，容器删除也不会丢失

四、常见问题汇总（重点）

❗ 问题 1：Jupyter 不存在

exec: jupyter: not found

原因
官方 PyTorch 镜像 不包含 Jupyter
解决

pip install notebook

或启动时：

bash-c"pip install notebook && jupyter notebook ..."

❗ 问题 2：网络问题

Could not handshake: Errorinthe pull function.[IP:185.199.109.153443]E: Failed to fetch https://nvidia.github.io/libnvidia-container/stable/deb/amd64/./nvidia-docker2_2.14.0-1_all.deb Could not handshake: Errorinthe pull function.[IP:185.199.109.153443]E: Unable to fetch some archives, maybe runapt-getupdate or try with --fix-missing?

方法 1：使用代理或 VPN
如果服务器可以使用代理，设置环境变量：

export http_proxy="http://your-proxy:port" export https_proxy="http://your-proxy:port"

然后再执行安装命令。
这种方法适合有稳定代理的环境。

方法 2：用--fix-missing重试
APT 提示可以尝试 --fix-missing：

sudo apt update --fix-missing sudo apt install -y nvidia-docker2

有时网络抖动可以通过重试解决。

方法 3：使用国内镜像
镜像加速：
NVIDIA 官方镜像仓库可以替换成国内镜像（比如清华大学开源镜像站）
在/etc/apt/sources.list.d/nvidia-docker.list中，把https://nvidia.github.io/换成国内镜像（需要查找可用镜像，国内可用的镜像不多）。
或者直接下载 DEB 包手动安装：

wget https://github.com/NVIDIA/nvidia-docker/releases/download/v2.14.0/nvidia-docker2_2.14.0-1_all.deb sudo dpkg -i nvidia-docker2_2.14.0-1_all.deb sudo systemctl restart docker

如果 wget 也无法直接下载，可以先在本地电脑下载，然后通过 scp 上传到服务器。

❗ 问题 3：端口被占用

address alreadyinuse

解决：查看哪个进程占用了 8888

sudolsof-i:8888

• 会显示占用端口的进程，例如：

COMMAND PIDUSERFD TYPE DEVICE SIZE/OFF NODE NAME python31234root 4u IPv41234560t0 TCP *:8888(LISTEN)

• 可以选择停止占用的进程：

sudokill-91234

• 或更换端口：

-p8899:8888

❗ 问题 4：GPU 不可用

WARNING: The NVIDIA Driver was not detected. GPU functionality will not be available. Use the NVIDIA Container Toolkit to start this container with GPU support; see https://docs.nvidia.com/datacenter/cloud-native/ .

原因：容器检测不到 GPU 驱动
步骤1️⃣ ：确认宿主机有 NVIDIA GPU 驱动

nvidia-smi

• 如果能看到 GPU 型号和驱动版本，说明宿主机驱动正确
• 如果报错 NVIDIA-SMI has failed，说明驱动没装好，需要先安装 GPU 驱动

步骤2️⃣ ：安装 NVIDIA Container Toolkit

• 让 Docker 容器可以访问宿主机的 GPU
• Ubuntu 22.04 推荐手动安装 DEB 包方式（国内可下载）
• 安装完成后，启动容器要加参数：

dockerrun-d--gpusall--namemy_pytorch_jupyter\-p8899:8888\-v/home/youruser/my_pytorch:/workspace\-w/workspace\my_pytorch_jupyter_image

• – gpus all 表示容器可以使用所有可用 GPU

安装命令：

# 设置 NVIDIA Docker 仓库distribution=$(./etc/os-release;echo$ID$VERSION_ID)curl-s-Lhttps://nvidia.github.io/nvidia-docker/gpgkey|sudoapt-keyadd-curl-s-Lhttps://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list|sudotee/etc/apt/sources.list.d/nvidia-docker.listsudoaptupdatesudoaptinstall-ynvidia-docker2sudosystemctl restartdocker

然后再次尝试：

dockerrun--rm--gpusall nvidia/cuda:12.1-base nvidia-smi

如果能看到 GPU 信息，说明配置成功。

✅ 说明

• 系统检测：自动识别你的 Ubuntu/Debian 版本
• 安装 curl：保证下载仓库文件不出错
• 添加 NVIDIA Docker 仓库：让 apt 可以找到 nvidia-docker2
• 安装 nvidia-docker2 并重启 Docker：启用 GPU 支持
• 测试 GPU：nvidia-smi 输出 GPU 信息就表示成功

❗ 问题 5（核心）：nvml 权限错误

nvidia-container-cli: initialization error: nvml error: insufficient permissions

如果你不是 root 用户，需要加用户组：

sudousermod-aGdocker$USERsudousermod-aGvideo$USER

然后 注销并重新登录。

五、GPU 问题核心分析

Step 1. Docker runtime 未配置

dockerinfo|grepRuntimes

输出：

Runtimes: runc

❌ 说明没有 nvidia ，进行下一步配置

Step 2. 正确配置 NVIDIA runtime

编辑：

sudonano/etc/docker/daemon.json# 写入：{"runtimes":{"nvidia":{"path":"nvidia-container-runtime","runtimeArgs":[]}}}

Step 3. 重启 Docker

sudosystemctl restartdocker

Step 4. 测试 GPU

dockerrun--rm--gpusall nvidia/cuda:12.1-base nvidia-smi