2. 容器镜像管理

K3s 默认使用 Containerd 作为容器运行时（Runtime）。与 Docker 不同，Containerd 的配置文件和镜像管理方式有其独特性。

本章重点解决国内镜像拉取失败的问题，并介绍如何配置私有仓库。

2.1 镜像加速配置 (关键)

由于 Docker Hub 的限流和网络问题，配置国内镜像加速是必须步骤。K3s 通过 /etc/rancher/k3s/registries.yaml 文件来管理镜像仓库。

2.1.1 配置 registries.yaml

创建或编辑配置文件：

sudo mkdir -p /etc/rancher/k3s
sudo vi /etc/rancher/k3s/registries.yaml

写入以下内容（推荐配置）：

mirrors:
  "docker.io":
    endpoint:
      - "https://docker.m.daocloud.io" 
      - "https://mirror.ccs.tencentyun.com"
      - "https://registry.docker-cn.com"

2.1.2 生效配置

修改配置后，必须重启 K3s 服务才能生效：

sudo systemctl restart k3s
# 如果是 Worker 节点
# sudo systemctl restart k3s-agent

2.2 验证镜像拉取

K3s 内置了 crictl 工具（类似 docker cli）来调试容器运行时。

# 1. 拉取测试镜像
sudo crictl pull docker.io/library/nginx:alpine

# 2. 查看已下载镜像
sudo crictl images

# 预期输出
# IMAGE                     TAG                 IMAGE ID            SIZE
# docker.io/library/nginx   alpine              a9876...           10MB

如果拉取速度很快，说明加速配置生效。

2.3 配置私有仓库

如果您的企业有私有 Harbor 或 Docker Registry，需要配置认证信息。

2.3.1 修改 registries.yaml

mirrors:
  "my-private-registry.com:5000":
    endpoint:
      - "https://my-private-registry.com:5000"
configs:
  "my-private-registry.com:5000":
    auth:
      username: "myuser"
      password: "mypassword"
    tls:
      insecure_skip_verify: true # 如果使用自签名证书

注意：生产环境中不建议在 yaml 中明文存储密码，推荐使用 Kubernetes 的 ImagePullSecrets。

2.4 导入导出镜像（离线场景）

在完全离线的环境中，您需要手动导入镜像。

2.4.1 导出镜像 (在有网机器)

# 使用 docker 导出
docker pull nginx:alpine
docker save nginx:alpine -o nginx-alpine.tar

2.4.2 导入镜像 (在 K3s 节点)

将 .tar 包复制到 K3s 节点，然后导入：

sudo k3s ctr images import nginx-alpine.tar

注意：这里使用的是 k3s ctr 命令，直接与 containerd 交互。

2.5 常见问题

Q: crictl pull 报错 failed to verify certificate？ A: 目标仓库使用了自签名证书。请在 registries.yaml 中配置 insecure_skip_verify: true，或将 CA 证书放入系统信任库。

Q: 如何查看当前生效的配置？ A: Containerd 的配置是动态生成的，查看 K3s 日志可以看到加载过程，或者直接查看 /var/lib/rancher/k3s/agent/etc/containerd/config.toml.tmpl（这是模板文件，不要直接修改生成的 config.toml）。