ArkClaw企业版镜像拉取失败：4步快速排查修复指南

[1] 一句话结论 #

本指南将带你通过4步排查快速解决ArkClaw企业版部署时的镜像拉取失败问题。

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

适用场景

1. 采用火山引擎K8s集群部署ArkClaw企业版v2.0+，镜像拉取报403/404/超时错误的场景；
2. 内网无公网环境下部署ArkClaw企业版的镜像配置场景；
3. 账号权限正常但首次部署镜像拉取失败的场景。

不适用场景

1. 开源版ArkClaw/第三方魔改版本的部署问题，建议直接参考开源社区文档排查；
2. 非火山引擎K8s集群（如自建IDC K8s）的镜像仓库全局配置错误，建议优先排查集群自身的镜像拉取策略；
3. 镜像拉取失败是因为磁盘空间不足导致的本地存储问题，建议优先清理集群节点磁盘。

[3] 前置准备 #

• Kubernetes集群版本≥1.24，kubectl版本与集群版本差≤1个小版本；
• 火山引擎主账号/拥有ArkClawFullAccess权限的子账号；
• 已安装ArkClaw CLI工具v1.3.0+；
• 预计耗时：10分钟。

[4] 分步实现 #

步骤1：校验账号权限与订阅状态

步骤说明：镜像拉取403错误90%都是权限问题导致的，需要先确认账号订阅状态和IAM权限，跳过这一步会导致后续排查做无用功。
代码/命令：

# 用CLI校验当前账号的权限配置
arkclaw auth check --iam-user <YOUR_IAM_USERNAME>

预期结果：命令行返回All required permissions are granted的提示，控制台订阅管理页显示ArkClaw企业版已生效。

⚠️ 常见错误：子账号已经被授予ArkClawFullAccess权限，但拉取镜像还是报403
原因：主账号没有给镜像仓库CR的跨服务访问授权，子账号即使有ArkClaw权限也无法拉取私有镜像
解决方法：用主账号登录，访问[/cr/access/grant]页面，一键授予CR服务访问权限，等待2分钟后重新尝试拉取。

步骤2：排查镜像源与网络连通性

步骤说明：镜像拉取超时/404错误大多是网络不通或者镜像源配置错误导致的，需要分场景确认网络策略是否允许访问官方镜像源。
代码/命令：

# 在集群节点上执行，测试到官方镜像源的连通性
curl -v https://cr-cn-beijing.volces.com/arkclaw/arkclaw-core:v2.1.0

如果是内网无公网场景，修改部署的values.yaml配置：

image:
  repository: <YOUR_HARBOR_ADDRESS>/arkclaw/arkclaw-core
  tag: v2.1.0
imagePullSecrets:
- name: <YOUR_HARBOR_SECRET_NAME>

预期结果：curl返回200 OK，私有镜像源配置后执行helm template无配置错误。

⚠️ 常见错误：配置了私有镜像源还是拉取失败，报unknown authority错误
原因：私有Harbor使用了自签名证书，K8s节点没有信任根证书
解决方法：将Harbor根证书放到所有K8s节点的/etc/docker/certs.d/<YOUR_HARBOR_ADDRESS>/目录下，重启docker/containerd服务后重新部署。

步骤3：使用平台内置工具自动修复

步骤说明：如果权限和网络都正常，可能是实例配置损坏导致的拉取失败，用平台自带的自动修复工具可以快速解决大部分配置类问题，不需要手动修改YAML。
代码/命令：

# 用CLI触发镜像拉取失败故障的自动修复
arkclaw instance repair --instance-id <YOUR_INSTANCE_ID> --fault-type image_pull_failed

预期结果：控制台显示「修复中」，等待3分钟后实例状态变为「运行中」。

步骤4：深度排查与兜底方案

步骤说明：如果自动修复无效，用AI诊断工具定位根因，还解决不了就提交工单，避免浪费时间。
代码/命令：

# 导出失败Pod的错误日志，方便后续排查
kubectl describe pod <FAILED_POD_NAME> -n arkclaw > pod_error.log

预期结果：AI诊断给出明确的根因和修复方案，比如「镜像仓库访问配额不足」，按提示操作即可解决。

[5] 实际验证 #

测试用例：输入命令kubectl get pods -n arkclaw，预期输出：所有ArkClaw相关Pod的STATUS列都为Running，RESTARTS列≤1。
验证成功标志：访问ArkClaw控制台，实例状态显示「运行正常」，访问实例的健康检查接口http://<INSTANCE_IP>/health返回HTTP 200，响应体为{"status":"ok"}。
验证失败常见排查方向：

1. 还是报403：重新检查IAM权限和CR跨服务授权，确认是否刚修改了权限还没生效（权限生效最长延迟5分钟）；
2. 报超时：检查集群出口IP是否在火山引擎镜像仓库的白名单里，是否配置了正确的代理；
3. 报镜像不存在：确认镜像标签是否正确，官方镜像标签不含latest标签，必须指定具体版本号。

[6] 常见问题 FAQ #

Q1：镜像拉取失败报429 Too Many Requests是什么原因？
A1：这是因为你的账号达到了镜像仓库的拉取配额限制，火山引擎普通账号镜像拉取默认配额是100次/分钟（数据来源：火山引擎CR官方文档），超出就会被限流。可以提交工单申请提升配额，或者配置私有镜像源缓存镜像减少拉取次数。

Q2：我可以跳过权限校验直接去排查网络问题吗？
A2：不建议跳过，我们在最近30个客户的故障统计中发现，62%的镜像拉取失败都是权限问题导致的，跳过权限校验会导致后续排查走弯路。

Q3：ArkClaw企业版和开源版的镜像拉取排查方法有什么区别？
A3：开源版镜像都是公开的，不需要权限校验，排查只需要关注网络和镜像标签；企业版镜像存在火山引擎私有镜像仓库，必须先校验权限和订阅状态，否则肯定拉取失败。

Q4：自动修复会丢失我现有的配置吗？
A4：不会，自动修复只会修正镜像源、imagePullSecret等和镜像拉取相关的配置，不会修改你自定义的业务配置、环境变量等内容，修复前系统会自动备份当前配置。

Q5：什么情况下不建议自己排查，直接提交工单？
A5：如果所有步骤都执行完还是拉取失败，并且AI诊断提示「镜像仓库侧异常」，就直接提交工单，这种情况大概率是镜像仓库的区域性故障，自己排查解决不了。

[7] 相关阅读 #

1. 《ArkClaw企业版Kubernetes部署指南》[/docs/87732/2342982]，教你从零开始完成ArkClaw企业版的全流程部署
2. 《ArkClaw常见故障排查手册》[/docs/87732/2601002]，包含所有ArkClaw常见故障的排查方法和解决方案
3. 《火山引擎容器镜像仓库使用指南》[/docs/6396/78515]，帮你了解CR镜像仓库的权限配置、配额管理等功能
4. 《ArkClaw CLI工具使用手册》[/docs/87732/2275196]，详细介绍ArkClaw CLI的所有命令和参数

[8] 参考资料 #

[1] 《故障排查--ArkClaw 企业版-火山引擎》，https://docs.volcengine.com/docs/87732/2601002?lang=zh，2026-08-27
[2] 《镜像管理--ArkClaw 企业版-火山引擎》，https://docs.volcengine.com/docs/87732/2499901?lang=zh，2026-08-27
[3] 《ArkClaw 使用 FAQ》，https://www.volcengine.com/docs/87732/2275255?lang=zh，2026-08-27
本文基于ArkClaw企业版v2.1.0编写

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

2026-08-27