安装清单

1
pip install --timeout 120 <替换成库名>

1. 获取镜像（三选一）

假设已经安装并配置好了 Docker，那么只需两行命令即可完成深度学习的环境配置，以 dl 镜像为例，拉取：

1
sudo docker pull dockerpull.org/hoperj/quickstart:dl-torch2.5.1-cuda11.8-cudnn9-devel

1
sudo docker pull hoperj/quickstart:dl-torch2.5.1-cuda11.8-cudnn9-devel

1
cd ~/Downloads

1
sudo docker load -i dl.tar

2. 运行容器

1
sudo docker run --gpus all -it --name ai hoperj/quickstart:dl-torch2.5.1-cuda11.8-cudnn9-devel /bin/zsh

如果需要使用 Jupyter，可以使用以下命令：

1
sudo docker run --gpus all -it --name ai -p 8888:8888 hoperj/quickstart:dl-torch2.5.1-cuda11.8-cudnn9-devel /bin/zsh

Tip

常用操作提前看：

• 启动容器：docker start <容器名>
• 运行容器：docker exec -it <容器名> /bin/zsh
  • 容器内退出：Ctrl + D 或 exit。
• 停止容器：docker stop <容器名>
• 删除容器：docker rm <容器名>

卸载旧版本

在安装 Docker Engine 之前，需要卸载所有有冲突的包，运行以下命令：

1
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove $pkg; done

apt-get 可能会报告没有安装这些包，忽略即可。

注意，卸载 Docker 的时候，存储在 /var/lib/docker/ 中的镜像、容器、卷和网络不会被自动删除。如果你想从头开始全新安装，请阅读 Uninstall Docker Engine 部分。

使用 apt 仓库安装

首次安装 Docker Engine 之前，需要设置 Docker 的 apt 仓库。

1. 设置 Docker 的 apt 仓库

   1
   # 添加 Docker 的官方 GPG 密钥：
   2
   sudo apt-get update
   3
   sudo apt-get install ca-certificates curl
   4
   sudo install -m 0755 -d /etc/apt/keyrings
   5
   sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
   6
   sudo chmod a+r /etc/apt/keyrings/docker.asc
   7
   
   8
   # 将仓库添加到 Apt 源：
   9
   echo \
   10
     "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
   11
     $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
   12
     sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
   13
   sudo apt-get update

   Note

   如果你使用的是 Ubuntu 的衍生发行版，例如 Linux Mint，可能需要使用 UBUNTU_CODENAME 而不是 VERSION_CODENAME。

   如果 sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc 执行失败，可以尝试以下命令：

   1
   sudo wget -qO- https://download.docker.com/linux/ubuntu/gpg | sudo tee /etc/apt/keyrings/docker.asc

2. 安装 Docker 包

   1
   sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3. 通过运行 hello-world 镜像来验证安装是否成功

   1
   sudo docker run hello-world

查看本地镜像

1
docker images

列出本地所有的 Docker 镜像，包括仓库名、标签、镜像 ID、创建时间和大小。

拉取镜像

1
docker pull <image_name>:<tag>

例如：

1
docker pull hoperj/quickstart:dl-torch2.5.1-cuda11.8-cudnn9-devel

Note

docker pull 可以从远程仓库更新镜像，如果镜像已存在，则只会拉取更新部分（层），不严谨地类比为 git pull 进行理解。

删除镜像

1
docker rmi <image_id_or_name>

在删除镜像前，请确保没有容器正在使用它。

基础用法

1
docker run --gpus all -it [--rm] <image_name>:<tag>

• --gpus all：允许容器使用主机的所有 GPU 资源（如有）。
• -it：交互式终端。这是两个参数的组合，-i 表示“交互式”（interactive），-t 表示为容器分配一个伪终端（pseudo-TTY）。
• --rm：在容器退出后自动删除容器，避免试验产生无用容器。

以当前使用的深度学习镜像为例：

1
docker run --gpus all -it hoperj/quickstart:dl-torch2.5.1-cuda11.8-cudnn9-devel

Tip

使用 docker run --help 可以查看更多参数的用法。

挂载

如果需要在容器内访问主机的文件，可以使用 -v 参数。

1. 挂载卷（Volume）

   1
   docker run --gpus all -it -v my_volume:/container/path hoperj/quickstart:dl-torch2.5.1-cuda11.8-cudnn9-devel

   • my_volume：Docker 卷的名称。
   • /container/path：容器中的路径。

   挂载卷可让数据在容器删除后仍保留。

2. 挂载主机目录到容器中

   使用绝对路径挂载主机目录到容器中：

   1
   docker run --gpus all -it -v /host/path:/container/path hoperj/quickstart:dl-torch2.5.1-cuda11.8-cudnn9-devel

   • /host/path：主机上的路径。
   • /container/path：容器中的路径。

以当前项目为例，假设已经在主机的 ~/Downloads 文件夹克隆了项目并做了一些修改，那么所需要同步的目录为 ~/Downloads/AI-Guide-and-Demos-zh_CN，想同步到容器的同名文件夹中，对应命令：

1
docker run --gpus all -it -v ~/Downloads/AI-Guide-and-Demos-zh_CN:/workspace/AI-Guide-and-Demos-zh_CN hoperj/quickstart:dl-torch2.5.1-cuda11.8-cudnn9-devel

容器中的 /workspace/AI-Guide-and-Demos-zh_CN 会与主机上的 ~/Downloads/AI-Guide-and-Demos-zh_CN 目录同步，所有更改都会反映到主机的目录中。

在容器中启动 Jupyter Lab

如果需要在容器内启动 Jupyter Lab，并通过主机的浏览器进行访问，可以使用 -p 参数映射端口。Jupyter Lab 默认使用 8888 端口，使用以下命令：

1
docker run --gpus all -it -p 8888:8888 -v ~/Downloads/AI-Guide-and-Demos-zh_CN:/workspace/AI-Guide-and-Demos-zh_CN hoperj/quickstart:dl-torch2.5.1-cuda11.8-cudnn9-devel

• -p 8888:8888 将容器内的 8888 端口映射到主机的 8888 端口。

然后在容器内运行：

1
jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root

现在可以在主机浏览器中访问 http://localhost:8888。

如果需要映射多个端口，比如 7860，那么命令对应如下：

1
docker run --gpus all -it --name ai -p 8888:8888 -p 7860:7860 ...（后续一致）

• 7860 端口在这里对应于 Gradio。

你可以根据实际情况重新指定端口号。

在容器终端内停止

• 使用 Ctrl+D 或输入 exit：退出并停止容器（适用于通过 docker run 启动的情况）。
• 使用 Ctrl+P 然后 Ctrl+Q：仅退出容器的终端（detach），让容器继续在后台运行。

Note

以上的“停止”行为适用于通过 docker run 启动的容器。如果容器是通过 docker start 启动的，Ctrl+D 或 exit 只会退出终端，而不会停止容器。通过 docker ps 可以察觉到这一点。

从主机停止

如果你想从主机停止正在运行的容器，可以使用：

1
docker stop <container_id_or_name>

替换 <container_id_or_name> 为容器的 ID 或名称。

使用 --name 参数

在创建容器时，可以使用 --name 参数为容器指定一个名称。例如：

1
docker run --gpus all -it --name ai hoperj/quickstart:dl-torch2.5.1-cuda11.8-cudnn9-devel

容器被命名为 ai，以后可通过该名称管理容器，不需要记住容器的 ID。

运行 docker ps -a

使用容器名称的命令示例

• 启动容器：

  1
  docker start ai

• 停止容器：

  1
  docker stop ai

• 重新连接到容器：

  1
  docker exec -it ai /bin/zsh

从主机复制文件到容器

1
docker cp /host/path <container_id_or_name>:/container/path

从容器复制文件到主机

1
docker cp <container_id_or_name>:/container/path /host/path

删除指定容器

如果想删除一个容器，可以使用 docker rm 命令：

1
docker rm <container_id_or_name>

删除前需先 stop 容器。

删除所有已退出的容器

1
docker container prune

这将删除所有已停止的容器（请谨慎使用，因为删除后无法恢复，适用于刚安装 Docker “不小心”创建了一堆容器的情况）。

查看容器日志

1
docker logs <container_id_or_name>

可加 -f 参数实时跟随日志输出。

查看容器详细信息

1
docker inspect <container_id_or_name>

输出容器的 JSON 配置信息（环境变量、卷挂载、网络信息等）。

查看容器资源使用情况

1
docker stats

显示所有容器的 CPU、内存、网络和存储 I/O 实时数据。

使用 docker commit 提交容器为镜像

1
docker commit <container_id_or_name> <new_image_name>:<tag>

• <container_id_or_name>：容器的 ID 或名称。
• <new_image_name>：为生成的新镜像指定名称。
• <tag>（可选）：为镜像指定标签，默认是 latest。

假设容器名为 ai，我们在其中安装了一些软件并做了环境修改，现在希望将其保存为新镜像 ai2:latest：

1
docker commit ai ai2:latest

执行成功后，使用 docker images 查看：

1
docker images

此时，ai2:latest 就是基于容器 ai 保存的新镜像，其中包含了所有最近的修改。

导出镜像

使用 docker save 将指定镜像及其历史层打包成 .tar 文件：

1
docker save <image_name>:<tag> -o <output_file.tar>

例如，将刚才创建的 ai2:latest 镜像导出为 quickstart_ai_image.tar：

1
docker save ai2:latest -o quickstart_ai_image.tar

现在我们拥有了一个 quickstart_ai_image.tar 文件，可以将其迁移到其他机器上。

加载镜像

在另一台机器上，使用 docker load 来加载 .tar 文件中的镜像：

1
docker load -i <input_file.tar>

例如：

1
docker load -i quickstart_ai_image.tar

加载完成后可以使用 docker images 查看该镜像已成功导入。

区别于 export/import：

• docker save 与 docker load 针对镜像操作，并保留镜像的元数据（包括标签和镜像分层信息）。
• docker export 与 docker import 针对容器操作，而非镜像本身（此时不需要 commit），将运行后的容器文件系统导出为单一文件系统快照，并不会保留完整的镜像层结构（如果只需要将容器环境打包并在另一端恢复为镜像，可以考虑这一对命令）。

压缩镜像文件

为了减少传输的文件大小，可以对导出的 .tar 文件进行压缩：

1
gzip quickstart_ai_image.tar

生成 quickstart_ai_image.tar.gz 后，在目标机器上解压：

1
gzip -d quickstart_ai_image.tar.gz
2
docker load -i quickstart_ai_image.tar

通过这种方式，可显著减少镜像备份文件的大小（接近 1/2）。

方法 1：使用 sudo

在 Docker 命令前加上 sudo：

1
sudo docker ps

方法 2：将用户添加到 docker 用户组

1. 创建 docker 用户组

   1
   sudo groupadd docker

2. 将当前用户添加到 docker 组

   1
   sudo usermod -aG docker $USER

3. 重新加载用户组设置

   1
   newgrp docker

4. 验证

   运行 Docker 命令，如果不提示权限错误（permission denied），说明配置成功。

   1
   docker ps

方法一：配置镜像

镜像参考：目前国内可用Docker镜像源汇总（截至2024年11月）

临时使用：

直接在原 <image_name>:<tag> 前增加网址，比如：

1
docker pull dockerpull.org/<image_name>:<tag>

快速测试可用性：

1
docker pull dockerpull.org/hello-world

永久使用：

运行以下命令配置文件，如果有一天突然拉（pull）不动了，说明链接挂了需要更新。

1
# 创建目录
2
sudo mkdir -p /etc/docker
3

4
# 写入配置文件
5
sudo tee /etc/docker/daemon.json > /dev/null <<-'EOF'
6
{
7
    "registry-mirrors": [
8
        "https://docker.unsee.tech",
9
        "https://dockerpull.org",
10
        "https://docker.1panel.live",
11
        "https://dockerhub.icu"
12
    ]
13
}
14
EOF
15

16
# 重启 Docker 服务
17
sudo systemctl daemon-reload
18
sudo systemctl restart docker

方法二：设置 HTTP/HTTPS 代理

这一项提供给🪜科学上网的同学进行配置。对于本项目来说，所有文件都会提供网盘链接和对应的国内镜像命令。

1. 创建并编辑 Docker 的系统服务配置文件

   1
   sudo mkdir -p /etc/systemd/system/docker.service.d
   2
   sudo vim /etc/systemd/system/docker.service.d/http-proxy.conf

2. 添加代理配置

   在 http-proxy.conf 文件中添加以下内容（将 http://localhost:7890/ 替换为你自己的代理地址）：

   1
   [Service]
   2
   Environment="HTTP_PROXY=http://localhost:7890/"
   3
   Environment="HTTPS_PROXY=http://localhost:7890/"

   使用 ESC + :wq 回车保存配置。

   如果不熟悉 vim 的操作，也可以使用直接运行（将 http://localhost:7890/ 替换为你自己的代理地址）：

   1
   sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf > /dev/null <<EOF
   2
   [Service]
   3
   Environment="HTTP_PROXY=http://localhost:7890/"
   4
   Environment="HTTPS_PROXY=http://localhost:7890/"
   5
   EOF

3. 重新加载配置并重启 Docker 服务

   1
   sudo systemctl daemon-reload
   2
   sudo systemctl restart docker

更改 Docker 的数据目录

1. 查看当前的磁盘空间

   检查 /var/lib/docker 所在分区的剩余空间：

   1
   sudo df -h /var/lib/docker

2. 选择具有足够空间的目录

   创建文件夹：

   1
   mkdir -p ~/Downloads/Docker && cd ~/Downloads/Docker && pwd

   复制输出。

3. 修改 Docker 的配置文件

   编辑 /etc/docker/daemon.json 文件（如果不存在会自动创建）：

   1
   sudo vim /etc/docker/daemon.json

   添加或修改以下内容（将 Path/to/Docker 替换为你的新数据目录的绝对路径，也就是刚刚复制的输出）：

   1
   {
   2
      "data-root": "Path/to/Docker"
   3
   }

   ESC + :wq保存并退出。

4. 重启 Docker 服务并验证

   1
   sudo systemctl restart docker
   2
   docker info -f '{{ .DockerRootDir}}'