基于 CNB 云原生构建平台的腾讯云 CVM 管理插件。通过页面按钮一键创建/管理云服务器，支持定时自动销毁。

动作	说明
创建 CVM	自动匹配机型和可用区，支持竞价实例，定时自动销毁，支持开机初始化脚本
列出实例	按标签/状态过滤，导出变量供后续流水线使用
销毁实例	按实例ID销毁，支持预检模式
清理过期实例	按保留分组扫描过期实例并销毁

1. 一个 CNB 密钥仓库，包含腾讯云 API 密钥文件：

# 密钥仓库中的文件，如 ThirdParty/TencentCloud.yml
SECRET_ID: "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
SECRET_KEY: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. 插件镜像地址：docker.cnb.cool/bring/tools/cvmtools:latest

在你的项目 .cnb.yml 中引用本插件镜像：

# 定义密钥仓库引用
.cvm_imports: &cvm_imports
  - https://cnb.cool/your-org/your-keystore/-/blob/main/TencentCloud.yml

"**":
  # 创建实例
  web_trigger_create_cvm:
    - imports: *cvm_imports
      stages:
        - name: 创建 CVM 实例
          image: docker.cnb.cool/bring/tools/cvmtools:latest
          settings:
            action: create
            secret_id: $SECRET_ID
            secret_key: $SECRET_KEY
            region: ap-guangzhou
            instance_type: SA9.MEDIUM4
            image: Ubuntu 22.04
            retain: 3h
            init_script: |
              #!/bin/bash
              apt-get update && apt-get install -y docker.io
          exports:
            instance_ids: INSTANCE_IDS
            public_ips: PUBLIC_IPS
        - name: 使用创建结果
          script:
            - echo "实例ID: $INSTANCE_IDS"
            - echo "公网IP: $PUBLIC_IPS"
            - ssh root@$PUBLIC_IPS "echo connected"

  # 列出实例
  web_trigger_list_cvm:
    - imports: *cvm_imports
      stages:
        - name: 列出实例
          image: docker.cnb.cool/bring/tools/cvmtools:latest
          settings:
            action: list
            secret_id: $SECRET_ID
            secret_key: $SECRET_KEY
            region: ap-guangzhou
            tag_key: cvmtools:managed
            tag_value: "true"
          exports:
            instance_ids: INSTANCE_IDS
            public_ips: PUBLIC_IPS

  # 销毁实例
  web_trigger_terminate_cvm:
    - imports: *cvm_imports
      stages:
        - name: 销毁实例
          image: docker.cnb.cool/bring/tools/cvmtools:latest
          settings:
            action: terminate
            secret_id: $SECRET_ID
            secret_key: $SECRET_KEY
            region: ap-guangzhou
            instance_ids: $instance_ids
            dry_run: "false"

  # 清理过期实例
  web_trigger_cleanup:
    - imports: *cvm_imports
      stages:
        - name: 清理过期实例
          image: docker.cnb.cool/bring/tools/cvmtools:latest
          settings:
            action: terminate-by-tag
            secret_id: $SECRET_ID
            secret_key: $SECRET_KEY
            region: ap-guangzhou
            tag_key: cvmtools:managed
            tag_value: "true"
            retain_group: short
            dry_run: "false"

在 .cnb/web_trigger.yml 中配置自定义按钮，点击按钮时弹出表单填写参数：

branch:
  - buttons:
      - name: 创建 CVM
        event: web_trigger_create_cvm
        inputs:
          region:
            name: 地域
            type: select
            default: ap-guangzhou
            options:
              - name: 广州
                value: ap-guangzhou
              - name: 上海
                value: ap-shanghai
          instance_type:
            name: 机型
            type: select
            default: SA9.MEDIUM4
            options:
              - name: "SA9.MEDIUM4 (2C4G)"
                value: SA9.MEDIUM4
              - name: "SA9.LARGE8 (4C8G)"
                value: SA9.LARGE8
          retain:
            name: 保留时长
            type: select
            default: 3h
            options:
              - name: 1 小时
                value: 1h
              - name: 3 小时
                value: 3h
              - name: 1 天
                value: 1d

完整的按钮配置参见本仓库 .cnb/web_trigger.yml

参数	必选	默认值	说明
action	是	-	create / list / terminate / terminate-by-tag
secret_id	是	-	腾讯云 SecretId
secret_key	是	-	腾讯云 SecretKey
region	否	ap-guangzhou	地域
dry_run	否	false	预检模式（写操作时仅展示不执行）

参数	默认值	说明
instance_type	-	机型（如 SA9.MEDIUM4），与 cpu/memory 二选一
cpu	2	CPU 核数（未指定 instance_type 时生效）
memory	4	内存 GB（未指定 instance_type 时生效）
image	Ubuntu 22.04	镜像ID（img-xxx）或关键字
disk_size	50	系统盘大小 GB
disk_type	CLOUD_BSSD	CLOUD_BSSD(通用SSD) / CLOUD_HSSD(增强SSD)
bandwidth	5	公网带宽 Mbps
name	cvm-{timestamp}	实例名称
retain	3h	保留时长：1h/3h/6h/12h/1d/3d/7d/never
charge_type	POSTPAID_BY_HOUR	POSTPAID_BY_HOUR(按量) / SPOTPAID(竞价)
spot_max_price	-	竞价上限（元/小时），仅竞价模式生效
password	-	登录密码
key_id	-	SSH 密钥ID（优先于密码）
sg_id	-	安全组ID（留空自动创建全放通安全组）
count	1	创建数量
init_script	-	开机初始化脚本（Shell），实例就绪后通过 TAT 执行

参数	默认值	说明
tag_key	-	按标签键过滤
tag_value	-	按标签值过滤
instance_ids	-	实例ID列表（逗号分隔）
state	-	按状态过滤（RUNNING/STOPPED 等）

参数	说明
instance_ids	要销毁的实例ID（逗号分隔），必填

参数	默认值	说明
tag_key	cvmtools:managed	标签键
tag_value	true	标签值
retain_group	-	按分组过滤：short / long / permanent
only_expired	true	仅销毁已过期实例

插件通过 ##[set-output key=value] 输出变量，配合 exports 映射为环境变量：

变量	动作	说明
instance_ids	create / list	实例ID（逗号分隔）
public_ips	create / list	公网IP（逗号分隔）
private_ips	create / list	内网IP（逗号分隔）
expire_at	create	过期时间 UTC
instance_type	create	实际使用的机型
instance_count	create / list	实例数量
init_invocation_id	create	TAT 初始化脚本执行活动ID
init_script_status	create	初始化脚本执行结果（逗号分隔）
instances_json	list	实例详情 JSON（base64 编码）
terminated_ids	terminate / terminate-by-tag	已销毁的实例ID
terminated_count	terminate / terminate-by-tag	已销毁数量

使用示例：

stages:
  - name: 创建实例
    image: docker.cnb.cool/bring/tools/cvmtools:latest
    settings:
      action: create
      # ...
    exports:
      instance_ids: INSTANCE_IDS
      public_ips: PUBLIC_IPS
  - name: 部署应用
    script: ssh root@$PUBLIC_IPS "docker pull myapp && docker run -d myapp"

创建实例时按顺序执行以下步骤（有初始化脚本时为 8 步，无则 6 步）：

步骤	说明	调用 API
[1] 解析机型和可用区	匹配机型，查询可用区库存	cvm:DescribeInstanceTypeConfigs + cvm:DescribeZoneInstanceConfigInfos
[2] 解析镜像	按关键字或 ID 查找镜像	cvm:DescribeImages
[3] 解析安全组	查找或自动创建全放通安全组	vpc:DescribeSecurityGroups + vpc:CreateSecurityGroupWithPolicies（按需）
[4] 构建请求参数	本地计算，无网络调用	—
[5] 创建实例	发起创建请求	cvm:RunInstances
[6] 等待实例就绪	轮询直到所有实例 RUNNING	cvm:DescribeInstancesStatus（轮询）
[7] 等待 TAT Agent 上线	轮询直到 Agent 状态 Online	tat:DescribeAutomationAgentStatus（轮询）
[8] 执行初始化脚本	下发脚本并等待执行完成	tat:RunCommand + tat:DescribeInvocationTasks（轮询）

最后调用 cvm:DescribeInstances 获取实例详情（IP 等）用于结果输出。

步骤 [7] 和 [8] 仅在设置了 init_script 时执行。

保留时长	分组	用途
1h / 3h / 6h	short	临时调试
12h / 1d / 3d / 7d	long	开发测试
never	permanent	长期运行

实例创建时会打上标签：

• cvmtools:managed=true — 标识由本插件创建
• cvmtools:retain=3h — 保留时长
• cvmtools:retain-group=short — 保留分组
• cvmtools:expire-at=2026-05-02T18:00:00Z — 过期时间

到期后通过腾讯云 ActionTimer 自动销毁。也可通过「清理过期实例」按钮按分组扫描兜底。

• VPC: 使用地域默认 VPC/子网
• 安全组: 未指定时自动查找/创建 cvmtools-allow-all（入出全放通）
• 机型匹配优先级: SA9 > SA5 > S5 > SA3 > S6
• 可用区: 自动选择首个有该机型库存的可用区
• 写操作安全: 销毁类按钮默认开启预检模式，需手动关闭才执行

pip install -r requirements.txt

# 预检模式测试创建
export PLUGIN_ACTION=create
export PLUGIN_SECRET_ID=AKIDxxx
export PLUGIN_SECRET_KEY=xxx
export PLUGIN_REGION=ap-guangzhou
export PLUGIN_INSTANCE_TYPE=SA9.MEDIUM4
export PLUGIN_IMAGE="Ubuntu 22.04"
export PLUGIN_RETAIN=1h
export PLUGIN_DRY_RUN=true
python -m src.main

# Docker 构建测试
docker build -t cvmtools .
docker run --rm -e PLUGIN_ACTION=list -e PLUGIN_SECRET_ID=xxx -e PLUGIN_SECRET_KEY=xxx cvmtools