Ubuntu 22.04下containerd配置Harbor私有仓库全指南-代码聚汇网

Ubuntu 22.04下containerd配置Harbor私有仓库全指南

故小里

1. 项目背景与核心需求

在基于Ubuntu 22.04的容器化环境中，企业内网通常需要搭建私有镜像仓库来管理容器镜像。Harbor作为企业级Registry解决方案，提供了安全、高效的镜像管理能力。而containerd作为轻量级容器运行时，相比Docker更适合生产环境使用。这个配置过程涉及容器运行时与私有仓库的深度集成，是Kubernetes生产环境部署的前置条件。

我最近在部署某金融系统容器化平台时，就遇到了containerd无法正常拉取Harbor镜像的问题。经过排查发现，官方文档对自签名证书和认证配置的描述较为分散，这里将完整梳理配置流程和避坑要点。

2. 基础环境准备

2.1 系统与软件版本要求

Ubuntu 22.04 LTS（内核5.15+）
containerd 1.6.8+（建议通过官方二进制安装）
Harbor 2.7.0+（已部署在内网环境）
OpenSSL 3.0+（用于证书处理）

注意：Ubuntu 22.04默认的containerd版本可能较旧，建议从GitHub直接下载最新release版。我曾遇到过1.5版本与Harbor的兼容性问题。

2.2 网络与防火墙配置

确保以下端口可访问：

Harbor服务端口（默认80/443）
containerd与Harbor通信端口（通常443）

如果使用防火墙，需要添加规则：

bash复制sudo ufw allow 443/tcp comment 'Harbor HTTPS'
sudo ufw allow 80/tcp comment 'Harbor HTTP'

3. containerd核心配置

3.1 配置文件定位与结构

containerd的主配置文件通常位于：

code复制/etc/containerd/config.toml

如果文件不存在，可先生成默认配置：

bash复制containerd config default | sudo tee /etc/containerd/config.toml

配置文件主要包含以下关键部分：

toml复制[plugins]
  [plugins."io.containerd.grpc.v1.cri"]
    [plugins."io.containerd.grpc.v1.cri".registry]
      [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
      [plugins."io.containerd.grpc.v1.cri".registry.configs]

3.2 Harbor仓库镜像配置

在[plugins."io.containerd.grpc.v1.cri".registry.mirrors]下添加Harbor仓库地址：

toml复制[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."harbor.example.com"]
    endpoint = ["https://harbor.example.com"]

实测发现：endpoint必须带协议头(https://)，否则会报"invalid endpoint"错误。

3.3 自签名证书配置

对于使用自签名证书的Harbor，需要将CA证书放入containerd信任链：

获取Harbor的CA证书：

bash复制openssl s_client -showcerts -connect harbor.example.com:443 </dev/null | sed -n '/BEGIN CERTIFICATE/,/END CERTIFICATE/p' > harbor-ca.crt

bash复制sudo mkdir -p /etc/containerd/certs.d/harbor.example.com
sudo cp harbor-ca.crt /etc/containerd/certs.d/harbor.example.com/ca.crt

在config.toml中添加证书配置：

toml复制[plugins."io.containerd.grpc.v1.cri".registry.configs]
  [plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.example.com".tls]
    ca_file = "/etc/containerd/certs.d/harbor.example.com/ca.crt"

3.4 认证信息配置

对于需要认证的私有仓库，有两种配置方式：

方式一：直接配置auth

toml复制[plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.example.com".auth]
  username = "admin"
  password = "Harbor12345"

方式二：使用credential helper（推荐）

安装docker-credential-helpers：

bash复制sudo apt install docker-credential-helpers

创建认证文件：

bash复制mkdir -p ~/.docker
echo '{"auths":{"harbor.example.com":{"auth":"$(echo -n 'admin:Harbor12345' | base64)"}}}' > ~/.docker/config.json

安全提示：建议使用项目专用账户而非admin账户，并定期轮换密码。

4. 服务重启与验证

4.1 重启containerd服务

bash复制sudo systemctl restart containerd

检查服务状态：

bash复制sudo systemctl status containerd

4.2 镜像拉取测试

bash复制sudo ctr images pull harbor.example.com/library/nginx:latest

成功输出应包含：

code复制harbor.example.com/library/nginx:latest: resolved

4.3 常见问题排查

问题1：x509证书验证失败

code复制ctr: failed to resolve reference "harbor.example.com/library/nginx:latest": failed to do request: x509: certificate signed by unknown authority

解决方案：

确认ca.crt文件路径正确
检查证书有效期：openssl x509 -in harbor-ca.crt -noout -dates
重新加载配置：sudo killall -SIGHUP containerd

问题2：认证失败

code复制ctr: failed to authorize: failed to fetch anonymous token: unexpected status: 401 Unauthorized

解决方案：

检查auth配置格式是否正确
验证账号密码：curl -u admin:Harbor12345 https://harbor.example.com/v2/
更新config.json后执行：sudo cp ~/.docker/config.json /root/.docker/

5. 生产环境优化建议

5.1 性能调优参数

在config.toml中添加：

toml复制[plugins."io.containerd.grpc.v1.cri".registry]
  [plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.example.com".tls]
    insecure_skip_verify = false  # 生产环境必须为false
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."harbor.example.com"]
    endpoint = ["https://harbor.example.com"]
    timeout = "15s"  # 适当增加超时时间

5.2 日志与监控配置

调整日志级别：

toml复制[debug]
  level = "info"  # 生产环境建议info，调试时可设为debug

配置Prometheus监控：

toml复制[metrics]
  address = "0.0.0.0:1338"
  grpc_histogram = false

5.3 高可用方案

对于关键生产环境，建议：

配置多个endpoint实现负载均衡：

toml复制endpoint = [
  "https://harbor-node1.example.com",
  "https://harbor-node2.example.com"
]

使用Harbor的复制功能实现多中心镜像同步
配置containerd的retry策略：

toml复制[plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.example.com".retry]
  max = 5
  delay = "5s"

6. 安全加固措施

6.1 证书管理最佳实践

使用企业级CA签发证书而非自签名
定期轮换证书（建议每90天）
配置证书自动更新机制

6.2 认证安全

启用Harbor的OIDC集成
使用机器人账户而非个人账户
配置镜像扫描和漏洞阻断策略

6.3 网络隔离

将Harbor部署在独立网络分区
配置网络策略限制containerd访问范围
启用Harbor的审计日志功能

我在实际部署中发现，很多团队会忽略containerd的运行时安全配置。建议额外配置：

toml复制[plugins."io.containerd.runtime.v1.linux"]
  no_pivot = true  # 禁用pivot_root，增强安全性
  shim_debug = false

7. 与Kubernetes集成

当containerd作为Kubernetes的运行时时，还需要注意：

7.1 kubelet配置调整

修改/etc/default/kubelet：

code复制KUBELET_EXTRA_ARGS="--container-runtime=remote --container-runtime-endpoint=unix:///run/containerd/containerd.sock"

7.2 Pod拉取镜像配置

在PodSpec中需要明确指定imagePullSecrets：

yaml复制apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  containers:
  - name: nginx
    image: harbor.example.com/library/nginx:latest
  imagePullSecrets:
  - name: harbor-cred

创建secret：

bash复制kubectl create secret docker-registry harbor-cred \
  --docker-server=harbor.example.com \
  --docker-username=admin \
  --docker-password=Harbor12345

7.3 性能优化参数

在kubelet配置中增加：

json复制{
  "registryBurst": 20,
  "registryPullQPS": 10
}

8. 维护与排错指南

8.1 日常维护命令

查看镜像列表：

bash复制sudo ctr images ls

清理无用镜像：

bash复制sudo ctr images rm --sync harbor.example.com/library/nginx:latest

查看当前配置：

bash复制sudo containerd config dump

8.2 日志分析技巧

containerd日志通常位于：

code复制/var/log/syslog

关键日志过滤：

bash复制journalctl -u containerd --since "1 hour ago" | grep -E 'error|warning|failed'

8.3 诊断工具推荐

ctr命令：内置管理工具
crictl：兼容CRI的工具
nerdctl：Docker-like体验的工具

对于复杂网络问题，建议使用：

bash复制sudo apt install apache2-utils  # 包含ab等测试工具
ht