huawei-cloud-swr-enterprise-instance

华为云 SWR 企业版实例管理

概述

此技能通过 hcloud CLI 提供华为云 SWR（Software Repository for Container）企业版实例的生命周期管理能力。企业版实例提供专用、隔离的容器镜像仓库环境，并具备安全扫描、复制策略和自定义域名支持等高级功能。

注意：某些功能（例如复制策略）通过 SWR 企业版实例控制台管理，而非通过 CLI 管理。请参阅上文的范围之外。

架构：hcloud CLI → SWR Service API → 实例/命名空间/镜像仓库/仓库/制品/凭据/终端节点/域名资源

相关技能：

• huawei-cloud-swr-image-management - 镜像生命周期管理（基本 SWR 命名空间、仓库、标签、身份验证、配额）
• huawei-cloud-swr-image-governance - 镜像治理（权限、保留、共享、标签、不可变规则）
• huawei-cloud-swr-image-automation - 镜像自动化运维（同步、触发器、域名）

范围之外：

此技能不支持以下操作。如果用户请求执行其中任何操作，请告知他们并建议使用正确的技能：

操作	请改用	原因
管理基本（非企业版）SWR 命名空间	huawei-cloud-swr-image-management	基本 SWR 命名空间生命周期管理
推送/拉取镜像（docker login/push/pull）	Docker CLI（先使用此技能获取凭据）	Docker CLI 操作，而非 API 操作
构建镜像	CodeArts Build、CCE 或本地 Docker	SWR 是镜像仓库，而非构建服务
管理命名空间/仓库权限	huawei-cloud-swr-image-governance	权限治理属于独立技能
在基本 SWR 上创建保留/老化策略	huawei-cloud-swr-image-governance	基本 SWR 的保留治理
在基本 SWR 上创建镜像同步规则	huawei-cloud-swr-image-automation	基本 SWR 的同步自动化
在基本 SWR 上创建/删除触发器	huawei-cloud-swr-image-automation	基本 SWR 的触发器自动化
管理基本 SWR 的委托授权	huawei-cloud-swr-image-governance	基本 SWR 的委托授权

• 创建和管理 SWR 企业版实例
• 管理启用安全扫描和漏洞阻断的实例命名空间
• 配置用于跨实例镜像同步的实例镜像仓库
• 查询和管理实例仓库及制品
• 获取实例访问凭据（长期和临时）
• 配置实例网络访问（内部 VPC 终端节点、带白名单的公网访问）
• 管理实例访问的自定义域名
• 监控实例统计信息和任务状态

典型用例：

• “为我的组织创建一个 SWR 企业版实例”
• “创建一个启用自动扫描和漏洞阻断的命名空间”
• “配置一个用于将镜像同步到另一个实例的镜像仓库”
• “获取我的实例的 docker login 凭据”
• “为我的实例添加 VPC 内部终端节点或自定义域名”

前提条件

1. hcloud CLI 要求（必需）

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

2. 凭据配置

hcloud CLI 支持两种凭据模式。完整详情请参阅 references/credential-configuration.md。

快速设置（任选一种）：

# Mode A — Long-term AK/SK
export HUAWEI_CLOUD_AK=<your-ak>
export HUAWEI_CLOUD_SK=<your-sk>
export HUAWEI_CLOUD_REGION=cn-north-4

# Mode B — Temporary 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

• 安全规则：切勿泄露 AK/SK/SecurityToken 值。使用 hcloud configure list 仅检查是否已配置。

3. 激活 SWR 企业服务（必需）

创建 SWR 企业实例前，用户必须先在华为云控制台激活 SWR 企业服务。每个账号/区域只需启用一次。

激活步骤：

1. 通过直接 URL 访问 SWR 企业实例控制台：https://console.huaweicloud.com/swr-instance
   • 重要：SWR 企业实例控制台无法通过主控制台导航菜单访问。用户必须使用此直接 URL 访问。
2. 如果系统提示，请阅读并接受 SWR 企业服务条款
3. 确认服务已激活，方法是验证控制台是否成功加载
4. 如果目标区域无法激活，控制台会显示错误，或者不会列出该服务

验证：激活后，运行 hcloud SWR ListInstance --cli-region=<region>——如果服务已激活，将返回空列表（或现有实例）。如果未激活，则会返回错误。

控制台访问：

• SWR 企业实例控制台：https://console.huaweicloud.com/swr-instance
• 此 URL 可用于访问实例管理、命名空间配置、仓库浏览和复制策略设置
• 控制台会识别区域——打开 URL 后，请在右上角选择目标区域

4. IAM 权限要求

此技能需要 SWR 企业实例权限（实例、命名空间、注册表、仓库、制品、凭据、端点、域名、作业、统计操作）。完整权限表和策略 JSON，请参阅 IAM 权限策略。

权限失败处理：

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

核心命令

1. 实例生命周期

详细工作流请参见 任务：实例生命周期。

# Create an enterprise instance
# ⚠️ hcloud CLI CreateInstance has a known bug (duplicate --project_id parameter).
# Use the Python SDK helper script instead:
python scripts/swr_instance_helper.py create --name=my-instance --spec=swr.ee.professional \
    --vpc_id=<vpc-id> --subnet_id=<subnet-id> --enterprise_project_id=0 --cli-region=cn-north-4

# Alternatively, use --cli-jsonInput (see references/common-pitfalls.md Pitfall 15)
# hcloud SWR CreateInstance --cli-jsonInput=create_instance.json --cli-region=cn-north-4

# List all instances
hcloud SWR ListInstance --cli-region=cn-north-4

# List instances with status filter
hcloud SWR ListInstance --status=Running --cli-region=cn-north-4

# Show instance details
# Show instance details
hcloud SWR ShowInstance --instance_id=<instance-id> --cli-region=cn-north-4

**Note**: `ShowInstance` does not return endpoint information. To view network access endpoints, use:
- `hcloud SWR ListInstanceInternalEndpoints --instance_id=<instance-id> --cli-region=cn-north-4` for internal VPC endpoints
- `hcloud SWR ShowInstanceEndpointPolicy --instance_id=<instance-id> --cli-region=cn-north-4` for public access status and whitelist

# View instance configuration
hcloud SWR ShowInstanceConfiguration --instance_id=<instance-id> --cli-region=cn-north-4

# Update instance configuration (anonymous access)
# Update instance configuration (anonymous access)
hcloud SWR UpdateInstanceConfiguration --instance_id=<instance-id> --anonymous_access=false --cli-region=cn-north-4

**Configuration Scope**: `UpdateInstanceConfiguration` only supports the `--anonymous_access` parameter (boolean). This is the sole instance-level configuration option available via API. Other settings (spec, VPC, encryption) are set at creation time and cannot be modified afterward.

# Delete instance (CAUTION: removes all data permanently)
hcloud SWR DeleteInstance --instance_id=<instance-id> --cli-region=cn-north-4

实例命名规则：

• 以小写字母开头
• 后续字符可为小写字母、数字或连字符（-）
• 连字符不能连续出现
• 不能以连字符结尾
• 长度：3–48 个字符

实例规格选项：swr.ee.basic（基础版）、swr.ee.professional（专业版）

规格与区域可用性：

• 并非所有规格（flavor）都在所有区域可用。创建实例前，请确认目标区域支持所需规格。
• 使用 hcloud SWR ListInstance --cli-region=<region> 检查 SWR 企业版服务是否在某个区域可用。如果 API 返回错误，则该区域可能不提供此服务。
• 使用 hcloud SWR ListSyncRegions --cli-region=<region> 列出支持 SWR 服务跨区域同步的区域。
• 支持 SWR 企业版的常见区域包括：cn-north-4、cn-north-1、cn-east-3、cn-south-1、cn-east-2、cn-southwest-2、cn-north-9、ap-southeast-1、ap-southeast-2、ap-southeast-3。
• 如果创建实例时出现规格或区域相关错误，请尝试更换规格或区域。错误消息会说明目标区域是否不支持该规格。

计费详情：

• 警告：创建 SWR 企业版实例会产生按小时计费的费用。 操作前必须告知用户。
• --charge_mode：仅支持 postPaid（按需／按量付费）。不支持预付费或按年／月计费。
• --spec=swr.ee.basic：基础版 — 适合小型团队，功能有限。每小时费用较低。
• --spec=swr.ee.professional：专业版 — 提供完整功能，包括安全扫描、复制和自定义域名。每小时费用较高。
• 费用根据实例规格按小时计收。无需预付款。实例进入 Running 状态后开始计费。
• 停止计费：使用 hcloud SWR DeleteInstance 删除实例。删除后立即停止计费。
• 使用 --enterprise_project_id 将实例关联到企业项目，以便跟踪和归属费用。
• 如需详细定价信息，请参阅华为云 SWR 定价页面，或访问 SWR 企业版实例控制台：https://console.huaweicloud.com/swr-instance。

实例状态值：Initial、Creating、Running、Unavailable

2. 实例命名空间

详细工作流请参见 任务：实例命名空间。

# Create a namespace with auto-scan and vulnerability blocking
hcloud SWR CreateInstanceNamespace --instance_id=<instance-id> --namespace_name=group-dev --metadata.public=false --metadata.auto_scan=true --metadata.prevent_vul=true --metadata.severity=high --cli-region=cn-north-4

# List namespaces
hcloud SWR ListInstanceNamespaces --instance_id=<instance-id> --cli-region=cn-north-4

# List namespaces with filter
hcloud SWR ListInstanceNamespaces --instance_id=<instance-id> --public=false --limit=20 --offset=0 --cli-region=cn-north-4

# Show namespace details
hcloud SWR ShowInstanceNamespace --instance_id=<instance-id> --namespace_name=group-dev --cli-region=cn-north-4

# Update namespace (change visibility, scan settings)
hcloud SWR UpdateInstanceNamespace --instance_id=<instance-id> --namespace_name=group-dev --metadata.public=true --metadata.prevent_vul=false --cli-region=cn-north-4

# Delete namespace (CAUTION: removes all repositories under it)
hcloud SWR DeleteInstanceNamespace --instance_id=<instance-id> --namespace_name=group-dev --cli-region=cn-north-4

命名空间命名规则：

• 以小写字母或数字开头
• 后续字符可为小写字母、数字、点、下划线或连字符
• 点、下划线和连字符不能直接相连
• 以小写字母或数字结尾
• 长度：1–64 个字符

漏洞严重级别：none、low、medium、high、critical

3. 实例镜像仓库（同步目标）

详细工作流请参见 任务：实例镜像仓库。

# Create a registry (sync target for another SWR enterprise instance)
hcloud SWR CreateInstanceRegistry --instance_id=<instance-id> --name=target-instance --type=swr-pro-internal --url=<target-url> --credential.type=basic --credential.access_key=<ak> --credential.access_secret=<sk> --insecure=false --instance_id=<target-instance-id> --project_id=<target-project-id> --region_id=cn-east-3 --cli-region=cn-north-4

# Create a registry for open-source Harbor
hcloud SWR CreateInstanceRegistry --instance_id=<instance-id> --name=harbor-target --type=swr-pro --url=https://harbor.example.com --credential.type=basic --credential.access_key=<username> --credential.access_secret=<password> --insecure=false --cli-region=cn-north-4

# List registries
hcloud SWR ListInstanceRegistries --instance_id=<instance-id> --cli-region=cn-north-4

# Show registry details
hcloud SWR ShowInstanceRegistry --instance_id=<instance-id> --registry_id=<registry-id> --cli-region=cn-north-4

# Update registry
hcloud SWR UpdateInstanceRegistry --instance_id=<instance-id> --registry_id=<registry-id> --name=new-name --url=<new-url> --credential.type=basic --credential.access_key=<new-ak> --credential.access_secret=<new-sk> --insecure=false --type=swr-pro --cli-region=cn-north-4

# Delete registry
hcloud SWR DeleteInstanceRegistry --instance_id=<instance-id> --registry_id=<registry-id> --cli-region=cn-north-4

镜像仓库类型：swr-pro（开源 Harbor）、swr-pro-internal（另一个 SWR 企业版实例）、huawei-SWR（基础 SWR）

获取目标镜像仓库的凭据：

• 对于 swr-pro-internal（另一个 SWR 企业版实例）：在目标实例上使用 CreateInstanceLtCredential 获取 access_key（凭据名称）和 access_secret（凭据密码）。
• 对于 huawei-SWR（基础 SWR）：使用 CreateInstanceTempCredential 或基础 SWR 的 CreateAuthorizationToken 获取临时凭据。
• 对于 swr-pro（Harbor）：使用 Harbor 账户的用户名和密码。
• 凭据由实例安全存储，仅用于复制操作。

4. 实例镜像仓库

仓库部分请参见 任务：实例镜像仓库。

# List repositories in instance
hcloud SWR ListInstanceRepositories --instance_id=<instance-id> --cli-region=cn-north-4

# List repositories with filter
hcloud SWR ListInstanceRepositories --instance_id=<instance-id> --namespace_id=<ns-id> --limit=20 --offset=0 --order_column=updated_at --order_type=desc --cli-region=cn-north-4

# Show repository details
hcloud SWR ShowInstanceRepository --instance_id=<instance-id> --namespace_name=group-dev --repository_name=my-app --cli-region=cn-north-4

# Update repository description
hcloud SWR UpdateInstanceRepository --instance_id=<instance-id> --namespace_name=group-dev --repository_name=my-app --description="Updated description" --cli-region=cn-north-4

# Delete repository (CAUTION: removes all artifacts)
hcloud SWR DeleteInstanceRepository --instance_id=<instance-id> --namespace_name=group-dev --repository_name=my-app --cli-region=cn-north-4

5. 实例制品（镜像版本）

详细工作流程请参阅 任务：实例制品。

# List artifacts in a repository
hcloud SWR ListInstanceArtifacts --instance_id=<instance-id> --namespace_name=group-dev --repository_name=my-app --cli-region=cn-north-4

# List artifacts with filter
hcloud SWR ListInstanceArtifacts --instance_id=<instance-id> --namespace_name=group-dev --repository_name=my-app --type=IMAGE --limit=20 --offset=0 --cli-region=cn-north-4

# Show artifact details
hcloud SWR ShowInstanceArtifact --instance_id=<instance-id> --namespace_name=group-dev --repository_name=my-app --reference=<digest> --cli-region=cn-north-4

# Show artifact with scan overview
hcloud SWR ShowInstanceArtifact --instance_id=<instance-id> --namespace_name=group-dev --repository_name=my-app --reference=<digest> --with_scan_overview=true --cli-region=cn-north-4

# Get artifact build history
hcloud SWR ShowInstanceArtifactAddition --instance_id=<instance-id> --namespace_name=group-dev --repository_name=my-app --reference=<digest> --addition=build_history --cli-region=cn-north-4

# List artifact vulnerabilities
hcloud SWR ListInstanceArtifactVulnerabilities --instance_id=<instance-id> --namespace_name=group-dev --repository_name=my-app --reference=<digest> --cli-region=cn-north-4

# Start manual vulnerability scan
hcloud SWR StartManualScanning --instance_id=<instance-id> --namespace_name=group-dev --repository_name=my-app --reference=<digest> --cli-region=cn-north-4

# Delete artifact (CAUTION: removes the image version permanently)
hcloud SWR DeleteInstanceArtifact --instance_id=<instance-id> --namespace_name=group-dev --repository_name=my-app --reference=<digest> --cli-region=cn-north-4

制品类型：IMAGE（容器镜像）、CHART（Helm chart）

⚠️ 镜像漏洞扫描限制：镜像漏洞扫描依赖 Huawei Cloud HSS（主机安全服务）。当前技能不支持 HSS 配置或管理。如需使用扫描功能：

• 基础版（swr.ee.basic）：不支持扫描。请升级到专业版。
• 专业版（swr.ee.professional）：扫描需要启用 HSS。请先在 Huawei Cloud 控制台中激活 HSS，然后使用 SWR 企业实例控制台（https://console.huaweicloud.com/swr-instance）确认扫描功能正常，再在自动化工作流中使用。
• 如果专业版实例上的扫描失败，请检查 HSS 服务状态，并确保已为目标区域正确激活 HSS。

6. 实例凭证

详细工作流程请参阅 任务：实例凭证。

# Create a long-term access credential
hcloud SWR CreateInstanceLtCredential --instance_id=<instance-id> --name=my-credential --cli-region=cn-north-4

# Create a temporary access credential
hcloud SWR CreateInstanceTempCredential --instance_id=<instance-id> --cli-region=cn-north-4

# List long-term credentials
hcloud SWR ListInstanceLtCredentials --instance_id=<instance-id> --cli-region=cn-north-4

# Enable/disable a long-term credential
hcloud SWR UpdateInstanceLtCredential --instance_id=<instance-id> --credential_id=<cred-id> --enable=false --cli-region=cn-north-4

# Delete a long-term credential
hcloud SWR DeleteInstanceLtCredential --instance_id=<instance-id> --credential_id=<cred-id> --cli-region=cn-north-4

凭证命名规则（与命名空间相同）：以小写字母或数字开头，长度为 1-64 个字符

7. 实例终端节点（网络访问）

详细工作流程请参阅 任务：实例终端节点。

# Create internal VPC endpoint
hcloud SWR CreateInstanceInternalEndpoint --instance_id=<instance-id> --vpc_id=<vpc-id> --subnet_id=<subnet-id> --project_id=<vpc-project-id> --cli-region=cn-north-4

# List internal endpoints
hcloud SWR ListInstanceInternalEndpoints --instance_id=<instance-id> --cli-region=cn-north-4

# Show internal endpoint details
hcloud SWR ShowInstanceInternalEndpoint --instance_id=<instance-id> --internal_endpoints_id=<endpoint-id> --cli-region=cn-north-4

# Delete internal endpoint
hcloud SWR DeleteInstanceInternalEndpoint --instance_id=<instance-id> --internal_endpoints_id=<endpoint-id> --cli-region=cn-north-4

# Enable public access
hcloud SWR CreateInstanceEndpointPolicy --instance_id=<instance-id> --enable=true --cli-region=cn-north-4

# Disable public access
hcloud SWR CreateInstanceEndpointPolicy --instance_id=<instance-id> --enable=false --cli-region=cn-north-4

# View public access status and whitelist
hcloud SWR ShowInstanceEndpointPolicy --instance_id=<instance-id> --cli-region=cn-north-4

# Update public access whitelist (full replacement)
hcloud SWR UpdateInstanceEndpointPolicy --instance_id=<instance-id> --ip_list.1.ip=10.0.0.0/8 --ip_list.1.description="Internal network" --ip_list.2.ip=192.168.0.0/16 --ip_list.2.description="VPN network" --cli-region=cn-north-4

8. 实例域名

详细工作流程请参阅 任务：实例域名。

# Add a custom domain
hcloud SWR AddDomainName --instance_id=<instance-id> --domain_name=registry.example.com --certificate_id=<scm-cert-id> --cli-region=cn-north-4

# List all domains
hcloud SWR ListDomainNames --instance_id=<instance-id> --cli-region=cn-north-4

# Get domain overview
hcloud SWR ShowDomainOverview --cli-region=cn-north-4

# Delete a domain (default domain cannot be deleted)
hcloud SWR DeleteDomainName --instance_id=<instance-id> --domainname_id=<domain-id> --cli-region=cn-north-4

# Update domain certificate
hcloud SWR UpdateDomainName --instance_id=<instance-id> --domainname_id=<domain-id> --certificate_id=<new-cert-id> --cli-region=cn-north-4

9. 实例统计信息和作业

# Get instance statistics
hcloud SWR ListInstanceStatistics --instance_id=<instance-id> --cli-region=cn-north-4

# List instance jobs (async operations)
hcloud SWR ListInstanceJobs --cli-region=cn-north-4

# Show job details
hcloud SWR ShowInstanceJob --job_id=<job-id> --cli-region=cn-north-4

# Delete a job record
hcloud SWR DeleteInstanceJob --job_id=<job-id> --cli-region=cn-north-4

10. 实例审计日志

SWR 企业实例通过 ListAuditLogs API 内置审计日志功能（拉取、删除、创建操作），无需依赖 CTS。

hcloud SWR ListAuditLogs --instance_id=<instance-id> --project_id=<project-id> --operation=pull --cli-region=cn-north-4
# --operation: pull, delete, or create; --limit/--offset for pagination

完整详情请参阅 API 指南。

参数参考

完整的参数表请参阅 参数参考，包括：通用参数、实例创建（名称、规格、VPC、子网、加密）、命名空间（public、auto_scan、prevent_vul、severity）、镜像仓库（type、url、credential）以及终端节点白名单参数。

输出格式

详细的响应格式示例请参阅 输出格式（实例列表、实例详情、命名空间列表、内部终端节点列表、域名列表、长期凭证）。

验证

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

最佳实践

1. 实例命名和 VPC：使用描述性名称（prod-instance、dev-instance）；选择与工作负载环境相匹配的 VPC/子网
2. 命名空间安全：生产环境启用 auto_scan=true 和 prevent_vul=true；生产环境将 severity 设为 high/critical，开发环境设为 none/low
3. 凭证：安全存储镜像仓库凭证并定期轮换；CI/CD 使用 CreateInstanceLtCredential，临时访问使用 CreateInstanceTempCredential
4. 公开访问：通过 UpdateInstanceEndpointPolicy 启用公开访问时，务必配置 IP 白名单；自定义域名 HTTPS 使用 SCM 证书
5. 谨慎删除：删除实例会永久移除所有数据；删除命名空间会移除所有镜像仓库
6. 实例规格：小型团队使用 swr.ee.basic；具备高级功能需求的企业使用 swr.ee.professional

参数确认

操作	CLI 命令	风险级别	是否需要确认
CreateInstance	hcloud SWR CreateInstance	高	创建付费实例会产生费用。继续操作前，请确认实例规格（swr.ee.basic 或 swr.ee.professional）、VPC/子网配置和企业项目。
UpdateInstanceConfiguration	hcloud SWR UpdateInstanceConfiguration --anonymous_access=true	高	启用匿名访问后，未通过身份验证的用户可以拉取镜像，从而降低安全性。继续操作前，请确认这是预期行为。
CreateInstanceEndpointPolicy	hcloud SWR CreateInstanceEndpointPolicy --enable=true	中	启用公网访问会使实例暴露在互联网中。必须通过 UpdateInstanceEndpointPolicy 配置 IP 白名单以限制访问。继续操作前请确认。
DeleteInstanceLtCredential	hcloud SWR DeleteInstanceLtCredential	中	删除凭证会立即撤销使用该凭证的 CI/CD 流水线的访问权限。建议先禁用凭证（UpdateInstanceLtCredential --enable=false），确认没有正在运行的流水线，然后再删除。
CreateInstanceRegistry	hcloud SWR CreateInstanceRegistry	中	创建同步目标仓库会存储目标仓库的身份验证凭证（access_key/access_secret）。继续操作前，请确认目标仓库 URL 和凭证信息。

工作流

此技能遵循 SWR 企业实例管理的标准工作流：

0. ⚠️ 费用确认（强制） — 执行任何操作前，告知用户可能产生的费用，并取得明确同意：
   • 创建实例会产生按小时计费的费用：swr.ee.basic（约 ¥0.35/小时）和 swr.ee.professional（约 ¥1.05/小时）是付费规格。企业实例没有免费套餐。
   • 存储费用：存储在企业实例中的镜像会产生 OBS 存储费用。
   • 网络费用：跨区域同步和公网访问可能产生流量费用。
   • 请用户确认：“您是否了解相关费用，并希望继续？（yes/no）”
   • 仅在用户明确确认后继续。如果用户拒绝，请停止操作，不要执行任何操作。
1. 前置条件检查 — 确认已安装 hcloud CLI 并配置凭证
2. 实例识别 — 列出或查看现有实例以获取 instance_id
3. 执行操作 — 执行所请求的操作（创建/更新/删除/查询）
4. 结果验证 — 通过查询最终状态确认操作成功
5. 凭证管理 — 对于写操作，获取并安全存储返回的任何凭证
6. 清理确认 — 对于破坏性操作，继续前先与用户确认

KooCLI 命令格式标准

所有 CLI 命令都使用 hcloud SWR <Operation> --param1=value1 --cli-region=<region> 格式。

关键规则：使用 --key=value 格式，始终指定 --cli-region，绝不泄露 AK/SK，执行写操作前先确认，使用 --cli-output=json 获取结构化输出。

已知 CLI 限制：CreateInstance 存在一个已知的 hcloud CLI 错误（--project_id 参数重复）。请优先使用 Python SDK 辅助脚本（scripts/swr_instance_helper.py），或使用包含 path/body 部分的 --cli-jsonInput 作为替代方案。其他存在同名参数冲突的命令（CreateInstanceInternalEndpoint、CreateInstanceRegistry）可以使用 --cli-jsonInput。完整详情请参阅 常见问题（问题 15）和 CLI 格式指南。

参考文档

• 命令参考 — 完整的 hcloud SWR 命令参考及示例
• 参数参考 — 所有 API 参数及其类型和说明
• SWR 实例 API 指南 — hcloud SWR 实例 API 参考
• 输出格式 — 响应格式示例
• 凭证配置 — 凭证设置（长期和临时 AK/SK）
• IAM 权限策略 — 所需权限和策略 JSON
• 验证方法 — 分步验证
• 常见问题 — 故障排除指南
• 任务：实例生命周期 — 实例创建、列表、查看和配置更新
• 任务：实例命名空间 — 命名空间 CRUD 工作流
• 任务：实例镜像仓库 — 镜像仓库 CRUD 和仓库管理
• 任务：实例制品 — 制品管理和扫描
• 任务：实例凭证 — 凭证管理工作流
• 任务：实例端点 — 内部和公共访问配置
• 任务：实例域名 — 自定义域名管理
• CLI 安装指南 — hcloud CLI 安装和配置
• 验收标准 — 所有操作的成功标准

注意事项

• 删除实例/命名空间/制品不可撤销 — 所有数据将被永久删除
• 默认域名无法删除 — 只能移除自定义域名
• 绝不可将 AK/SK 硬编码 — 只能使用环境变量
• 分页 offset 必须是 limit 的倍数 — offset 必须为 0 或 limit 的倍数
• 镜像仓库 credential.access_secret 属于敏感信息 — 切勿泄露或记录访问密钥

常见问题

有关详细的故障排除指南，请参阅常见问题与解决方案，内容涵盖：无效的实例名称、VPC/子网错误、实例创建状态、分页 offset 规则、镜像仓库凭证问题、域名证书问题、公共访问白名单格式、SWR 服务激活和规格可用性。