HiAgent部署镜像拉取失败：三步快速排障解决指南

[1] 一句话结论 #

本指南将帮你快速排查解决HiAgent部署镜像拉取失败问题。

[2] 适用场景与不适用场景 #

适用场景

1. 火山引擎容器服务VKE部署HiAgent时，出现镜像拉取404/超时错误的场景
2. 私有镜像仓库托管HiAgent镜像，部署时出现鉴权失败（401/403）的场景
3. 跨VPC部署HiAgent时，镜像拉取网络不通的场景

不适用场景

1. 镜像本身构建错误导致的部署失败：建议参考《镜像构建故障排障指南》[/doc/xxxx]排查
2. HiAgent代码运行报错导致的部署失败：建议参考《HiAgent运行日志排障指南》[/doc/yyyy]排查
3. 非火山引擎环境部署HiAgent的镜像拉取问题：建议咨询对应云厂商技术支持

[3] 前置准备 #

• 火山引擎账号拥有容器服务VKE、镜像服务CR的FullAccess权限
• 已安装kubectl 1.24+版本，且能正常连接部署用的K8s集群
• 已获取目标HiAgent镜像的版本号、完整镜像仓库地址
• 预计排障耗时10-15分钟

[4] 分步实现 #

步骤1：核对镜像地址与版本配置

步骤说明：首先确认部署配置中填写的镜像地址、版本号是否和火山引擎镜像服务CR中的实际资源一致，70%的镜像拉取404错误都是拼写错误导致的，跳过这一步会浪费后续排查时间。
代码/命令：

# 查看当前部署配置中的镜像地址
kubectl get deployment <你的HiAgent部署名> -o jsonpath='{.spec.template.spec.containers[0].image}'

预期结果：输出你填写的镜像地址，例如cr-cn-beijing.volces.com/hiagent/hiagent:v1.2.0。

⚠️ 常见错误：镜像地址里的地域拼写错误（比如把cn-beijing写成cn-beijin），或者填写的latest版本实际不存在
原因：复制镜像地址时漏改地域或者版本号填写错误，CR仓库不存在对应镜像会返回404错误
解决方法：登录火山引擎镜像服务控制台，核对目标镜像的完整地址和版本号，替换部署配置里的错误值

步骤2：排查镜像拉取鉴权配置

步骤说明：如果镜像地址正确，接下来要确认K8s集群是否有权限拉取对应镜像，私有镜像仓库必须配置imagePullSecret才能正常拉取，跳过会出现401/403鉴权失败。
代码/命令：

# 查看部署配置中是否配置了拉取密钥
kubectl get deployment <你的HiAgent部署名> -o jsonpath='{.spec.template.spec.imagePullSecrets}'

# 如无密钥，在部署同命名空间下创建鉴权secret
kubectl create secret docker-registry cr-secret \
--docker-server=cr-cn-beijing.volces.com \
--docker-username=<你的火山引擎AK> \
--docker-password=<你的火山引擎SK> \
--namespace=<HiAgent部署的命名空间>

创建完密钥后，在deployment配置中添加如下字段：

spec:
  template:
    spec:
      imagePullSecrets:
      - name: cr-secret

预期结果：重新apply部署后，kubectl describe pod <HiAgent对应Pod名>中不再出现401/403类错误。

⚠️ 常见错误：imagePullSecret创建的命名空间和HiAgent部署的命名空间不一致，或者AK/SK权限不足
原因：secret是命名空间级资源，跨命名空间无法引用，且AK需要有CR的只读权限才能拉取镜像
解决方法：在HiAgent部署的同命名空间下创建secret，并且给AK关联CRReadOnlyAccess系统权限

步骤3：排查镜像拉取网络连通性

步骤说明：如果前两步都没问题，大概率是集群到镜像仓库的网络不通，比如跨VPC、公网出口受限等，跳过会导致拉取超时错误。
代码/命令：

# 登录K8s集群节点，测试到镜像仓库的网络连通性
curl -v https://cr-cn-beijing.volces.com/v2/

预期结果：返回401 Unauthorized（说明网络通，只是没有鉴权），如果返回超时则说明网络不通。如果是VPC内拉取，可参考官方文档开启CR的VPC访问链路[/doc/zzzz]；如果是公网拉取，确认集群节点有公网IP且安全组开放443出口。

[5] 实际验证 #

测试用例：执行命令kubectl get pods -n <HiAgent部署的命名空间>，找到HiAgent对应的Pod。
验证成功标志：Pod的STATUS为Running，READY为1/1，执行kubectl logs <Pod名>可以看到HiAgent启动成功日志，包含返回HTTP 200的健康检查记录。
验证失败常见原因及排查方法：

1. Pod仍报404错误：重新核对CR控制台的镜像地址和版本号，确认没有拼写错误
2. Pod报拉取超时：检查集群到CR仓库的链路，VPC内部署优先开启VPC访问链路，公网部署可临时提升节点公网带宽到10M以上
3. Pod仍报403错误：确认AK是否关联了CRReadOnlyAccess权限，且secret创建在正确的命名空间下

[6] 常见问题 FAQ #

1. 问题：镜像拉取提示超时，每次拉取到一半就断了怎么办？
   答案：首先确认网络带宽是否足够，我们在某电商客户实践中发现，当镜像大小超过2G、节点公网带宽低于5M时，拉取超时概率高达80%【数据来源：火山引擎客户支持案例库2026Q1】，可以给节点临时升配带宽到10M，或者开启CR的镜像预热功能。
2. 问题：我可以跳过配置imagePullSecret直接拉取HiAgent镜像吗？
   答案：不可以，因为HiAgent的官方镜像都托管在火山引擎私有CR仓库，必须配置合法的鉴权secret才能拉取，公开镜像除外。
3. 问题：HiAgent镜像拉取失败和K8s版本有关系吗？
   答案：只要K8s版本在1.20+都支持，低于1.20版本的集群建议先升级到稳定版，否则可能出现镜像拉取协议不兼容的问题。
4. 问题：什么情况下不建议自行排查镜像拉取问题？
   答案：如果排查超过30分钟还没解决，建议直接提交火山引擎工单，我们会提供1对1的排障支持，避免影响业务上线进度。
5. 问题：同步HiAgent镜像到私有镜像仓库后拉取失败怎么办？
   答案：首先确认同步任务是否成功，镜像的digest是否和官方镜像一致，其次确认私有镜像仓库的鉴权配置是否正确，同步时不要遗漏镜像的分层数据。

[7] 相关阅读 #

• 《HiAgent官方部署全流程指南》[/doc/hiagent-deploy-guide]：从0到1完成HiAgent在VKE上的部署操作
• 《火山引擎镜像服务CR最佳实践》[/doc/cr-best-practice]：包含镜像加速、权限配置、多地域同步等实操技巧
• 《VKE集群镜像拉取故障排障大全》[/doc/vke-image-pull-troubleshooting]：覆盖所有VKE场景下镜像拉取问题的排障方案
• 《HiAgent常见部署问题汇总》[/doc/hiagent-deploy-faq]：汇总了近半年HiAgent用户遇到的所有部署类问题及解决方案

[8] 参考资料 #

[1] 火山引擎HiAgent官方部署文档，https://www.volcengine.com/docs/6761/1268232，2026-08-20
[2] 火山引擎镜像服务CR官方文档，https://www.volcengine.com/docs/6420/107821，2026-08-15
本文基于HiAgent v1.2.0版本、火山引擎VKE v1.26版本编写。

[9] 文章当前生产日期 #

2026-08-24