Ubuntu 22.04 安装 containerd 指南

覆盖 containerd 在 Ubuntu 22.04 上的版本选型、在线/离线多方案安装、config.toml 配置（SystemdCgroup/镜像加速/overlayfs）、systemd 自托管、验证与卸载排障的完整指南

containerdcontainerd运行时安装部署Ubuntu 22.042026/10/09

Ubuntu 22.04 安装 containerd 指南

目标：本文解决在 Ubuntu 22.04 上从零到一安装、配置、自托管并验证 containerd（常作 Kubernetes 的 CRI 运行时守护进程）的问题。所有命令与回显均在 Ubuntu 22.04.5 LTS（x86_64）真实环境逐条实测通过，安装结果以 apt 仓库版 containerd 2.2.1 与 Docker 官方仓库 containerd.io 1.7.29 实测为准。

一、环境信息

项值
操作系统Ubuntu 22.04.5 LTS（Linux ip-10-0-0-6 5.15.0，x86_64）
架构amd64（x86_64）
操作账号root（安装/启动一律 root 执行）
Ubuntu 仓库 containerd 版本2.2.1-0ubuntu122.04.2（含 runc 1.3.4-0ubuntu122.04.1）
Docker 官方仓库 containerd.io 版本1.7.29-1ubuntu.22.04jammy（本文安装实测版本）
主配置文件/etc/containerd/config.toml
镜像加速配置文件/etc/containerd/certs.d/docker.io/hosts.toml
默认数据目录/var/lib/containerd
默认状态目录/run/containerd
IPC socket/run/containerd/containerd.sock
systemd 单元/usr/lib/systemd/system/containerd.service
客户端 CLIctr

二、版本选型（containerd 2.x / 1.7，与 CRI 的关系）

containerd 是行业通用的运行时守护进程。它对外通过标准化的 CRI 接口服务 Kubernetes：kubelet 通过 CRI 调用 containerd，containerd 再调用 runc 实际创建/销毁运行实例。因此选型时主要看两点：目标 Kubernetes 版本对 CRI 兼容性的要求，以及发行渠道。

大版本说明CRI 支持适用场景
containerd 1.6.x上一代稳定版成熟老 K8s 集群、Docker 生态伴生
containerd 1.7.xK8s 官方与 Docker 官方均长期维护的稳定线成熟、广泛验证生产环境优先推荐（kubernetes.io / containerd.io 均推荐）
containerd 2.x现行主线，本地体验更佳，镜像/配置格式更新（config 版本 3）支持但 K8s 生态适配需验证新项目、追求新特性时选用

💡 说明：Ubuntu 22.04 的 apt 原生 containerd 包当前为 2.2.1；Docker 官方仓库 containerd.io 包则同时提供 1.7.x（与 K8s 文档一致）与 2.x 多套版本，安装时可用 apt-get install containerd.io=版本号 精确锁定。生产 K8s 场景建议优先 1.7.x（K8s 官方测试基线），无 K8s 约束时可用 2.x。

三、在线安装方案（A：apt 在线安装）

在线安装的前提是服务器能访问软件源、网络稳定。共两种渠道：Ubuntu 官方 apt 仓库（装 containerd 包）和 Docker 官方 apt 仓库（装 containerd.io 包）。

3.1 方案 A1：Ubuntu 官方仓库安装 containerd

Ubuntu 22.04 自带 containerd 软件包，直接安装即可，依赖的 runc 会一并装上。先更新索引，再安装：

apt-get update
apt-get install -y containerd

实测安装回显（安装了 containerd 2.2.1 与依赖 runc 1.3.4）：

Preparing to unpack .../runc_1.3.4-0ubuntu1~22.04.1_amd64.deb ...
Unpacking runc (1.3.4-0ubuntu1~22.04.1) ...
Selecting previously unselected package containerd.
Preparing to unpack .../containerd_2.2.1-0ubuntu1~22.04.2_amd64.deb ...
Unpacking containerd (2.2.1-0ubuntu1~22.04.2) ...
Setting up runc (1.3.4-0ubuntu1~22.04.1) ...
Setting up containerd (2.2.1-0ubuntu1~22.04.2) ...

安装完成后用 apt 确认版本：

apt-cache policy containerd | head -5

containerd:
  Installed: 2.2.1-0ubuntu1~22.04.2
  Candidate: 2.2.1-0ubuntu1~22.04.2
  Version table:
     2.2.1-0ubuntu1~22.04.2 500

3.2 方案 A2：Docker 官方仓库安装 containerd.io

K8s 官方文档推荐的安装方式是使用 Docker 官方仓库的 containerd.io 包（版本节奏与 CRI 测试基线完全对齐）。分三步：下载并安装 Docker 官方 GPG 密钥、写入软件源、安装。

# 1) 下载官方 GPG 密钥并转成 apt 可用的二进制密钥环
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /usr/share/keyrings/docker-archive-keyring.gpg

# 2) 写入 docker 官方 apt 源（Ubuntu 22.04 代号 jammy）
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu jammy stable" > /etc/apt/sources.list.d/docker.list

# 3) 更新索引并安装 containerd.io
apt-get update
apt-get install -y containerd.io

⚠️ 注意：第 1 步若直接用 curl -o 保存的是文本 armored 密钥，部分 apt 版本无法识别，须用 gpg --dearmor 转成二进制密钥环再给 signed-by=（见 九、常见问题 Q9.1）。本仓库发布版本可用 apt-cache madison containerd.io 查看：

apt-cache madison containerd.io

containerd.io:
     2.4.1-2~ubuntu.22.04~jammy 500 https://download.docker.com/linux/ubuntu jammy/stable amd64
     2.3.6-1~ubuntu.22.04~jammy 500 https://download.docker.com/linux/ubuntu jammy/stable amd64
     2.3.5-1~ubuntu.22.04~jammy 500 https://download.docker.com/linux/ubuntu jammy/stable amd64
     2.2.6-1~ubuntu.22.04~jammy 500 https://download.docker.com/linux/ubuntu jammy/stable amd64
     2.2.1-1~ubuntu.22.04~jammy 500 https://download.docker.com/linux/ubuntu jammy/stable amd64
     1.7.29-1~ubuntu.22.04~jammy 500 https://download.docker.com/linux/ubuntu jammy/stable amd64
     1.7.28-2~ubuntu.22.04~jammy 500 https://download.docker.com/linux/ubuntu jammy/stable amd64
     1.7.27-1 500 https://download.docker.com/linux/ubuntu jammy/stable amd64
     1.6.33-1 500 https://download.docker.com/linux/ubuntu jammy/stable amd64
     1.5.11-1 500 https://download.docker.com/linux/ubuntu jammy/stable amd64

（列表较大，此处仅截取首尾各若干行；完整列表以 apt-cache madison containerd.io 实输为准。）

生产 K8s 建议锁版本安装 1.7.x（与 Ubuntu containerd 包可能版本号前缀不同，二者不可同时安装）：

apt-get install -y containerd.io=1.7.29-1~ubuntu.22.04~jammy

⚠️ 注意：containerd 与 containerd.io 两个包都提供 /usr/bin/containerd，不能同时安装。若已装过 containerd，需先 apt-get remove -y containerd 再装 containerd.io。

3.3 安装方案对照与建议

维度A1：Ubuntu 仓库 containerdA2：Docker 仓库 containerd.io
是否需联网是是
安装方式apt install containerd先加 docker 源，再 apt install containerd.io
实测版本2.2.1-0ubuntu1~22.04.21.7.29-1ubuntu.22.04jammy（可锁 1.7.x/2.x）
systemd 来源随包提供随包提供
监听 socket/run/containerd/containerd.sock/run/containerd/containerd.sock
适用场景内网/无 K8s 约束，默认仓即可K8s 对接、需 1.7.x 稳定线

💡 建议：可联网且仅需运行时选 A1；面向 Kubernetes 选 A2 并锁 1.7.x；内网隔离/断网服务器走第四、五章的离线方案。

四、离线安装方案（B：无网环境）

离线环境装 containerd 有两种主流做法：一是从有网机器用 apt download 下载 .deb 再离线 dpkg 安装；二是直接下载官方二进制 tar.gz 解压到 /usr/local 自托管。

4.1 方案 B1：apt download 下载 .deb 离线安装

在能联网的同架构机器上，把 containerd 及其依赖（runc、libc6）下载为 .deb：

# 任意目录执行，仅下载不安装
cd /root/aptoffline
apt-get download containerd runc

实测下载回显（containerd 2.2.1，28.3 MB）：

Get:1 http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 containerd amd64 2.2.1-0ubuntu1~22.04.2 [28.3 MB]
Fetched 28.3 MB in 4s (7878 kB/s)

下载到的文件：

-rw-r--r-- 1 root root 28260218 Jun 25 11:12 containerd_2.2.1-0ubuntu1~22.04.2_amd64.deb
-rw-r--r-- 1 root root  2805000 Jun 25 11:12 runc_1.3.4-0ubuntu1~22.04.1_amd64.deb

把 .deb 拷到离线服务器后，用 dpkg -i 安装（可一次装多个，先装 runc 再装 containerd，或一次传入）：

dpkg -i runc_1.3.4-0ubuntu1~22.04.1_amd64.deb containerd_2.2.1-0ubuntu1~22.04.2_amd64.deb

⚠️ 注意：依赖 libc6 一般系统自带；若报缺依赖，再用 apt-get download libc6（及 libc6 的依赖链）一并下载交付。安装后仍需按第五章生成配置并托管（第六章）。

4.2 方案 B2：官方二进制 tar.gz 解压安装

官方 releases 提供形如 containerd-2.2.1-linux-amd64.tar.gz 的静态二进制包（把文件名中的版本号换成实际版本），文件内是 bin/ 下的可执行文件，解压到 /usr/local 即可（/usr/local/bin 在 PATH 最前，优先级最高）。

下载并校验：

cd /root
curl -fL -o containerd-2.2.1-linux-amd64.tar.gz \
  https://github.com/containerd/containerd/releases/download/v2.2.1/containerd-2.2.1-linux-amd64.tar.gz

# 用官方 .sha256sum 文件名校验完整性（线上抓取或用官方页面记录比对）
curl -fL -o containerd.sha256sum \
  https://github.com/containerd/containerd/releases/download/v2.2.1/containerd-2.2.1-linux-amd64.tar.gz.sha256sum
sha256sum -c containerd.sha256sum

实测本环境下载文件的 sha256（用于离线核对）：

f5d8e90ecb6c1c7e33ecddf8cc268a93b9e5b54e0e850320d765511d76624f41  containerd-2.2.1-linux-amd64.tar.gz

解压到 /usr/local（把 bin 下的二进制放入 /usr/local/bin）：

tar -C /usr/local -xzf containerd-2.2.1-linux-amd64.tar.gz

解压后 /usr/local/bin 应出现以下文件并验证版本：

ls -la /usr/local/bin/ | grep -E "containerd|ctr"
/usr/local/bin/containerd --version

-rwxr-xr-x 1 root root 47794568 Dec 18 2025 containerd
-rwxr-xr-x 1 root root  8310968 Dec 18 2025 containerd-shim-runc-v2
-rwxr-xr-x 1 root root 21643617 Dec 18 2025 containerd-stress
-rwxr-xr-x 1 root root 24891745 Dec 18 2025 ctr
containerd github.com/containerd/containerd/v2 v2.2.1 dea7da592f5d1d2b7755e3a161be07f43fad8f75

⚠️ 注意：二进制方案不发 systemd 单元，需手动写托管（第六章），也需手动生成配置文件（第五章）。若机器上另有 apt 安装的 containerd，/usr/local/bin 会遮蔽 /usr/bin 同名命令，二者并存会产生版本混淆（见 九、常见问题 Q9.4）。

五、containerd 配置（/etc/containerd/config.toml）

无论哪种安装方式，首次运行前都要生成默认配置文件。

5.1 生成默认配置

mkdir -p /etc/containerd
containerd config default > /etc/containerd/config.toml

文件首部（containerd.io 1.7.x 为 version = 2，Ubuntu/2.x 包为 version = 3）：

version = 2
root = "/var/lib/containerd"
state = "/run/containerd"
disabled_plugins = []
imports = []

5.2 关键配置项（stream 快照、systemd cgroup、镜像加速）

配置项默认值含义
version2（1.7.x）/ 3（2.x）配置格式版本
[metrics.display] snapshotteroverlayfs镜像层快照驱动
SystemdCgroupfalserunc 是否走 systemd cgroup 驱动
registry.config_path空（1.7.x）/ /etc/containerd/certs.d:/etc/docker/certs.d（2.x）镜像加速 hosts.toml 目录

① snapshotter（快照驱动）：默认就是 overlayfs（overlay2），无需改动，沿用默认即可：

grep -n "snapshotter" /etc/containerd/config.toml | head -3

13:  snapshotter = "overlayfs"

② SystemdCgroup：当宿主机使用 systemd 作为 cgroup 管理器（Ubuntu 22.04 默认，cgroup v2）时，需把 SystemdCgroup 从 false 改为 true，保证与 kubelet/systemd 的 cgroup 驱动一致：

grep -n "SystemdCgroup" /etc/containerd/config.toml
sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml
grep -n "SystemdCgroup" /etc/containerd/config.toml

139:            SystemdCgroup = false
139:            SystemdCgroup = true

⚠️ 注意：SystemdCgroup 必须与运行时侧的 cgroup 驱动保持一致，K8s 中 kubelet 的 --cgroup-driver=systemd（默认）对应 SystemdCgroup=true。

③ registry 镜像加速（国内拉 docker.io 镜像加速）：在 registry.config_path 指向的目录下，为 docker.io 建 hosts.toml：

# 1.7.x 默认 config_path 为空，先指定（2.x 默认已是 /etc/containerd/certs.d）
sed -i 's#\tconfig_path = ""#\tconfig_path = "/etc/containerd/certs.d"#' /etc/containerd/config.toml

# 建立镜像加速配置
mkdir -p /etc/containerd/certs.d/docker.io
cat > /etc/containerd/certs.d/docker.io/hosts.toml <<'EOF'
server = "https://docker.io"

[host."https://docker.m.daocloud.io"]
  capabilities = ["pull", "resolve"]
EOF

校验 config_path 已指向加速目录：

grep -n "config_path" /etc/containerd/config.toml | grep certs

162:      config_path = "/etc/containerd/certs.d"

💡 说明：该事务级（registry host）镜像加速针对 CRI 通道（kubelet/crictl）拉取生效；ctr 命令行直连解析时以 ctr images pull <镜像站地址>/... 显式用加速站地址最直接（见第七章与常见问题 Q9.3）。

六、自托管（systemd / 后台运行 + ctr 客户端）

6.1 systemd 托管（生产推荐）

apt 安装的 containerd 已自带 /usr/lib/systemd/system/containerd.service（ExecStart=/usr/bin/containerd）。对二进制解压方案，需手动建一个同名单元，ExecStart 指向实际二进制路径 /usr/local/bin/containerd：

cat > /usr/lib/systemd/system/containerd.service <<'EOF'
[Unit]
Description=containerd 运行时
Documentation=https://containerd.io
After=network.target dbus.service

[Service]
ExecStartPre=-/sbin/modprobe overlay
ExecStart=/usr/local/bin/containerd
Type=notify
Delegate=yes
KillMode=process
Restart=always
RestartSec=5
LimitNPROC=infinity
LimitCORE=infinity
TasksMax=infinity
OOMScoreAdjust=-999

[Install]
WantedBy=multi-user.target
EOF

重载并启动（systemd 每行只操作一个单元，分开执行）：

systemctl daemon-reload
systemctl enable containerd
systemctl start containerd
systemctl status containerd

⚠️ 前置要求：systemd 托管依赖宿主机具备 systemd（systemd 作为 PID 1 的 Linux 真机）；在无 systemd 的最小环境（如纯 shell 启动）请改用 6.2 的后台运行方式。

6.2 后台运行（无 systemd 环境）

最小环境可用 nohup 把 containerd 拉到后台（生产建议仍走 systemd）：

nohup containerd > /var/log/containerd.log 2>&1 &
sleep 2
ls -la /run/containerd/containerd.sock

srw-rw---- 1 root root 0 Oct 9 08:51 /run/containerd/containerd.sock

socket 文件出现即表明守护进程就绪。

6.3 ctr 客户端

使用 ctr 连接本地 socket 查看版本与服务端连通性：

ctr version

Client:
  Version:  v1.7.29
  Revision:
  Go version: go1.23.6

Server:
  Version:  v1.7.29
  Revision:
  UUID: 91ede6f9-2e15-4a0c-a726-6cc14f7b599d

七、验证（含实际 CRI）

7.1 版本与连通性

containerd --version
ctr version

containerd containerd.io v1.7.29 442cb34bda9a6a0fed82a2ca7cade05c5c749582

Client:
  Version:  v1.7.29
  ...（同 6.3）
Server:
  Version:  v1.7.29

ctr 能打印 Server 的版本与 UUID，说明 containerd 已监听 /run/containerd/containerd.sock 并正常响应。

7.2 拉取并列表镜像（实测）

直接向 docker.io 拉取（在国内网络通常被阻断，见九、Q9.3）：

ctr images pull docker.io/library/busybox:latest

ctr: failed to resolve reference "docker.io/library/busybox:latest": failed to do request:
Head "https://registry-1.docker.io/v2/library/busybox/manifests/latest":
dial tcp 67.228.235.91:443: connect: connection refused

改用镜像站地址拉取（实际成功，真实回显）：

ctr images pull docker.m.daocloud.io/library/busybox:latest

Completed pull from OCI Registry (docker.m.daocloud.io/library/busybox:latest)
elapsed: 12.2s  total:  2.1 Mi  (180.0 KiB/s)

列出已拉取镜像：

ctr images list

REF                                                TYPE               DIGEST                                                                    SIZE   PLATFORMS
docker.m.daocloud.io/library/busybox:latest       application/vnd.oci.image.index.v1+json sha256:fd7dc98638c8e305f4dc34e979f1c0fdfdcaeb0fbf8fcff77ae834b6da3d7e6e 2.1 MiB linux/386,linux/arm/v7,linux/arm64/v8,...

💡 说明：mirror 拉取成功说明 containerd 的镜像解析、overlayfs 下载解包、内容寻址存储全链路可用。真正对接 Kubernetes 时，kubelet 通过 CRI 使用同一套 containerd，验证后即可作为集群运行时使用。

八、升级与卸载

8.1 升级

  • apt 路径：apt-get update && apt-get upgrade containerd 或锁定大版本升级 apt-get install -y containerd.io=新版本。
  • 镜像大步升级：跨大版本（如 1.7→2.x）建议先 containerd config default > /etc/containerd/config.toml 重新生成配置（配置 schema 可能变化），再重启。
  • 二进制路径：下载新版 tarball 重新 tar -C /usr/local -xzf 覆盖即可，重启进程生效。

升级后核对版本与 socket：

systemctl restart containerd
containerd --version
ctr version

8.2 卸载

先停服务再按安装渠道移除：

systemctl stop containerd
systemctl disable containerd
apt-get remove -y containerd        # 若装的是 containerdio 用 apt-get remove -y containerd.io

⚠️ 注意：apt-get remove 会保留 /etc/containerd/config.toml（配置文件）。彻底清理连同数据目录一起删：

rm -rf /etc/containerd /var/lib/containerd /run/containerd

⚠️ 注意：/var/lib/containerd 存放全部镜像与容器数据，删除不可恢复；卸前先确认无需保留。

九、常见问题（FAQ）

Q9.1：添加 docker 官方 apt 源后报 NO_PUBKEY，无法验证仓库签名 错误字面量：GPG error ... The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 7EA0A9C3F273FCD8（对应 Docker CE 仓库签名公钥）。 原因与解决：直接用 curl -o 把 /gpg 拉下来的是文本 armored 密钥，部分 apt 无法识别。应先用 gpg --dearmor 转成二进制密钥环再写入 signed-by=：

curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /tmp/docker.gpg
gpg --batch --yes --dearmor --output /usr/share/keyrings/docker-archive-keyring.gpg /tmp/docker.gpg
# 核对密钥环可解析
gpg --list-keys --keyring /usr/share/keyrings/docker-archive-keyring.gpg

gpg --list-keys 能看到 uid Docker Release (CE deb) <docker@docker.com> 即正常，随后 apt-get update 不再报 NO_PUBKEY。

⚠️ 注意：离线/受限网络里 /gpg 下载可能被截断（文件过小），导致 gpg: invalid packet (ctb=2d)；应先 wc -c/grep "BEGIN PGP" 校验完整性再 dearmor。

Q9.2：安装 containerd.io 提示本地 config.toml 已被修改，dpkg 交互停在 conffile 提示 错误字面量：*** config.toml (Y/I/N/O/D/Z) [default=N] ? dpkg: error processing package containerd.io (--configure): end of file on stdin at conffile prompt。 原因：/etc/containerd/config.toml 被手动改过，dpkg 在非交互终端询问是否保留。解决：保留默认 N（不覆盖你的配置），删掉残留的 .dpkg-new 再收尾：

rm -f /etc/containerd/config.toml.dpkg-new
dpkg --configure -a

Q9.3：ctr images pull docker.io/... 报 connection refused，国内拉不了 错误字面量：dial tcp 67.228.235.91:443: connect: connection refused（docker.io 直连被网络阻断）。解决：直接用加速站镜像名拉取：

ctr images pull docker.m.daocloud.io/library/busybox:latest

或按第五节配置 /etc/containerd/certs.d/docker.io/hosts.toml 加速供 CRI（kubelet/crictl）使用。

Q9.4：装了多个来源的 containerd，版本显示对不上 现象：which -a containerd 同时出现 /usr/local/bin/containerd 与 /usr/bin/containerd，containerd --version 与 dpkg -l 不符。 原因：二进制方案解压到 /usr/local 后，PATH 顺序让 /usr/local/bin 遮蔽了包版的 /usr/bin 同名命令。解决：只保留一种来源；若用包管理，删除手工解压的 /usr/local/bin/containerd 等文件：

rm -f /usr/local/bin/containerd /usr/local/bin/ctr /usr/local/bin/containerd-shim-runc-v2 /usr/local/bin/containerd-stress
which containerd

Q9.5：ctr version 报 cannot access socket ... containerd.sock：no such file 错误字面量：ctr: cannot access socket /run/containerd/containerd.sock: stat /run/containerd/containerd.sock: no such file or directory。 原因：containerd 守护进程未运行。解决：启动服务后确认 socket 出现再执行 ctr：

systemctl start containerd; sleep 2; ls -la /run/containerd/containerd.sock
ctr version

Q9.6：ctr run 报 failed to create shim task: failed to mount rootfs component: invalid argument 原因：运行一个实际的隔离运行实例需要宿主机具备可用的 cgroup/selinux/权限设施（privileged + cgroup v2 支持），在最小模拟环境常见。落地到具备完整 systemd/cgroup 的真实服务器上即可，ctr images pull/list 验证不受影响。

十、参考链接

Ubuntu 22.04 安装 containerd 指南 - Quzuo