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

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

一、背景

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

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

二、基础环境确认

Docker 是否安装

bash 复制代码

docker -v

NVIDIA 驱动是否正常

bash 复制代码

nvidia-smi

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

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

bash 复制代码

docker run -d \
    --name my_pytorch_jupyter \
    -p 8888: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，类似：

bash 复制代码

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

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

bash 复制代码

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

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

bash 复制代码

docker start -ai my_pytorch_container

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

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

❗ 问题 1：Jupyter 不存在

bash 复制代码

exec: jupyter: not found

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

复制代码

pip install notebook

或启动时：

bash 复制代码

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

❗ 问题 2：网络问题

bash 复制代码

Could not handshake: Error in the pull function. [IP: 185.199.109.153 443] E: Failed to fetch https://nvidia.github.io/libnvidia-container/stable/deb/amd64/./nvidia-docker2_2.14.0-1_all.deb Could not handshake: Error in the pull function. [IP: 185.199.109.153 443] E: Unable to fetch some archives, maybe run apt-get update or try with --fix-missing?

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

ini 复制代码

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

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

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

sql 复制代码

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 包手动安装：

bash 复制代码

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：端口被占用

bash 复制代码

address already in use

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

bash 复制代码

sudo lsof -i :8888

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

bash 复制代码

COMMAND   PID  USER   FD   TYPE  DEVICE SIZE/OFF NODE NAME
python3  1234  root    4u  IPv4  123456      0t0  TCP *:8888 (LISTEN)

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

bash 复制代码

sudo kill -9 1234

或更换端口：

bash 复制代码

-p 8899:8888

❗ 问题 4：GPU 不可用

arduino 复制代码

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 驱动

bash 复制代码

nvidia-smi

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

步骤2️⃣ ：安装 NVIDIA Container Toolkit

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

bash 复制代码

docker run -d --gpus all --name my_pytorch_jupyter \
    -p 8899:8888 \
    -v /home/youruser/my_pytorch:/workspace \
    -w /workspace \
    my_pytorch_jupyter_image

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

安装命令：

bash 复制代码

# 设置 NVIDIA Docker 仓库
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt update
sudo apt install -y nvidia-docker2
sudo systemctl restart docker

然后再次尝试：

bash 复制代码

docker run --rm --gpus all 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 权限错误

bash 复制代码

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

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

bash 复制代码

sudo usermod -aG docker $USER
sudo usermod -aG video $USER

然后注销并重新登录。

五、GPU 问题核心分析

Step 1. Docker runtime 未配置

bash 复制代码

docker info | grep Runtimes

输出：

Runtimes: runc

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

Step 2. 正确配置 NVIDIA runtime

编辑：

bash 复制代码

sudo nano /etc/docker/daemon.json

# 写入：

{
    "runtimes": {
        "nvidia": {
            "path": "nvidia-container-runtime",
            "runtimeArgs": []
        }
    }
}

Step 3. 重启 Docker

bash 复制代码

sudo systemctl restart docker

Step 4. 测试 GPU

bash 复制代码

docker run --rm --gpus all nvidia/cuda:12.1-base nvidia-smi