huawei-cloud-swr-image-management

华为云 SWR 镜像管理

概述

此技能使用 hcloud CLI 提供华为云 SWR（Software Repository for Container）镜像的生命周期管理能力。

架构：hcloud CLI → SWR Service API → 命名空间／仓库／标签／认证／配额资源

• 创建和管理 SWR 命名空间（组织）
• 创建和管理可设置为公开或私有的镜像仓库
• 查询和管理镜像标签／版本
• 获取 Docker 登录凭据（临时和长期）
• 检查 SWR 资源配额

典型用例：

• “为我的项目创建一个 SWR 命名空间”
• “列出命名空间 ‘group-dev’ 中的所有镜像仓库”
• “查询命名空间 ‘group-dev’ 中仓库 ‘nginx’ 的镜像标签”
• “获取 SWR 的 Docker 登录命令”
• “删除旧的镜像标签以清理存储空间”
• “检查我的 SWR 配额使用情况”
• “为我的自定义镜像创建私有仓库”
• “更新仓库描述和可见性”

工作流

0. ⚠️ 费用确认（必须） — 执行任何操作前，告知用户可能产生的费用，并征得用户明确同意：
   • SWR 基础服务：SWR 基础服务在配额范围内免费。超出命名空间或仓库配额可能需要升级到企业版实例（这会产生费用）。
   • 存储费用：SWR 中的镜像存储会占用 OBS 存储空间。镜像较大或标签较多都会增加存储费用。
   • 流量费用：频繁拉取／推送镜像，尤其是跨区域操作，可能会产生网络流量费用。
   • 请用户确认：“您是否了解相关费用影响并希望继续？（是／否）”
   • 只有在用户明确确认后才能继续。如果用户拒绝，请停止操作，不要执行任何操作。
1. 解析用户请求 — 识别 SWR 操作类型（命名空间、仓库、标签、认证、配额）
2. 验证前提条件 — 检查 hcloud CLI 是否已安装，以及凭据是否已配置
3. 确认参数 — 向用户展示操作、目标资源和参数以供确认
4. 执行读取操作 — 对于查询操作（Show、List），直接运行 hcloud CLI
5. 确认写入操作 — 对于写入操作（Create、Update、Delete），执行前请用户确认（参见参数确认）
6. 解析并格式化输出 — 提取相关字段，并格式化为表格或结构化输出
7. 报告结果 — 提供结果及相关上下文（例如，已创建命名空间、仓库可见性已更改）
8. 建议后续操作 — 推荐相关操作（例如，创建命名空间后，建议创建仓库）

参数确认

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

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

1. 显示即将执行的确切 hcloud 命令
2. 显示目标资源（命名空间、存储库、标签等）
3. 显示要应用的更改（创建、删除、更改可见性）
4. 等待用户确认（“yes” / “确认”）后再继续
5. 如果用户拒绝，则中止操作并返回第 1 步

需要确认的写操作：

操作	命令	风险等级	描述
创建命名空间	CreateNamespace	中	创建新的 SWR 命名空间（会占用配额）
创建存储库	CreateRepo	中	创建新的镜像存储库
更新存储库	UpdateRepo	中	更改存储库可见性（公开／私有）。将 is_public 更改为 true（私有→公开）时，必须显示明确的安全警告： ⚠️ 公开存储库允许任何用户拉取镜像，可能带来安全风险。技能必须向用户发出警告，并要求用户明确确认后再继续。如果用户拒绝，则中止操作。
删除命名空间	DeleteNamespaces	高	删除命名空间及其下的所有存储库／镜像
删除存储库	DeleteRepo	高	永久删除存储库及其所有镜像标签
删除标签	DeleteRepoTag	高	永久删除镜像标签（不可恢复）

前提条件

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:namespace:create	创建命名空间	创建 SWR 组织
swr:namespace:list	列出命名空间	查询所有命名空间
swr:namespace:get	获取命名空间	查看单个命名空间信息
swr:namespace:delete	删除命名空间	移除组织
swr:repository:create	创建仓库	创建镜像仓库
swr:repository:list	列出仓库	查询镜像仓库
swr:repository:get	获取仓库	查看仓库详情
swr:repository:update	更新仓库	修改仓库属性
swr:repository:delete	删除仓库	移除镜像仓库
swr:tag:list	列出标签	查询镜像标签/版本
swr:tag:get	获取标签	查看特定标签详情
swr:tag:create	创建标签	创建镜像标签
swr:tag:delete	删除标签	移除镜像标签
swr:login:get	获取登录令牌	获取 Docker 登录凭据
swr:quota:get	获取配额	检查资源配额

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

权限不足处理：

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

KooCLI 命令格式标准

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

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

主要约定：

• 服务名称：SWR（大写，与 KooCLI Services 列表一致）
• 操作名称：PascalCase（例如，ShowNamespace、CreateRepo、ListRepoTags）
• 区域参数：--cli-region=<value>（默认值：cn-north-4，或使用 HUAWEI_CLOUD_REGION 环境变量）
• 输出格式：--cli-output=json（用于 Agent 处理）
• JMESPath 筛选：--cli-query="<expression>"（用于减少输出）
• 对象类型参数：JSON 字符串格式 --key={subkey:value}

示例 — 读取操作：

hcloud SWR ShowNamespace --namespace=pancake --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 CreateNamespace --namespace=my-project --cli-region=cn-north-4

核心命令

1. 命名空间（组织）管理

详细工作流请参阅 任务：命名空间管理。

# List all namespaces
hcloud SWR ListNamespaces --cli-region=cn-north-4

# List namespaces with filter
hcloud SWR ListNamespaces --filter="namespace::group-dev|mode::visible" --cli-region=cn-north-4

# Show namespace details
hcloud SWR ShowNamespace --namespace=group-dev --cli-region=cn-north-4

# Create a namespace
hcloud SWR CreateNamespace --namespace=group-dev --cli-region=cn-north-4

# Delete a namespace (CAUTION: removes all repos under it)
hcloud SWR DeleteNamespaces --namespace=group-dev --cli-region=cn-north-4

命名空间命名规则：

• 以小写字母开头
• 后续字符可以是小写字母、数字、点、下划线或连字符
• 最多允许连续 2 个下划线
• 点、下划线和连字符不能直接相连
• 以小写字母或数字结尾
• 长度：1-64 个字符

2. 仓库（镜像仓库）管理

详细工作流请参阅 任务：仓库管理。

# List all repositories
hcloud SWR ListReposDetails --cli-region=cn-north-4

# List repositories in a namespace
hcloud SWR ListReposDetails --namespace=group-dev --cli-region=cn-north-4

# List repositories with pagination and sorting
hcloud SWR ListReposDetails --namespace=group-dev --limit=20 --offset=0 --order_column=updated_time --order_type=desc --cli-region=cn-north-4

# List repositories by category
hcloud SWR ListReposDetails --category=database --cli-region=cn-north-4

# Show repository details
hcloud SWR ShowRepository --namespace=group-dev --repository=nginx --cli-region=cn-north-4

# Create a repository
hcloud SWR CreateRepo --namespace=group-dev --repository=my-app --is_public=false --category=other --description="Custom app image" --cli-region=cn-north-4

# Update repository (change visibility, description, category)
# ⚠️ SECURITY WARNING: When changing is_public to true (private→public):
#   "Public repositories allow any user to pull images, which may pose security risks."
#   The skill MUST display this warning and require explicit user confirmation before proceeding.
hcloud SWR UpdateRepo --namespace=group-dev --repository=my-app --is_public=true --description="Updated description" --cli-region=cn-north-4

# Delete a repository (CAUTION: removes all image tags)
hcloud SWR DeleteRepo --namespace=group-dev --repository=my-app --cli-region=cn-north-4

仓库命名规则：

• 以小写字母或数字开头
• 后续字符可以是小写字母、数字、点、斜杠、下划线或连字符
• 最多允许连续 2 个下划线
• 点、斜杠、下划线和连字符不能直接相连
• 以小写字母或数字结尾
• 长度：1-128 个字符

仓库类别：app_server、linux、framework_app、database、lang、other、windows、arm

3. 镜像标签（版本）管理

详细工作流请参阅 任务：标签管理。

# List all tags in a repository
hcloud SWR ListRepositoryTags --namespace=group-dev --repository=nginx --cli-region=cn-north-4

# List tags with pagination and sorting
hcloud SWR ListRepositoryTags --namespace=group-dev --repository=nginx --limit=50 --offset=0 --order_column=updated_at --order_type=desc --cli-region=cn-north-4

# Search for a specific tag
hcloud SWR ListRepositoryTags --namespace=group-dev --repository=nginx --filter="tag::v1.0" --cli-region=cn-north-4

# Show tag details (image digest, size, create time)
hcloud SWR ShowRepoTag --namespace=group-dev --repository=nginx --tag=v1.0 --cli-region=cn-north-4

# Create a tag (retag existing image)
hcloud SWR CreateRepoTag --namespace=group-dev --repository=nginx --source_tag=v1.0 --destination_tag=v1.0-stable --override=false --cli-region=cn-north-4

# Delete a tag (CAUTION: removes the image version permanently)
hcloud SWR DeleteRepoTag --namespace=group-dev --repository=nginx --tag=v1.0-old --cli-region=cn-north-4

4. Docker 登录与身份验证

详细工作流请参阅 任务：身份验证管理。

# Get temporary docker login credentials (valid for 12 hours)
hcloud SWR CreateAuthorizationToken --cli-region=cn-north-4

# Get long-term docker login credentials (valid for 1 year)
hcloud SWR CreateSecret --cli-region=cn-north-4

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

响应会返回一个 Docker 身份验证配置对象：

{
  "auths": {
    "swr.cn-north-4.myhuaweicloud.com": {
      "auth": "base64-encoded-auth-token"
    }
  }
}

• auths：Docker 配置中的身份验证对象，以注册表主机名为键
• auth：经过 Base64 编码的 username:password 字符串

Docker 登录：

⚠️ 安全提示：Agent 绝不能解码 auth 字段。请向用户提供以下命令，让他们在自己的终端中运行。

Agent 应从 API 响应中提取 auth 字段的值，并向用户提供以下命令：

# User runs these in their terminal (agent must NOT execute):
echo <auth_value> | base64 -d  # Outputs username:password
docker login -u <username> -p <password> swr.cn-north-4.myhuaweicloud.com

5. 配额管理

详细工作流请参阅 任务：配额管理。

# Check SWR quotas
hcloud SWR ListQuotas --cli-region=cn-north-4

参数参考

有关详细参数表和各命令的有效值，请参阅 参数参考。

输出格式

有关所有 SWR API 命令的 JSON 响应格式，请参阅 输出格式参考。

验证

分步验证说明请参阅 验证方法。

最佳实践

1. 命名空间组织：使用清晰的命名空间名称，并遵循团队／项目命名规范（例如：team-backend、proj-ai）
2. 仓库可见性：内部镜像应设置 is_public=false；仅当镜像要公开共享时才设置 is_public=true
3. 标签命名规范：使用语义化版本号（例如：v1.0、v1.0-stable、latest），避免使用含义模糊的标签
4. 定期清理：定期删除过时的标签，以管理存储配额
5. 重新打标签，而非重新推送：使用 CreateRepoTag 创建版本别名，而不是多次推送同一镜像
6. 用于 CI/CD 的长期登录凭据：自动化流水线使用 CreateSecret；临时访问使用 CreateAuthorizationToken
7. 谨慎删除：删除命名空间会移除其下的所有仓库；删除仓库会移除所有标签

相关能力（由 Agent 编排）

此技能不提供以下能力。Agent 可以通过单独的技能编排这些能力。

技能	描述
huawei-cloud-swr-enterprise-instance	企业版 SWR 实例管理：创建／删除实例、配置访问端点、管理长期凭据、镜像安全扫描（StartManualScanning）、构建历史（ShowInstanceArtifactAddition --addition=build_history）以及镜像同步注册表
huawei-cloud-swr-image-automation	SWR 镜像自动化：跨区域自动同步镜像、基于触发器部署到 CCE/CCI
huawei-cloud-swr-image-governance	SWR 镜像治理：保留策略、共享下载域名、命名空间／仓库授权

参考文档

文档	描述
SWR API 指南	hcloud SWR API 参考
参数参考	参数表和区域 ID
输出格式	JSON 响应格式
IAM 权限策略	所需权限和策略 JSON
验证方法	分步验证
常见问题	故障排查指南
任务：命名空间管理	命名空间工作流
任务：仓库管理	仓库工作流
任务：标签管理	标签工作流
任务：身份验证管理	登录凭据工作流
任务：配额管理	配额检查工作流
CLI 安装指南	hcloud 安装、配置和验证
验收标准	正确/错误模式对比

不支持的操作

此技能通过 hcloud CLI 管理 SWR 命名空间、仓库、标签、身份验证凭据和配额。此技能不支持以下操作：

推送/拉取镜像（docker CLI 操作）

此技能通过 CreateAuthorizationToken 或 CreateSecret 提供 docker 登录凭据，但不会执行 docker push 或 docker pull。获取凭据后，请直接使用 docker CLI：

分步工作流：

1. 获取凭据 — 使用此技能获取 SWR 登录凭据
2. 向用户提供身份验证令牌 — 从响应中提取 auth 字段并展示给用户。⚠️ Agent 不得解码此字段。
3. 用户解码并登录 — 用户在终端中运行以下命令：

# User runs these in their terminal (agent must NOT execute):
echo <auth_value> | base64 -d  # Outputs username:password
docker login -u <username> -p <password> swr.cn-north-4.myhuaweicloud.com

4. 推送/拉取镜像 — 用户使用标准 docker CLI 命令：

docker push swr.cn-north-4.myhuaweicloud.com/<namespace>/<repo>:<tag>
docker pull swr.cn-north-4.myhuaweicloud.com/<namespace>/<repo>:<tag>

对于长期使用的 CI/CD 凭据，请使用 CreateSecret，而不是 CreateAuthorizationToken（有效期为 1 年，而非 12 小时）。

镜像安全扫描

此技能不提供镜像安全扫描功能。该功能需要企业版 SWR 实例，并依赖 Huawei Cloud HSS（主机安全服务）。StartManualScanning API 仅适用于企业版 SWR 实例，不适用于基础版 SWR。

检查企业版实例是否已启用扫描，请查询实例配置并查找 enableArtifactScanning 字段（参见 SWR API 文档）。如果 enableArtifactScanning 为 false，必须先在企业版实例上启用扫描。

此技能不支持镜像安全扫描。用户应启用 HSS（主机安全服务），并通过 SWR Web 控制台执行扫描。

构建历史

基础版 SWR 不提供构建历史。对于企业版 SWR 实例，可通过 ShowInstanceArtifactAddition API 使用 --addition=build_history 查询构建历史（参见 SWR API 文档）：

# Query build history for an enterprise instance artifact (requires instance_id)
hcloud SWR ShowInstanceArtifactAddition --instance_id={instance_id} --namespace_name={ns} --repository_name={repo} --reference={digest} --addition=build_history --cli-region=cn-north-4

对于基础版 SWR（非企业版），只能在 SWR Web 控制台 https://console.huawei.com/swr 中使用镜像构建功能。

外部镜像导入

SWR API 不提供直接导入镜像的操作。若要导入外部镜像（例如来自 Docker Hub 的镜像），请使用 docker CLI 的重新标记并推送工作流：

# Step 1: Pull the external image
docker pull docker.io/library/nginx:latest

# Step 2: Get SWR login credentials from this skill
hcloud SWR CreateAuthorizationToken --cli-region=cn-north-4

# Step 3: Tag and push to SWR
docker tag docker.io/library/nginx:latest swr.cn-north-4.myhuaweicloud.com/<namespace>/nginx:latest
docker push swr.cn-north-4.myhuaweicloud.com/<namespace>/nginx:latest

限制：

• 此工作流要求本地已安装并运行 docker CLI（例如 Docker Desktop 或 dockerd）
• 拉取和推送大型镜像可能需要较长时间，具体取决于网络带宽
• 本地机器必须有足够的磁盘空间来临时存储拉取的镜像

写操作返回值

有关写操作的返回值和写入后的验证步骤，请参阅验证方法。

分页参数范围

有关分页参数范围的详情，请参阅SWR API 指南。

注意事项

• 删除命名空间不可撤销 — 会删除其下所有仓库和镜像
• 删除仓库不可撤销 — 会永久删除所有镜像标签
• 删除标签不可撤销 — 无法恢复该镜像版本
• 绝不能对 AK/SK 进行硬编码 — 只能通过环境变量获取凭据
• 仅支持 hcloud CLI — 所有操作均使用 hcloud SWR <Operation> 格式
• 大型数据集需要分页 — 列出仓库和标签时，请使用 --limit 和 --offset

常见问题

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

快速参考：

问题	症状	快速解决方案
命名空间名称无效	400 Bad Request	遵循命名规则：小写，1-64 个字符
找不到命名空间	404 Not Found	使用 ShowNamespace 验证命名空间是否存在
仓库已存在	409 Conflict	先使用 ShowRepository 检查
标签摘要不匹配	重新标记失败	使用 ShowRepoTag 验证 source_tag 是否存在
超出配额	403 Quota limit	使用 ListQuotas 检查配额
身份验证令牌已过期	Docker 登录失败	使用 CreateAuthorizationToken 重新生成
Tag 字段名称	标签查询返回意外结构	使用 Tag（大写 T），而不是 name
num_images 而非 tag_count	仓库列表字段不匹配	响应使用 num_images；--order_column 使用 tag_count