在 Raspberry Pi OS (32-bit / armhf) 上安装 Docker Engine

Table of contents
Warning

Raspberry Pi OS 32 位 (armhf) 弃用

Docker Engine v28 将是支持 Raspberry Pi OS 32 位 (armhf) 的最后一个主要版本。 从 Docker Engine v29 开始，新的主要版本将不再为 Raspberry Pi OS 32 位 (armhf) 提供软件包。

迁移选项

  • 64 位 ARM： 安装 Debian arm64 软件包（完全支持）。请参阅 Debian 安装说明。
  • 32 位 ARM (v7)： 安装 Debian armhf 软件包（针对 ARMv7 CPU）。

注意： 基于 ARMv6 架构的旧设备不再受官方软件包支持，包括：

  • Raspberry Pi 1 (Model A/B/A+/B+)
  • Raspberry Pi Zero 和 Zero W

要在 Raspberry Pi OS 上开始使用 Docker Engine，请确保您 满足先决条件，然后按照 安装步骤 操作。

Important

本安装说明指的是 Raspberry Pi OS 的 32 位 (armhf) 版本。如果您使用的是 64 位 (arm64) 版本，请遵循 Debian 的说明。

先决条件

防火墙限制

Warning

在安装 Docker 之前，请确保您考虑了以下 安全影响和防火墙不兼容性。

  • 如果您使用 ufw 或 firewalld 管理防火墙设置，请注意，当您使用 Docker 暴露容器端口时，这些端口会绕过您的防火墙规则。更多信息，请参阅 Docker 和 ufw。
  • Docker 仅兼容 iptables-nft 和 iptables-legacy。 在安装了 Docker 的系统上，不支持使用 nft 创建的防火墙规则。 确保您使用的任何防火墙规则集都是使用 iptables 或 ip6tables 创建的， 并将它们添加到 DOCKER-USER 链中， 请参阅 数据包过滤和防火墙。

操作系统要求

要安装 Docker Engine，您需要以下操作系统版本之一：

  • 32 位 Raspberry Pi OS Bookworm 12 (stable)
  • 32 位 Raspberry Pi OS Bullseye 11 (oldstable)
Warning

Docker Engine v28 是支持 Raspberry Pi OS 32 位 (armhf) 的最后一个主要版本。从 v29 开始， 将不再为 32 位 Raspberry Pi OS 提供新的软件包。

迁移选项：

  • 64 位 ARM：使用 Debian arm64 软件包；请参阅 Debian 安装说明。
  • 32 位 ARM (v7)：使用 Debian armhf 软件包（针对 ARMv7 CPU）。

注意：基于 ARMv6 的设备（Raspberry Pi 1 型号和 Raspberry Pi Zero/Zero W）不受 官方软件包支持。

卸载旧版本

在安装 Docker Engine 之前，您需要卸载任何冲突的软件包。

您的 Linux 发行版可能会提供非官方的 Docker 软件包，这些软件包可能与 Docker 提供的官方软件包冲突。在安装官方版本的 Docker Engine 之前，您必须卸载这些软件包。

需要卸载的非官方软件包是：

  • docker.io
  • docker-compose
  • docker-doc
  • podman-docker

此外，Docker Engine 依赖于 containerd 和 runc。Docker Engine 将这些依赖项捆绑为一个包：containerd.io。如果您之前安装了 containerd 或 runc，请卸载它们以避免与 Docker Engine 捆绑的版本发生冲突。

运行以下命令以卸载所有冲突的软件包：

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

apt-get 可能会报告您没有安装这些软件包。

存储在 /var/lib/docker/ 中的镜像、容器、卷和网络在您卸载 Docker 时不会自动删除。如果您想从头开始安装，并希望清理任何现有数据，请阅读 卸载 Docker Engine 部分。

安装方法

您可以根据需要以不同的方式安装 Docker Engine：

Apache License, Version 2.0. 请参阅 LICENSE 获取完整许可证。

使用 apt 仓库安装

在新主机上首次安装 Docker Engine 之前，您需要设置 Docker apt 仓库。之后，您可以从仓库安装和更新 Docker。

  1. 设置 Docker 的 apt 仓库。

    # 添加 Docker 的官方 GPG 密钥：
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/raspbian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# 将仓库添加到 Apt 源中：
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/raspbian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

  2. 安装 Docker 软件包。

    要安装最新版本，请运行：

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

    要安装特定版本的 Docker Engine，首先列出仓库中可用的版本：

    # 列出可用版本：
$ apt-cache madison docker-ce | awk '{ print $3 }'

5:29.1.3-1~raspbian.12~bookworm
5:29.1.2-1~raspbian.12~bookworm
...

    选择所需的版本并安装：

    $ VERSION_STRING=5:29.1.3-1~raspbian.12~bookworm
$ sudo apt-get install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin
    Note

    Docker 服务在安装后会自动启动。要验证 Docker 是否正在运行，请使用：

    $ sudo systemctl status docker

    某些系统可能禁用了此行为，需要手动启动：

    $ sudo systemctl start docker

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

    $ sudo docker run hello-world

    此命令下载测试镜像并在容器中运行。当容器运行时，它会打印一条确认消息并退出。

您现已成功安装并启动了 Docker Engine。

Tip

尝试以非 root 用户身份运行时遇到错误？

docker 用户组存在但不包含任何用户，这就是为什么您需要使用 sudo 来运行 Docker 命令。请继续阅读 Linux 安装后配置，了解如何允许非特权用户运行 Docker 命令以及其他可选配置步骤。

升级 Docker Engine

要升级 Docker Engine，请按照 安装说明 的步骤 2 操作，选择您要安装的新版本。

从软件包安装

如果您无法使用 Docker 的 apt 仓库来安装 Docker Engine，您可以下载适用于您发行版的 deb 文件并手动安装。每次想要升级 Docker Engine 时，都需要下载一个新文件。

  1. 转到 https://download.docker.com/linux/raspbian/dists/。

  2. 在列表中选择您的 Raspberry Pi OS 版本。

  3. 转到 pool/stable/ 并选择适用的架构（amd64、armhf、arm64 或 s390x）。

  4. 下载 Docker Engine、CLI、containerd 和 Docker Compose 软件包的以下 deb 文件：

    • containerd.io_<version>_<arch>.deb
    • docker-ce_<version>_<arch>.deb
    • docker-ce-cli_<version>_<arch>.deb
    • docker-buildx-plugin_<version>_<arch>.deb
    • docker-compose-plugin_<version>_<arch>.deb

  5. 安装 .deb 软件包。更新以下示例中的路径，指向您下载 Docker 软件包的位置。

    $ sudo dpkg -i ./containerd.io_<version>_<arch>.deb \
  ./docker-ce_<version>_<arch>.deb \
  ./docker-ce-cli_<version>_<arch>.deb \
  ./docker-buildx-plugin_<version>_<arch>.deb \
  ./docker-compose-plugin_<version>_<arch>.deb
    Note

    Docker 服务在安装后会自动启动。要验证 Docker 是否正在运行，请使用：

    $ sudo systemctl status docker

    某些系统可能禁用了此行为，需要手动启动：

    $ sudo systemctl start docker

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

    $ sudo docker run hello-world

    此命令下载测试镜像并在容器中运行。当容器运行时，它会打印一条确认消息并退出。

您现已成功安装并启动了 Docker Engine。

Tip

尝试以非 root 用户身份运行时遇到错误？

docker 用户组存在但不包含任何用户，这就是为什么您需要使用 sudo 来运行 Docker 命令。请继续阅读 Linux 安装后配置，了解如何允许非特权用户运行 Docker 命令以及其他可选配置步骤。

升级 Docker Engine

要升级 Docker Engine，请下载较新的软件包文件，并重复 安装过程，指向新的文件。

使用便捷脚本安装

Docker 提供了一个便捷脚本，位于 https://get.docker.com/，用于以非交互方式将 Docker 安装到开发环境中。该便捷脚本不推荐用于生产环境，但对于创建符合您需求的配置脚本很有用。另请参阅使用仓库安装步骤，了解使用软件包仓库进行安装的相关步骤。该脚本的源代码是开源的，您可以在 GitHub 上的 docker-install 仓库 中找到它。

在本地运行从互联网下载的脚本之前，请务必仔细检查。在安装之前，请熟悉便捷脚本的潜在风险和限制：

  • 该脚本需要 root 或 sudo 权限才能运行。
  • 该脚本会尝试检测您的 Linux 发行版和版本，并为您配置包管理系统。
  • 该脚本不允许您自定义大多数安装参数。
  • 该脚本会安装依赖项和推荐包，而不会要求确认。根据主机机器的当前配置，这可能会安装大量软件包。
  • 默认情况下，该脚本会安装 Docker、containerd 和 runc 的最新稳定版本。使用此脚本配置机器时，可能会导致 Docker 意外地进行主要版本升级。在将升级部署到生产系统之前，请务必在测试环境中测试升级。
  • 该脚本并非用于升级现有的 Docker 安装。使用该脚本更新现有安装时，依赖项可能不会更新到预期版本，从而导致版本过时。
Tip

在运行脚本之前预览脚本步骤。您可以使用 --dry-run 选项运行脚本，以了解脚本被调用时将运行的步骤：

$ curl -fsSL https://get.docker.com -o get-docker.sh
$ sudo sh ./get-docker.sh --dry-run

此示例从 https://get.docker.com/ 下载脚本并运行它，以在 Linux 上安装 Docker 的最新稳定版本：

$ curl -fsSL https://get.docker.com -o get-docker.sh
$ sudo sh get-docker.sh
Executing docker install script, commit: 7cae5f8b0decc17d6571f9f52eb840fbc13b2737
<...>

现在，您已成功安装并启动了 Docker 引擎。基于 Debian 的发行版会自动启动 docker 服务。在基于 RPM 的发行版（如 CentOS、Fedora 或 RHEL）上，您需要使用适当的 systemctl 或 service 命令手动启动它。如消息所示，默认情况下，非 root 用户无法运行 Docker 命令。

以非特权用户使用 Docker，或以无根模式安装？

安装脚本需要 root 或 sudo 权限才能安装和使用 Docker。如果您想授予非 root 用户访问 Docker 的权限，请参阅 Linux 安装后步骤。您也可以在没有 root 权限的情况下安装 Docker，或配置为以无根模式运行。有关以无根模式运行 Docker 的说明，请参阅 以非 root 用户身份运行 Docker 守护进程（无根模式）。

安装预发布版本

Docker 还在 https://test.docker.com/ 提供了一个便捷脚本，用于在 Linux 上安装 Docker 的预发布版本。该脚本与 get.docker.com 上的脚本相同，但会将您的包管理器配置为使用 Docker 软件包仓库的测试通道。测试通道包括 Docker 的稳定版本和预发布版本（测试版本、候选发布版本）。使用此脚本可以提前获取新版本，并在它们作为稳定版本发布之前在测试环境中对其进行评估。

要在 Linux 上从测试通道安装 Docker 的最新版本，请运行：

$ curl -fsSL https://test.docker.com -o test-docker.sh
$ sudo sh test-docker.sh

使用便捷脚本后升级 Docker

如果您使用便捷脚本安装了 Docker，则应直接使用包管理器升级 Docker。重新运行便捷脚本没有任何优势。如果它尝试重新安装主机上已存在的仓库，重新运行它可能会导致问题。

卸载 Docker Engine

  1. 卸载 Docker Engine、CLI、containerd 和 Docker Compose 软件包：

    $ sudo apt-get purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras

  2. 主机上的镜像、容器、卷或自定义配置文件不会自动删除。要删除所有镜像、容器和卷：

    $ sudo rm -rf /var/lib/docker
$ sudo rm -rf /var/lib/containerd

  3. 删除源列表和密钥环

    $ sudo rm /etc/apt/sources.list.d/docker.list
$ sudo rm /etc/apt/keyrings/docker.asc

您必须手动删除任何编辑过的配置文件。

后续步骤