huaweicloud-devkit 1.0.2-dev.8 → 1.0.2-next.0

package/plugins/huaweicloud-core/skills/huawei-ecs/references/create-instance.md

@@ -1,133 +1,133 @@
-# Create ECS Instance SOP
-
-**Before executing any command: If MCP tools are not available** (new session after install), restart your session or use hcloud CLI directly with caution. Commands using adminPass/password WILL appear in shell history — prefer key_name.
-
-## 1. Discover flavors
-hcloud ECS ListFlavors --cli-region=<region> --cli-output=json
-Filter for `os_extra_specs.cond:operation:status == normal` — most results are abandoned. See references/flavors.md.
-
-## 2. Find availability zones
-hcloud ECS NovaListAvailabilityZones --cli-region=<region>
-
-## 3. Find image
-
-```bash
-# Broad search — specific names may return empty in some regions
-hcloud IMS ListImages --cli-region=<region> --__imagetype=gold --__isregistered=true --limit=20
-```
-
-If searching by name (e.g. --name="Ubuntu") returns empty: use broad search without name filter, pick from results. Some regions only offer Huawei Cloud EulerOS (HCE).
-
-Common images (verify live per region):
-| Image | Region | ID |
-|-------|--------|----|
-| HCE 2.0 Standard | cn-north-4 | 7d940784-ac0a-425f-b3fa-8478f1a1df70 |
-| Ubuntu 22.04 | Query live | Query live |
-| CentOS 8.2 | Query live | Query live |
-
-## 4. Verify or create VPC/subnet
-hcloud VPC ListVpcs --cli-region=<region>
-hcloud VPC ListSubnets --vpc_id=<vpc-id> --cli-region=<region>
-If no VPC/subnet exists: load `huawei-vpc` skill → create VPC → create subnet (with DNS) → create security group → return here.
-
-## 5. Create keypair (recommended over adminPass)
-hcloud ECS NovaCreateKeypair --keypair.name=<name>
-Save the returned private key to a local file. The public key is auto-injected.
-
-Password alternative:
-- adminPass: 8-26 chars, must have uppercase + lowercase + digit + special char
-- Passwords appear ONCE in creation output and are not retrievable
-- Passwords are logged in shell history — this is a security risk
-
-## 6. Create instance
-hcloud ECS CreateServers --cli-region=<region> --server.name=<name> --server.flavorRef=<flavor-id> --server.imageRef=<image-id> --server.nics.1.subnet_id=<subnet-id> --server.root_volume.volumetype=<type> --server.root_volume.size=<minsize> --server.vpcid=<vpc-id> --server.availability_zone=<az> --server.key_name=<keypair-name> --server.count=1
-
-### Bootstrap with user_data (cloud-init)
-
-Use `--server.user_data` to run a cloud-init script at first boot. The value must be **base64-encoded**. This is also the recommended bootstrap path when SCP policies block SSH access — user_data serves as the full deployment path, no SSH needed.
-
-```bash
-# Encode the script
-user_data=$(cat << 'SCRIPT' | base64
-#!/bin/bash
-# Your bootstrap commands here.
-# Output logs: /var/log/cloud-init-output.log
-SCRIPT
-)
-
-hcloud ECS CreateServers ... --server.user_data=$user_data
-```
-
-> **Security**: Never embed secrets (passwords, AK/SK, tokens) in user_data. It is stored unencrypted and readable from within the instance via IMDS. Fetch secrets at boot from DEW/CSMS instead.
->
-> **Debugging**: If the script didn't run, check `/var/log/cloud-init-output.log` on the instance.
->
-> **Recovery after failure**: user_data only executes on **first boot**. Restarting the instance will NOT re-run user_data scripts. If cloud-init fails (e.g., DNS missing → `yum`/`apt` cannot resolve repos):
-> 1. Fix the root cause (e.g., update subnet DNS via `VPC UpdateSubnet`)
-> 2. Either: SSH into the instance and run the setup commands manually (see `huawei-ecs` → SSH Connection Verification → Running Commands Inside the Instance)
-> 3. Or: Delete the instance and recreate with corrected user_data (fresh boot)
-
-## 7. EIP (two methods)
-
-### Method A: Inline with CreateServers (Recommended)
-Add EIP parameters to the `CreateServers` command in step 6:
-
-```bash
-hcloud ECS CreateServers \
-  --server.publicip.eip.iptype=<type> \
-  --server.publicip.eip.bandwidth.sharetype=<share-type> \
-  --server.publicip.eip.bandwidth.size=<size> \
-  --server.publicip.eip.bandwidth.chargemode=traffic \
-  ...
-```
-
-> **Trap**: Parameter names differ from `EIP CreatePublicip`. Use `iptype` (not `type`), `sharetype` (not `share_type`), and `chargemode` (not `charging_mode`). Always verify with `hcloud ECS CreateServers --help`.
-
-### Method B: Create and bind separately
-hcloud EIP CreatePublicip --publicip.type=<type> --bandwidth.size=<size> --bandwidth.share_type=<share-type> --bandwidth.name=<name>
-
-```bash
-# Get the ECS network port ID
-hcloud ECS ListServersDetails --cli-region=<region> --server_id=<instance-id>
-# → addresses.<vpc-id>[].OS-EXT-IPS:port_id
-
-# Bind EIP via port
-hcloud EIP AssociatePublicips --publicip_id=<eip-id> --publicip.associate_instance_id=<port-id> --publicip.associate_instance_type=PORT
-```
-
-## 8. Verify
-
-ECS creation is asynchronous. Wait times vary widely (20s to 3min). Status transitions: `BUILD` → `ACTIVE` (or `ERROR`). Never use fixed sleep — poll actively:
-
-```bash
-for i in $(seq 1 30); do
-  status=$(hcloud ECS ListServersDetails --cli-region=<region> --server_id=<instance-id> --cli-output=json | jq -r '.servers[0].status')
-  if [ "$status" = "ACTIVE" ]; then break; fi
-  if [ "$status" = "ERROR" ]; then echo "Creation failed"; exit 1; fi
-  sleep 10
-done
-```
-
-- Poll interval: 10 seconds
-- Maximum wait: 5 minutes (30 iterations)
-- After ACTIVE, confirm once more: `hcloud ECS ListServersDetails --cli-region=<region> --server_id=<instance-id>`
-
-### Verify HTTP accessibility (if EIP bound)
-
-```bash
-# Get the EIP address from instance details
-hcloud ECS ListServersDetails --cli-region=<region> --server_id=<instance-id>
-# → addresses.<vpc-id>[].OS-EXT-IPS:addr
-
-curl http://<eip-address>
-# Expected: HTTP 200 (if port 80 open and web server installed)
-
-## 9. Delete instance (with cleanup)
-hcloud ECS DeleteServers --servers.1.id=<instance-id> --delete_publicip=true --delete_volume=true
-Warning: --delete_publicip and --delete_volume default to false. Set to true to avoid orphaned charges.
-
-## Constraints
-- Name: 1-64 chars, letters/digits/hyphens
-- Flavor: must be available in target region — always ListFlavors first
-- Root volume: SSD 40GB min
-- Keypair is safer than adminPass (passwords leak into shell history)
+# Create ECS Instance SOP
+
+**Before executing any command: If MCP tools are not available** (new session after install), restart your session or use hcloud CLI directly with caution. Commands using adminPass/password WILL appear in shell history — prefer key_name.
+
+## 1. Discover flavors
+hcloud ECS ListFlavors --cli-region=<region> --cli-output=json
+Filter for `os_extra_specs.cond:operation:status == normal` — most results are abandoned. See references/flavors.md.
+
+## 2. Find availability zones
+hcloud ECS NovaListAvailabilityZones --cli-region=<region>
+
+## 3. Find image
+
+```bash
+# Broad search — specific names may return empty in some regions
+hcloud IMS ListImages --cli-region=<region> --__imagetype=gold --__isregistered=true --limit=20
+```
+
+If searching by name (e.g. --name="Ubuntu") returns empty: use broad search without name filter, pick from results. Some regions only offer Huawei Cloud EulerOS (HCE).
+
+Common images (verify live per region):
+| Image | Region | ID |
+|-------|--------|----|
+| HCE 2.0 Standard | cn-north-4 | 7d940784-ac0a-425f-b3fa-8478f1a1df70 |
+| Ubuntu 22.04 | Query live | Query live |
+| CentOS 8.2 | Query live | Query live |
+
+## 4. Verify or create VPC/subnet
+hcloud VPC ListVpcs --cli-region=<region>
+hcloud VPC ListSubnets --vpc_id=<vpc-id> --cli-region=<region>
+If no VPC/subnet exists: load `huawei-vpc` skill → create VPC → create subnet (with DNS) → create security group → return here.
+
+## 5. Create keypair (recommended over adminPass)
+hcloud ECS NovaCreateKeypair --keypair.name=<name>
+Save the returned private key to a local file. The public key is auto-injected.
+
+Password alternative:
+- adminPass: 8-26 chars, must have uppercase + lowercase + digit + special char
+- Passwords appear ONCE in creation output and are not retrievable
+- Passwords are logged in shell history — this is a security risk
+
+## 6. Create instance
+hcloud ECS CreateServers --cli-region=<region> --server.name=<name> --server.flavorRef=<flavor-id> --server.imageRef=<image-id> --server.nics.1.subnet_id=<subnet-id> --server.root_volume.volumetype=<type> --server.root_volume.size=<minsize> --server.vpcid=<vpc-id> --server.availability_zone=<az> --server.key_name=<keypair-name> --server.count=1
+
+### Bootstrap with user_data (cloud-init)
+
+Use `--server.user_data` to run a cloud-init script at first boot. The value must be **base64-encoded**. This is also the recommended bootstrap path when SCP policies block SSH access — user_data serves as the full deployment path, no SSH needed.
+
+```bash
+# Encode the script
+user_data=$(cat << 'SCRIPT' | base64
+#!/bin/bash
+# Your bootstrap commands here.
+# Output logs: /var/log/cloud-init-output.log
+SCRIPT
+)
+
+hcloud ECS CreateServers ... --server.user_data=$user_data
+```
+
+> **Security**: Never embed secrets (passwords, AK/SK, tokens) in user_data. It is stored unencrypted and readable from within the instance via IMDS. Fetch secrets at boot from DEW/CSMS instead.
+>
+> **Debugging**: If the script didn't run, check `/var/log/cloud-init-output.log` on the instance.
+>
+> **Recovery after failure**: user_data only executes on **first boot**. Restarting the instance will NOT re-run user_data scripts. If cloud-init fails (e.g., DNS missing → `yum`/`apt` cannot resolve repos):
+> 1. Fix the root cause (e.g., update subnet DNS via `VPC UpdateSubnet`)
+> 2. Either: SSH into the instance and run the setup commands manually (see `huawei-ecs` → SSH Connection Verification → Running Commands Inside the Instance)
+> 3. Or: Delete the instance and recreate with corrected user_data (fresh boot)
+
+## 7. EIP (two methods)
+
+### Method A: Inline with CreateServers (Recommended)
+Add EIP parameters to the `CreateServers` command in step 6:
+
+```bash
+hcloud ECS CreateServers \
+  --server.publicip.eip.iptype=<type> \
+  --server.publicip.eip.bandwidth.sharetype=<share-type> \
+  --server.publicip.eip.bandwidth.size=<size> \
+  --server.publicip.eip.bandwidth.chargemode=traffic \
+  ...
+```
+
+> **Trap**: Parameter names differ from `EIP CreatePublicip`. Use `iptype` (not `type`), `sharetype` (not `share_type`), and `chargemode` (not `charging_mode`). Always verify with `hcloud ECS CreateServers --help`.
+
+### Method B: Create and bind separately
+hcloud EIP CreatePublicip --publicip.type=<type> --bandwidth.size=<size> --bandwidth.share_type=<share-type> --bandwidth.name=<name>
+
+```bash
+# Get the ECS network port ID
+hcloud ECS ListServersDetails --cli-region=<region> --server_id=<instance-id>
+# → addresses.<vpc-id>[].OS-EXT-IPS:port_id
+
+# Bind EIP via port
+hcloud EIP AssociatePublicips --publicip_id=<eip-id> --publicip.associate_instance_id=<port-id> --publicip.associate_instance_type=PORT
+```
+
+## 8. Verify
+
+ECS creation is asynchronous. Wait times vary widely (20s to 3min). Status transitions: `BUILD` → `ACTIVE` (or `ERROR`). Never use fixed sleep — poll actively:
+
+```bash
+for i in $(seq 1 30); do
+  status=$(hcloud ECS ListServersDetails --cli-region=<region> --server_id=<instance-id> --cli-output=json | jq -r '.servers[0].status')
+  if [ "$status" = "ACTIVE" ]; then break; fi
+  if [ "$status" = "ERROR" ]; then echo "Creation failed"; exit 1; fi
+  sleep 10
+done
+```
+
+- Poll interval: 10 seconds
+- Maximum wait: 5 minutes (30 iterations)
+- After ACTIVE, confirm once more: `hcloud ECS ListServersDetails --cli-region=<region> --server_id=<instance-id>`
+
+### Verify HTTP accessibility (if EIP bound)
+
+```bash
+# Get the EIP address from instance details
+hcloud ECS ListServersDetails --cli-region=<region> --server_id=<instance-id>
+# → addresses.<vpc-id>[].OS-EXT-IPS:addr
+
+curl http://<eip-address>
+# Expected: HTTP 200 (if port 80 open and web server installed)
+
+## 9. Delete instance (with cleanup)
+hcloud ECS DeleteServers --servers.1.id=<instance-id> --delete_publicip=true --delete_volume=true
+Warning: --delete_publicip and --delete_volume default to false. Set to true to avoid orphaned charges.
+
+## Constraints
+- Name: 1-64 chars, letters/digits/hyphens
+- Flavor: must be available in target region — always ListFlavors first
+- Root volume: SSD 40GB min
+- Keypair is safer than adminPass (passwords leak into shell history)

package/plugins/huaweicloud-core/skills/huawei-ecs/references/evs.md

@@ -1,31 +1,31 @@
-# EVS Cloud Disk
-
-## Create Volume
-
-```bash
-hcloud EVS CreateVolume --help
-# Required: --volume.availability_zone, --volume.size, --volume.volume_type
-```
-
-```bash
-hcloud EVS CreateVolume \
-  --volume.availability_zone=<az> \
-  --volume.size=<size> \
-  --volume.volume_type=<type> \
-  --volume.name=<name>
-```
-
-## Attach to ECS
-
-```bash
-hcloud EVS AttachVolume --volume_id=<vol-id> --server_id=<ecs-id>
-```
-
-## List / Delete
-
-```bash
-hcloud EVS ListVolumes
-hcloud EVS DeleteVolume --volume_id=<id>
-```
-
-> Deleting an ECS instance does NOT automatically delete attached EVS volumes unless `--delete_volume=true` is set during instance deletion.
+# EVS Cloud Disk
+
+## Create Volume
+
+```bash
+hcloud EVS CreateVolume --help
+# Required: --volume.availability_zone, --volume.size, --volume.volume_type
+```
+
+```bash
+hcloud EVS CreateVolume \
+  --volume.availability_zone=<az> \
+  --volume.size=<size> \
+  --volume.volume_type=<type> \
+  --volume.name=<name>
+```
+
+## Attach to ECS
+
+```bash
+hcloud EVS AttachVolume --volume_id=<vol-id> --server_id=<ecs-id>
+```
+
+## List / Delete
+
+```bash
+hcloud EVS ListVolumes
+hcloud EVS DeleteVolume --volume_id=<id>
+```
+
+> Deleting an ECS instance does NOT automatically delete attached EVS volumes unless `--delete_volume=true` is set during instance deletion.

package/plugins/huaweicloud-core/skills/huawei-ecs/references/flavors.md

@@ -1,55 +1,55 @@
-# ECS Flavor Selection
-
-**Always discover flavors dynamically before recommending a specific flavor name.** Flavor availability varies by region and changes over time.
-
-## Step 1: List available flavors
-
-Use JMESPath to filter in-line — raw output returns hundreds of records and floods context:
-
-```bash
-# Filter by family prefix (e.g. ac7), return name + specs only
-hcloud ECS ListFlavors --cli-region=<region> --cli-output=json \
-  --cli-query="flavors[?contains(name, 'ac7')].{name:name, vcpus:vcpus, ram:ram}"
-
-# Filter by vCPU range
-hcloud ECS ListFlavors --cli-region=<region> --cli-output=json \
-  --cli-query="flavors[?vcpus >= '2' && vcpus <= '4'].{name:name, vcpus:vcpus, ram:ram}"
-```
-
-> Always use `--cli-query` with JMESPath to narrow results. Never run bare `ListFlavors` without filtering.
-
-## Step 2: Filter by scenario
-
-| Scenario | Look for | Preference |
-|----------|----------|------------|
-| Web app / microservices | General-purpose families (ac, s, sn) | 2-4 vCPU, 4-8 GB RAM |
-| Database / big data | Memory-optimized families (m, r) | 4-8 vCPU, 16-64 GB RAM |
-| AI inference / training | GPU families (g, p) | 8+ vCPU, 64+ GB RAM |
-| HPC / high throughput | High-IO families (h, ir, i) | 8+ vCPU, local SSD |
-
-## Step 3: Match spec from ListFlavors output
-
-Common naming pattern: `<family><gen>.<type>x<ratio>`
-- `ac6.2xlarge.2` = ac6 family, 2xlarge (8 vCPU), ratio 2 (vCPU:RAM = 1:2 → 16 GB)
-
-## Do Not Hardcode
-
-Flavor family names are region-dependent. Example discrepancies seen in testing:
-- cn-south-1: ac6/ac7/kc/r-c7e (s6/m6/g6 NOT available)
-- Other regions may have s6/m6/g6 families
-
-Always run ListFlavors and pick from actual results.
-
-## Step 3: Filter out abandoned / sold-out specs
-
-`ListFlavors` returns ALL specs including abandoned ones. Before selecting a spec, check the `os_extra_specs` field in the JSON response:
-
-| Field | Values | Meaning |
-|-------|--------|---------|
-| `os_extra_specs.cond:operation:status` | `normal`, `abandon`, `sellout` | Only `normal` specs can be created. `abandon` = deprecated, `sellout` = out of stock |
-| `os_extra_specs.cond:operation:az` | e.g. `cn-north-4g(normal)` | Spec is available in this AZ. Multiple entries = multiple AZ support |
-
-A flavor can be `normal` globally but `abandon` in specific AZs. Selecting an `abandon` or `sellout` spec will fail with **`Ecs.0019`** at creation time — there is no pre-flight validation in `ListFlavors`. If creation fails:
-
-1. Switch to a different AZ: `hcloud ECS NovaListAvailabilityZones --cli-region=<region>`
-2. Or switch to a different flavor family (e.g., `at7` → `ac7`)
+# ECS Flavor Selection
+
+**Always discover flavors dynamically before recommending a specific flavor name.** Flavor availability varies by region and changes over time.
+
+## Step 1: List available flavors
+
+Use JMESPath to filter in-line — raw output returns hundreds of records and floods context:
+
+```bash
+# Filter by family prefix (e.g. ac7), return name + specs only
+hcloud ECS ListFlavors --cli-region=<region> --cli-output=json \
+  --cli-query="flavors[?contains(name, 'ac7')].{name:name, vcpus:vcpus, ram:ram}"
+
+# Filter by vCPU range
+hcloud ECS ListFlavors --cli-region=<region> --cli-output=json \
+  --cli-query="flavors[?vcpus >= '2' && vcpus <= '4'].{name:name, vcpus:vcpus, ram:ram}"
+```
+
+> Always use `--cli-query` with JMESPath to narrow results. Never run bare `ListFlavors` without filtering.
+
+## Step 2: Filter by scenario
+
+| Scenario | Look for | Preference |
+|----------|----------|------------|
+| Web app / microservices | General-purpose families (ac, s, sn) | 2-4 vCPU, 4-8 GB RAM |
+| Database / big data | Memory-optimized families (m, r) | 4-8 vCPU, 16-64 GB RAM |
+| AI inference / training | GPU families (g, p) | 8+ vCPU, 64+ GB RAM |
+| HPC / high throughput | High-IO families (h, ir, i) | 8+ vCPU, local SSD |
+
+## Step 3: Match spec from ListFlavors output
+
+Common naming pattern: `<family><gen>.<type>x<ratio>`
+- `ac6.2xlarge.2` = ac6 family, 2xlarge (8 vCPU), ratio 2 (vCPU:RAM = 1:2 → 16 GB)
+
+## Do Not Hardcode
+
+Flavor family names are region-dependent. Example discrepancies seen in testing:
+- cn-south-1: ac6/ac7/kc/r-c7e (s6/m6/g6 NOT available)
+- Other regions may have s6/m6/g6 families
+
+Always run ListFlavors and pick from actual results.
+
+## Step 3: Filter out abandoned / sold-out specs
+
+`ListFlavors` returns ALL specs including abandoned ones. Before selecting a spec, check the `os_extra_specs` field in the JSON response:
+
+| Field | Values | Meaning |
+|-------|--------|---------|
+| `os_extra_specs.cond:operation:status` | `normal`, `abandon`, `sellout` | Only `normal` specs can be created. `abandon` = deprecated, `sellout` = out of stock |
+| `os_extra_specs.cond:operation:az` | e.g. `cn-north-4g(normal)` | Spec is available in this AZ. Multiple entries = multiple AZ support |
+
+A flavor can be `normal` globally but `abandon` in specific AZs. Selecting an `abandon` or `sellout` spec will fail with **`Ecs.0019`** at creation time — there is no pre-flight validation in `ListFlavors`. If creation fails:
+
+1. Switch to a different AZ: `hcloud ECS NovaListAvailabilityZones --cli-region=<region>`
+2. Or switch to a different flavor family (e.g., `at7` → `ac7`)

package/plugins/huaweicloud-core/skills/huawei-ecs/references/troubleshooting.md

@@ -1,52 +1,52 @@
-# ECS Troubleshooting
-
-基于真实测试暴露的常见错误和诊断步骤。
-
-## 错误码映射
-
-| 错误 | 根因 | 修复 |
-|------|------|------|
-| `Ecs.0005` flavor-image 不匹配 | 镜像虚拟化类型与规格不兼容 | 检查 image `__support_amd`/`__support_xen` 与 flavor `os_extra_specs`。BareMetal 镜像不兼容标准 ECS 规格 |
-| `[USE_ERROR]不正确的参数:imagetype` | 参数名错误 | KooCLI 使用双下划线前缀：`--__imagetype=gold`（不是 `--imagetype`） |
-| `[USE_ERROR]不正确的参数:chargingMode` | 参数路径错误 | 计费模式参数路径：`--server.extendparam.chargingMode=postPaid`。不传默认按需付费 |
-| `[USE_ERROR]不正确的参数:__support_amd` | 参数无效 | `IMS ListImages` 某些版本不支持此过滤。去掉该参数，使用 client-side 过滤 |
-| Cannot SSH | 安全组未开放22端口 或 未绑定EIP | 1) 添加入方向规则 tcp 22。2) `hcloud EIP BindPublicIp` |
-| Flavor unavailable | 区域不支持该规格 | `hcloud ECS ListFlavors --cli-region=<r>` 先查。不硬编码 s6/m6 等规格名 |
-| Insufficient resources | AZ 库存不足 | 换规格、换 AZ、或等待资源释放 |
-| AuthFailure | AK/SK 过期或无效 | `hcloud configure init` 重新配置 |
-
-## 创建失败诊断流程
-
-1. 运行 `hcloud ECS ListFlavors` — 确认规格在目标区域可用
-2. 运行 `hcloud IMS ListImages --__imagetype=gold --limit=20` — 确认可用的公共镜像
-3. 交叉检查：flavor `os_extra_specs` 中的虚拟化类型 vs image 的 `__support_*` 属性
-4. 运行 `hcloud VPC ListVpcs` / `ListSubnets` — 确认 VPC 和子网存在
-5. 运行 `hcloud ECS NovaListAvailabilityZones` — 确认 AZ 可用
-6. 创建后：`hcloud ECS ListServersDetails --server_id=<id>` 检查状态
-7. 状态 `BUILD` → 等待。`ERROR` → 查看 job_id 详情
-
-## 镜像查询正确姿势
-
-```bash
-# 正确：双下划线前缀
-hcloud IMS ListImages --cli-region=<r> --__imagetype=gold --__isregistered=true --limit=20
-
-# 按需过滤（如果参数支持）
-# --virtual_env_type=FusionCompute  排除 BareMetal
-# 不支持的参数不要传，用 client-side 过滤
-```
-
-## 密钥对 vs 密码
-
-| 方式 | 安全 | 建议 |
-|------|------|------|
-| `--server.key_name=<name>` | ✅ 高 | **推荐**。先 `hcloud DEW CreateKeypair` 创建密钥对 |
-| `--server.adminPass=<pw>` | ❌ 低 | 密码明文进入 shell 历史。仅测试用 |
-
-密码要求：8-26 字符，含大写 + 小写 + 数字 + 特殊字符。
-
-## 删除注意事项
-
-- `--delete_publicip` 默认 false — EIP 不随实例删除，继续计费
-- `--delete_volume` 默认 false — 系统盘不随实例删除
-- 数据盘默认随实例删除（与系统盘行为相反）
+# ECS Troubleshooting
+
+基于真实测试暴露的常见错误和诊断步骤。
+
+## 错误码映射
+
+| 错误 | 根因 | 修复 |
+|------|------|------|
+| `Ecs.0005` flavor-image 不匹配 | 镜像虚拟化类型与规格不兼容 | 检查 image `__support_amd`/`__support_xen` 与 flavor `os_extra_specs`。BareMetal 镜像不兼容标准 ECS 规格 |
+| `[USE_ERROR]不正确的参数:imagetype` | 参数名错误 | KooCLI 使用双下划线前缀：`--__imagetype=gold`（不是 `--imagetype`） |
+| `[USE_ERROR]不正确的参数:chargingMode` | 参数路径错误 | 计费模式参数路径：`--server.extendparam.chargingMode=postPaid`。不传默认按需付费 |
+| `[USE_ERROR]不正确的参数:__support_amd` | 参数无效 | `IMS ListImages` 某些版本不支持此过滤。去掉该参数，使用 client-side 过滤 |
+| Cannot SSH | 安全组未开放22端口 或 未绑定EIP | 1) 添加入方向规则 tcp 22。2) `hcloud EIP BindPublicIp` |
+| Flavor unavailable | 区域不支持该规格 | `hcloud ECS ListFlavors --cli-region=<r>` 先查。不硬编码 s6/m6 等规格名 |
+| Insufficient resources | AZ 库存不足 | 换规格、换 AZ、或等待资源释放 |
+| AuthFailure | AK/SK 过期或无效 | `npx huaweicloud-devkit auth init` 重新配置统一凭据 |
+
+## 创建失败诊断流程
+
+1. 运行 `hcloud ECS ListFlavors` — 确认规格在目标区域可用
+2. 运行 `hcloud IMS ListImages --__imagetype=gold --limit=20` — 确认可用的公共镜像
+3. 交叉检查：flavor `os_extra_specs` 中的虚拟化类型 vs image 的 `__support_*` 属性
+4. 运行 `hcloud VPC ListVpcs` / `ListSubnets` — 确认 VPC 和子网存在
+5. 运行 `hcloud ECS NovaListAvailabilityZones` — 确认 AZ 可用
+6. 创建后：`hcloud ECS ListServersDetails --server_id=<id>` 检查状态
+7. 状态 `BUILD` → 等待。`ERROR` → 查看 job_id 详情
+
+## 镜像查询正确姿势
+
+```bash
+# 正确：双下划线前缀
+hcloud IMS ListImages --cli-region=<r> --__imagetype=gold --__isregistered=true --limit=20
+
+# 按需过滤（如果参数支持）
+# --virtual_env_type=FusionCompute  排除 BareMetal
+# 不支持的参数不要传，用 client-side 过滤
+```
+
+## 密钥对 vs 密码
+
+| 方式 | 安全 | 建议 |
+|------|------|------|
+| `--server.key_name=<name>` | ✅ 高 | **推荐**。先 `hcloud DEW CreateKeypair` 创建密钥对 |
+| `--server.adminPass=<pw>` | ❌ 低 | 密码明文进入 shell 历史。仅测试用 |
+
+密码要求：8-26 字符，含大写 + 小写 + 数字 + 特殊字符。
+
+## 删除注意事项
+
+- `--delete_publicip` 默认 false — EIP 不随实例删除，继续计费
+- `--delete_volume` 默认 false — 系统盘不随实例删除
+- 数据盘默认随实例删除（与系统盘行为相反）