huawei-cloud-swr-image-automation

华为云 SWR 镜像自动化

概述

此技能使用 hcloud CLI 为华为云 SWR（容器镜像服务）提供镜像自动化功能，包括跨区域镜像同步和基于触发器的自动部署。

架构：hcloud CLI → SWR 服务 API → SyncRepo/Trigger/SyncJob/SyncRegion 资源

相关技能：

• huawei-cloud-swr-image-management - 镜像生命周期管理（命名空间、仓库、标签、认证、配额）。要端到端验证触发器，必须推送镜像并完成身份验证（CreateAuthorizationToken、docker login、docker push）。 如果尚未安装，请先安装：

  npx skills add huaweicloud/huaweicloud-skills --skill huawei-cloud-swr-image-management -y
  

  如需了解完整的镜像推送和身份验证流程，请参阅 SWR 官方快速入门指南：https://support.huaweicloud.com/qs-swr/index.html

• huawei-cloud-swr-image-governance - 镜像治理（权限、保留策略、共享、标签、不可变规则）

• huawei-cloud-swr-enterprise-instance - 企业版实例管理

• 配置自动同步，在推送镜像时将其复制到其他区域

• 手动将指定镜像标签同步到目标区域

• 列出可用的同步目标区域

• 检查同步作业的执行状态

• 创建和管理用于自动部署到 CCE/CCI 工作负载的触发器

• 启用/禁用触发器并更新触发器配置

典型用例：

• “为我的镜像仓库设置自动同步到 cn-east-3”
• “将镜像标签 v1.0 和 v2.0 手动同步到其他区域”
• “列出可用于镜像同步的区域”
• “检查我的镜像同步作业状态”
• “创建一个触发器，在推送新镜像时自动更新我的 CCE 部署”
• “列出某个仓库的所有触发器”
• “暂时禁用一个触发器”
• “删除旧的触发器配置”
• “配置跨多个区域的镜像复制”

参数确认

所有写操作（创建、更新、删除）都必须在执行前获得用户的明确确认。

执行任何写操作前，此技能必须：

1. 显示即将执行的完整 hcloud 命令
2. 显示目标资源（命名空间、仓库、远程区域等）
3. 显示将应用的更改（同步配置、触发器设置、覆盖状态）
4. 等待用户确认（“yes” / “confirm”）后再继续
5. 如果用户拒绝，则中止操作并返回步骤 1

需要确认的写操作：

操作	命令	风险级别	描述
创建自动同步配置	CreateImageSyncRepo	🟠 高	创建跨区域镜像复制。如果 override=true，将覆盖目标区域中的现有镜像，且无法恢复。继续前请警告用户
删除自动同步配置	DeleteImageSyncRepo	🟡 中	移除自动同步配置。新推送的镜像将不再自动复制到目标区域。已同步的镜像会保留
手动同步标签	CreateManualImageSyncRepo	🟡 中	一次性同步指定标签。如果 override=true，将覆盖目标区域中的现有镜像
创建触发器	CreateTrigger	🟡 中	设置自动部署到 CCE/CCI。推送新镜像后将自动更新目标工作负载，请核实触发条件，避免非预期部署
更新触发器	UpdateTrigger	🟡 中	修改触发器配置。启用或禁用触发器会立即改变自动部署行为
删除触发器	DeleteTrigger	🟡 中	移除自动部署触发器。推送新镜像后，目标工作负载将不再自动更新

前提条件

1. hcloud CLI 要求（必需）

• 已安装 hcloud CLI（版本 >= 7.2.2）
• 运行 hcloud version 验证安装
• 首次使用：运行 printf "y\n" | hcloud version 接受隐私声明

2. 凭证配置

hcloud CLI 支持通过环境变量配置两种凭证模式，并会在运行时自动检测：

模式 A — 长期 AK/SK（永久访问）：

export HUAWEI_CLOUD_AK=<your-ak>
export HUAWEI_CLOUD_SK=<your-sk>
export HUAWEI_CLOUD_REGION=cn-north-4

模式 B — 临时 AK/SK + SecurityToken（推荐用于临时或委托访问）：

export HUAWEI_CLOUD_AK=<your-temp-ak>
export HUAWEI_CLOUD_SK=<your-temp-sk>
export HUAWEI_CLOUD_SECURITY_TOKEN=<your-security-token>
export HUAWEI_CLOUD_REGION=cn-north-4

如果存在 HUAWEI_CLOUD_SECURITY_TOKEN，hcloud CLI 会自动使用临时凭证进行身份验证。如果只设置了 AK/SK，则使用长期凭证进行身份验证。

• 安全规则：
  • 🚫 切勿在代码、对话或命令中暴露 AK/SK/SecurityToken 值
  • 🚫 切勿使用 echo $HUAWEI_CLOUD_AK 或 echo $HUAWEI_CLOUD_SK 检查凭证
  • ✅ 使用环境变量：HUAWEI_CLOUD_AK、HUAWEI_CLOUD_SK、HUAWEI_CLOUD_REGION、HUAWEI_CLOUD_SECURITY_TOKEN
  • ✅ 云操作优先使用 IAM 用户，而非根账户
  • ✅ 为敏感操作启用 MFA

⚠️ 重要安全说明：

• 切勿将凭证提交到版本控制系统
• 使用仅具有所需最低权限的 IAM 用户
• 为敏感操作启用 MFA
• 定期轮换 AK/SK

3. IAM 权限要求

API 操作	权限	用途
swr:sync:create	创建同步仓库	配置跨区域镜像同步
swr:sync:delete	删除同步仓库	移除同步配置
swr:sync:list	列出同步仓库	查询自动同步配置
swr:syncmanual:create	手动同步	触发手动镜像同步
swr:syncregion:list	列出同步区域	查询可用的同步目标区域
swr:syncjob:get	获取同步作业状态	检查同步执行状态
swr:trigger:create	创建触发器	设置自动部署触发器
swr:trigger:list	列出触发器	查询触发器配置
swr:trigger:get	获取触发器	查看特定触发器的详细信息
swr:trigger:update	更新触发器	修改触发器配置
swr:trigger:delete	删除触发器	移除触发器配置

完整的策略 JSON，请参阅 IAM 权限策略。

权限失败处理：

1. 如果任何命令因权限错误而失败，请阅读 references/iam-policies.md
2. 向用户展示所需权限列表和策略 JSON
3. 指导用户在 IAM 控制台中创建自定义策略并授予授权
4. 暂停执行，等待用户确认已授予权限

工作流

0. ⚠️ 账单确认（必须） — 执行任何操作前，告知用户可能产生的费用，并获得明确同意：
   • 跨区域同步：在不同区域之间同步映像会产生跨区域流量费用。自动同步（syncAuto=true）会持续复制映像，从而产生持续的流量费用。
   • 触发器执行：部署到 CCE/CCI 的触发器可能会产生目标集群的计算费用。
   • 存储费用：同步的映像会占用源区域和目标区域的存储空间。
   • 请用户确认：“您是否了解相关费用，并希望继续？（是/否）”
   • 只有用户明确同意后才能继续。如果用户拒绝，请停止，不要执行任何操作。
1. 确认参数 — 查看上方的确认表；在执行任何写入操作前，与用户确认风险级别和关键参数
2. 查询同步区域 — 使用 ListSyncRegions 获取可用的跨区域同步目标
3. 配置同步 — 使用 CreateImageSyncRepo（自动同步）或 CreateManualImageSyncRepo（单次手动同步）
4. 管理触发器 — 使用 CreateTrigger / UpdateTrigger / DeleteTrigger 配置自动部署到 CCE/CCI
5. 查询状态 — 使用 ListImageAutoSyncReposDetails / ShowTrigger / ListSyncJobsDetails 检查同步和触发器状态
6. 清理 — 使用 DeleteImageSyncRepo 停止同步，使用 DeleteTrigger 移除触发器

KooCLI 命令格式规范

所有命令均遵循标准的 hcloud KooCLI 格式：

hcloud SWR <Operation> --param1=value1 --param2=value2 --cli-region=<region>

主要约定：

• 服务名称：SWR（大写，与 KooCLI 服务列表一致）
• 操作名称：PascalCase（例如，CreateImageSyncRepo、ListSyncRegions、CreateTrigger）
• 区域参数：--cli-region=<value>（默认值：cn-north-4，或使用 HUAWEI_CLOUD_REGION 环境变量）
• 输出格式：--cli-output=json（用于 Agent 处理）
• JMESPath 筛选：--cli-query="<expression>"（用于精简输出）
• 数组格式参数：--imageTag.1=v1 --imageTag.2=v2（索引从 1 开始，而非 0）

示例 — 读取操作：

hcloud SWR ListSyncRegions --cli-region=cn-north-4 --cli-output=json

示例 — 写入操作（需要用户确认）：

# Step 1: Display command and parameters for user confirmation
# Step 2: After user confirms, execute:
hcloud SWR CreateImageSyncRepo --namespace=pancake --repository=openclaw-sandbox \
  --remoteRegionId=cn-east-3 --remoteNamespace=pancake --syncAuto=true --override=false \
  --cli-region=cn-north-4

核心命令

1. 自动同步（跨区域映像复制）

详细工作流请参阅任务：映像同步。

# List available sync target regions
hcloud SWR ListSyncRegions --cli-region=cn-north-4

# Configure auto-sync for a repository to target region
hcloud SWR CreateImageSyncRepo --namespace=group-dev --repository=my-app --remoteRegionId=cn-east-3 --remoteNamespace=group-dev --override=false --syncAuto=true --cli-region=cn-north-4

# List auto-sync configurations for a repository
hcloud SWR ListImageAutoSyncReposDetails --namespace=group-dev --repository=my-app --cli-region=cn-north-4

# Delete auto-sync configuration
hcloud SWR DeleteImageSyncRepo --namespace=group-dev --repository=my-app --remoteRegionId=cn-east-3 --remoteNamespace=group-dev --cli-region=cn-north-4

自动同步行为：当 syncAuto=true 时，每次向源仓库推送新映像都会自动触发同步至目标区域。当 syncAuto=false 时，只有手动触发才会进行同步。

⚠️ 查询限制：ListImageAutoSyncReposDetails 仅返回 syncAuto=true 的配置。syncAuto=false 的配置不会出现在查询结果中；未显示并不代表创建失败。

2. 手动同步

# Manually sync specific image tags to target region
hcloud SWR CreateManualImageSyncRepo --namespace=group-dev --repository=my-app --remoteRegionId=cn-east-3 --remoteNamespace=group-dev --imageTag.1=v1.0 --imageTag.2=v2.0 --override=false --cli-region=cn-north-4

⚠️ 重要：--imageTag 使用带索引的数组格式，而非普通值格式：

• ✅ 正确：--imageTag.1=v1.0 --imageTag.2=v2.0
• ❌ 错误：--imageTag=v1.0（缺少索引）
• ❌ 错误：--imageTag=v1.0,v2.0（不支持逗号分隔）

3. 同步区域

# List all regions available as sync targets
hcloud SWR ListSyncRegions --cli-region=cn-north-4

响应格式（已根据实际 API 验证）：

[
  {
    "regionID": "cn-north-4"
  }

返回可用于同步映像的所有区域。将 regionID 字段的值用作 --remoteRegionId 参数。

4. 同步作业状态

# Check sync job status (--filter is REQUIRED with limit and offset)
hcloud SWR ShowSyncJob --namespace=group-dev --repository=my-app --filter="limit::10|offset::0" --cli-region=cn-north-4

⚠️ 重要：必须提供 --filter，且其中必须同时包含 limit::N 和 offset::N（例如，"limit::10|offset::0"）。如果未提供该参数，命令会返回缺少参数错误。

响应格式（已根据实际 API 验证）：返回扁平的 JSON 数组。没有同步作业时返回 []。

5. 触发器管理（自动部署到 CCE/CCI）

详细工作流请参阅 任务：触发器管理。

# Create a trigger for auto-deploy to CCE
hcloud SWR CreateTrigger --namespace=group-dev --repository=my-app --name=deploy-trigger --trigger_type=all --condition=".*" --action=update --app_type=deployments --application=my-deployment --cluster_ns=default --enable=true --trigger_mode=cce --cluster_id=<cluster-id> --cluster_name=<cluster-name> --cli-region=cn-north-4

# List all triggers for a repository
hcloud SWR ListTriggersDetails --namespace=group-dev --repository=my-app --cli-region=cn-north-4

# Show trigger details
hcloud SWR ShowTrigger --namespace=group-dev --repository=my-app --trigger=deploy-trigger --cli-region=cn-north-4

# Update a trigger (enable/disable or modify configuration)
hcloud SWR UpdateTrigger --namespace=group-dev --repository=my-app --trigger=deploy-trigger --enable=false --cli-region=cn-north-4

# Delete a trigger
hcloud SWR DeleteTrigger --namespace=group-dev --repository=my-app --trigger=deploy-trigger --cli-region=cn-north-4

触发器类型：

• all：推送任意镜像时触发（condition=".*"）
• tag：推送指定标签时触发（condition=tag-name）
• regular：推送匹配正则表达式的标签时触发（condition=regex-pattern）

触发器模式：

• cce：部署到 CCE（云容器引擎）集群 — 需要 --cluster_id
• cci：部署到 CCI（云容器实例）— 无需集群 ID

参数参考

通用参数

参数	必填/可选	说明	默认值
--cli-region	必填	华为云区域 ID	配置值或 HUAWEI_CLOUD_REGION
--namespace	视上下文而定	SWR 命名空间（组织）	N/A
--repository	视上下文而定	镜像仓库名称	N/A

自动同步参数

参数	必填	说明	限制条件
--namespace	是	源命名空间	已存在的命名空间名称
--repository	是	源仓库	已存在的仓库名称
--remoteRegionId	是	目标区域 ID	必须来自 ListSyncRegions 结果
--remoteNamespace	是	目标命名空间	目标区域中的命名空间名称
--override	否	覆盖现有镜像	true 或 false（默认值为 false）
--syncAuto	否	推送时自动同步	true 或 false（默认值为 false）

手动同步参数

参数	必填	说明	限制条件
--namespace	是	源命名空间	已存在的命名空间名称
--repository	是	源仓库	已存在的仓库名称
--remoteRegionId	是	目标区域 ID	必须来自 ListSyncRegions 结果
--remoteNamespace	是	目标命名空间	目标区域中的命名空间名称
--imageTag.[N]	是	标签列表（索引数组）	--imageTag.1=v1.0 --imageTag.2=v2.0
--override	否	覆盖现有镜像	true 或 false（默认值为 false）

触发器参数

参数	必填	描述	约束
--namespace	是	SWR 命名空间	已存在的命名空间名称
--repository	是	镜像仓库	已存在的仓库名称
--name	是	触发器名称	在仓库内唯一
--trigger_type	是	触发器类型	all、tag、regular
--condition	是	匹配条件	全部为 .*，标签为标签名称，正则表达式为正则表达式
--action	是	触发器操作	update
--app_type	是	应用类型	deployments 或 statefulsets
--application	是	CCE/CCI 应用名称	已存在的部署名称
--cluster_ns	是	应用命名空间	Kubernetes 命名空间（例如：default）
--enable	是	启用触发器	true 或 false
--trigger_mode	否	部署目标	cce（默认）或 cci
--cluster_id	仅 CCE	CCE 集群 ID	cce 模式下必填，cci 模式下留空
--cluster_name	否	CCE 集群名称	可选的集群名称
--container	否	目标容器	特定容器名称（默认：全部）

输出格式

ListSyncRegions（已验证）

响应是一个包含区域对象的扁平 JSON 数组：

[
  {
    "regionID": "cn-north-4",
    "region_name": "north-1"
  }
]

注意：返回所有可用的同步目标区域。将 region_id 用作 --remoteRegionId。

ListImageAutoSyncReposDetails

响应格式待验证——存在同步仓库配置时返回配置列表。未配置自动同步时返回空结果。

⚠️ 限制：仅返回 syncAuto=true（自动同步）的配置。syncAuto=false（仅手动同步）的配置不会出现在结果中。解决方法请参见任务：镜像同步 W3。

ListTriggersDetails

响应格式待验证——存在触发器时返回触发器对象列表。未配置触发器时返回空结果。

ShowTrigger

响应格式待验证。使用 --namespace、--repository、--trigger（触发器名称）作为参数。

ShowSyncJob（已验证）

响应是一个扁平 JSON 数组。不存在同步作业时返回 []：

[]

注意：需要 --filter="limit::N|offset::N" 参数。用法请参见同步作业状态。

验证

分步验证方法请参见验证方法。

常见区域 ID

区域名称	区域 ID
中国华北 - 北京 4	cn-north-4
中国华北 - 北京 1	cn-north-1
中国华东 - 上海 1	cn-east-3
中国华东 - 上海 2	cn-east-2
中国华南 - 广州	cn-south-1
中国华南 - 深圳	cn-south-4
中国西南 - 贵阳 1	cn-southwest-2
亚太 - 曼谷	ap-southeast-2
亚太 - 新加坡	ap-southeast-1
亚太 - 香港	ap-southeast-3
欧洲 - 巴黎	eu-west-0

最佳实践

1. 生产仓库自动同步：为生产仓库设置 syncAuto=true，确保镜像自动复制到目标区域
2. 按需手动同步：仅需同步特定标签（例如生产版本）时，使用 CreateManualImageSyncRepo
3. 谨慎覆盖：仅当确实要覆盖目标区域中的现有镜像时，才设置 override=true
4. 触发器命名：使用描述性触发器名称（例如 prod-deploy-trigger、staging-update-trigger）
5. 触发条件设计：使用 trigger_type=regular 和正则表达式，以便灵活匹配（例如，使用 v\d+\.\d+\.\d+ 匹配 semver 标签）
6. 删除前先禁用：删除触发器前，先禁用触发器（enable=false），避免清理期间意外部署
7. 验证目标命名空间：创建同步配置前，确保目标区域中存在目标命名空间
8. 区域间命名空间保持一致：在各区域使用相同的命名空间名称，以便更轻松地进行跨区域管理
9. 先检查同步区域：创建同步配置前，始终运行 ListSyncRegions，确认目标区域可用

参考文档

文档	说明
SWR Automation API Guide	hcloud SWR 自动化 API 参考
IAM Permission Policies	所需权限和策略 JSON
Verification Method	分步验证
Common Pitfalls	故障排除指南
Task: Image Sync	自动/手动同步工作流
Task: Trigger Management	触发器工作流
CLI Installation Guide	KooCLI 安装和凭证配置
Acceptance Criteria	正确/错误模式对比

注意事项

• 自动同步会持续生效——配置完成后，每次有新推送时都会自动触发，直到删除该配置
• 手动同步仅执行一次——每次调用 CreateManualImageSyncRepo 都只会同步指定标签一次
• --imageTag.[N] 使用索引数组格式——不能使用普通值或逗号分隔格式
• 同步目标命名空间必须存在——同步前先在目标区域创建命名空间
• 绝不能硬编码 AK/SK——只能通过环境变量获取凭证
• 仅支持 hcloud CLI——所有操作均使用 hcloud SWR <Operation> 格式
• 触发器需要 CCE/CCI 集群——触发器仅适用于现有的 CCE 集群或 CCI 实例
• 响应格式待验证——ListImageAutoSyncReposDetails、ListTriggersDetails、ShowTrigger 的响应格式需要通过实际调用验证
• CLI 退出码的局限性——即使 SWR API 返回错误，hcloud CLI（KooCLI 7.2.2）也可能返回退出码 0。在自动化脚本中，切勿仅依赖退出码；应检查输出中的 error_code 或 error_msg 字段来判断成功或失败
• 必须进行预验证——SWR API 不会在请求时验证目标命名空间是否存在、标签是否存在或区域是否有效。创建同步配置或手动同步任务前，务必运行预验证检查（ShowNamespace、ListRepositoryTags、ListSyncRegions）
• CCI 授权是前置条件——创建 trigger_mode=cci 触发器前，通过 hcloud CCI ListNamespaces 验证 CCI 服务已获授权。CCI 未授权时会返回容易误导的“Server internal error”，而不是授权提示

常见陷阱

详细的故障排查指南请参阅常见陷阱与解决方案。

快速参考：

陷阱	现象	快速修复
--imageTag 格式错误	手动同步失败	使用带索引的格式：--imageTag.1=v1.0
目标命名空间不存在	创建同步失败	先在目标区域创建命名空间
remoteRegionId 无效	创建同步失败	使用 ListSyncRegions 检查
找不到 CCE 集群	创建触发器失败	在 CCE 控制台中验证 cluster_id
触发器已存在	409 Conflict	先使用 ShowTrigger 检查
CCI 未授权	“Server internal error”	先在控制台授权 CCI
创建触发器时出现“Invalid param”	通用错误，原因多种	预先检查名称、集群和应用是否存在
API 出错但退出代码为 0	脚本误以为成功	检查输出中的 error_code，而不是退出代码
列表中没有 syncAuto=false	配置似乎缺失	ListImageAutoSyncReposDetails 仅显示 true
同步到不存在的命名空间	表面上成功，配置无效	先使用 ShowNamespace 验证命名空间
不需要自动同步	镜像意外同步	设置 syncAuto=false 或删除同步配置