containerd 2.x接入Harbor私有仓库配置与排障实战-北京尧图网络

很多朋友在Kubernetes节点上碰到containerd配置Harbor私有仓库时一脸懵最大的困惑点在于明明Docker那边配个daemon.json就能用得飞起怎么到了containerd这边各种推不上去、拉不下来尤其是containerd升级到2.x之后配置结构又变了一轮网上老教程大多还停留在1.x时代的写法按着旧配置改完镜像还是卡在dial tcp或者x509错误上。这篇文章我就围绕containerd 2.x接入Harbor仓库整个链路把配置原理、具体改法、推送拉取实操、以及高频报错的排查思路一次性讲透。适合正在维护K8s节点、想让节点直接从Harbor拉取私有镜像的运维和开发同学如果你恰好遇到了harbor推送失败 get https://192.168.209.133/v2/: dial tcp 192.168.209.133: connect: connection refused这类问题那这篇文章基本就是照着你的报错来写的。1. 接入前必须搞清楚的三件基础事1.1 containerd 2.x和Docker的配置逻辑不是一回事先别急着拿Docker那一套来套containerd。Docker的仓库配置集中在/etc/docker/daemon.json里面塞了insecure-registries、registry-mirrors、auths改完执行systemctl restart docker就生效。containerd走的是完全不同的路子它本身是一个行业标准的容器运行时不只服务Docker还直接服务Kubernetes的kubelet所以它的配置拆得非常细CRI插件的配置给kubelet用的镜像仓库hosts配置给containerd自身用的命名空间隔离不同容器的镜像存储彼此隔离2.x版本里面官方推荐的方式是使用config_path指向一个目录目录里按registry域名/地址分文件夹每个文件夹里放一个hosts.toml文件用来声明这个仓库的endpoint、CA证书、跳过证书验证等。这个设计比旧版把所有endpoint写在config.toml里灵活得多支持给不同的仓库配不同的TLS策略也方便按节点分发配置。我在实际维护中见过不少同事把1.x的旧配置直接搬到2.x上结果containerd服务起得来但crictl pull直接报failed to resolve reference因为2.x对旧字段的兼容性已经没那么友好了。如果你升级了containerd或者新装的就是2.x版本务必优先确认当前版本对应的配置写法。1.2 版本确认和目录结构动手前别瞎猜登录到节点上第一步永远是确认版本。执行ctr version输出里的Version字段会告诉你containerd的准确版本号比如v2.0.x。如果手头有多个节点要批量操作建议写个循环脚本把这些信息收集一下避免在2.x和1.x节点上用了同一种配置结果一台能跑一台跑不了。接着检查当前配置目录结构ls -l /etc/containerd/正常情况下有一个config.toml2.x版本还会默认把CRI插件的仓库配置指向/etc/containerd/certs.d这个路径可以通过配置修改不一定是固定的。我们可以在config.toml里搜一下config_pathgrep -n config_path /etc/containerd/config.toml如果有输出说明当前配置已经启用了hosts目录方案如果没有说明要么还在用旧版段落式配置要么就是还没配置过。也建议看一眼Harbor侧的服务状态。Harbor是部署在独立一台机器上的它跑的端口通常有80和443但也可以通过nginx对外暴露自定义端口如8443或者30002这类NodePort。你需要确认Harbor自己用的哪个端口、走的是HTTP还是HTTPS、以及证书是不是自签的。这三个信息直接决定了containerd侧怎么配。1.3 三个命令行工具的分工别搞混接触containerd节点的人一定会遇到三个命令ctr、crictl、nerdctl。经常有人问为什么ctr不能用crictl的配置、为什么nerdctl推镜像的方式和crictl不一样根源在于它们面向的调用链不一样ctr是containerd原生CLI直接和containerd内置的各种服务打交道比如k8s.io、default命名空间下的镜像管理但它不关心CRI层配置所以如果你的仓库配置放在CRI插件段落里ctr可能不受影响。crictl是独立的容器运行时接口CLIKubernetes的kubelet通过CRI和containerd通信因此crictl的配置走的是CRI插件段。生产环境拉镜像、给K8s用基本以crictl为准。nerdctl是containerd的Docker兼容CLI体验最接近Docker它支持login、pull、push这些用户友好的子命令底层自动处理了认证和配置映射很多场景下排查问题比ctr直观得多。所以在下面的实际操作里我会区分给你看节点上给K8s拉镜像的配置应该走config_pathhosts.toml手动调试推送和拉取时用nerdctl最省心用ctr操作时要注意加-n指定命名空间比如ctr -n k8s.io images pull。2. 接入Harbor仓库的两种标准姿势2.1 姿势一HTTP明文仓库 allow_insecure跳过验证这是测试环境用得最多的快速接入方式。如果你的Harbor没有配置HTTPS证书就用IP加端口直接访问比如192.168.209.133做仓库首页/v2是Docker Registry V2协议的基础路径。常见报错里的dial tcp 192.168.209.133:...如果端口对不上很可能就是node和Harbor之间不通或者端口规则没放行。先说明一下生产环境强烈不建议长期用HTTP明文仓库镜像在传输过程中是裸奔的一旦网络链路被监听镜像内容等于直接暴露。所以这个姿势适合开发、测试、内网可信任环境。如果你一定要在测试环境快速接入操作如下在/etc/containerd/config.toml里找到CRI插件段落看有没有registry配置块。以2.x版本为例需要确保以下两项存在version 2 [plugins.io.containerd.grpc.v1.cri.registry] config_path /etc/containerd/certs.d [plugins.io.containerd.grpc.v1.cri.registry.mirrors] [plugins.io.containerd.grpc.v1.cri.registry.mirrors.192.168.209.133] endpoint [http://192.168.209.133/v2]然后创建仓库对应的hosts配置文件mkdir -p /etc/containerd/certs.d/192.168.209.133 vim /etc/containerd/certs.d/192.168.209.133/hosts.toml内容如下server http://192.168.209.133/v2 [host.http://192.168.209.133/v2] capabilities [pull, resolve, push] skip_verify true重启containerd让配置生效systemctl restart containerd有些环境里你还需要注意[plugins.io.containerd.grpc.v1.cri.registry.mirrors]段落配置的endpoint是给CRI拉镜像时走的镜像源地址而hosts.toml里的[host.http://...]是具体访问规则两者一个管“去哪里找”一个管“怎么连”别混。配置完先用下面小节的方法验证能通再继续。2.2 姿势二HTTPS自签名证书仓库生产推荐但凡涉及生产环境、多个节点、需要走公网或跨机房拉镜像我都只推荐HTTPS方式。Harbor通常自带一套nginx服务你可以给它配自签名证书也可以接入企业内部CA签发的证书。自签名证书需要在每个节点上配置信任没有配置的话containerd拉镜像会报x509: certificate signed by unknown authority。实际操作分三步走。第一步准备好Harbor的CA证书。如果你在Harbor机器上操作证书一般位于/data/cert/或者你自己指定过的路径比如ca.crt。没有的话从nginx配置里找ssl_certificate对应的证书文件它本身如果就是自签CA签出来的可以直接当CA用。第二步把证书放到containerd节点的可信目录下并在hosts.toml里显式指定。以Harbor地址registry.internal:8443为例mkdir -p /etc/containerd/certs.d/registry.internal:8443 cp /path/to/ca.crt /etc/containerd/certs.d/registry.internal:8443/ca.crthosts.toml文件内容server https://registry.internal:8443/v2 [host.https://registry.internal:8443/v2] ca /etc/containerd/certs.d/registry.internal:8443/ca.crt capabilities [pull, resolve, push]第三步确认config.toml里已启用config_path并重启containerd。如果Harbor的证书不是自签CA而是某个私有CA签发的那么这个私有CA的根证书一定要放到每个节点上且hosts.toml里的ca路径要指向它。系统级的/etc/ssl/certs不加的话光靠containerd自身的信任链是不够的。我自己的倾向是只要能管控Harbor侧就一律用自签CA签发的HTTPS证书然后在节点初始化脚本里统一分发CA避免每台机器手工配置。这样后续新增节点也只是一个copy restart的动作。2.3 验证配置生效从拉一个镜像开始配置改完了立刻验证。比如Harbor里已经有一个library/busybox:latest镜像你想从节点直接拉取crictl pull registry.internal:8443/library/busybox:latest如果顺利会看到Image is up to date或下载进度。这时候说明config_path和hosts.toml这套链路已经打通了。想进一步确认到底是哪段配置生效可以用nerdctl边调试边看nerdctl --namespace k8s.io pull registry.internal:8443/library/busybox:latest如果卡住了ctrlc之后加上--debug参数重新跑它会输出非常详细的HTTP请求过程包括它实际请求的endpoint地址、证书验证结果、以及请求头信息。3. 镜像推送与拉取的完整实操流程3.1 用nerdctl操作体验最接近Docker如果你在节点上装好了nerdctl推送和拉取Harbor镜像的体验和Docker几乎一样。先登录nerdctl login registry.internal:8443 -u admin -p Harbor12345登录成功后认证信息会写入~/.config/nerdctl/相关配置里后续推送拉取自动带上token。注意这里和Docker的~/.docker/config.json不是同一个位置别指望containerd会自动读取Docker的凭据文件。推送镜像前先给本地已有的镜像打上Harbor仓库的标签# 本地已有镜像 local-web:latest nerdctl tag local-web:latest registry.internal:8443/library/local-web:latest然后推送nerdctl --namespace k8s.io push registry.internal:8443/library/local-web:latest整个推送过程中如果Harbor侧启用了漏洞扫描推送完成后的上传阶段会多一个等待时间那是正常的。推送结束后回到Harbor的Web界面在library项目下能看到这个镜像及tag。3.2 用ctr操作必须明确指定命名空间ctr操作时最容易被忽略的就是命名空间。containerd默认的命名空间是default而Kubernetes节点上的镜像存储在k8s.io命名空间里。如果你用ctr images pull拉了一个镜像K8s的kubelet并不会去default命名空间找所以你会发现“明明拉下来了但节点上还是说没有这个镜像”。推荐的做法是ctr -n k8s.io images pull registry.internal:8443/library/busybox:latest-n k8s.io指定命名空间为k8s.io这行命令拉下来的镜像才真正落到K8s可用的仓库里。同理推送已有镜像ctr -n k8s.io images push registry.internal:8443/library/busybox:latestctr默认不处理登录态的自动注入它更依赖config.toml里配置好的仓库认证信息。这就是为什么很多纯ctr环境里拉公共镜像没问题拉Harbor私有镜像就不断报401的原因——hosts.toml里没配认证信息或者没有执行过nerdctl login。3.3 离线镜像包和Harbor的导入导出如果Harbor节点本身没法访问公网你拿到的可能是一个tar格式的镜像包比如ubuntu-harbor-images.tar。这类包在containerd节点上导入导出也有一套固定动作。导入单个镜像包ctr -n k8s.io images import ubuntu-harbor-images.tar批量导入目录下所有tar包可以用循环for tarfile in /data/offline/*.tar; do ctr -n k8s.io images import $tarfile echo imported: $tarfile done导出镜像为tar包ctr -n k8s.io images export ubuntu-harbor-images.tar registry.internal:8443/library/ubuntu:22.04如果你想在Harbor和节点之间搬运一批镜像最省事的方式是先用nerdctl pull到本地缓存再nerdctl push到Harbor中间无需落地tar文件速度也更快。对于批量镜像我一般维护一个images.list文件循环执行while read -r image; do nerdctl --namespace k8s.io pull $image nerdctl --namespace k8s.io push $image done images.list4. 高频故障排查与避坑心得4.1 最经典的dial tcp先把网络层排查干净以harbor 推送失败 get https://192.168.209.133/v2/: dial tcp 192.168.209.133:...为例这类报错是接入Harbor时最常碰到的第一道坎。很多人一看到get https://.../v2/就急着改containerd配置其实这个报错传达的信息是containerd服务器根本没能和Harbor建立TCP连接。排查路径按下面顺序来IP和端口是否可达在节点上执行telnet 192.168.209.133 443或者nc -vz 192.168.209.133 443如果Connection refused要么Harbor服务没起要么端口不是443。Harbor默认80和443但如果你把它映射到30002这类端口那配置里就得写192.168.209.133:30002。Harbor核心服务是否正常登录Harbor机器docker ps看Harbor的nginx容器是否在运行。Harbor停了节点侧永远都会是连接问题。防火墙和安全组检查节点到Harbor的中间链路上有没有防火墙策略。很多环境里K8s节点和Harbor不在同一个网段中间的防火墙规则忘了放行Telnet结果就一直是超时。域名解析如果你配置的是域名而不是IP先getent hosts registry.internal看解析结果对不对。有一个速查技巧如果curl -k https://192.168.209.133/v2/在节点上能返回{}或一个JSON说明Harbor的HTTPS服务和端口是通的问题大概率出在配置细节上如果curl直接失败就别折腾containerd配置了先把Harbor服务弄成可从节点访问再说。4.2 x509证书问题和HTTP访问HTTPS的错配排除网络连接问题后第二类高频报错集中在TLS握手阶段。一种是x509: certificate signed by unknown authority这基本就是证书信任问题。在hosts.toml里要么配上ca路径指向可信CA要么在测试环境里临时用skip_verify true。生产建议走CA分发方案不要为省事跳过验证否则任何中间设备都能冒充Harbor。另一种是http: server gave HTTP response to HTTPS client。这个报错翻译过来是你的containerd客户端用的是HTTPS去访问但Harbor这边返回的却是HTTP响应。说白了就是协议不一致。解决办法是在hosts.toml和endpoint里都明确写http://而不是https://我见过最迷惑的情况是config.toml里写的是http://而hosts.toml里写的是https://两边不一致导致怎么试都失败。4.3 默认仓库解析失败和docker hub访问问题节点上有些镜像默认带的是docker.io/library/ubuntu:22.04形式如果节点没有外网拉取权限或者被墙卡住会看到failed to resolve reference docker.io/library/ubuntu:22.04。这类问题不属于Harbor接入本身但和config.toml里的镜像加速器配置有关。在2.x版本里CRI插件的registry.mirrors段落可以指定一个docker.io的镜像源地址[plugins.io.containerd.grpc.v1.cri.registry.mirrors] [plugins.io.containerd.grpc.v1.cri.registry.mirrors.docker.io] endpoint [https://docker.m.daocloud.io]不过具体镜像源地址要以你的网络环境为准我这里只是举个例子。该配置定位是加速和代理不能把它当成Harbor接入的替代方案。4.4 认证相关的401和invalid credentials仓库地址和TLS都通了拉取私有镜像时如果报unauthorized: unauthorized to access repository或者401 Unauthorized就说明认证信息没有正确传递。如果你用的是nerdctl检查登录是否成功、凭据是否写进当前用户的配置里。如果你用的是ctr配置认证信息可以通过在hosts.toml里显式写auth字段或者配置[plugins.io.containerd.grpc.v1.cri.registry.configs]。不过我不推荐在config.toml里明文塞用户名密码尤其在共享服务器上很容易被其他人看到。更稳妥的方式是用nerdctl login生成凭据。还有一个细节需要留意镜像路径中项目名的大小写、以及Harbor项目是否存在。比如Harbor里只有library项目但你推了一个harbor.local/MyProject/nginx:latest的路径MyProject大小写和实际项目不一致时Harbor也可能返回unauthorized因为在它看来你请求的仓库根本不存在。4.5 问题排查速查表报错特征根因方向排查建议dial tcp IP:port: connect: connection refused网络不通、端口错误、Harbor服务未运行检查监听端口、telnet/curl 连通性dial tcp IP:port: i/o timeout防火墙拦截、路由不通检查安全组和防火墙策略x509: certificate signed by unknown authority证书不在信任链配置ca路径或安装CA到系统证书http: server gave HTTP response to HTTPS client客户端和服务端协议不一致统一http://或https://配置401 Unauthorized认证信息缺失、项目不存在检查登录态、镜像路径的项目名failed to resolve reference仓库地址写错、mirror解析失败检查hosts.toml的server和endpointconnection reset by peer中间设备拦截、Harbor并发限制检查Harbor日志和网络设备这七类问题基本覆盖了90%的containerd接入Harbor故障场景。真到了排查环节我希望你记住一个准则先网络、后协议、再认证、最后才是配置格式不要一上来就改配置文件容易越改越乱。5. 把配置做成可复用的标准化方案5.1 hosts.toml目录化管理带来的便利相比把仓库信息全塞在config.toml一段里2.x版本推荐的config_path目录化管理方式在规模化运维里优势非常明显。每个Harbor仓库一个文件夹、一个hosts.toml增删仓库不会互相干扰也不会因为改了一个镜像源导致其他仓库的配置意外失效。假设你给生产集群规划了一套目录/etc/containerd/certs.d/ ├── registry.internal:8443/ │ ├── hosts.toml │ └── ca.crt ├── docker.io/ │ └── hosts.toml └── 192.168.209.133/ └── hosts.toml这样哪个仓库走HTTPS、哪个走HTTP、哪个需要特殊CA一眼就能看明白。新加一个Harbor项目或镜像源无非就是创建目录复制模板比在几百行的config.toml里找字段位置爽太多。5.2 用脚本批量分发配置到多节点K8s集群不可能只有一台节点只要节点数量超过三五台手工改配置的效率就扛不住了。我用得比较顺手的方式是准备一个目录包把certs.d里所有配置文件夹打成一个certs.d.tar.gz然后通过Ansible或者简单的scp循环分发到每个节点。分法如下tar -czf certs.d.tar.gz -C /etc/containerd certs.d然后在每个目标节点上执行tar -xzf certs.d.tar.gz -C /etc/containerd systemctl restart containerd如果是新节点初始化可以在装机脚本里加上这段逻辑保证节点一亮相就具备访问Harbor的能力。还有个小坑如果你同时启用了K8s集群里的其他组件复用同一份certs.d一定要先确认配置项use_containerd_for_pull等特殊开关没有打开否则某些组件会绕过containerd自己直接用HTTPS拉镜像和hosts.toml的配置驴唇不对马嘴。5.3 配置变更之后的优雅生效方式很多人改完配置习惯性systemctl restart containerd但生产环境里直接重启containerd会让节点上所有容器跟着重启影响面非常大。K8s节点上更稳妥的做法是只重启CRI插件的relaod或者用systemctl reload containerd试试看你的containerd版本是否支持热加载。多数2.x版本支持修改config_path下面的配置后部分生效但如果你是动config.toml里的registry段落那就别侥幸了老老实实重启并在非业务高峰窗口操作。实际操作中我的判断标准是只改hosts.toml里的skip_verify、ca、endpointsystemctl reload containerd基本能生效优先级最高失败再考虑重启。改了config.toml里的镜像源字段或者认证配置直接挑维护窗口重启别拿生产环境赌运气。6. 实际运维中最值得留意的几个细节6.1 命名空间和命令工具选型是隐蔽雷区如果你在一个节点上同时装了ctr和nerdctl很容易出现“配置一样但结果不同”的迷惑现象。核心差异就在命名空间。Kubernetes节点上kubelet的CRI调用会把镜像存到k8s.io命名空间而nerdctl默认操作的是default命名空间。如果你用nerdctl pull拉了一个Harbor镜像然后K8s调度Pod时kubelet去k8s.io里找找不到镜像就会重新用CRI的配置去拉。所以调试K8s节点时建议明确指定命名空间nerdctl --namespace k8s.io pull registry.internal:8443/library/busybox:latestcrictl本身就对接CRI不需要手动指定命名空间它拉下来的镜像就在k8s.io里这也是为什么生产上我更喜欢用crictl来验证拉取链路。6.2 离线节点导入镜像包要小心的标签问题前面提到的ubuntu harbor 镜像包这类离线包导入时常常遇到tag丢失的问题。因为你离线包里镜像的tag可能带着原始仓库域名导入后containerd会保留这个域名但不一定和你本地的registry.internal:8443匹配。这时候可以用ctr images tag重新打标签或者用nerdctl tag转换。我踩过一次很深的坑离线包里的镜像tag是127.0.0.1:5000/ubuntu:22.04导入节点后我直接在K8s的yaml里填127.0.0.1:5000/ubuntu:22.04K8s认为是私有仓库又去走Harbor认证最后报401。后来才意识到问题出在旧的tag路径上重新打标签后才解决。6.3 Harbor页面上传镜像到私有项目时的权限限制最后提一句Harbor侧的细节。如果推送镜像时报了project library not found或者denied大概率不是containerd配置的问题而是你推送的路径里项目名没配对。Harbor里项目的可见性和推送权限分得细给运维账号赋予的权限可能只覆盖部分项目。建议先检查登录账号在目标项目里是否有Push权限再检查项目名大小写和路径是否准确。具体来说Harbor的项目名是区分大小写的Library和library是两个不同的东西。在维护Harbor的这两三年里我的一个强烈感受是containerd 2.x接入Harbor真正让人头疼的不是配置项多而是Docker思维和containerd思维之间的转换。只要你理解了config_path目录 hosts.toml这套模型再对照着网络、协议、认证三个层次去排错绝大多数问题都能在十分钟内定位到根因。最后再补充一个小技巧改完配置不要急着重启先执行containerd config dump看一下实际生效的配置摘要改没改对一眼就知道。

containerd 2.x接入Harbor私有仓库配置与排障实战

相关推荐

论文洞察：面向RAG场景的KV Cache复用技术——用TaoToken统一Key跑通CacheBlend验证

郑州实木书桌源头工厂挑选全攻略，用料扎实资质齐全

系统架构师备考：用霍尔三维结构打通案例分析任督二脉

更多资讯

医院排班系统开发实战：Spring Boot+MySQL排班算法与数据库设计

数据岗位考证指南：能力比证书更重要，避免盲目内卷

豆包智能体聊天记录管理指南：查找、导出、备份与迁移

AnyPS5解析：跨平台适配PS5手柄的兼容层设计与实践

C语言在线编辑器选型指南：5款工具深度对比与实战场景匹配

山东盖无双建材重型电缆沟盖板多种规格型号可按需定制电厂变电站专用

今日更新

再见，SSE！你好，Streamable HTTP！轻松开发 Streamable HTTP MCP Server 并接入 TaoToken

工业软件标准化路线图：国产替代的落地施工图

VCMI安卓版实操指南：原生运行英雄无敌3的3步技术落地

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？