在 Raspberry Pi OS (32位) 上安装 Docker Engine

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

重要

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

先决条件

防火墙限制

警告

在安装 Docker 之前,请务必考虑以下安全隐患和防火墙不兼容性。

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

操作系统要求

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

  • 32 位 Raspberry Pi OS Bookworm 12 (稳定版)
  • 32 位 Raspberry Pi OS Bullseye 11 (旧稳定版)

卸载旧版本

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

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

需要卸载的非官方包有:

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

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

运行以下命令卸载所有冲突的包:

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

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

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

安装方法

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

使用 apt 仓库安装

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

  1. 设置 Docker 的 apt 仓库。

    # Add Docker's official GPG key:
    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
    
    # Add the repository to Apt sources:
    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,请先列出仓库中的可用版本:

    # List the available versions:
    $ apt-cache madison docker-ce | awk '{ print $3 }'
    
    5:28.1.1-1~raspbian.12~bookworm
    5:28.1.0-1~raspbian.12~bookworm
    ...
    

    选择所需版本并安装:

    $ VERSION_STRING=5:28.1.1-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
    

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

    $ sudo docker run hello-world
    

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

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

提示

尝试在非 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, arm64s390x)。

  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
    

    Docker daemon 会自动启动。

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

    $ sudo service docker start
    $ sudo docker run hello-world
    

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

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

提示

尝试在非 root 用户下运行时遇到错误?

docker 用户组存在但没有用户,这就是您需要使用 sudo 来运行 Docker 命令的原因。继续阅读 Linux 安装后配置,以允许非特权用户运行 Docker 命令以及进行其他可选的配置步骤。

升级 Docker Engine

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

使用便捷脚本安装

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

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

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

提示

运行前预览脚本步骤。您可以运行带 --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 Engine。docker 服务会在基于 Debian 的发行版上自动启动。在基于 RPM 的发行版上,例如 CentOS、Fedora、RHEL 或 SLES,您需要使用相应的 systemctlservice 命令手动启动它。如消息所示,默认情况下非 root 用户无法运行 Docker 命令。

将 Docker 用作非特权用户,还是安装在无根模式下?

安装脚本需要 rootsudo 权限来安装和使用 Docker。如果您想授权非 root 用户访问 Docker,请参阅Linux 的安装后步骤。您也可以在没有 root 权限的情况下安装 Docker,或将其配置为在无 root 模式下运行。有关在无 root 模式下运行 Docker 的说明,请参阅将 Docker 守护进程作为非 root 用户运行(无 root 模式)

安装预发布版本

Docker 还在https://test.docker.com/ 提供了一个便利脚本,用于在 Linux 上安装 Docker 的预发布版本。此脚本与 get.docker.com 上的脚本相同,但会将您的包管理器配置为使用 Docker 包仓库的 test 通道。test 通道包括 Docker 的稳定版和预发布版本(beta 版本、候选发布版本)。使用此脚本可以抢先体验新版本,并在其发布稳定版之前在测试环境中进行评估。

要从 test 通道安装 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
    

您必须手动删除所有已编辑的配置文件。

后续步骤

页面选项