---

在 Debian 上安装 Docker 详细指南

引言：拥抱容器化技术，在 Debian 上部署 Docker

在当今快速发展的软件开发和部署领域，容器化技术已经成为不可或缺的一部分。它提供了一种轻便、可移植、自给自足的方式来打包、分发和运行应用程序，从而极大地简化了开发、测试和生产环境之间的一致性问题。而在众多容器化工具中，Docker 无疑是最受欢迎和广泛使用的。

Debian 作为一款以稳定性、自由性和广泛社区支持著称的 Linux 发行版，是许多服务器和开发者工作站的首选操作系统。将强大的 Docker 容器平台部署在稳定可靠的 Debian 系统上，可以为应用程序的开发、测试和生产提供一个坚实且高效的基础。

本文将为您提供一份详尽的指南，手把手教您如何在 Debian 系统上安装 Docker。我们将探讨几种不同的安装方法，重点介绍推荐的官方仓库安装方式，并详细讲解安装后的配置、验证以及一些常见问题的排查。无论您是 Docker 新手还是有一定经验的用户，希望本文都能帮助您顺利在 Debian 上搭建起您的 Docker 环境。

在开始之前，请确保您拥有一个运行 Debian 系统的服务器或虚拟机，并且具备执行管理命令（如 sudo）的权限，以及稳定的互联网连接。

准备工作：在安装 Docker 前需要了解和准备什么？

在正式开始安装 Docker 之前，了解一些背景信息和做好必要的准备是非常重要的。

1. 选择合适的 Debian 版本

Docker Engine 支持多个 Debian 版本。通常推荐在 Debian 的稳定（Stable）版本上安装，以获得最佳的稳定性和支持。撰写本文时，Debian 12 (Bookworm) 和 Debian 11 (Bullseye) 是主流的稳定版本。Docker 官方通常会支持当前稳定版及前一个稳定版。在安装前，建议查阅 Docker 官方文档，确认您的 Debian 版本是否在支持列表中。您可以通过以下命令查看您的 Debian 版本代号：

bash
lsb_release -cs

或者查看 /etc/os-release 文件：

bash
cat /etc/os-release

例如，如果您看到 VERSION_CODENAME=bookworm，则您的版本代号是 bookworm。

2. 确保系统是最新状态

在安装任何新软件之前，更新系统软件包列表并升级现有软件包是一个良好的习惯。这可以确保您拥有最新的系统组件和依赖，避免潜在的兼容性问题。

打开终端，执行以下命令：

bash
sudo apt update
sudo apt upgrade -y

sudo apt update 会从配置的软件源下载最新的软件包列表信息。
sudo apt upgrade -y 会将系统中所有已安装的软件包升级到可用新版本（-y 参数表示自动确认升级提示）。

3. 具备必要的权限

安装 Docker 需要管理员权限。您可以使用 root 用户执行所有命令，但更安全和推荐的做法是使用一个具有 sudo 权限的非 root 用户。请确保您当前登录的用户属于 sudo 组，或者您知道 root 用户的密码。

4. 了解 Docker 的核心组件

安装 Docker Engine 通常会包含以下几个主要组件：

• Docker Daemon (dockerd)：Docker 守护进程，运行在主机上，负责构建、运行和管理 Docker 容器。
• Docker CLI (docker)：Docker 命令行接口工具，用户通过它与 Docker Daemon 进行交互。
• containerd：一个工业标准的容器运行时，Docker Engine 使用它来执行容器。
• Docker Compose (可选，但强烈推荐)：用于定义和运行多容器 Docker 应用程序的工具。虽然现在通常作为插件安装 (docker-compose-plugin)，但在复杂应用场景中非常有用。
• Docker Buildx (可选)：一个 CLI 插件，用于构建增强的构建功能，如多平台镜像构建。通常作为插件安装 (docker-buildx-plugin)。

官方仓库安装方式通常会一并安装 docker-ce (社区版 Docker Engine)、docker-ce-cli (CLI 工具)、containerd.io 以及相应的插件。

5. 磁盘空间考虑

Docker 镜像和容器会占用磁盘空间，尤其是在拉取多个大型镜像或运行大量容器后。请确保您的系统有足够的可用磁盘空间。默认情况下，Docker 的数据存储在 /var/lib/docker 目录下。

安装 Docker 的方法

在 Debian 上安装 Docker 有几种常见的方法。官方推荐且最常用的是通过 Docker 官方提供的 APT 仓库进行安装。此外，还有通过便捷脚本安装和手动安装等方式，但各有优缺点。

我们将重点介绍通过官方仓库安装这种最推荐的方式。

方法一：通过 Docker 官方仓库安装（推荐）

通过 Docker 官方仓库安装 Docker 是最推荐的方法，因为它能确保您安装的是最新版本、获得及时的安全更新，并且安装过程遵循标准的包管理流程。

这个过程主要包括：
1. 安装必要的软件包，以便通过 HTTPS 使用 APT 仓库。
2. 添加 Docker 官方的 GPG 密钥，以验证软件包的真实性。
3. 设置 Docker 的 APT 仓库。
4. 更新 APT 包索引。
5. 安装 Docker Engine、CLI 和 Containerd。

下面是详细的步骤：

步骤 1：更新现有软件包并安装必要工具

首先，更新您的 APT 软件包列表，并安装一些必要的软件包，这些包用于允许 apt 通过 HTTPS 安全地使用仓库，并管理 GPG 密钥。

bash
sudo apt update
sudo apt install ca-certificates curl gnupg -y

• ca-certificates: 包含 CA 证书，用于验证 HTTPS 连接的合法性。
• curl: 一个命令行工具，用于传输数据，这里用来下载 GPG 密钥。
• gnupg: GNU Privacy Guard，用于处理 GPG 密钥，这里用来添加和管理 Docker 的 GPG 密钥。

步骤 2：添加 Docker 的官方 GPG 密钥

为了确保您下载的 Docker 软件包是来自 Docker 官方且未被篡改，您需要下载并添加 Docker 官方的 GPG 密钥。APT 会使用这个密钥来验证软件包的数字签名。

首先，创建一个用于存放 APT 密钥环的目录（如果它不存在的话）：

bash
sudo install -m 0755 -d /etc/apt/keyrings

然后，下载 Docker 官方 GPG 密钥，并将其保存到新创建的密钥环目录中。

bash
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

• curl -fsSL ...: 使用 curl 下载 GPG 密钥文件。-f 静默失败，-s 静默进度显示，-S 在出错时显示错误，-L 跟随重定向。
• |: 管道符，将 curl 的输出作为输入传递给下一个命令。
• sudo gpg --dearmor -o ...: 使用 gpg 命令将 ASCII armored 格式的密钥转换为二进制格式（--dearmor），并使用 sudo 将其输出到指定的 /etc/apt/keyrings/docker.gpg 文件。

设置刚刚添加的 GPG 密钥文件的权限，使其对所有人可读：

bash
sudo chmod a+r /etc/apt/keyrings/docker.gpg

这是 APT 读取密钥文件所必需的权限设置。

步骤 3：设置 Docker 的 APT 仓库

接下来，您需要将 Docker 的 APT 仓库添加到您的 APT 源列表中。这将告诉 APT 包管理器去哪里查找 Docker 软件包。

您需要知道您的 Debian 版本代号（如 bookworm 或 bullseye）。如果您还不确定，可以使用 lsb_release -cs 命令获取。

使用以下命令将 Docker 的仓库信息添加到 /etc/apt/sources.list.d/docker.list 文件中：

bash
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

让我们分解一下这个复杂的命令：

• echo "...": 打印仓库配置字符串。
  • deb: 表示这是一个二进制软件包仓库。
  • [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg]: 这是 APT 的选项。
    • arch=$(dpkg --print-architecture): 指定仓库适用的架构。$(dpkg --print-architecture) 会自动检测并输出您系统的架构（如 amd64）。
    • signed-by=/etc/apt/keyrings/docker.gpg: 指定用于验证此仓库中软件包签名的 GPG 密钥文件路径。这确保了软件包来自一个可信的来源。
  • https://download.docker.com/linux/debian: 这是 Docker 官方仓库的 URL。
  • $(lsb_release -cs): 这部分会被替换为您的 Debian 版本代号（如 bookworm）。APT 会根据这个代号查找对应版本的软件包。
  • stable: 指定使用 stable 版本的 Docker 软件包。Docker 还提供 test 和 nightly 仓库，但 stable 是最推荐用于生产或日常使用的。
• |: 管道符，将 echo 命令的输出传递给 tee 命令。
• sudo tee /etc/apt/sources.list.d/docker.list: 使用 tee 命令以 root 权限将输入（即仓库配置字符串）写入到 /etc/apt/sources.list.d/docker.list 文件中。使用 tee 而不是简单的重定向 (>) 是因为重定向是在当前用户的权限下执行的，而 /etc/apt/sources.list.d/ 目录通常需要 root 权限才能写入。tee 命令可以与 sudo 结合使用来解决这个问题。
• > /dev/null: 将 tee 命令的标准输出（它默认也会输出到屏幕）重定向到 /dev/null，以避免在终端显示配置字符串。

步骤 4：更新 APT 包索引

在添加了新的仓库后，您需要再次更新 APT 的软件包索引，以便 APT 能够识别并从 Docker 仓库获取软件包信息。

bash
sudo apt update

执行此命令后，APT 会连接到 Docker 的官方仓库，下载其中包含的软件包列表和元数据。

5. 安装 Docker Engine、CLI 和 Containerd

现在，您可以安装 Docker 的核心组件了。执行以下命令：

bash
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

• docker-ce: Docker Community Edition，这是 Docker Engine 本身。
• docker-ce-cli: Docker 命令行客户端。
• containerd.io: Docker Engine 依赖的标准容器运行时。
• docker-buildx-plugin: Docker Buildx 插件，用于构建多平台镜像。
• docker-compose-plugin: Docker Compose 插件，用于定义和运行多容器应用。

安装过程中，APT 会计算依赖关系并下载所有必需的软件包。-y 参数会自动确认安装过程中的提示。

至此，您已经成功通过官方仓库在 Debian 上安装了 Docker Engine。

方法二：使用便捷脚本安装（不推荐用于生产）

Docker 也提供了一个便捷脚本，可以在几分钟内快速安装 Docker。这个脚本适用于开发或测试环境，但不推荐用于生产环境，因为它自动化了安装过程，缺乏透明度，且无法方便地安装特定版本的 Docker。

bash
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

这个脚本会检测您的操作系统和架构，然后配置仓库并安装 Docker Engine、CLI 和 Containerd。脚本执行完毕后，Docker 服务会自动启动。

警告： 直接运行从互联网下载的脚本存在安全风险。在生产环境或对安全性要求高的场景下，强烈建议使用官方仓库方式。

脚本的一个副作用是它会尝试将当前非 root 用户添加到 docker 组（我们稍后会详细介绍这个组），但这需要注销并重新登录才能生效。

方法三：手动下载安装包（适用于特定场景）

如果您需要在没有网络连接的环境中安装 Docker，或者需要安装非常特定、官方仓库不直接提供的版本，可以手动下载 Docker Engine、CLI 和 Containerd 的 .deb 安装包，然后使用 dpkg 命令进行安装。

您可以从 https://download.docker.com/linux/debian/dists/<debian-codename>/stable/pool/stable/<architecture>/ 路径下找到对应的 .deb 文件。例如，对于 Debian Bookworm (amd64)，您可以在 https://download.docker.com/linux/debian/dists/bookworm/stable/pool/stable/amd64/ 找到。

下载所有必需的 .deb 文件后，在终端中切换到文件所在的目录，然后执行：

bash
sudo dpkg -i *.deb

注意： 使用 dpkg -i 安装不会自动解决依赖关系。您可能需要手动下载并安装所有依赖包，或者在安装失败后运行 sudo apt --fix-broken install 来尝试解决依赖问题（这需要网络连接）。因此，这种方法只适用于非常特殊的场景。

安装后的验证

安装完成后，您应该验证 Docker Engine 是否正确安装并且正在运行。

1. 检查 Docker 服务状态

Docker Engine 作为系统服务运行。您可以使用 systemctl 命令来检查其状态：

bash
sudo systemctl status docker

如果 Docker 正在运行，您会看到类似 Active: active (running) 的输出。如果服务没有启动，您可以使用 sudo systemctl start docker 命令来启动它。

2. 运行 hello-world 容器

验证安装最简单也最常用的方法是运行 Docker 官方提供的 hello-world 容器。这个小巧的容器会拉取一个测试镜像，并在容器中运行一个简单的程序，输出一段欢迎信息，然后退出。

bash
sudo docker run hello-world

首次运行此命令时，Docker 会从 Docker Hub 下载 hello-world 镜像（如果本地没有的话）。然后，它会基于这个镜像创建一个并运行一个新容器。如果一切正常，您将在终端看到类似以下的输出：

“`
Unable to find image ‘hello-world:latest’ locally
latest: Pulling from library/hello-world
… (下载进度) …
Digest: sha256:…
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
1. The Docker client connected to the Docker daemon.
2. The Docker daemon pulled the “hello-world” image from the Docker Hub (if it did not already have it locally).
3. The Docker daemon created a new container from that image which runs the executable that produces the output you are currently reading.
4. The Docker daemon streamed that output to the Docker client, which sent it to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
$ docker run -it ubuntu bash
“`

如果您看到这段输出，恭喜您，Docker 已成功安装并在您的 Debian 系统上正常工作！

安装后的重要配置

默认安装完成后，Docker Engine 已经可以工作，但为了方便日常使用和提高安全性，通常还需要进行一些额外的配置。

1. 让非 root 用户管理 Docker

默认情况下，docker 命令需要 sudo 权限才能运行，因为它需要与 Docker Daemon（作为 root 用户运行）进行通信。这意味着每次执行 Docker 命令（如 docker run, docker ps 等）时，您都需要在前面加上 sudo。这非常不方便，并且存在一定的安全风险（意外以 root 权限执行命令）。

Docker 安装时会创建一个名为 docker 的 Unix 用户组。属于 docker 组的用户可以无需 sudo 权限即可运行 Docker 命令。为了让您的非 root 用户能够直接使用 docker 命令，您需要将该用户添加到 docker 组。

假设您的用户名是 your_username，执行以下命令将用户添加到 docker 组：

bash
sudo usermod -aG docker your_username

• sudo: 以 root 权限执行命令。
• usermod: 修改用户账户的命令。
• -aG docker: 将用户添加到 docker 组 (-a 表示追加，-G 指定组)。
• your_username: 替换为您实际的用户名。您可以使用 $USER 环境变量来自动获取当前登录的用户名：sudo usermod -aG docker $USER。

添加用户到组的更改通常不会立即生效。您需要注销当前的终端会话并重新登录，或者完全注销您的桌面会话（如果使用桌面环境）并重新登录。

或者，您可以在不注销的情况下，通过执行 newgrp docker 命令来临时激活新的组设置。然而，请注意 newgrp 命令只对当前的 shell session 生效，并且可能有一些不符合预期的行为（例如，它会替换当前的 shell 进程）。最稳妥的方法是注销并重新登录。

重新登录后，您可以尝试再次运行 hello-world 容器，这次不使用 sudo：

bash
docker run hello-world

如果命令成功执行，说明您已经可以作为非 root 用户管理 Docker 了。

安全提示： docker 组拥有非常强大的权限，它实际上等同于 root 权限，因为组成员可以通过运行容器来获取 root 权限。因此，请谨慎将用户添加到 docker 组，只将必要的用户添加到此组中。

2. 配置 Docker 开机自启动

通过官方仓库安装的 Docker 通常会默认配置为在系统启动时自动启动。您可以使用 systemctl 命令来确认和管理这一点：

• 检查 Docker 是否已配置为开机自启动：
  bash
sudo systemctl is-enabled docker
  输出 enabled 表示已配置自启动，输出 disabled 表示未配置。

• 启用 Docker 开机自启动：
  bash
sudo systemctl enable docker

• 禁用 Docker 开机自启动：
  bash
sudo systemctl disable docker

通常情况下，您不需要手动启用它，因为安装过程已经处理了。

3. 配置 Docker 镜像加速器（可选）

由于网络原因，从 Docker Hub 拉取镜像可能会比较慢。您可以配置 Docker 使用国内的镜像加速器，以提高镜像下载速度。许多云服务提供商（如阿里云、腾讯云、网易云等）都提供了免费的 Docker 镜像加速服务。

配置镜像加速器的方法是修改 Docker 的配置文件 /etc/docker/daemon.json。如果文件不存在，就创建一个。

bash
sudo nano /etc/docker/daemon.json

在文件中添加或修改 registry-mirrors 字段，指向您的镜像加速器地址。例如，使用阿里云的加速器地址（请替换为您实际获取的地址）：

json
{
"registry-mirrors": ["https://<your_accelerator_id>.mirror.aliyuncs.com"]
}

保存并关闭文件。然后，重启 Docker 服务以使配置生效：

bash
sudo systemctl daemon-reload
sudo systemctl restart docker

您可以通过 docker info 命令查看配置是否生效，输出中应该包含 Registry Mirrors 字段。

bash
docker info | grep "Registry Mirrors"

4. 了解和配置存储驱动（高级）

Docker 使用存储驱动来管理镜像和容器的文件系统层。不同的存储驱动有不同的性能特点和兼容性。在大多数现代 Debian 系统上，默认的存储驱动是 overlay2，它是推荐的存储驱动，性能良好且稳定。

通常情况下，您不需要手动配置存储驱动。但如果您在特定环境下遇到问题，或者需要优化性能，可以查阅 Docker 官方文档了解不同存储驱动的详细信息，并在 /etc/docker/daemon.json 中进行配置。

例如，强制使用 overlay2 驱动（通常是默认行为，不需要显式设置）：

json
{
"storage-driver": "overlay2"
}

修改配置后，同样需要重启 Docker 服务。

常见问题和故障排除

在安装和使用 Docker 过程中，可能会遇到一些问题。以下是一些常见问题及其解决方法：

1. docker: command not found

• 原因： docker 命令没有安装成功，或者所在的目录不在系统的 PATH 环境变量中。
• 解决方法：
  • 检查是否按照前面的步骤成功执行了 sudo apt install docker-ce docker-ce-cli ... 命令，并且没有报错。
  • 如果您是使用便捷脚本安装的，脚本可能会提示您需要执行 newgrp docker 或重新登录。请尝试重新登录系统。
  • 如果使用的是手动安装方法，请确保 Docker 二进制文件所在的目录（通常是 /usr/bin/ 或 /usr/local/bin/）在您的 PATH 环境变量中。

2. Got permission denied while trying to connect to the Docker daemon socket ...

• 原因： 当前用户没有权限访问 Docker Daemon 的 Unix 套接字（/var/run/docker.sock）。这通常是因为用户没有加入 docker 组。
• 解决方法：
  • 确保您已经将当前用户添加到了 docker 组：sudo usermod -aG docker $USER。
  • 最重要的一步： 在将用户添加到 docker 组后，必须注销当前的终端会话并重新登录（或完全注销桌面会话），或者使用 newgrp docker 命令（有副作用）。新的组设置只在新的登录会话中生效。
  • 重新登录后，再次尝试运行 Docker 命令，这次不要使用 sudo。

3. Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

• 原因： Docker Daemon 服务没有启动或运行异常。
• 解决方法：
  • 检查 Docker 服务的状态：sudo systemctl status docker。
  • 如果服务未运行（状态不是 active (running)），尝试启动它：sudo systemctl start docker。
  • 如果启动失败或状态显示错误，可以查看 Docker 服务的日志以获取更多信息：sudo journalctl -u docker.service。日志可能会包含具体的错误原因，如配置文件错误、端口冲突等。
  • 检查防火墙设置。如果系统启用了防火墙（如 ufw），请确保它没有阻止与 Docker Daemon 相关的通信。默认情况下，Docker Daemon 使用 Unix 套接字，通常不受防火墙影响，但如果您配置了 Docker 监听 TCP 端口，则需要确保该端口是开放的。

4. Error response from daemon: pull access denied for ..., repository does not exist or may require 'docker login': denied: requested access to the resource is denied

• 原因： Docker 尝试拉取一个需要认证的镜像，但您没有登录 Docker 仓库，或者没有权限访问该镜像。
• 解决方法：
  • 如果您尝试拉取私有仓库的镜像，需要使用 docker login <registry-url> 命令登录。对于 Docker Hub，直接使用 docker login。
  • 确认您拉取的镜像名称和标签是否正确，并且该镜像确实存在于您尝试访问的仓库中。

5. 安装速度非常慢或卡住

• 原因： 网络连接问题，或者 APT 源配置问题。
• 解决方法：
  • 检查您的网络连接是否正常。
  • 尝试修改系统的 APT 源为国内镜像源，以提高软件包下载速度。
  • 如果您尝试拉取 Docker 镜像速度慢，考虑配置 Docker 镜像加速器（参考前面的配置步骤）。

更新 Docker

当 Docker 发布新版本时，您可以通过 APT 包管理器轻松更新 Docker Engine 和相关组件，前提是您是通过官方仓库安装的。

首先，更新 APT 软件包列表以获取最新的可用版本信息：

bash
sudo apt update

然后，升级 Docker 相关的软件包：

bash
sudo apt upgrade docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

这会升级所有指定的 Docker 组件到仓库中可用的最新版本。

卸载 Docker

如果您不再需要 Docker，或者需要进行干净的重装，可以将其从系统中卸载。

卸载 Docker Engine、CLI 和 Containerd 软件包：

bash
sudo apt remove docker docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

这只会移除 Docker 的软件包，但不会删除相关的镜像、容器、卷（Volumes）或配置文件。

如果您想彻底移除所有 Docker 相关的数据（镜像、容器、卷等），需要手动删除 Docker 的数据目录。请注意，这是一个破坏性操作，会永久删除所有容器和镜像数据！

bash
sudo rm -rf /var/lib/docker

此外，您可能还想移除 Docker 的配置文件目录（如果存在）：

bash
sudo rm -rf /etc/docker

如果您是通过官方仓库安装的，并且不再计划重新安装 Docker，您还可以选择移除 Docker 的 GPG 密钥和 APT 仓库文件：

bash
sudo rm /etc/apt/keyrings/docker.gpg
sudo rm /etc/apt/sources.list.d/docker.list

最后，再次运行 autoremove 清理不再需要的依赖包：

bash
sudo apt autoremove -y

总结

本文详细介绍了在 Debian 系统上安装 Docker 的过程，重点推荐了通过 Docker 官方 APT 仓库进行的标准安装方法。我们涵盖了从准备工作、安装步骤、安装后验证到重要的配置（如非 root 用户管理、开机自启动、镜像加速器）以及常见的故障排除和维护（更新、卸载）。

Docker 在 Debian 上的稳定运行，为您提供了构建、分发和运行各种应用程序的强大能力。无论是开发微服务、搭建测试环境，还是部署生产应用，Docker 都能为您带来极大的便利和效率提升。

现在，您已经成功在 Debian 上安装了 Docker。接下来，您可以开始探索 Docker 的更多功能，例如构建自己的镜像（docker build）、使用 Dockerfile 定义应用环境、使用 Docker Compose 管理复杂的多容器应用等等。祝您在容器化的世界里探索愉快！

如果您在安装过程中遇到任何特定问题，建议首先查阅 Docker 官方文档，它通常包含最权威和最新的信息。同时，广阔的 Docker 社区和 Debian 社区也是寻求帮助的好地方。