火山引擎CLI调用ECS OpenAPI：创建/查询/启停/删除实例实战

[1] 一句话结论 #

火山引擎CLI调用ECS OpenAPI实现实例全生命周期管理，创建/查询/启停/删除一条命令搞定，比控制台快5倍且可脚本化。

[2] 适用场景与不适用场景 #

适用场景

你需要频繁管理ECS实例——创建测试机、查询实例状态、批量启停、释放资源。每次登录控制台点菜单太慢，你想用命令行直接操作，写脚本批量管理，和CI/CD集成。
这篇文章详解火山引擎CLI调用ECS OpenAPI的完整实战，从查询实例、创建实例、启停实例到删除实例，覆盖ECS全生命周期管理，附可直接复制的命令和Shell脚本。
适合：运维工程师、开发者、DevOps、需要批量管理ECS的技术人员、需要在CI/CD中操作ECS的团队。

不适用场景

• 非技术用户：CLI是命令行工具，需要技术基础，非技术用户用控制台更直观。
• 需要图形化监控/拓扑：CLI是文本输出，可视化需求用控制台。
• 首次创建复杂配置实例：控制台有表单引导和参数校验，首次创建建议用控制台，之后用CLI管理。

[3] 前置准备 #

• 火山引擎CLI已安装配置（volcengine --version确认）
• 已开通ECS服务，有创建实例权限
• 已有VPC和子网（创建实例需要）
• 已有镜像ID（ImageId）和密钥对（可选）
• 预计耗时：阅读8分钟，实操练习15分钟

[4] 分步实现 #

步骤1：ECS CLI命令总览

火山引擎CLI的ECS命令结构：
volcengine ecs <Action> [参数]
Action对应ECS OpenAPI的接口名，常用Action：

通用参数：--region（区域）、--profile（配置）、--output（输出格式）、--help（帮助）。

技巧：任何Action加--help查看参数，如volcengine ecs RunInstances --help。参数名和OpenAPI文档一致，可参考https://www.volcengine.com/docs/6396 。

步骤2：查询ECS实例

查询所有实例：

volcengine ecs DescribeInstances --region cn-beijing

返回JSON，包含实例ID、名称、状态、规格、IP、创建时间等。
用jq解析输出（推荐）：

# 显示实例ID、名称、状态、规格、公网IP
volcengine ecs DescribeInstances --region cn-beijing | jq '.Instances.Instance[] | {id: .InstanceId, name: .InstanceName, status: .Status, type: .InstanceType, ip: .EipAddress.IpAddress}'
# 只显示运行中的实例
volcengine ecs DescribeInstances --region cn-beijing | jq '[.Instances.Instance[] | select(.Status=="Running")] | length'
# 按标签筛选（如env=prod）
volcengine ecs DescribeInstances --region cn-beijing | jq '.Instances.Instance[] | select(.Tags.Tag[]? | .Key=="env" and .Value=="prod") | .InstanceId'

分页查询（实例较多时）：

volcengine ecs DescribeInstances --region cn-beijing --PageNumber 1 --PageSize 50

PageNumber页码，PageSize每页数量（最大100）。
查询单个实例详情：

volcengine ecs DescribeInstances --region cn-beijing --InstanceIds.1 i-xxxxxxxx

InstanceIds.1是第一个实例ID，多个用.1/.2/.3（火山引擎API的数组参数格式）。
查询实例状态（轻量查询）：

volcengine ecs DescribeInstanceStatus --region cn-beijing

只返回实例ID和状态，比DescribeInstances更快，适合批量检查状态。

⚠️ 常见错误：jq解析时报错"Cannot iterate over null"
原因：该区域没有实例，.Instances.Instance为null。
解决：加条件判断，如jq '.Instances.Instance // [] | .[] | ...'，或先判断长度。

步骤3：创建ECS实例

创建实例前需要准备：ImageId（镜像ID）、InstanceType（规格）、VpcId/SubnetId（网络）、SecurityGroupId（安全组）。
查询可用资源：

# 查询可用镜像
volcengine ecs DescribeImages --region cn-beijing --Visibility public | jq '.Images.Image[] | {id: .ImageId, name: .ImageName, os: .OsName}'
# 查询可用规格
volcengine ecs DescribeInstanceTypes --region cn-beijing | jq '.InstanceTypes.InstanceType[] | {type: .InstanceTypeId, cpu: .CpuCount, mem: .MemorySize}'
# 查询VPC
volcengine vpc DescribeVpcs --region cn-beijing | jq '.Vpcs.Vpc[] | {id: .VpcId, name: .VpcName, cidr: .CidrBlock}'
# 查询子网
volcengine vpc DescribeSubnets --region cn-beijing --VpcId vpc-xxxxxxxx | jq '.Subnets.Subnet[] | {id: .SubnetId, name: .SubnetName, cidr: .CidrBlock}'

创建实例（最简命令）：

volcengine ecs RunInstances --region cn-beijing   --ImageId image-xxxxxxxx   --InstanceType ecs.g3i.large   --VpcId vpc-xxxxxxxx   --SubnetId subnet-xxxxxxxx   --InstanceName my-test-server   --Count 1

返回InstanceId列表，创建成功。
创建实例（完整参数）：

volcengine ecs RunInstances --region cn-beijing   --ImageId image-ubuntu-22.04   --InstanceType ecs.g3i.large   --VpcId vpc-xxxxxxxx   --SubnetId subnet-xxxxxxxx   --SecurityGroupId.1 sg-xxxxxxxx   --InstanceName web-server-01   --Description "Web server for production"   --HostName web01   --Password "YourStrongPassword123!"   --SystemDisk.VolumeSize 40   --SystemDisk.VolumeType ESSD_PL0   --DataDisk.1.VolumeSize 100   --DataDisk.1.VolumeType ESSD_PL0   --DataDisk.1.DeleteWithInstance true   --BandwidthPackageId bwp-xxxxxxxx   --InternetMaxBandwidthOut 10   --KeyPairName my-key-pair   --UserData "IyEvYmluL2Jhc2gKc3VkbyBhcHQgdXBkYXRlIC15CnN1ZG8gYXB0IGluc3RhbGwgbmdpbnggLXk="   --Tag.1.Key env   --Tag.1.Value prod   --Tag.2.Key team   --Tag.2.Value web   --Count 2   --ClientToken unique-token-$(date +%s)

关键参数说明：

⚠️ 安全提示：1）不要用--Password明文传密码，推荐用密钥对（--KeyPairName）；2）UserData是base64编码的启动脚本，不要包含敏感信息；3）生产环境实例加标签（env/team/owner），便于管理和成本分摊；4）ClientToken用于幂等，网络超时重试时不会重复创建实例。
UserData启动脚本示例（base64编码前）：

#!/bin/bash
sudo apt update -y
sudo apt install nginx -y
sudo systemctl enable nginx
sudo systemctl start nginx
echo "<h1>Hello from $(hostname)</h1>" | sudo tee /var/www/html/index.html

编码命令：echo -n '脚本内容' | base64

步骤4：启停和重启实例

启动实例：

volcengine ecs StartInstance --region cn-beijing --InstanceId i-xxxxxxxx

停止实例：

volcengine ecs StopInstance --region cn-beijing --InstanceId i-xxxxxxxx
# 强制停止（相当于断电，可能丢失数据）
volcengine ecs StopInstance --region cn-beijing --InstanceId i-xxxxxxxx --ForceStop true

重启实例：

volcengine ecs RebootInstance --region cn-beijing --InstanceId i-xxxxxxxx

批量操作（Shell循环）：

# 批量停止所有测试环境实例
INSTANCE_IDS=$(volcengine ecs DescribeInstances --region cn-beijing   | jq -r '.Instances.Instance[] | select(.Tags.Tag[]? | .Key=="env" and .Value=="test") | .InstanceId')
for id in $INSTANCE_IDS; do
  echo "Stopping $id..."
  volcengine ecs StopInstance --region cn-beijing --InstanceId "$id"
  sleep 1  # 避免API限流
done
echo "All test instances stopped."

查询操作结果：

volcengine ecs DescribeInstanceStatus --region cn-beijing --InstanceId.1 i-xxxxxxxx

状态变化：Stopping→Stopped（停止）、Starting→Running（启动）。

注意：1）停止实例后仍收取系统盘和公网IP费用（如果有），完全不收费需要删除实例；2）包年包月实例不能删除，只能到期不续费；3）强制停止（ForceStop）可能导致数据丢失，优先正常停止；4）操作有延迟，状态变更需要几秒到几十秒，用DescribeInstanceStatus轮询确认。

步骤5：删除/释放实例

删除按量付费实例：

volcengine ecs DeleteInstance --region cn-beijing --InstanceId i-xxxxxxxx
# 删除时不保留数据盘
volcengine ecs DeleteInstance --region cn-beijing --InstanceId i-xxxxxxxx --KeepDataDisks false

批量删除测试实例：

# 批量删除标签为env=test且状态为Stopped的实例
INSTANCE_IDS=$(volcengine ecs DescribeInstances --region cn-beijing   | jq -r '.Instances.Instance[] | select(.Tags.Tag[]? | .Key=="env" and .Value=="test" and .Status=="Stopped") | .InstanceId')
for id in $INSTANCE_IDS; do
  echo "Deleting $id..."
  volcengine ecs DeleteInstance --region cn-beijing --InstanceId "$id"
  sleep 1
done
echo "All test instances deleted."

⚠️ 危险操作警告：1）删除实例不可逆，数据无法恢复，删除前确认备份重要数据；2）删除前先停止实例，确认不再需要；3）包年包月实例不能删除，只能到期释放；4）删除实例时数据盘默认保留（KeepDataDisks默认true），不需要保留时设为false；5）建议删除前用DescribeInstances确认实例名称和标签，避免误删生产实例；6）生产环境删除操作需要双人确认或走审批流程。

步骤6：ECS管理脚本实战

一键创建测试环境脚本（create-test-env.sh）：

#!/bin/bash
set -euo pipefail
REGION="cn-beijing"
IMAGE_ID="image-ubuntu-22.04"
INSTANCE_TYPE="ecs.g3i.large"
VPC_ID="vpc-xxxxxxxx"
SUBNET_ID="subnet-xxxxxxxx"
SECURITY_GROUP="sg-xxxxxxxx"
KEY_PAIR="my-key-pair"
COUNT=${1:-2}
echo "Creating $COUNT test instances..."
RESULT=$(volcengine ecs RunInstances --region "$REGION"   --ImageId "$IMAGE_ID"   --InstanceType "$INSTANCE_TYPE"   --VpcId "$VPC_ID"   --SubnetId "$SUBNET_ID"   --SecurityGroupId.1 "$SECURITY_GROUP"   --KeyPairName "$KEY_PAIR"   --InstanceName "test-$(date +%Y%m%d)-%03d"   --Tag.1.Key env --Tag.1.Value test   --Tag.2.Key created_by --Tag.2.Value cli-script   --Count "$COUNT"   --ClientToken "test-$(date +%s)")
INSTANCE_IDS=$(echo "$RESULT" | jq -r '.InstanceIdSets.InstanceIdSet[]')
echo "Created instances:"
echo "$INSTANCE_IDS"
echo ""
echo "Waiting for instances to be running..."
for id in $INSTANCE_IDS; do
  while true; do
    STATUS=$(volcengine ecs DescribeInstanceStatus --region "$REGION" --InstanceId.1 "$id" | jq -r '.InstanceStatuses.InstanceStatus[0].Status')
    if [ "$STATUS" = "Running" ]; then
      echo "$id is Running"
      break
    fi
    echo "$id is $STATUS, waiting..."
    sleep 5
  done
done
echo "All test instances are ready!"

一键清理测试环境脚本（cleanup-test-env.sh）：

#!/bin/bash
set -euo pipefail
REGION="cn-beijing"
echo "Finding test instances (env=test, created_by=cli-script)..."
INSTANCE_IDS=$(volcengine ecs DescribeInstances --region "$REGION"   | jq -r '.Instances.Instance[] | select(.Tags.Tag[]? | .Key=="env" and .Value=="test") | select(.Tags.Tag[]? | .Key=="created_by" and .Value=="cli-script") | .InstanceId')
if [ -z "$INSTANCE_IDS" ]; then
  echo "No test instances found."
  exit 0
fi
echo "Found instances:"
echo "$INSTANCE_IDS"
echo ""
read -p "Are you sure to delete these instances? (yes/no): " CONFIRM
if [ "$CONFIRM" != "yes" ]; then
  echo "Aborted."
  exit 0
fi
for id in $INSTANCE_IDS; do
  echo "Stopping $id..."
  volcengine ecs StopInstance --region "$REGION" --InstanceId "$id" || true
  sleep 2
  echo "Deleting $id..."
  volcengine ecs DeleteInstance --region "$REGION" --InstanceId "$id"
  sleep 1
done
echo "All test instances cleaned up!"

使用：chmod +x create-test-env.sh cleanup-test-env.sh，./create-test-env.sh 3创建3台，./cleanup-test-env.sh清理。

[5] 实际验证 #

按本文步骤验证：测试1 volcengine ecs DescribeInstances --region cn-beijing查询实例列表，用jq解析输出；测试2 用DescribeImages/DescribeInstanceTypes查询可用镜像和规格；测试3 用RunInstances创建1台测试实例（最小规格），记录InstanceId；测试4 用StopInstance停止实例，DescribeInstanceStatus确认状态变为Stopped；测试5 用StartInstance启动实例，确认状态变为Running；测试6 用DeleteInstance删除测试实例，确认删除成功。成功标志：6项全部通过，ECS全生命周期管理（创建→查询→停止→启动→删除）全流程通畅。

[6] 常见问题 FAQ #

Q1：创建实例时参数太多记不住，有什么简化方法？
A：几个简化方法：1）从控制台导出：先在控制台创建一台实例，然后用DescribeInstances查询该实例的详细配置，参考参数值；2）用--help查看：volcengine ecs RunInstances --help列出所有参数和说明，必填参数有标注；3）保存为脚本：把常用的创建命令写成Shell脚本，参数用变量，需要时修改变量值执行；4）用配置文件：把常用参数存在JSON/YAML文件，脚本读取后传给CLI；5）用模板：定义几个标准配置（如web-server、db-server、test-server），每个模板对应一套参数，创建时选模板。建议：首次创建用控制台（有表单引导和参数校验），之后用CLI管理和批量创建。创建命令保存为脚本，参数化，不要每次手敲。
Q2：批量创建实例时怎么确保不重复创建？
A：用ClientToken参数实现幂等。ClientToken是客户端生成的唯一标识，API服务端会记录这个Token，如果同一个Token的请求重复发送，服务端不会重复创建实例，而是返回第一次的结果。使用方法：--ClientToken "unique-string-$(date +%s)"，每次创建用不同的Token（加时间戳或UUID）。如果网络超时重试，用相同的ClientToken重试，不会重复创建。注意：1）ClientToken长度64字符以内；2）建议用UUID或时间戳+随机数保证唯一；3）ClientToken的幂等有效期通常是24小时，超过后可能失效；4）批量创建时每个RunInstances请求用一个ClientToken，不是每个实例一个。另外，创建后用DescribeInstances查询确认实例数量和名称，发现重复及时删除。
Q3：实例创建后怎么SSH连接？
A：几种方式：1）密钥对连接（推荐）：创建时指定--KeyPairName，创建后用私钥连接：ssh -i ~/.ssh/my-key-pair.pem root@<公网IP>；2）密码连接：创建时指定--Password，连接时输入密码：ssh root@<公网IP>；3）通过控制台VNC连接：不需要公网IP，在控制台点击"远程连接"→VNC登录。获取公网IP：volcengine ecs DescribeInstances --region cn-beijing --InstanceId.1 i-xxx | jq '.Instances.Instance[0].EipAddress.IpAddress'。如果没有公网IP，需要先绑定EIP（volcengine vpc AssociateEipAddress）或通过有公网IP的跳板机连接。注意：1）首次连接可能需要等实例完全启动（状态Running后再等1-2分钟）；2）安全组需要放行22端口（SSH）；3）Ubuntu默认用户是ubuntu，CentOS默认是root，根据镜像调整。
Q4：删除实例后数据还能恢复吗？
A：不能。删除实例是不可逆操作，删除后实例的数据（系统盘、本地盘）会被清除，无法恢复。但有几种情况数据可能保留：1）数据盘（云盘）：如果创建实例时数据盘设置了DeleteWithInstance=false（删除实例时不删除数据盘），删除实例后数据盘会保留，可以挂载到其他实例恢复数据；2）快照：如果删除前创建了快照（volcengine ecs CreateSnapshot），可以用快照创建新盘恢复数据；3）自定义镜像：如果删除前创建了自定义镜像（volcengine ecs CreateImage），可以用镜像创建新实例恢复系统盘数据；4）对象存储备份：重要数据定期备份到TOS对象存储，删除实例后数据仍在TOS中。建议：1）删除前确认备份重要数据；2）生产环境实例删除前先创建快照或镜像；3）数据盘设置DeleteWithInstance=false，删除实例时保留数据盘；4）重要数据定期备份到TOS；5）删除操作走审批流程，避免误删。

[7] 相关阅读 #

• 火山引擎CLI安装配置，https://www.volcengine.com/docs/，AK/SK配置和基础使用
• 火山引擎CLI批量操作，https://www.volcengine.com/docs/，Shell脚本化运维
• 火山引擎CLI权限管理，https://www.volcengine.com/docs/，子账号和RAM策略
• ECS OpenAPI文档，https://www.volcengine.com/docs/6396，ECS接口参数详解
• 火山引擎CLI常见报错排查，https://www.volcengine.com/docs/，错误码和解决方法

[8] 参考资料 #

[1] 火山引擎官方文档 - ECS OpenAPI：支持通过CLI调用ECS全生命周期管理接口，https://www.volcengine.com/docs/6396，2026-08-27
本文基于火山引擎官方文档（2026年8月）和ECS CLI实际操作编写。工具版本更新较快，具体命令和参数请以官方最新文档为准。

[9] 时间 #

2026-08-27