实例

创建虚拟机

接口描述

创建虚拟机。

接口路径

POST /v1/domains

请求参数

名称	类型	是否必须	默认值	描述
name	string	否	vm+vmId	虚拟机name
memory	int	是		虚拟机内存（KB)
cpu_count	int	是		虚拟机cpu数量
networks	[]Network	否	default（NAT）网络	虚拟机网络配置
gpu_model	string	否		GPU型号
gpu_count	int	否	1（指定GPU型号时，默认配置一块GPU）	GPU数量
system_volume	Volume	是		虚拟机系统盘配置
data_volumes	[]Volume	否		虚拟机数据盘配置
metadata	string	否		实例metadata
userdata	Userdata	否		userdata
count	int	否	1	虚拟机数量
image_id	int	是		镜像ID
datacenter_id	int	是		数据中心ID

metadata：

创建实例时可设置一些实例的元数据，比如hostname：

// 数据要base64编码，比如把hostname设置为win10_demo1:
// metadata参数: {"hostname": "win10_demo1"}
// 需要base64编码:
{
    ...
    "metadata": "eyJob3N0bmFtZSI6ICJ3aW4xMF9kZW1vMSJ9Cg=="
}

创建实例时设置hostname有可能会在第一次开机时重启一次实例。

Userdata：

名称	类型	描述
WriteFiles	[]Fields	创建实例时可传入一些数据，写到指定的文件中

Fields：

名称	类型	描述
content	string	文件内容，需要base64编码
path	string	文件路径

userdata示例：

{
    ...
    "userdata": {
        "write_files": [
            {
                "content": "dGhpcyBpcyB0ZXN0Cg==",
                "path": "C:\path\to\file"
            },
            {
                "content": "dGhpcyBpcyB0ZXN0Cg==",
                "path": "C:\path\to\file"
            }
        ]
    }
}

Network：

名称	类型	是否必须	默认值	描述
network_id	int	是		网络id（网络id和子网id必须使用一个）
subnet_id	int	是		子网id（网络id和子网id必须使用一个）
type	string	是		网络类型，当前支持default（nat）和bridge两种类型

Volume：

名称	类型	是否必须	默认值	描述
capacity	int	是（当指定backing_file时，capacity的值不应小于backing_file磁盘的size）		磁盘容量
storage_pool	string	是		磁盘所在存储池
format	string	否	qcow2（qcow2格式的磁盘才支持快照功能）	磁盘格式
backing_file	string	否		qcow2磁盘的backing file
backing_file_pool	string	否		backing file所在存储池
filesystem	string	否	Windows系统为ntfs，Linux系统为ext4	磁盘文件系统

请求示例：

// 创建桥接网络虚拟机
{
    "name": "demo1",
    "memory": 60817408,
    "cpu_count": 18,
    "image_id": 6,
    "data_volumes": [
        {"capacity": 320,"storage_pool": "vmdata"}
    ],
    "datacenter_id": 6,
    "networks": [ // 虚拟机有三块网卡
        {"subnet_id": 18, "type":"bridge"},
        {"subnet_id": 19, "type":"bridge"},
        {"subnet_id": 20, "type":"bridge"}
    ],
    "gpu_model":"NVIDIA GeForce RTX 3070 Ti",
    "count": 40  // 批量创建40台虚拟机
}

响应数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述
data	[]int	虚机ID
reason	string	异常时的原因

重启虚拟机

接口描述

重启虚拟机（异步）。

接口路径

PUT /v1/domains/:id/reboot

请求参数

参数名称	是否必须	示例	备注
id	是	/v1/domains/1/reboot	虚拟机id

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
task_id	int	任务id（重启为异步操作，可以通过虚机id查看虚机状态，或者通过任务id查看重启任务状态）
reason	string	异常时的原因

启动虚拟机

接口描述

启动虚拟机。

接口路径

PUT /v1/domains/:id/start

请求参数

参数名称	是否必须	示例	备注
id	是	/v1/domains/1/start	虚拟机id

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
reason	string	异常时的原因

关闭虚拟机

接口描述

关闭虚拟机（异步）。

接口路径

PUT /v1/domains/:id/shutdown

请求参数

参数名称	是否必须	示例	备注
id	是	/v1/domains/1/shutdown	虚拟机id

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
task_id	int	任务id（关闭虚机为异步操作，可以通过虚机id查看虚机状态，或者通过任务id查看关闭虚机任务状态）
reason	string	异常时的原因

强制关机

接口描述

强制关机。

接口路径

PUT /v1/domains/:id/destroy

请求参数

参数名称	是否必须	示例	备注
id	是	/v1/domains/1/destroy	虚拟机id

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
reason	string	异常时的原因

重置虚拟机

接口描述

重建虚拟机（异步）。

接口路径

PUT /v1/domains/:id/rebuild

请求参数

路径参数：

参数名称	是否必须	示例	备注
id	是	/v1/domains/1/rebuild	虚拟机id

body参数：

参数名称	参数类型	默认值	描述
rebuild_self	bool		使用当前镜像重装虚拟机
image_id	int		使用指定镜像重置系统盘
system_disk	Volume
data_disks	[]Volume
auto_boot	bool	false	重置后是否启动虚拟机

请求示例：

// 使用虚机磁盘的当前backing file重置，并自动开机
{"rebuild_self": true, "auto_boot":true}

// 使用指定镜像重置系统盘
{"image_id":1, "auto_boot":true}

// 使用指定镜像重置系统盘，指定backing_file重置数据盘
{
    "image_id": 1,
    "data_disks": [
        {
            "backing_file_id": 11
        }
    ],
    "auto_boot":true
}

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
task_id	int	任务id
reason	string	异常时的原因

查看实例就绪状态

接口描述

查看当前实例是否就绪（操作系统是否已完全启动）。

接口路径

GET /v1/domains/:id/readiness

请求参数

路径参数：

参数名称	是否必须	示例	备注
id	是	/v1/domains/1/readiness	虚拟机id

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
data	string	就绪状态： Ready：已就绪 NotReady：未就绪
reason	string	异常时的原因

查看虚拟机

接口描述

查看虚拟机详情。

接口路径

GET /v1/domains/:id

请求参数

参数名称	是否必须	示例	备注
id	是	/v1/domains/1	虚拟机id

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
data	object	响应数据，数据结构见示例
reason	string	异常时的原因

返回数据示例：

{
    "code": 100001,
    "msg": "success",
    "data": {
        "id": 7, // 虚拟机id
        "created_at": "2025-01-22T11:13:54.099+08:00",  // 创建时间
        "updated_at": "2025-01-22T11:14:31.158+08:00",  // 更新时间
        "uuid": "f3d1d7a9-f4e8-4b06-b861-a99b2b8760f0", // 虚拟机uuid
        "name": "vm012",  // 虚拟机名字
        "os": "windows10", // 虚拟机系统
        "real_name": "vm7", // 虚拟机在服务器上的名字(vm+id)
        "state": "running", // 虚拟机状态
        "memory": 8388608,  // 内存(KB)
        "max_memory": 8388608, // 最大可用内存(KB)
        "cpus": 4, // cpu核心数
        "cpu_model": "Intel(R) Xeon(R) CPU E5-2650 v3 @ 2.30GHz", // CPU型号
        "server_id": 2,  // 服务器id
        "server_hostname": "10.100.9.31", // 服务器hostname
        "server_ip": "10.100.9.31",  // 服务器ip
        "image_id": 2,  // 镜像id
        "datacenter_id": 1, // 数据中心id
        "datacenter_name": "office", // 数据中心名称
        "is_release": false, // 是否已是否
        "volumes": [  // 虚拟机磁盘
            {
                "id": 9,  // 磁盘id
                "created_at": "2025-01-22T11:13:54.118+08:00", // 创建时间
                "updated_at": "2025-01-22T11:14:31.162+08:00", // 更新时间
                "volume_name": "3aebf81268514e0f8b3c7c61b0fbffc2", // 磁盘文件名称
                "device": "vda",
                "capacity": 40,  // 磁盘容量
                "type": "file", // 磁盘类型
                "is_system": true, // 是否是系统盘
                "backing_file": "/opt/export/baseimg/debug_ems.qcow2",  // 磁盘镜像文件
                "backing_file_pool": "baseimg",  // 磁盘镜像存储池名称
                "backing_file_format": "qcow2", // 磁盘镜像格式
                "mount_flag": "persistent",  // 挂载选项
                "disk_type": "SSD",  // 磁盘类型
                "filesystem": "",
                "path": "/opt/srv/kvm/3aebf81268514e0f8b3c7c61b0fbffc2",  // 磁盘路径
                "storage_pool": "local_system",  // 磁盘所在存储池名称
                "storage_pool_name": "local_system",  // 磁盘所在存储池名称
                "storage_pool_id": 1,  磁盘所在存储池id
                "format": "qcow2",  // 磁盘格式
                "datacenter_name": "office",
                "virtual_machine_id": 7,
                "volume_type": "volume",
                "image_id": 2,
                "uid": 1,
                "parent": 2,
                "root": 9,
                "active": 9,
                "aged": false
            },
            {
                "id": 10,
                "created_at": "2025-01-22T11:13:54.118+08:00",
                "updated_at": "2025-01-22T11:14:31.163+08:00",
                "volume_name": "0112e9c1969b4e05a5a2f957c15a2060",
                "device": "sdb",
                "capacity": 100,
                "type": "file",
                "backing_file": "/opt/srv/kvm/d48ea901ad864f9894ccb721156d09e6",
                "backing_file_format": "qcow2",
                "mount_flag": "persistent",
                "disk_type": "SSD",
                "filesystem": "ntfs",
                "path": "/opt/srv/kvm/0112e9c1969b4e05a5a2f957c15a2060",
                "storage_pool": "local_system",
                "storage_pool_name": "local_system",
                "storage_pool_id": 1,
                "format": "qcow2",
                "datacenter_name": "office",
                "virtual_machine_id": 7,
                "volume_type": "volume",
                "uid": 1,
                "parent": 11,
                "root": 10,
                "active": 10,
                "aged": false
            }
        ],
        "ip_addresses": [ // 虚拟机网络信息
            {
                "id": 7,
                "created_at": "2025-01-22T11:13:54.131+08:00",
                "updated_at": "2025-01-22T11:14:31.16+08:00",
                "ip": "192.168.122.99",
                "mac_address": "a8:3a:44:3e:cb:76",
                "bridge_name": "default",
                "state": 2,
                "static": false,
                "virtual_machine_id": 7,
                "subnet_id": 0
            }
        ],
        "deleted_at": null
    }
}

虚拟机state字段含义

• running：运行中
• starting：启动中
• start_failure：启动失败
• creating：创建中
• create_failure：创建失败
• shutting_down：关机中
• shutdown_failure：关机失败
• shutdown：已关机
• destroy：已销毁
• paused：已挂起
• snapshot_reverting：正在使用快照回滚
• snapshot_revert_failure：使用快照回滚失败
• rebuilding：正在重置虚拟机
• rebuild_failure：重置虚拟机失败
• rebooting：重启中
• reboot_failure：重启失败
• migrating：迁移中
• migrate_failure：迁移失败
• unknown：未知

查看虚拟机列表

接口描述

查看虚拟机列表。

接口路径

GET /v1/domains

请求参数

参数名称	是否必须	示例	备注
datacenter_id	否	/v1/domains?datacenter_id=1	查询指定数据中心的虚拟机
server_id	否	/v1/domains?server_id=1	查询指定服务器上的虚拟机
state	否	/v1/domains?state=running	查询指定状态的虚拟机
mac	否	/v1/domains?mac=a8:06:cb:be:c9:04	通过mac地址过滤虚拟机
offset	否	/v1/domains?offset=10	跳过记录数量
limit	否	/v1/domains?limit=10	限制查询数量（default：100）

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
data	[]object	响应数据，数据结构见示例
reason	string	异常时的原因

返回数据示例：

{
    "code": 100001,
    "msg": "success",
    "data": {
        "count": 2,
        "items": [
            {
                "id": 5, // 实例id
                "created_at": "2025-01-22T10:58:14.704+08:00", // 实例创建时间
                "updated_at": "2025-01-22T11:13:40.877+08:00", // 实例更新时间
                "uuid": "002263a9-fc96-475e-846d-954211582f2a", // 实例uuid
                "name": "vm", // 实例name
                "os": "windows10", // 系统
                "real_name": "ins5", // 实例在服务器上的name
                "state": "running", // 实例状态
                "memory": 8388608, // 内存(KB)
                "max_memory": 8388608, // 最大可用内存(KB)
                "cpus": 4,  // cpu
                "cpu_model": "Intel(R) Xeon(R) CPU E5-2650 v3 @ 2.30GHz", // CPU型号
                "server_id": 2,  // 实例所在服务器id
                "server_hostname": "10.100.9.31", // 实例所在服务器hostname
                "server_ip": "10.100.9.31",
                "datacenter_id": 1, // 数据中心id
                "datacenter_name": "office", // 数据中心名称
                "is_release": false,  // 实例是否已经被释放
                "deleted_at": null
            },
            {
                "id": 7,
                "created_at": "2025-01-22T11:13:54.099+08:00",
                "updated_at": "2025-01-22T11:14:31.158+08:00",
                "uuid": "f3d1d7a9-f4e8-4b06-b861-a99b2b8760f0",
                "name": "vm012",
                "os": "windows10",
                "real_name": "ins7",
                "state": "running",
                "memory": 8388608,
                "max_memory": 8388608,
                "cpus": 4,
                "cpu_model": "Intel(R) Xeon(R) CPU E5-2650 v3 @ 2.30GHz",
                "server_id": 2,
                "server_hostname": "10.100.9.31",
                "server_ip": "10.100.9.31",
                "datacenter_id": 1,
                "datacenter_name": "office",
                "is_release": false,
                "deleted_at": null
            }
        ]
    }
}

挂载磁盘

接口描述

挂载磁盘到虚拟机。

接口路径

PUT /v1/domains/mount

请求参数

参数名称	参数类型	是否必须	默认值	描述
domain_id	int	是		虚拟机Id
volume_id	int	是		volume id
readonly	bool	否	false	是否只读挂载
flags	string	是		挂载选项： - live：必须在开机状态下挂载，重启后失效； - config：需要重启虚机后生效； - persistent：即时生效，重启后不失效（相当于live+config，必须要在开机状态使用）
serial	string	否		挂载时指定磁盘serial

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
reason	string	异常时的原因

卸载磁盘

接口描述

从虚拟机卸载磁盘。

接口路径

PUT /v1/domains/umount

请求参数

参数名称	参数类型	是否必须	默认值	描述
domain_id	int	是		虚拟机Id
volume_id	int	是		volume id
flags	string	是		卸载选项： - live：必须在开机状态下挂载，重启后失效； - config：需要重启虚机后生效； - persistent：即时生效，重启后不失效（相当于live+config，必须要在开机状态使用）
deletable	bool	否	false	卸载后是否要删除磁盘

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
reason	string	异常时的原因

修改虚拟机配置

接口描述

修改虚拟机CPU、内存、磁盘配置。

接口路径

PUT /v1/domains/:id/modify

请求参数

路径参数

参数名称	参数类型	是否必须	备注
id	int	是	虚拟机id

body参数

参数名称	参数类型	是否必须	默认值	描述
memory	int	否		内存（KB）
cpus	int	否		cpu
system_disk_capacity	int	否		系统盘容量（GB）
data_disk_capacity	int	否		数据盘容量（GB）
power_on	bool	否	false	修改完配置后是否自动开机

多数据盘虚机暂不支持修改数据盘容量

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
reason	string	异常时的原因

删除虚拟机

接口描述

删除虚拟机。

接口路径

DELETE /v1/domains/:id

请求参数

路径参数

参数名称	参数类型	是否必须	备注
id	int	是	虚拟机id

query参数

参数名称	参数类型	是否必须	示例	备注
delete_volumes	string	否	?delete_volume=all	删除虚机时，是否删除虚机磁盘，可选值： all：删除虚机所有磁盘； system：删除系统盘； data：删除数据盘； none：只删除虚机，不删除磁盘（default）

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
reason	string	异常时的原因

执行命令

接口描述

在虚拟机内执行系统命令。

接口路径

POST /v1/domains/guest-command

接口参数

参数名称	类型	是否必须	默认值	备注
id	int	是		虚拟机id
cmd	string	是		命令
args	array	否		命令参数
cmd_type	string	否	build-out	build-in OR build-out build-in用于执行qemu-guest-agent内置的命令 build-out用于执行自定义命令
timeout	string	否	15秒	超时时间

build-in可用命令：

command	含义
help	查看帮助(guest-info)
get-network	查看虚机网络信息
ping	Ping the guest agent，如果不返回错误信息，则成功
get-hostname	获取主机名
get-time	获取虚拟机系统时间（相对于1970-01-01 in UTC)
get-timezone	获取时区
get-user	获取用户
get-os	获取虚机系统信息

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
data	Result	异常时的原因

Result：

名称	类型	描述
id	int
exit_code	int	0：表示命令执行成功，可从stdout读取命令执行结果； -1表示内部错误，从stderr读取错误详情； 大于0表示命令执行失败，从stderr读取命令执行失败结果。
stdout	string	命令执行成功结果。
stderr	string	命令执行失败结果。

创建快照

接口描述

创建虚拟机快照（异步）。

接口路径

POST /v1/snapshots

接口参数

参数名称	类型	是否必须	默认值	备注
domain_id	int	是		虚拟机Id
name	string	是		快照名称
description	string	否		快照描述
backup_type	int	否	快照类型	可用值： 1：只给系统盘做快照 2：只给数据盘做快照 3：给所有磁盘做快照

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
reason	string	响应异常时的原因
data	Object	响应数据

Object：

名称	类型	描述
backup_id	int	快照Id
task_id	int	任务Id

快照回滚

接口描述

使用快照回滚虚拟机（回滚后并不会自动开机，异步）。

接口路径

PUT /v1/snapshots/:id/revert

接口参数

参数名称	类型	是否必须	默认值	备注
id	int	是		快照Id

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
reason	string	响应异常时的原因
data	Object	响应数据

Object：

名称	类型	描述
task_id	int	任务Id

删除快照

接口描述

删除快照（异步）。

接口路径

DELETE /v1/snapshots/:id DELETE /v1/snapshots/:id

接口参数

路径参数

参数名称	类型	是否必须	默认值	备注
id	int	是		快照Id
路径参数

参数名称	类型	是否必须	默认值	备注
id	int	是		快照Id

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
reason	string	响应异常时的原因

查看快照列表

接口描述

查看快照列表。

接口路径

GET /v1/snapshots

接口参数

query参数：

参数名称	类型	是否必须	默认值	备注
vm_id	int	否		虚拟机id
limit	int	否	100	限制查询数量
offset	int	否		跳过记录数

返回数据

名称	类型	描述
code	int	状态码（100001表示成功，其它表示异常）
msg	string	状态码描述信息
data	[]object	响应数据，数据结构见示例
reason	string	异常时的原因

返回数据示例：

{
    "code": 100001,
    "data": {
        "count": 1,
        "count": 1,
        "items": [
            {
                    "id": 1,  // 快照id
                    "created_at": "2025-02-19T06:45:30.442Z",  // 创建时间
                    "updated_at": "2025-02-19T06:46:30.595Z",  // 更新时间
                    "name": "test001",  // 快照名称
                    "description": "",  // 快照描述
                    "status": "active", // 快照状态
                    "virtual_machine_id": 740  // 虚拟机Id
             }
                    "id": 1,  // 快照id
                    "created_at": "2025-02-19T06:45:30.442Z",  // 创建时间
                    "updated_at": "2025-02-19T06:46:30.595Z",  // 更新时间
                    "name": "test001",  // 快照名称
                    "description": "",  // 快照描述
                    "status": "active", // 快照状态
                    "virtual_machine_id": 740  // 虚拟机Id
             }
        ]
    },
    "msg": "success"
}