容器镜像服务使用 TCR 触发器自动预热 Agent 沙箱镜像

操作场景
本文介绍如何在容器镜像服务 TCR 中配置 Agent 沙箱镜像预热触发器，在推送镜像后自动调用 Agent 沙箱的 CreatePreCacheImageTask 接口，发起镜像预热任务。
镜像预热通过 TCR 现有的触发器机制实现，适用于以下场景：
推送即预热：向实例推送镜像后，满足触发规则的推送会自动发起 AGS 镜像预热调用，无需人工操作。
按命名空间配置预热策略：每条规则必须选定一个命名空间，命名空间下的仓库可精确指定，也可使用正则表达式匹配。
系统托管触发器：触发器类型选择 Agent 沙箱镜像预热，无需填写 URL 和 Header，也无需引入独立的触发服务。
说明：
TCR 仅记录并展示预热接口的调用结果（成功或失败），不同步预热任务状态。任务状态请在 Agent 沙箱的 加速中心 > 镜像预热页面查询。
前提条件
在配置 Agent 沙箱镜像预热前，您需要完成以下准备工作：
实例版本与功能开通：该功能处于灰度发布阶段，相关 TCR 实例需提交工单升级后方可使用。Agent 沙箱镜像预热触发器类型仅对白名单用户可见。
CAM 授权：预热动作依赖服务角色 TCR_QCSRole 绑定预设策略 QcloudAccessForAgsRoleInTCR，以授权调用 CreatePreCacheImageTask 等接口。首次提交配置时，控制台会自动弹出授权窗口；如子账号无 CAM 授权权限，需联系主账号完成授权。
地域要求：预热目标地域为 AGS 所在地域。TCR 实例与 AGS 需保持同地域，不支持跨地域预热。
命名空间：目标 TCR 实例中已创建至少一个命名空间，预热规则以命名空间为维度配置。
操作步骤
配置 Agent 沙箱镜像预热触发器
步骤1：进入触发器页面
1. 登录 容器镜像服务控制台，进入目标实例详情页。
2. 在左侧导航栏选择触发器。
﻿
步骤2：新建触发器
单击新建触发器，按以下参数填写配置：
配置项
必填
说明
名称
是
支持小写字母、数字及 -、.、_，以字母或数字开头。
描述
否
触发器用途备注。
触发器类型
是
选择 Agent 沙箱镜像预热，仅对白名单用户可见。
触发动作
-
固定为推送镜像，不可修改。
命名空间
是
预热策略的作用维度，必须选定一个命名空间。
仓库名称
否
正则表达式，需包含命名空间前缀，格式如 namespace/repo；留空表示命名空间内全部仓库。
版本 Tag
否
正则表达式；留空表示全部版本。
预热目标地域
是
AGS 所在地域，需与 TCR 实例保持同地域。
仓库名称和版本 Tag 的填写方式请参考下文 配置仓库名称与版本 Tag 匹配规则。
步骤3：完成授权并提交配置
单击确认提交配置：
若 TCR_QCSRole 尚未绑定预设策略，将弹出 CAM 授权窗口，请按提示完成授权。该操作需由主账号或具备 CAM 权限的子账号确认。
授权失败时，提交会被阻止，避免创建无法成功调用预热接口的规则。
配置仓库名称与版本 Tag 匹配规则
触发规则中的仓库名称和版本 Tag 使用正则表达式匹配：
仓库名称匹配的是完整路径，即 命名空间/仓库，可包含多级路径，因此需要带命名空间前缀。
匹配采用非锚定的子串匹配方式。需要精确限定时，请使用 ^ 和 $ 锚定。
. 表示任意字符。匹配字面量点号（如版本号分隔符）时，需转义为 \\.。
以下写法均已在 TCR 实例上实测验证，以命名空间 demo 为例：
场景
仓库名称填写
版本 Tag 填写
命名空间内全部仓库
留空（控制台自动按 .* 处理）
留空
以 path 为名称前缀的所有一级仓库
^demo/path[^/]*$
留空
以 path1、path2 为名称前缀的所有一级仓库
^demo/(path1|path2)[^/]*$
留空
path1、path2 目录下的所有仓库
^demo/(path1|path2)/.+
留空
以 path1、path2 为名称前缀的所有仓库（任意层级）
^demo/(path1|path2)
留空
仓库内所有 1.x 版本 Tag
demo/tagtest
^1\\.
以 env1、env2 为名称前缀的版本 Tag
demo/tagtest
^(env1|env2)
注意：
*、**、?、{a,b} 在此不是通配符语法，请勿直接套用同步规则或版本保留规则的通配符写法。
单独填写 ** 或 ? 是非法正则表达式。
{env1*, env2*} 不是用于选择两个前缀的正则写法，花括号会被视为字面量，无法按预期匹配 Tag。
^1. 会误匹配 12、1x 等内容，因为 . 表示任意字符。匹配 1.x 版本前缀应填写 ^1\\.。
触发镜像预热并验证结果
步骤1：推送镜像触发预热
配置完成后，使用 docker push 向实例推送镜像。任何满足触发规则的镜像推送都会自动发起预热调用，无需人工操作。
步骤2：查看触发日志
在控制台的触发器页面，单击对应触发器行的触发日志，查看每次推送的调用记录与结果。
说明：
触发日志中的调用结果仅代表预热任务发起是否成功，不代表预热任务已完成。
步骤3：查询 AGS 预热任务状态
预热任务状态请在 AGS 侧查询。您可前往 API Explorer，调用 DescribePreCacheImageTask 接口查看任务状态。
通过云 API 配置触发器
除控制台外，您也可通过云 API 创建、查询或修改镜像预热触发器，并查询触发日志。
创建镜像预热触发器
调用 CreateWebhookTrigger 接口，请求参数示例如下：
{
  "RegistryId": "tcr-ejwv1234",
  "Namespace": "nginx-test",
  "Product": "ags",
  "PreheatRegion": "ap-guangzhou",
  "Trigger": {
    "Name": "preheat-demo",
    "Targets": [],
    "EventTypes": ["pushImage"],
    "Condition": ".*",
    "Enabled": true,
    "Description": "Agent 沙箱镜像预热示例"
  }
}
查询触发器列表
调用 DescribeWebhookTrigger 接口，请求参数示例如下：
{
  "RegistryId": "tcr-ejwv1234",
  "Product": "ags",
  "Limit": 20,
  "Offset": 1
}
查询触发日志
调用 DescribeWebhookTriggerLog 接口，请求参数示例如下：
{
  "RegistryId": "tcr-ejwv1234",
  "Namespace": "nginx-test",
  "Id": 38,
  "Limit": 20,
  "Offset": 1
}
修改触发器
调用 ModifyWebhookTrigger 接口，请求参数示例如下：
{
  "RegistryId": "tcr-ejwv1234",
  "Namespace": "nginx-test",
  "Product": "ags",
  "PreheatRegion": "ap-shanghai",
  "Trigger": {
    "Id": 38,
    "Name": "preheat-demo",
    "Targets": [],
    "EventTypes": ["pushImage"],
    "Condition": ".*",
    "Enabled": true
  }
}
说明：
上述请求中的实例 ID、命名空间、触发器 ID 和地域均为示例值，请替换为实际配置。创建和修改触发器时，PreheatRegion 均需与目标 TCR 实例保持同地域。
关键参数说明
接口
参数
说明
CreateWebhookTrigger
Product
必须为 "ags"，标识系统托管预热触发器；不传会被当作普通 webhook，并要求 Targets 非空。
CreateWebhookTrigger
PreheatRegion
AGS 预热目标地域，Product=ags 时必填。
CreateWebhookTrigger
Trigger.Targets
AGS 固定为空数组 []。
CreateWebhookTrigger
Trigger.EventTypes
固定为 ["pushImage"]。
CreateWebhookTrigger
Trigger.Condition
格式为 repo正则:tag正则，如 .* 匹配全部、nginx:.* 匹配 nginx 全部 Tag。
DescribeWebhookTrigger
Product
传入 "ags" 只查询预热触发器；省略则查询全部触发器。
DescribeWebhookTrigger
Limit / Offset
分页参数，Limit 为每页数量，Offset 为页码。
DescribeWebhookTrigger
返回 Response.Triggers
数组，元素包含 Id、Name、Condition、Product、PreheatRegion 等字段。
DescribeWebhookTriggerLog
Id
触发器的 Trigger.Id，必填。
DescribeWebhookTriggerLog
Limit / Offset
分页参数，Limit 为每页数量，Offset 为页码。
DescribeWebhookTriggerLog
返回 Response.Logs[].Status
TCR 触发调用状态：running、finished、error、stopped。
ModifyWebhookTrigger
Trigger.Id
必填，表示要修改的触发器 ID。
ModifyWebhookTrigger
部分更新
Trigger 中其余字段（Name、Targets、Condition、Description）可省略，省略则保留原值。
ModifyWebhookTrigger
PreheatRegion
省略时保留已持久化的地域。
﻿
常见问题与排查
现象
原因与处理
新建触发器时没有 Agent 沙箱镜像预热类型
功能白名单未开通，请联系腾讯云支持。
提交时提示 CAM 授权失败
TCR_QCSRole 未绑定 QcloudAccessForAgsRoleInTCR 预设策略。请由主账号或有 CAM 权限的子账号在弹窗中完成授权，或在 CAM 控制台手动为 TCR_QCSRole 绑定该策略。
触发日志报 ResourceNotFound.Image
预热调用已到达 AGS，但镜像不在 AGS 可预热的镜像目录中。请确认镜像存在于该地域，以及目标地域选择正确。
推送后没有触发记录
检查触发规则正则是否匹配，重点检查 ^、$ 锚定与 \\. 转义；确认发生的是推送镜像事件，删除或拉取不会触发预热；确认触发器未被禁用。
触发日志中查不到任务进度
TCR 仅展示调用结果，不同步任务状态。请在 Agent 沙箱的加速中心 -> 镜像预热 页面查询任务状态。
﻿

场景	仓库名称填写	版本 Tag 填写
命名空间内全部仓库	留空（控制台自动按 `.*` 处理）	留空
以 `path` 为名称前缀的所有一级仓库	`^demo/path[^/]*$`	留空
以 `path1`、`path2` 为名称前缀的所有一级仓库	`^demo/(path1\|path2)[^/]*$`	留空
`path1`、`path2` 目录下的所有仓库	`^demo/(path1\|path2)/.+`	留空
以 `path1`、`path2` 为名称前缀的所有仓库（任意层级）	`^demo/(path1\|path2)`	留空
仓库内所有 `1.x` 版本 Tag	`demo/tagtest`	`^1\\.`
以 `env1`、`env2` 为名称前缀的版本 Tag	`demo/tagtest`	`^(env1\|env2)`

接口	参数	说明
`CreateWebhookTrigger`	`Product`	必须为 `"ags"`，标识系统托管预热触发器；不传会被当作普通 webhook，并要求 `Targets` 非空。
`CreateWebhookTrigger`	`PreheatRegion`	AGS 预热目标地域，`Product=ags` 时必填。
`CreateWebhookTrigger`	`Trigger.Targets`	AGS 固定为空数组 `[]`。
`CreateWebhookTrigger`	`Trigger.EventTypes`	固定为 `["pushImage"]`。
`CreateWebhookTrigger`	`Trigger.Condition`	格式为 `repo正则:tag正则`，如 `.` 匹配全部、`nginx:.` 匹配 `nginx` 全部 Tag。
`DescribeWebhookTrigger`	`Product`	传入 `"ags"` 只查询预热触发器；省略则查询全部触发器。
`DescribeWebhookTrigger`	`Limit` / `Offset`	分页参数，`Limit` 为每页数量，`Offset` 为页码。
`DescribeWebhookTrigger`	返回 `Response.Triggers`	数组，元素包含 `Id`、`Name`、`Condition`、`Product`、`PreheatRegion` 等字段。
`DescribeWebhookTriggerLog`	`Id`	触发器的 `Trigger.Id`，必填。
`DescribeWebhookTriggerLog`	`Limit` / `Offset`	分页参数，`Limit` 为每页数量，`Offset` 为页码。
`DescribeWebhookTriggerLog`	返回 `Response.Logs[].Status`	TCR 触发调用状态：running、finished、error、stopped。
`ModifyWebhookTrigger`	`Trigger.Id`	必填，表示要修改的触发器 ID。
`ModifyWebhookTrigger`	部分更新	`Trigger` 中其余字段（`Name`、`Targets`、`Condition`、`Description`）可省略，省略则保留原值。
`ModifyWebhookTrigger`	`PreheatRegion`	省略时保留已持久化的地域。

配置项	必填	说明
名称	是	支持小写字母、数字及 `-`、`.`、`_`，以字母或数字开头。
描述	否	触发器用途备注。
触发器类型	是	选择 Agent 沙箱镜像预热，仅对白名单用户可见。
触发动作	-	固定为推送镜像，不可修改。
命名空间	是	预热策略的作用维度，必须选定一个命名空间。
仓库名称	否	正则表达式，需包含命名空间前缀，格式如 `namespace/repo`；留空表示命名空间内全部仓库。
版本 Tag	否	正则表达式；留空表示全部版本。
预热目标地域	是	AGS 所在地域，需与 TCR 实例保持同地域。

现象	原因与处理
新建触发器时没有 Agent 沙箱镜像预热类型	功能白名单未开通，请联系腾讯云支持。
提交时提示 CAM 授权失败	`TCR_QCSRole` 未绑定 `QcloudAccessForAgsRoleInTCR` 预设策略。请由主账号或有 CAM 权限的子账号在弹窗中完成授权，或在 CAM 控制台手动为 `TCR_QCSRole` 绑定该策略。
触发日志报 `ResourceNotFound.Image`	预热调用已到达 AGS，但镜像不在 AGS 可预热的镜像目录中。请确认镜像存在于该地域，以及目标地域选择正确。
推送后没有触发记录	检查触发规则正则是否匹配，重点检查 `^`、`$` 锚定与 `\\.` 转义；确认发生的是推送镜像事件，删除或拉取不会触发预热；确认触发器未被禁用。
触发日志中查不到任务进度	TCR 仅展示调用结果，不同步任务状态。请在 Agent 沙箱的加速中心 -> 镜像预热页面查询任务状态。

使用 TCR 触发器自动预热 Agent 沙箱镜像

本页目录：

操作场景

前提条件

操作步骤

配置 Agent 沙箱镜像预热触发器

步骤1：进入触发器页面

步骤2：新建触发器

步骤3：完成授权并提交配置

配置仓库名称与版本 Tag 匹配规则

触发镜像预热并验证结果

步骤1：推送镜像触发预热

步骤2：查看触发日志

步骤3：查询 AGS 预热任务状态

通过云 API 配置触发器

创建镜像预热触发器

查询触发器列表

查询触发日志

修改触发器

关键参数说明

﻿

常见问题与排查