共计 2156 个字符，预计需要花费 6 分钟才能阅读完成。
若遇“找不到镜像仓库”错误，需四步解决：一、验证私有仓库可达性与认证状态；二、修改 Helm values.yaml 中 workerGroup.skillsRegistry 为正确私有地址；三、配置 Docker daemon 信任该仓库（含 insecure-registries 或 CA 证书）；四、在 Kubernetes 中创建 ImagePullSecret 并注入 Worker Pod。
如果您在安装 WorkBuddy 集群时执行 helm install 或 worker 节点拉取 Skills 镜像过程中提示“找不到镜像仓库”或“repository not found”，则可能是由于 Worker 节点无法访问默认的公开技能镜像仓库，或未正确配置企业私有仓库地址。以下是解决此问题的步骤：
一、验证私有镜像仓库可达性与认证状态
该步骤用于确认私有仓库服务本身是否正常运行，以及当前节点是否具备合法访问权限。若仓库不可达或认证失败，所有镜像拉取操作均会中止。
1、在任意 Worker 节点执行命令：curl -I https://hub.codebuddy.cn/v2/，检查 HTTP 响应是否为 200 或 401（表示服务在线但需鉴权）。
2、若返回 404 或超时，请联系 IT 管理员确认私有仓库 URL 是否已更新，或是否因 DNS 策略导致域名解析失败。
3、若返回 401，需进一步验证 Docker 登录状态：执行docker login https://hub.codebuddy.cn，输入分配的仓库用户名与密码。
4、登录成功后，执行 docker pull hub.codebuddy.cn/skills/private/sales-report-v2:1.3 测试单镜像拉取能力。
二、修改 Helm Chart 中 skillsRegistry 配置项
WorkBuddy 集群通过 Helm values.yaml 中的 workerGroup.skillsRegistry 字段指定 Skills 镜像源。若该字段仍为默认公开地址或为空，Worker Pod 将尝试访问不可达的外部仓库。
1、打开已解压的 Helm Chart 目录下的 values.yaml 文件。
2、定位至 workerGroup: 区块，找到 skillsRegistry: 行。
3、将其值修改为您的企业私有仓库完整地址，例如：https://hub.codebuddy.cn/skills（末尾不加斜杠）。
4、若私有仓库启用了命名空间隔离（如按部门划分），可追加路径前缀，例如：https://hub.codebuddy.cn/skills/finance-team。
5、保存文件后，重新执行 helm upgrade 命令触发配置更新。
Heeyo：AI 儿童启蒙陪伴师，风靡于硅谷的儿童 AI 导师和玩伴
三、为 Worker 节点配置 Docker daemon 信任私有仓库
Docker 默认仅信任 HTTPS 且具备有效 CA 证书的仓库。若私有仓库使用自签名证书或 HTTP 协议，必须显式配置 daemon.json 使其被接受，否则 kubelet 无法拉取镜像。
1、在每台 Worker 节点上，编辑 Docker 守护进程配置文件：/etc/docker/daemon.json。
2、添加 insecure-registries 字段，例如：“insecure-registries”: [“hub.codebuddy.cn”]（仅适用于 HTTP 仓库）。
3、若使用 HTTPS 但证书非系统信任根签发，需将私有 CA 证书复制到系统证书目录：sudo cp ca.crt /usr/share/ca-certificates/，并执行sudo update-ca-certificates。
4、重启 Docker 服务：sudo systemctl restart docker。
5、验证配置生效：执行sudo docker info | grep -i registry，确认输出包含已配置的仓库地址。
四、在 Kubernetes 集群中配置 ImagePullSecrets
当 Worker Pod 以 ServiceAccount 身份运行时，需将 Docker Registry 凭证注入 Pod 上下文，否则即使节点本地已登录，Pod 内仍无法拉取私有镜像。
1、在 workbuddy-system 命名空间下创建 Secret：kubectl create secret docker-registry regcred –docker-server=https://hub.codebuddy.cn –docker-username=your-user –docker-password=your-pass –docker-email=unused@example.com -n workbuddy-system。
2、编辑 WorkBuddy Worker StatefulSet 或 Deployment 资源，于 spec.template.spec 部分添加：imagePullSecrets: [{name: regcred}]。
3、若使用 Helm 部署，可在 values.yaml 中设置workerGroup.imagePullSecrets: ["regcred"]，避免手动修改资源清单。
4、删除现有 Worker Pod，令其由控制器自动重建并加载新 Secret。
