1. 项目概述：为什么需要绕过Docker Daemon直接操作镜像？

在容器和云原生的日常运维里，我们最熟悉的镜像操作命令莫过于docker pull和docker push。Docker CLI 就像一个友好的前台，接收我们的指令，然后交给后台的 Docker Daemon 去真正执行拉取、推送这些“体力活”。这个架构清晰，但也带来了一个问题：强依赖。你必须确保 Docker Daemon 服务正常运行，并且你拥有调用它的权限（通常是需要sudo或加入docker用户组）。

但有些场景下，这个“前台-后台”的架构会显得笨重甚至不可用。比如，在一个高度定制化或安全策略严格的环境中，Docker Daemon 可能被禁用；或者，你需要在 CI/CD 流水线的某个无特权容器内直接操作镜像，而不想或不能运行一个完整的 Docker Daemon。再比如，当你需要对镜像的传输过程进行更底层的控制或调试时，绕过 Daemon 直接与容器运行时或镜像仓库对话，会给你带来前所未有的清晰视野。

这时，ctr命令就该登场了。它是 Containerd 这个行业标准容器运行时的命令行工具。Containerd 负责管理容器的完整生命周期，而镜像管理正是其核心功能之一。ctr允许你直接与 Containerd 交互，执行包括拉取、推送、导入、导出镜像在内的所有底层操作，完全不需要 Docker Daemon 的参与。而今天我们要深入探讨的，就是如何用ctr，通过最基本的 HTTP 协议，来完成镜像的推送（push）和拉取（pull）。这不仅是解决特定环境限制的钥匙，更是深入理解容器镜像分发机制的一扇窗。

2. 核心概念与前置准备

2.1 ctr、Containerd 与 Docker 的关系辨析

在开始实操前，理清这几个概念至关重要，否则很容易在后续步骤中混淆。

Containerd是一个容器运行时。它的职责是执行容器，管理容器的生命周期（创建、启动、停止、删除）、存储、网络等底层细节。它遵循 OCI（Open Container Initiative）标准，是 Kubernetes 默认的容器运行时，也是 Docker 引擎的底层核心组件。

ctr是 Containerd 自带的一个低级命令行客户端。你可以把它理解为 Containerd 的“瑞士军刀”，功能强大且直接，但用户界面相对不友好，主要面向开发者和高级运维人员，用于调试、测试或在不依赖 Docker 的情况下直接操作 Containerd。

Docker是一个完整的容器化平台。它包含 Docker Daemon（一个常驻后台进程）、Docker CLI（我们常用的docker命令）以及一系列工具。Docker Daemon 在内部调用 Containerd 来运行容器，但同时提供了镜像构建、网络管理、卷管理、用户友好的 API 等高层功能。

简单来说：ctr直接对话Containerd；docker命令对话Docker Daemon，后者再调用Containerd。因此，使用ctr操作镜像，是更接近底层、更轻量级的方式。

2.2 理解镜像仓库与 HTTP 协议

镜像仓库（Registry）是存储和分发容器镜像的地方，比如 Docker Hub、Google Container Registry (GCR)、Amazon ECR，以及私有的 Harbor、Nexus 等。

默认情况下，无论是docker还是ctr，与镜像仓库通信都使用HTTPS协议。这是为了保障传输安全，防止镜像被篡改。然而，在内网测试、开发环境或者某些特定架构中，我们可能会搭建或使用一个只支持HTTP的仓库（例如，一个简单的、未配置 TLS 证书的私有仓库）。

直接让ctr使用 HTTP 访问仓库，它会出于安全考虑而拒绝。这就需要我们明确地告诉 Containerd：“我知道这个仓库不安全，但我接受风险，请允许我使用 HTTP 连接它。”

2.3 环境检查与 ctr 安装

首先，确保你的系统已经安装了 Containerd。在大多数现代 Linux 发行版上，如果安装了 Docker，通常也会安装 Containerd。

# 检查 Containerd 服务状态 sudo systemctl status containerd # 检查 ctr 命令是否可用 ctr version

如果ctr命令不存在，你需要单独安装 Containerd。例如，在 Ubuntu 上：

# 安装 Containerd sudo apt-get update sudo apt-get install -y containerd.io # 启动并启用服务 sudo systemctl enable --now containerd

安装后，Containerd 的主配置文件通常位于/etc/containerd/config.toml。我们后续的 HTTP 仓库配置将主要在这里进行。

注意：直接操作ctr和 Containerd 配置通常需要root权限。请确保你使用sudo或在 root 用户下操作。

3. 配置 Containerd 以允许 HTTP 仓库

这是最关键的一步。Containerd 通过配置文件中的registry.mirrors和registry.configs节点来定义如何与各个镜像仓库通信。

3.1 生成默认配置文件

如果/etc/containerd/config.toml文件不存在，可以先让 Containerd 生成一个默认配置。

sudo mkdir -p /etc/containerd sudo containerd config default | sudo tee /etc/containerd/config.toml

3.2 修改配置文件以添加 HTTP 仓库

假设我们有一个内网私有仓库，地址是http://my-insecure-registry.local:5000。我们需要在配置文件中声明它。

使用文本编辑器（如vim或nano）打开配置文件：

sudo vim /etc/containerd/config.toml

找到[plugins.”io.containerd.grpc.v1.cri”.registry]这个部分。这是配置容器运行时接口（CRI）的 registry 设置，ctr命令也会参考这里的配置。

我们需要在configs下为我们仓库的 host 创建一个配置项，并指定insecure_skip_verify = true。同时，也可以在mirrors中为其定义一个镜像加速地址（这里就是它本身）。

在配置文件中添加或修改如下内容：

[plugins."io.containerd.grpc.v1.cri".registry] # 定义镜像仓库的镜像（加速）地址 [plugins."io.containerd.grpc.v1.cri".registry.mirrors] [plugins."io.containerd.grpc.v1.cri".registry.mirrors."my-insecure-registry.local:5000"] endpoint = ["http://my-insecure-registry.local:5000"] # 注意是 http # 定义针对特定仓库的配置 [plugins."io.containerd.grpc.v1.cri".registry.configs] [plugins."io.containerd.grpc.v1.cri".registry.configs."my-insecure-registry.local:5000"] [plugins."io.containerd.grpc.v1.cri".registry.configs."my-insecure-registry.local:5000".tls] insecure_skip_verify = true # 关键！跳过 TLS 验证

配置解析：

• mirrors.”my-insecure-registry.local:5000″：这为仓库主机名定义了一个端点列表。当拉取镜像时，Containerd 会尝试这些端点。这里我们直接指向 HTTP 地址。
• configs.”my-insecure-registry.local:5000″.tls.insecure_skip_verify = true：这是允许 HTTP 连接的核心。它告诉 Containerd，连接到这个主机时，不要验证 TLS 证书。对于 HTTP 连接，这个设置同样使其被允许。

3.3 重启 Containerd 服务并验证配置

修改保存配置文件后，必须重启 Containerd 服务使配置生效。

sudo systemctl restart containerd sudo systemctl status containerd # 确认服务重启成功，没有报错

验证配置是否被加载，可以查看服务的详细状态或使用ctr命令列出已知的命名空间（间接测试连接）。

# 查看 containerd 服务日志，看是否有配置错误 sudo journalctl -u containerd --since “5 minutes ago” | tail -20 # 使用 ctr 查看镜像，测试基础功能 sudo ctr images ls

如果服务重启成功且无错误日志，说明配置已生效。

4. 使用 ctr 进行 HTTP 镜像拉取（Pull）

配置好仓库后，我们就可以开始实际操作了。ctr命令的基本格式是ctr [全局选项] <对象类型> <子命令> [命令选项]。

4.1 拉取镜像的命令格式

拉取镜像到本地的命令是ctr images pull。

sudo ctr images pull [选项] <镜像引用>

一个完整的镜像引用（image reference）通常格式为：<仓库地址>/<命名空间>/<镜像名>:<标签>例如：my-insecure-registry.local:5000/library/nginx:alpine

4.2 从 HTTP 仓库拉取镜像实操

假设我们的 HTTP 私有仓库里有一个nginx:alpine镜像。

# 从我们配置的 HTTP 仓库拉取镜像 sudo ctr images pull my-insecure-registry.local:5000/library/nginx:alpine # 拉取成功后，查看本地镜像列表 sudo ctr images ls

执行过程解析：

1. ctr会解析镜像引用my-insecure-registry.local:5000/library/nginx:alpine。
2. 根据我们之前的配置，它知道my-insecure-registry.local:5000对应的 endpoint 是http://my-insecure-registry.local:5000，并且允许不安全连接。
3. ctr会向http://my-insecure-registry.local:5000/v2/发起请求，进行仓库 API 版本检查。
4. 然后请求http://my-insecure-registry.local:5000/v2/library/nginx/manifests/alpine获取镜像清单（manifest）。
5. 接着根据清单中的层（layer）摘要（digest），逐个拉取 blob 文件，例如http://my-insecure-registry.local:5000/v2/library/nginx/blobs/sha256:xxx...。
6. 所有层拉取完毕后，在本地构建出完整的镜像。

常见问题与排查：

• 错误：failed to resolve reference “my-insecure-registry.local:5000/...: http: server gave HTTP response to HTTPS client`原因：这是最典型的错误，意味着 Containerd 仍然试图用 HTTPS 去连接仓库。99% 的原因是你的配置文件没有生效。排查：

  1. 确认配置文件/etc/containerd/config.toml修改正确，特别是 host 名称（my-insecure-registry.local:5000）是否与镜像引用中的完全一致，包括端口。
  2. 确认重启了containerd服务 (sudo systemctl restart containerd)。
  3. 检查是否有其他配置文件覆盖，例如/etc/containerd/certs.d/目录下的配置。ctr也会参考这个目录。你可以尝试在这个目录下创建对应的 host 配置来允许 HTTP。例如：

     sudo mkdir -p /etc/containerd/certs.d/my-insecure-registry.local:5000 echo ‘{“http”: true}’ | sudo tee /etc/containerd/certs.d/my-insecure-registry.local:5000/hosts.toml

     然后再次重启 containerd。/etc/containerd/certs.d/的优先级有时比config.toml中的 CRI 配置更高。

• 错误：failed to do request: Head “http://.../v2/...“: dial tcp: lookup my-insecure-registry.local on ...: no such host原因：DNS 解析失败，无法找到仓库主机。解决：确保你的主机名可以被解析。对于内网地址，最简单的方法是在/etc/hosts文件中添加一条记录：

  echo “192.168.1.100 my-insecure-registry.local” | sudo tee -a /etc/hosts

  将192.168.1.100替换为你私有仓库的实际 IP 地址。

• 错误：unexpected status: 404 Not Found原因：镜像在仓库中不存在，或者镜像引用路径写错了（例如，命名空间或镜像名错误）。解决：使用curl或浏览器直接访问仓库的 API 来验证镜像是否存在：

  curl -X GET http://my-insecure-registry.local:5000/v2/_catalog curl -X GET http://my-insecure-registry.local:5000/v2/library/nginx/tags/list

4.3 拉取镜像的进阶选项

ctr images pull提供了一些有用的选项：

• --skip-verify：跳过镜像内容的完整性验证（不推荐在生产环境使用）。
• --platform：指定拉取特定平台的镜像（如linux/amd64,linux/arm64）。这在多架构仓库中非常有用。
• --all-platforms：拉取所有可用平台的镜像。

# 拉取特定平台的镜像 sudo ctr images pull --platform linux/arm64 my-insecure-registry.local:5000/library/nginx:alpine # 拉取时显示详细信息 sudo ctr -d images pull my-insecure-registry.local:5000/library/nginx:alpine

5. 使用 ctr 进行 HTTP 镜像推送（Push）

将本地镜像推送到仓库，是ctr images push。但这里有一个关键前提：你需要先为本地镜像打上符合目标仓库地址的标签。

5.1 镜像标签管理与推送准备

ctr无法像docker tag那样直接给镜像重命名。在ctr的世界观里，镜像的名称（严格说是镜像引用）是其不可分割的身份标识。因此，我们通常需要先通过其他方式（比如从 Docker 导出再导入，或者直接构建）得到一个带有正确仓库标签的镜像。

方法一：利用 Docker 中转（如果 Docker 可用）这是最方便的方法。先用 Docker 拉取或构建镜像，打上标签，然后导出给ctr。

# 1. 使用 Docker 拉取或构建一个基础镜像 docker pull nginx:alpine # 2. 给这个镜像打上目标 HTTP 仓库的标签 docker tag nginx:alpine my-insecure-registry.local:5000/myteam/nginx:my-version # 3. 将 Docker 镜像导出为 tar 包 docker save -o nginx-myversion.tar my-insecure-registry.local:5000/myteam/nginx:my-version # 4. 使用 ctr 导入这个 tar 包 sudo ctr images import nginx-myversion.tar # 5. 检查 ctr 中是否有这个镜像 sudo ctr images ls | grep my-insecure-registry

方法二：直接使用 ctr 从远程拉取（如果源可用）如果源镜像本身就在某个可访问的仓库（包括这个 HTTP 仓库），直接拉取即可。

# 直接从目标 HTTP 仓库拉取一个镜像（假设已存在） sudo ctr images pull my-insecure-registry.local:5000/myteam/nginx:base

5.2 执行镜像推送操作

确保本地ctr的镜像列表中已经有了一个标签为目标 HTTP 仓库地址的镜像后，就可以执行推送了。

# 推送镜像到 HTTP 仓库 sudo ctr images push my-insecure-registry.local:5000/myteam/nginx:my-version

推送过程解析：

1. ctr会先检查本地是否存在该镜像。
2. 向仓库http://my-insecure-registry.local:5000/v2/发起请求，确认 API 支持。
3. 检查目标仓库中是否已存在该镜像的清单（Manifest），以决定是否需要上传层（Layer）。
4. 对于仓库中不存在的镜像层（Blob），ctr会逐个通过 HTTP PUT 请求上传到http://my-insecure-registry.local:5000/v2/myteam/nginx/blobs/upload/...。
5. 所有层上传完毕后，最后上传镜像清单（Manifest）文件，完成推送。

5.3 推送过程中的常见问题与排查

• 错误：failed commit on ref “manifest”: unexpected status: 401 Unauthorized原因：仓库需要认证，但ctr没有提供有效的凭据。解决：需要在 Containerd 的配置中为这个仓库配置认证信息。编辑/etc/containerd/config.toml，在对应仓库的configs下添加auth部分。

  [plugins."io.containerd.grpc.v1.cri".registry.configs."my-insecure-registry.local:5000".auth] username = "myuser" password = "mypassword"

  或者，更安全的方式是使用config.json文件。ctr会尝试从 Docker 的认证配置中读取凭据（~/.docker/config.json）。你可以先用docker login my-insecure-registry.local:5000登录，然后ctr可能会自动使用这些凭据。但注意，ctr对config.json的支持可能因版本而异，最可靠的方法还是直接写在config.toml里。修改配置后别忘了重启containerd。

• 错误：unexpected status: 405 Method Not Allowed或unexpected status: 404 Not Found原因：仓库的 API 路径可能不正确，或者仓库不支持 v2 API。请确保你的私有仓库（如 Harbor, Nexus）正确部署并开启了 v2 API 支持。用curl测试：

  curl -X GET http://my-insecure-registry.local:5000/v2/

  应该返回{}或一个空 JSON 对象。如果返回 404，说明 v2 API 未启用。

• 错误：推送缓慢或超时原因：镜像层太大，HTTP 传输慢或网络不稳定。解决：

  1. 考虑优化镜像，减少层数和大小。
  2. 对于内网，确保网络带宽和延迟正常。
  3. ctr本身推送大镜像的进度反馈不如 Docker 友好，需要耐心等待。可以加上-d参数查看详细日志。

6. 高级技巧与生产环境考量

6.1 使用/etc/containerd/certs.d/目录进行更精细的配置

我们之前修改了config.toml。实际上，Containerd 推荐使用/etc/containerd/certs.d/目录来配置每个仓库的详细设置，这个目录的配置优先级更高，且更清晰。

目录结构规则是：/etc/containerd/certs.d/<host:port>/hosts.toml

为我们的 HTTP 仓库创建配置：

# 创建对应仓库的配置目录 sudo mkdir -p /etc/containerd/certs.d/my-insecure-registry.local:5000 # 创建 hosts.toml 配置文件 sudo tee /etc/containerd/certs.d/my-insecure-registry.local:5000/hosts.toml << EOF server = “http://my-insecure-registry.local:5000” [host.”http://my-insecure-registry.local:5000″] capabilities = [“pull”, “resolve”, “push”] skip_verify = true # 如果需要认证 # [host.”http://my-insecure-registry.local:5000″.header] # authorization = [“Basic <base64-encoded-auth>”] EOF

这个配置明确指定了服务器地址、允许的操作，并跳过了验证。使用这种方式后，甚至可以简化或移除config.toml中的相关配置。修改此目录配置通常不需要重启 containerd，但为了保险起见，重启一下服务总是好的。

6.2 处理多架构镜像（Multi-Arch Images）

现代镜像仓库通常支持存储多个平台（如 amd64, arm64）的镜像，并通过一个“清单列表”（manifest list）来统一引用。ctr对多架构镜像的支持是原生的。

• 拉取多架构镜像的特定平台：

  sudo ctr images pull --platform linux/amd64 my-insecure-registry.local:5000/library/nginx:latest sudo ctr images pull --platform linux/arm64 my-insecure-registry.local:5000/library/nginx:latest

• 推送多架构镜像：这通常不是直接用一个ctr push完成的。你需要先分别构建或拉取不同平台的镜像，并使用像docker buildx或manifest-tool这样的工具创建并推送一个清单列表到仓库。ctr主要用于拉取和运行特定平台的单个镜像。

6.3 镜像导入、导出与迁移

ctr是进行镜像迁移的利器，尤其是在无法运行 Docker Daemon 的环境中。

• 从ctr导出镜像：

  # 导出单个镜像为 tar 包 sudo ctr images export nginx.tar my-insecure-registry.local:5000/library/nginx:alpine # 导出时可以指定平台 sudo ctr images export --platform linux/arm64 nginx-arm64.tar my-insecure-registry.local:5000/library/nginx:alpine

• 向ctr导入镜像：

  sudo ctr images import nginx.tar # 或者指定镜像名（如果 tar 包内元信息丢失） sudo ctr images import --base-name my-registry.com/nginx nginx.tar

这个功能在离线环境部署、镜像备份和恢复时非常有用。

6.4 安全警告与生产建议

允许 HTTP 连接是极不安全的，因为它使中间人攻击成为可能，攻击者可以篡改你下载或上传的镜像。因此，请务必遵守以下原则：

1. 仅用于测试和开发：HTTP 仓库只应在完全可控的内网测试环境中使用。
2. 使用 HTTPS：对于任何生产环境或跨网络的仓库，必须使用 HTTPS，并配置有效的 TLS 证书。你可以使用 Let‘s Encrypt 获取免费证书，或使用私有 CA 签发的证书。
3. 如果必须在内网使用 HTTP，请确保网络边界安全，避免该仓库暴露在公网。
4. 在 Containerd 配置中，尽可能精确地指定insecure_skip_verify = true的仓库 host，而不是使用通配符，以减少安全风险。

7. 总结与故障排查速查表

通过ctr使用 HTTP 协议操作镜像，本质上是绕过了 Docker Daemon，直接与容器运行时和镜像仓库进行底层对话。这提供了更大的灵活性和对流程的控制力，特别适用于无 Docker 环境、CI/CD 流水线或深度调试。

核心步骤永远有三步：

1. 配置：在/etc/containerd/config.toml或/etc/containerd/certs.d/<host>/hosts.toml中，为目标 HTTP 仓库明确设置insecure_skip_verify = true。
2. 重启：修改配置后，务必执行sudo systemctl restart containerd。
3. 操作：使用sudo ctr images pull/push命令，确保镜像引用中的仓库地址与配置中的 host 完全一致。

故障排查速查表：

掌握ctr的 HTTP 镜像操作，不仅仅是学会了一条命令，更是理解了容器镜像分发协议的底层逻辑。下次当你面对复杂的容器环境或棘手的镜像问题时，这份底层的掌控感或许能帮你更快地找到突破口。