概述
首次使用镜像启动沙箱时，镜像下载和准备可能会增加沙箱启动的等待时间；如果镜像尚未准备就绪，还可能导致沙箱启动失败。
为减少镜像准备对沙箱启动的影响，Agent 沙箱（AGS）提供镜像预热和模板快照两种加速方式：
镜像预热：提前准备沙箱运行所需的镜像，适用于镜像种类多、更新频繁的场景；
模板快照：通过提前制作并复用模板快照加速启动沙箱，适用于镜像种类较少、重复使用频繁的场景。
本文介绍 AGS 的镜像预热能力。AGS 支持以下三类镜像预热方式：
主动预热：在创建沙箱工具或启动沙箱实例之前，通过 AGS 控制台或 API 主动创建镜像预热；
TCR 推送触发镜像预热：在 TCR 中配置镜像预热的触发规则，推送符合规则的镜像后自动触发预热；
平台按需预热：在创建沙箱工具或启动沙箱实例时，由 AGS 根据镜像准备情况按需自动进行预热。
对于首批沙箱实例启动时延敏感的业务，建议在启动前主动预热镜像，或通过 TCR 推送触发镜像的自动预热，并在 AGS 控制台确认镜像预热成功后再启动沙箱实例。
预热流程
您可以在创建沙箱工具或启动沙箱实例之前，通过 AGS 控制台或 API 主动预热镜像。
1. 选择需要预热的镜像：确认预热的镜像及目标地域。
2. 提交镜像预热请求：可以在 AGS 控制台中创建镜像预热，也可以调用 API 接口 提交镜像预热请求。
3. 查看镜像预热结果：可以在 AGS 控制台中查询镜像预热的状态，也可以调用 API 接口 对镜像预热的状态进行查询。如果镜像正在预热，请等待预热完成；如果预热失败，请根据任务信息排查原因。
您可以在 TCR 中配置镜像预热的触发规则，使 AGS 在镜像推送成功且符合触发规则时自动预热镜像，无需手动创建镜像预热。
1. 配置镜像预热的触发规则：通过在 TCR 的触发器中配置镜像预热的触发规则确认需要自动预热的镜像所属的 TCR 实例、命名空间、仓库名称、版本 Tag 以及目标地域；
2. 向 TCR 推送镜像：向指定的 TCR 实例推送符合触发规则的镜像，将触发 AGS 对该镜像进行自动预热；
3. 查询镜像预热结果：可以在 AGS 控制台中查询镜像预热的状态，也可以调用 API 接口 对镜像预热的状态进行查询。确认预热成功后，即可使用已预热的镜像缓存创建沙箱工具或启动沙箱实例。
创建沙箱工具或启动沙箱实例时，AGS 可以根据实际使用镜像的预热情况，按需自动预热镜像，无需您提前手动创建镜像预热。
1. 确认需要使用的镜像：在创建沙箱工具或启动沙箱实例时，配置需要使用的镜像；
2. 按需自动预热镜像：AGS 将检查目标镜像是否已经完成预热。如果尚未完成预热，平台则按需进行预热，并在镜像被成功预热后继续创建沙箱工具或启动沙箱实例。
注意：
镜像预热的状态机
镜像预热涉及以下状态：
状态 | 状态描述 |
Pending / 排队中 | 镜像预热的创建请求已提交。 |
Processing / 预热中 | 正在对镜像进行预热。 |
Success / 已预热 | 镜像预热执行成功，得到已预热的镜像缓存。 |
Failed / 预热失败 | 镜像预热执行失败。 |
Cancelled / 预热已取消 | 取消正在排队中的镜像预热。 |
Deleted / 预热已卸载 | 卸载已预热的镜像缓存。 |
说明：
状态为 Pending / 排队中的镜像预热可以被取消。
状态为 Success / 已预热时，已预热的镜像缓存可被用于加速启动沙箱。
主动卸载时，若该镜像仍被未删除的沙箱工具、运行中的沙箱实例、暂停中的沙箱实例、模板快照等引用时，则不能被卸载。
镜像预热的卸载将会卸载已预热的镜像缓存，但是不会删除镜像仓库中的源镜像。再次使用该镜像启动沙箱时，系统将重新对该镜像进行预热。
使用方式
AGS 控制台
1. 登录 AGS 控制台。
2. 在镜像预热 管理页面，查看镜像预热列表中具体的镜像预热信息。
3. 单击镜像预热 ID，可以查看镜像预热的详情信息。
4. 单击新建镜像预热，通过选择或输入镜像地址来预热新的镜像。
5. 单击卸载，可以主动卸载指定的、已预热的镜像缓存。
使用限制
限制项 | 说明 |
使用地域 | 应在后续使用沙箱的目标地域中预热镜像和查询镜像预热的结果。 |
使用权限 | 账号需具备镜像预热的接口级操作权限。 |
超时时间 | 可配置 10～180 分钟；TCR 企业版、CCR 个人版仓库类型默认为 120 分钟。这是预热超时时间的配置，不是完成时长承诺。 |
镜像预热的取消 | 仅当镜像预热的状态处于 Pending 可被取消；状态处于Processing 则不支持取消。 |
卸载已预热的镜像缓存 | 只能卸载已预热的镜像缓存。 |
引用保护 | 如果已预热的镜像缓存正在被使用，则拒绝卸载的操作。 |
常见问题
1. 镜像已经预热成功，为什么沙箱启动仍慢或失败？
镜像预热只完成镜像的拉取、格式转换和存储，但是沙箱启动受到网络、存储挂载等依赖的影响，不能仅依据镜像预热的状态来判断沙箱是否启动成功。
2. 遇到预热准备中或失败时，如何处理？
3. 启动沙箱实例时，镜像仍在预热中，如何处理？
TCR 企业版镜像、CCR 个人版镜像：平台会在当前请求中等待镜像准备完成。如果等待结束时，查询到的镜像状态仍为 Processing，接口返回 ResourceUnavailable，并提示镜像仍在准备中，请稍后重试。
与快照加速的区别
对比项 | 镜像预热 | 快照加速 |
提前准备什么 | 镜像本身：单个 OCI 镜像的拉取、转换与存储准备 | 沙箱的启动配置：将沙箱配置预先构建为可直接启动的模板快照 |
主要减少什么等待 | 减少冷启动时镜像下载、转换和准备的等待 | 不再重复执行环境准备、依赖下载等初始化工作 |
客户关注什么 | 镜像是否被成功预热； 镜像预热的状态。 | 模板快照是否被成功制作 模板快照的状态 |
适合什么时候使用 | 新镜像上传镜像仓库后提前预热；同一沙箱工具下多个沙箱实例使用不同镜像 | 继承沙箱工具配置的多个沙箱实例 |
说明：
镜像预热解决“镜像还没有准备好”的问题，模板快照解决“沙箱启动配置初始化太慢”的问题，两者适用的场景不同，不是互相替代的关系。
