上个月接到一个“看起来很简单的”任务：一台 Ubuntu 24.04 上新装的 containerd 2.x，怎么把镜像推到内网的 Harbor 仓库里去。本以为是三分钟的事，结果一执行就报了一个非常经典的错误——harbor 推送失败，get "https://192.168.209.133/v2/": dial tcp 192.168.209.133:connect: connection refused。
这个报错是不是很眼熟？如果眼熟，说明大概率也是从 Docker 切到 containerd 之后，直接把 Docker 那套“开箱即用”的思维带过来了。Docker 有 daemon.json，containerd 有自己的 config.toml 和 hosts.toml，两者完全不是一套体系。
这篇文章会把 containerd 2.x 接入 Harbor 的完整方法拆开讲清楚：先讲配置体系为什么和 Docker 不一样，再讲 hosts.toml 的核心规则，然后给出一套 Ubuntu 上可以直接抄的实操命令，最后把推送和拉取过程中的高频报错全部列出来，附上排查思路。适合三类人：正在切 containerd 的 Docker 老用户、需要维护 K8s 节点私有仓库的运维同学、以及第一次在 containerd 环境里对接 Harbor 的新手。
1. 先搞清楚：containerd 2.x 的仓库配置逻辑和 Docker 根本不是一回事
1.1 为什么 Docker 的 daemon.json 在 containerd 上完全不生效
很多人在 Docker 环境里配私有仓库，第一反应就是去改 /etc/docker/daemon.json，把 insecure-registries 加上，然后在每台机器上重启 docker。这个思路本身没有错，但切到 containerd 后，这套方法就完全失效了。
本质原因是进程环境不同。Docker 是通过 dockerd 这个守护进程统一下发配置，它认识 daemon.json 里的 insecure-registries、registry-mirrors 这些字段；而 containerd 是一个独立的容器运行时，它不读 daemon.json。containerd 2.x 的配置主文件只有一个，就是 /etc/containerd/config.toml，镜像仓库相关的细分配置则放在 /etc/containerd/certs.d 目录下。
我习惯把这两者做一个类比：daemon.json 相当于“手机运营商统一配置”，你告诉它“哪些号码免流”，它就全局记住；而 containerd 的 certs.d 目录更像是“通讯录分组”，每个仓库地址单独存一份联系人信息——协议是什么、证书是什么、要不要跳过验证。这个设计看似麻烦，实际上更适合多仓库环境，因为一台节点往往要对接多个私有仓库，每个仓库的协议和证书都不一样，全局一份配置反而容易互相冲突。
除了配置位置不一样，还有一层更容易被忽略的差异：Docker 的 insecure-registries 是“全局豁免”思维，只要这个地址被列进名单，所有对该地址的 HTTPS 校验都会被跳过。containerd 的 hosts.toml 则是“逐仓声明”思维，你要明确告诉它这个仓库用什么协议、用哪份证书、需不需要跳过校验。权限粒度不同，排查问题的入口也不同。
1.2 “get https://IP/v2/” 这句报错里藏着三个关键信息
开始动手之前，先学会看一句包含 get "https://192.168.209.133/v2/" 的报错。这个报错信息可以拆成三层：
- URL 部分：/v2/ 是 OCI 分发规范里所有 registry 的 API 固定前缀，Harbor 也不例外。containerd 在连接 Harbor 之前，会先请求这个路径做能力协商。只要这个请求失败，后面所有操作都会报错。
- 传输层部分：dial tcp 是 Go 语言网络库的标准报错前缀，后面跟着目标地址和端口。比如 dial tcp 192.168.209.133:443: connect: connection refused，说明 TCP 层根本没连上。
- 结果部分：后面跟着的具体错误类型，决定了你到底应该去查网络、查协议还是查证书。
很多新手看到 get "https://IP/v2/" 就开始怀疑 Harbor 配置，但真正的病根可能只是 Harbor 没有启动、端口写错了、或者仓库实际走的是 HTTP 而你写成了 HTTPS。所以我在后面第5章会把这些报错逐一展开。这里先记住一句话：containerd 接入 Harbor，一共就三件事要确认——目标通不通、协议对不对、认证过不过。先把这三件事梳理清楚，再去看具体配置，基本不会走弯路。
2. hosts.toml 才是接入 Harbor 的核心配置
2.1 目录结构：一个仓库地址对应一个目录
containerd 2.x 的镜像仓库配置，核心是 /etc/containerd/certs.d 目录。这个目录下不是一个大配置文件，而是按仓库地址分目录：
/etc/containerd/certs.d/192.168.209.133/hosts.toml /etc/containerd/certs.d/192.168.209.133:8443/hosts.toml目录的命名规则很严格：必须和镜像地址的主机名 + 端口完全一致。比如 Harbor 地址是 192.168.209.133:8443，目录就必须叫 192.168.209.133:8443；如果端口是默认的 80 或 443，一般可以省略，但我建议你宁可写上端口，也不要偷懒。因为目录名就是 containerd 判断“这份配置到底属于哪个仓库”的唯一依据。写错一个字符，配置再漂亮都白搭，而且这类错误很难定位，因为 containerd 不会主动告诉你“目录名匹配失败”。
目录里除了 hosts.toml，通常还会放 CA 证书，比如我自己习惯把 Harbor 的 ca.crt 直接放在这个目录下，和 hosts.toml 放一起。这样整个仓库相关的东西都集中在一个目录里，以后排查问题也好找。这个设计对多仓库环境特别友好：每个仓库一个独立目录，互相不干扰。改一个仓库的配置，也不会影响其他仓库。
2.2 让 containerd 真正认这个目录：config_path 开关
建好 certs.d 目录和 hosts.toml 之后，还有一个非常容易漏掉的环节：确认 config.toml 里有没有显式开启 certs.d 目录的开关。在 containerd 的配置体系里，这个开关叫 registry.config_path。
不同发行版里，这个配置所在的插件段落名称会有差异。K8s 里常见的写法是：
version = 2 [plugins."io.containerd.grpc.v1.cri".registry] config_path = "/etc/containerd/certs.d"而 containerd 2.x 如果采用了新的外部 CRI 插件方案，段落名可能变成 io.containerd.cri.v1.runtime，段落内部依然是 registry.config_path。我的实际经验是：别凭记忆写插件名，直接去现网配置文件里搜 registry 关键字，最稳妥。
grep -n "registry" /etc/containerd/config.toml如果输出里已经有 config_path 指向了 /etc/containerd/certs.d，那就不用再改；如果没有，需要手动加上。加完 config_path 后，一定要重启 containerd 让配置生效。这里强调一下，在 K8s 节点上执行 systemctl restart containerd，会把节点上所有容器重启一遍，建议提前做好工作负载迁移或排维护时间。
2.3 hosts.toml 关键字段解读
hosts.toml 里最常用到的字段就这么几个，我用一个表格整理出来：
| 字段 | 作用 | 典型值 |
|---|---|---|
| server | 声明这个仓库的默认访问地址，协议+主机+端口 | "https://192.168.209.133:8443" |
| [host."地址"] | 定义具体 endpoint 的详细配置 | [host."https://192.168.209.133:8443"] |
| ca | 访问该仓库时使用的 CA 证书路径 | "/etc/containerd/certs.d/192.168.209.133:8443/ca.crt" |
| skip_verify | 是否跳过 TLS 证书校验 | true / false |
| capabilities | 声明该 endpoint 支持的操作 | ["pull", "resolve", "push"] |
其中最容易理解错的是 server 字段。它决定了 containerd 默认用什么协议去访问目标仓库。如果 Harbor 是 HTTP 模式，server 就写 http:// 开头；如果是 HTTPS，就写 https:// 开头。我把这个字段理解为“本次对接的协议总开关”，很多“推送失败”的根源就在这里——服务端明明是 HTTP，客户端却按 HTTPS 去握手，自然报错。
举个实际的例子。如果 Harbor 是 HTTP 模式，hosts.toml 可以这样写：
server = "http://192.168.209.133" [host."http://192.168.209.133"] capabilities = ["pull", "resolve", "push"]如果是自签 HTTPS 模式，关键是把 Harbor 用的 CA 证书放进 ca 字段：
server = "https://192.168.209.133:8443" [host."https://192.168.209.133:8443"] ca = "/etc/containerd/certs.d/192.168.209.133:8443/ca.crt"注意，官方字段名是 capabilities 复数形式，我见过有人写成单数导致配置不生效，这个细节非常坑。另外，skip_verify 只在 HTTPS 场景下有意义；如果 server 已经写成 http，这个字段填不填都无所谓，因为根本没有 TLS 握手环节。
3. 接入之前，先确认清楚 Harbor 的协议、证书和权限
3.1 一个 curl 命令判断 Harbor 到底是 HTTP 还是 HTTPS
在写 hosts.toml 之前，最重要的一步是先确认 Harbor 实际提供的协议。很多人在这一步就踩坑：Harbor 明明是 HTTP 模式，却想当然地写 https，结果怎么改都不通。
判断方法非常简单，在客户端上用 curl 分别测试 http 和 https 两个协议，看哪个有正常响应：
curl -v http://192.168.209.133/v2/ curl -v https://192.168.209.133/v2/如果 http 那个能返回一个 JSON 或 401 之类的正常 HTTP 响应，说明 Harbor 的 nginx 入口走的是 HTTP；如果 https 那个能返回 401，说明走的是 HTTPS。两个都试一下，以实际输出为准，而不是以 Harbor 安装文档上写的为准。因为 Harbor 在很多内网环境里，安装时如果没有提供证书，安装器会自动生成一个 http 模式的配置，对外端口可能是 80，也可能是 8080，甚至可能是 443 上的 nginx 直接返回 502。
确认协议之后，再确认端口。Harbor 通过 docker compose 管理端口映射，常见端口是 80、443、8080、8443 等。在 Harbor 服务器上执行 docker ps | grep -E "nginx|proxy"，或者 docker compose ps，就能看到实际映射的端口。客户端这边可以用 nc 验证端口连通性：
nc -vz 192.168.209.133 8443如果端口不通，后面无论怎么调 hosts.toml 都没有用。先把网络层这一关过了，再去考虑协议和证书。这个检查顺序特别重要，我自己吃过亏：有次折腾了半小时证书，最后发现是 Harbor 升级后端口映射从 443 变成了 8443，连网络层都没通，纯属白忙。
3.2 证书策略：内网环境直接用 HTTP，还是配自签 HTTPS？
关于 Harbor 接入 containerd，我的观点很明确：如果你的环境是完全受信任的内网，HTTP 模式完全够用，配置最少，维护成本也最低。Docker 时代大家习惯配 insecure-registries，本质上也是放弃 TLS 校验，只是把配置放在一个全局字段里。containerd 时代无非是把同样的意图写进 hosts.toml，让 server 指向 http 协议。
但有些环境有安全审计要求，必须走 HTTPS。这时候建议直接生成一套自签名证书给 Harbor 用，然后把 CA 分发给所有需要访问的客户端。自签证书的生成逻辑是：先做一个 CA，再用 CA 签服务器证书。这里不展开完整的 openssl 配置，只提醒几个要点：
- 服务器证书的 Common Name 或 Subject Alternative Name 必须包含 Harbor 的访问地址，比如 IP 192.168.209.133，否则客户端校验时会报证书域名不匹配。
- Harbor 的 HTTPS 模式需要在安装配置里指定 certificate_path 和 private_key_path。
- 客户端的 hosts.toml 里 ca 字段填的是签发服务器证书的 CA 文件，而不是服务器证书本身。填错的话，证书校验依然会失败。
如果你已经拿到了 Harbor 用的 ca.crt，可以直接把它复制到客户端的 /etc/containerd/certs.d/<仓库地址>/ 目录下。复制完记得校验一下文件内容，不要复制了一个空文件或者复制成服务器证书。用 openssl 验证最简单：
openssl x509 -in /etc/containerd/certs.d/192.168.209.133:8443/ca.crt -noout -subject -issuer3.3 Harbor 项目与账号的最小权限配置
Harbor 的仓库路径里，项目名是必填的一级目录。比如要推送 nginx 镜像，完整路径是 192.168.209.133:8443/library/nginx:1.24，其中 library 是项目名，nginx 是仓库名，1.24 是 tag。项目名不能省略。很多新手第一次接触 Harbor 时，把镜像打成 192.168.209.133:8443/nginx:1.24，就会在推送时报错，因为 Harbor 找不到 nginx 这个项目。
权限方面，Harbor 的默认项目 library 对所有用户可见，但推送需要账号具备对应角色。测试阶段直接用 admin 账号没问题，生产环境我建议用机器人账号，或者创建一个专门的服务账号，只给它加入目标项目并分配“开发人员”角色。开发人员角色可以拉取和推送镜像，但无法删项目，权限边界比较清晰。
需要注意用户名和密码里如果有特殊字符，比如 @ 或者 /，login 时容易解析出错，可以先在终端里输入完整命令，确认输出提示登录成功再继续。另外，Harbor 的机器人账号在推送时，镜像路径前缀依然要带项目名，但凭证用户名是一个固定格式字符串，不要把账号和密码填反了。
4. Ubuntu 完整实操：从写配置到成功 push 镜像
4.1 确认 containerd 版本与安装 nerdctl
动手前先看一下自己手里的 containerd 到底是哪个版本，避免拿 1.x 的配置思路套 2.x：
containerd --version ctr versioncontainerd 2.x 的版本号现在类似 2.1.x，如果输出是 2.0.x 或 2.1.x，那就可以按本文方案操作。接下来确认有没有 nerdctl。ctr 是 containerd 自带的调试客户端，但它不支持 login 命令，日常推拉私有仓库体验很差，所以我又装了 nerdctl。nerdctl 是 containerd 生态里体验最好的 CLI，命令风格和 docker 几乎一致，支持 login、tag、push、pull、run 都行。
安装 nerdctl 很简单，从官方 release 页面下载对应的二进制，放到 /usr/local/bin，给执行权限就行：
curl -sSL -o /usr/local/bin/nerdctl <下载地址> chmod +x /usr/local/bin/nerdctl nerdctl version这里给个建议：不要用系统自带的 ctr 来登录 Harbor，它没有 login 子命令，每次配置凭证都比较绕。老老实实用 nerdctl，省心很多。如果你所在环境不允许从外网下载，也可以从另一台已经装了 nerdctl 的机器上直接拷贝二进制，依赖很少，一般能直接运行。
4.2 写入证书与 hosts.toml
假设 Harbor 地址是 192.168.209.133:8443，走 HTTPS，并且我已经拿到了 Harbor 的 ca.crt。接下来就是三步：
第一步，创建目录：
mkdir -p /etc/containerd/certs.d/192.168.209.133:8443 cp /path/to/ca.crt /etc/containerd/certs.d/192.168.209.133:8443/第二步，写 hosts.toml：
cat > /etc/containerd/certs.d/192.168.209.133:8443/hosts.toml <<'EOF' server = "https://192.168.209.133:8443" [host."https://192.168.209.133:8443"] ca = "/etc/containerd/certs.d/192.168.209.133:8443/ca.crt" capabilities = ["pull", "resolve", "push"] EOF如果你的 Harbor 走的是 HTTP，比如地址是 192.168.209.133，就用这个版本：
mkdir -p /etc/containerd/certs.d/192.168.209.133 cat > /etc/containerd/certs.d/192.168.209.133/hosts.toml <<'EOF' server = "http://192.168.209.133" [host."http://192.168.209.133"] capabilities = ["pull", "resolve", "push"] EOF第三步，检查 config.toml 里有没有指向 certs.d 的 config_path。如果 grep 不到，就手动追加。追加完成后重启 containerd：
systemctl restart containerd重启这步请注意：如果是 K8s 计算节点，上面所有 Pod 会经历一次重建。如果只是想验证配置，也可以先跳过重启，直接上手操作；但如果后续命令报“配置没生效”，大概率就是没有重启或没有正确设置 config_path。
4.3 登录 Harbor 并完成第一次推送
配置写完后，先用 nerdctl login 验证一遍认证链路：
nerdctl login 192.168.209.133:8443 -u admin它会提示输入密码。登录成功后，再执行镜像拉取、打 tag、推送流程。我演示一下完整命令序列，直接可以抄：
# 1. 从 Docker Hub 拉一个官方镜像 nerdctl pull nginx:1.24 # 2. 打成 Harbor 仓库路径的 tag nerdctl tag nginx:1.24 192.168.209.133:8443/library/nginx:1.24 # 3. 推送到 Harbor nerdctl push 192.168.209.133:8443/library/nginx:1.24push 过程中如果有进度条一直在走，说明 hosts.toml 的 capabilities 配置没问题；如果卡在 login 或者直接报错，回到第3节去查协议和证书。第一次推送成功之后，最好到 Harbor 的 Web 界面里刷新一下，确认 library/nginx 这个仓库真的出现了。这一步不麻烦，但能确认数据层面的写入确实成功，而不仅仅是 CLI 端认为成功。
4.4 从 Harbor 拉取镜像并运行容器验证
推送成功只验证了写路径，还需要验证读路径。在另外一台只配置了 containerd 的机器上，尝试直接拉取刚才推送的镜像：
nerdctl pull 192.168.209.133:8443/library/nginx:1.24 nerdctl run -d --name nginx-test -p 8080:80 192.168.209.133:8443/library/nginx:1.24如果这台机器没有登录过 Harbor，而 library 项目是公开的，拉取应该直接成功；如果项目是私有的，需要先执行 nerdctl login。实际验证一下 curl http://localhost:8080 返回正常 Nginx 页面，整个流程就闭环了。
这里补充一个经验：containerd 的命名空间概念对新手很容易产生困扰。nerdctl 默认工作在 default 命名空间，而 kubelet 使用的是 k8s.io 命名空间。如果用 nerdctl run 启动的容器，kubelet 是看不到的，两者互不干扰。但这也意味着你在命令行拉取的镜像，并不会自动出现在 K8s 可用的镜像列表里——除非你也在 k8s.io 命名空间里执行同样的操作。日常排查时别忘了查看当前命名空间：nerdctl --namespace k8s.io pull 才能命中 K8s 路径。
4.5 如果上面这套配置用在 Kubernetes 节点上
很多读者是在 K8s 节点上解决 containerd 接入 Harbor 的问题，所以单独说一节。核心配置是一样的，config_path 指向 certs.d 目录之后，kubelet 通过 CRI 调用 containerd 拉镜像时，自然就会使用 hosts.toml 里的协议和证书配置。区别在于认证方式：kubelet 不会直接使用你在终端里 nerdctl login 留下的凭证，需要在创建 Pod 时显式指定 imagePullSecrets。
标准做法是用 docker-registry 类型的 Secret 保存 Harbor 凭证：
kubectl create secret docker-registry harbor-cred \ --docker-server=192.168.209.133:8443 \ --docker-username=admin \ --docker-password=你的密码 \ --docker-email=你@example.com然后在 Deployment 或 Pod 里加上：
spec: imagePullSecrets: - name: harbor-cred containers: - name: nginx image: 192.168.209.133:8443/library/nginx:1.24另外，containerd 2.x 使用 K8s 时，还要留意 CRI 插件的形态。2.0 以后官方的 CRI 插件已经拆成了独立组件，如果你是用官方 release 包手动部署的，需要额外安装 cri 插件，否则 kubelet 会报 CRI 接口未实现。包管理器装出来的 containerd.io 一般已经包含 CRI 支持，但自编译或裸二进制部署很容易漏掉这一环。
5. 高频报错实录：每个报错我都替你踩过一遍
5.1 dial tcp 192.168.209.133:443: connect: connection refused
这个报错是网络层没连通，和 containerd 的配置没有半毛钱关系。先检查 Harbor 服务器上端口是否监听：
ss -lntp | grep -E "443|80|8443"再检查客户端到服务器的连通性：
nc -vz 192.168.209.133 8443如果服务器没监听，说明 Harbor 没起来或者端口映射不对，去 Harbor 服务器上执行 docker compose ps 看一下组件状态。如果客户端连不通，要检查防火墙和安全组规则。这里我踩过一个大坑：Harbor 服务器本地访问 443 是通的，但外部访问不通，最后发现是云安全组只放行了 80，没有放行 443。排查网络问题时，一定要在客户端机器上验证，而不是在服务器本机验证。
5.2 x509: certificate signed by unknown authority
这个报错是证书校验失败，包含两种具体情况。第一种是 Harbor 走了 HTTPS，但客户端 hosts.toml 里没有配置 ca，或者 ca 路径写错了；第二种是 ca 文件填成了服务器证书而不是签发它的 CA 证书。解决办法就是回到第3节的证书策略，把正确的 CA 文件放到 hosts.toml 指定的路径下，然后重启 containerd。
还有一种临时性做法：在 hosts.toml 里把 skip_verify 设为 true，绕过证书校验。这个操作在纯内网测试环境里可以应急，但生产环境我不建议长期开着，因为敏感流量等于裸奔。如果审计要求高，尽量把 ca 配置到位。判断 ca 文件到底对不对，用这条命令：
openssl x509 -in ca.crt -noout -subject -issuer输出里的 subject 要和你生成的 CA 名称一致，而 issuer 就是 CA 自身，这样才说明这是一个真正的 CA 证书。如果看到的就是服务端证书，那就要换。
5.3 http: server gave HTTP response to HTTPS client
这个报错是协议不匹配的经典症状，英文已经说得很直白：服务端返回的是 HTTP 响应，但客户端发的是 HTTPS 请求。最常发生在 Harbor 明明走 HTTP，而 hosts.toml 里 server 却写成 https://，或者干脆没写 server 导致 containerd 默认按 https 访问。
解决办法是把 hosts.toml 里 server 改成 http:// 对应的地址。改完重启 containerd，再重新 push。我测试过，这个错误在 push 时特别容易遇到，因为推送默认会用 manifest 和 blob 的完整 HTTP 请求，一旦协议不匹配，整个过程会非常干脆地失败。
5.4 unauthorized: unauthorized to access repository
这个报错是认证或权限问题，命令层面没有任何网络和 TLS 问题。常见原因有三个：
- 用户没有登录，或者登录的是别的仓库地址。检查一下 nerdctl login 的地址和 push 的镜像地址是否完全一致。
- 用户对目标项目没有 push 权限。Harbor 项目角色需要至少“开发人员”。
- 镜像路径里的项目名不存在或拼写错误。比如 library 写成了 libray，或者把项目名漏掉了。
另外，Harbor 项目如果是私有权限，拉取镜像时也要求登录，否则会看到类似 pull access denied 的报错。这时候回到 Pod 的 imagePullSecrets 配置，确认 Secret 里的 docker-server 字段和镜像地址完全一致，包括端口。
5.5 常见错误速查表
最后给你整理一个速查表，遇到问题时先对照表里看一遍，八成能直接定位：
| 报错关键词 | 大概率原因 | 第一动作 |
|---|---|---|
| connection refused | Harbor 未启动或端口不通 | nc 验证端口，docker compose ps 查组件 |
| no route to host | 网络路由问题 | 检查防火墙、安全组、跨网段访问 |
| x509 unknown authority | CA 未配置或配置错误 | 检查 hosts.toml 的 ca 字段 |
| server gave HTTP response to HTTPS client | 协议不匹配 | server 改成 http:// |
| unauthorized | 未登录或权限不足 | 检查登录、项目角色、路径 |
| manifest unknown | tag 不存在或仓库名错误 | 到 Harbor Web 确认仓库和 tag |
| project not found | 项目名不存在 | 在 Harbor 创建项目再推送 |
这个表我在排障时一直贴在旁边，基本覆盖了 containerd 对接 Harbor 的绝大多数问题。还有一些不太常见但会遇到的，比如磁盘不足导致 blob 写入失败、超大镜像推送时网络超时、Harbor 的垃圾回收任务锁住仓库导致 push 被拒，这些往往要结合 Harbor 服务端的日志来排查，属于另一个话题了。
最后说点个人体会。接触 containerd 2.x 一段时间之后，我发现它和 Docker 的区别并不只在配置格式上，更在思维模式上：Docker 希望你把所有仓库设置堆在一个全局文件里，而 containerd 的 hosts.toml 体系强调的是“每个仓库独立成册”。刚开始会觉得目录多、配置散，但维护过几台节点后，反而觉得这种方式更清晰，因为你永远不会因为改一个仓库的证书而影响其他仓库。
再分享一个实用小技巧：如果你有多个 Harbor 实例，或者想给同一个仓库地址配置多个端点（比如先走内网缓存，缓存挂了再回源 Harbor），可以在同一个 hosts.toml 里堆多个 host 块，containerd 会按顺序尝试。这个玩法非常香，等于把 Docker 时代要写好几处配置的事，浓缩在一个文件里完成。
这次我接入 Harbor 的实际过程，从报 connection refused 到最终成功 push，前后只花了不到半小时，熟练之后其实就是一个“写文件 + 重启 + login”的循环。希望这篇文章能帮你跳过我最开始踩的那些坑，一次就把 containerd 和 Harbor 打通。
