Agent Runtime 为 Agent 集群开启镜像加速

当 Agent 使用包含 Python 依赖、浏览器或开发工具的大镜像时，新节点首次运行任务往往需要等待镜像下载和解压。镜像加速通过提前转换镜像、在节点上按需读取数据，减少这一阶段的等待，适合扩容后启动 Agent、首次部署大镜像和批量创建沙箱等场景。
开启后，业务继续使用原始镜像地址和原有的镜像拉取凭证，无需将工作负载中的 image 改为转换后的制品地址。镜像加速不改变您选择的容器或沙箱运行时，也不会省去应用初始化、模型加载和健康检查的时间。
适用场景
场景
使用建议
新节点首次启动大镜像，启动时只读取其中部分文件
优先评估镜像加速，比较首次任务可执行时间。
同时启动多个使用相同镜像的 Agent
分别测试首批和后续批次；同一节点上的任务会共享缓存。
镜像已在节点缓存，或镜像本身较小
加速收益可能有限，应与原有启动方式对比。
启动时遍历大量文件或读取完整模型
按需读取可能把等待转移到应用运行阶段，应同时测试首次业务请求。
开始前准备
准备存放业务镜像的 TCR 实例，并为该实例开通 Agent 集群使用的 EROX 镜像加速能力。开通时提供实例 ID、地域和访问域名。
确认目标节点的操作系统、内核和 containerd 版本支持该加速组件；镜像架构应与节点一致。多架构镜像需完成对应平台的转换。
配置节点到 TCR 的网络访问和私有仓库权限。按需加载在运行期间仍可能读取仓库数据，应持续保持网络和凭证可用。
准备一个独立测试工作负载，先验证业务结果和首次请求耗时，再扩大使用范围。
镜像转换需要时间，生成的加速制品也会占用仓库存储空间；加速制品不一定比原镜像小。
步骤一：配置镜像转换规则
1. 登录 TCR 控制台，进入镜像加速，选择已开通 EROX 能力的实例地域和实例。
2. 添加镜像加速规则，填写规则名称，选择业务镜像所在的命名空间，并配置仓库名称和版本 Tag 的匹配条件。首次使用建议只匹配测试仓库和测试版本。
3. 使用规则验证功能检查业务镜像地址是否匹配，保存并启用规则。
4. 按仓库的推送指引上传一个匹配规则的新镜像版本，等待该版本转换成功，并确认转换结果对应目标节点的 CPU 架构。
规则针对匹配的镜像推送触发转换。仅启用规则，不代表仓库中已有的所有版本都已转换；已有版本需重新触发推送或使用实例支持的补转换方式。转换完成后，记录源镜像版本和 digest，后续部署仍填写源镜像地址。
步骤二：在创建 Agent 集群时开启镜像加速
1. 登录 Agent 集群控制台，在集群总览单击新建 Agent 集群。
2. 在基础与网络配置中开启镜像加速，选择步骤一使用的 TCR 实例。
3. 完成地域、网络及其他必填配置，提交创建，并按照 创建集群和节点池 添加用于运行 Agent 的节点。
4. 待节点就绪后，检查镜像加速组件和目标节点的安装结果，再部署测试工作负载。
以下为安装结果的只读检查。先参考 通过 Kubernetes API 访问 Agent 集群 取得访问配置，并配置已安装的腾讯云 CLI。CLUSTER_ID 填写关联 TKE 集群 ID，TARGET_NODE 填写实际节点名称。
export KUBECONFIG='/absolute/path/to/kubeconfig'
export REGION='ap-guangzhou'
export CLUSTER_ID='cls-xxxxxxxx'
export TARGET_NODE='<目标节点名称>'
﻿
tccli tke DescribeAddon \\
  --region "$REGION" \\
  --ClusterId "$CLUSTER_ID" \\
  --AddonName erox-node
﻿
kubectl --kubeconfig="$KUBECONFIG" get node "$TARGET_NODE" \\
  -o jsonpath='{.metadata.labels.erox\\.tencentcloud\\.com/enabled}{"\\n"}{.metadata.labels.erox\\.tencentcloud\\.com/ready}{"\\n"}'
组件返回的 Phase 应为 Succeeded，目标节点的 erox.tencentcloud.com/enabled 和 erox.tencentcloud.com/ready 均应为 true。如果未满足，先检查组件的 Reason 和节点状态；不要手动写入 ready 标签。扩容后也要检查新增节点，已有节点安装成功不代表新节点已经可以加速。
步骤三：使用原始镜像运行 Agent
按照 部署已有 Kubernetes 工作负载 创建测试工作负载，核对以下配置：
配置
填写方式
镜像地址
填写步骤一完成转换的原始镜像地址，保持版本不变。
私有仓库凭证
使用原有源镜像的拉取凭证；凭证应位于工作负载所在命名空间。
运行时
保留业务原有运行时选择；使用 Cube 的任务仍需具备可用的 Cube 运行时。
调度范围
将测试工作负载调度到已完成镜像加速安装的目标节点，保留业务所需的其他调度约束。
启动命令与健康检查
使用真实业务命令和就绪条件，验证任务能执行并返回正确结果。
部署后记录命名空间和 Pod 名称，执行以下只读检查：
export TEST_NAMESPACE='<测试命名空间>'
export TEST_POD='<测试 Pod 名称>'
﻿
kubectl --kubeconfig="$KUBECONFIG" -n "$TEST_NAMESPACE" get pod "$TEST_POD" -o wide
kubectl --kubeconfig="$KUBECONFIG" -n "$TEST_NAMESPACE" describe pod "$TEST_POD"
kubectl --kubeconfig="$KUBECONFIG" -n "$TEST_NAMESPACE" logs "$TEST_POD" --all-containers=true
确认 Pod 落在目标节点、镜像版本正确，并完成一次真实任务。仅看到 Running 或 Ready，还不能判断本次启动是否使用了镜像加速。
步骤四：确认加速生效并比较效果
将本次 Pod 的节点、创建时间和源镜像 digest，与节点上的加速记录对应起来。在有节点运维权限的终端登录实际运行该 Pod 的节点，检查服务状态及本次启动时段的日志：
sudo systemctl is-active erox-tcr-adapter erox-node-snapshotter containerd kubelet
sudo journalctl -u erox-tcr-adapter -u erox-node-snapshotter \\
  --since '10 min ago' --no-pager
核对日志中本次镜像对应的加速制品发现与挂载结果。监控指标 erox_snapshotter_accelerated_mount_total 的增长可辅助确认新增加速挂载，但其他任务也会影响该计数，复用已有挂载时计数可能不增长。应结合镜像身份、节点和时间判断本次任务，不能仅凭节点累计值认定命中。
比较效果时，保持源镜像 digest、节点规格、业务命令、资源配置、运行时和并发量一致，分别记录：
检查项
衡量内容
镜像准备耗时
镜像拉取与准备阶段的等待。
首条业务命令开始时间
容器启动后多久可以实际执行代码。
应用就绪时间
包含语言运行时、依赖和应用初始化的完整等待。
首次任务耗时与结果
验证按需读取后续数据时的影响，并核对成功率。
冷缓存和暖缓存结果分别统计；同一节点并发使用相同镜像的多个任务不是多个独立冷启动样本。不要在共享业务节点上清空缓存来构造测试。
常见问题
现象
检查与处理
镜像推送后没有转换结果
检查实例是否开通 EROX、规则是否启用，以及命名空间、仓库和版本是否匹配；确认本次推送已经触发转换。
节点未完成加速安装
检查 erox-node 的 Phase、Reason、节点启用标签及操作系统和 containerd 兼容性。
Pod 一直 Pending
检查节点选择条件、污点、可调度状态和剩余资源，确认目标节点能够接收该任务。
私有镜像拉取失败
检查命名空间中的拉取凭证、仓库访问权限和节点网络；不要将鉴权失败视为正常回退。
镜像可以运行，但没有加速记录
核对实际节点、镜像版本、平台及转换结果；未发现可用加速制品的普通 OCI 镜像可能走常规路径。
已发现制品却启动失败
检查制品关联信息和完整性及访问权限；制品校验失败不代表会自动回退成功。
容器启动快，但首次任务仍慢
检查应用是否全量扫描镜像文件、导入大量依赖或加载模型，同时分析首次读取和应用初始化耗时。
﻿

场景	使用建议
新节点首次启动大镜像，启动时只读取其中部分文件	优先评估镜像加速，比较首次任务可执行时间。
同时启动多个使用相同镜像的 Agent	分别测试首批和后续批次；同一节点上的任务会共享缓存。
镜像已在节点缓存，或镜像本身较小	加速收益可能有限，应与原有启动方式对比。
启动时遍历大量文件或读取完整模型	按需读取可能把等待转移到应用运行阶段，应同时测试首次业务请求。

配置	填写方式
镜像地址	填写步骤一完成转换的原始镜像地址，保持版本不变。
私有仓库凭证	使用原有源镜像的拉取凭证；凭证应位于工作负载所在命名空间。
运行时	保留业务原有运行时选择；使用 Cube 的任务仍需具备可用的 Cube 运行时。
调度范围	将测试工作负载调度到已完成镜像加速安装的目标节点，保留业务所需的其他调度约束。
启动命令与健康检查	使用真实业务命令和就绪条件，验证任务能执行并返回正确结果。

检查项	衡量内容
镜像准备耗时	镜像拉取与准备阶段的等待。
首条业务命令开始时间	容器启动后多久可以实际执行代码。
应用就绪时间	包含语言运行时、依赖和应用初始化的完整等待。
首次任务耗时与结果	验证按需读取后续数据时的影响，并核对成功率。

现象	检查与处理
镜像推送后没有转换结果	检查实例是否开通 EROX、规则是否启用，以及命名空间、仓库和版本是否匹配；确认本次推送已经触发转换。
节点未完成加速安装	检查 `erox-node` 的 `Phase`、`Reason`、节点启用标签及操作系统和 containerd 兼容性。
Pod 一直 Pending	检查节点选择条件、污点、可调度状态和剩余资源，确认目标节点能够接收该任务。
私有镜像拉取失败	检查命名空间中的拉取凭证、仓库访问权限和节点网络；不要将鉴权失败视为正常回退。
镜像可以运行，但没有加速记录	核对实际节点、镜像版本、平台及转换结果；未发现可用加速制品的普通 OCI 镜像可能走常规路径。
已发现制品却启动失败	检查制品关联信息和完整性及访问权限；制品校验失败不代表会自动回退成功。
容器启动快，但首次任务仍慢	检查应用是否全量扫描镜像文件、导入大量依赖或加载模型，同时分析首次读取和应用初始化耗时。

为 Agent 集群开启镜像加速

本页目录：

适用场景

开始前准备

步骤一：配置镜像转换规则

步骤二：在创建 Agent 集群时开启镜像加速

步骤三：使用原始镜像运行 Agent

步骤四：确认加速生效并比较效果

常见问题