虚拟机生命周期管理 API 概览

VergeOS 虚拟机生命周期管理的完整 REST API 指南——以编程方式创建、管理、配置和删除虚拟机。

要点

• 用于虚拟机生命周期管理和自动化的完整 REST API
• 通过 HTTP 端点以编程方式创建、配置、管理和删除虚拟机
• 四阶段 API 工作流：创建 → 电源管理 → 配置 → 高级操作
• 面向开发者和自动化工具优化的完整 API 文档

阶段: API 概览（入口点） 输入: 开发者需求，自动化需求 输出: 引导式工作流，指向特定 API 文档 导航路径:

• 从这里开始 → 选择具体操作 → 按照详细指南执行
• 完整生命周期：创建 → 电源 → 配置 → 高级

本文档适用于

• “VM API 概览与快速入门”
• “VM 管理的 REST API 工作流”
• “API 端点参考与导航”
• “VergeOS API 开发者入门”
• “基础设施即代码规划”
• “自动化工作流设计”
• “API 集成指南”
• “VM 管理自动化策略”

API 工作流阶段

1. VM 创建 API

使用 REST API 调用以编程方式创建带有磁盘、设备和网络接口的虚拟机。 → 参见： VM 创建

2. VM 电源管理 API

通过 API 端点启动、停止、重启并监控 VM 的电源状态。 → 参见： VM 电源管理

3. VM 配置 API

通过 API 调用修改 CPU、RAM、存储磁盘和网络设置。 → 参见： VM 配置

4. 高级 VM 操作 API

使用 API 方法克隆 VM、创建快照、删除虚拟机并排查问题。 → 参见： VM 高级操作

关键 API 概念

• VM 键与 Machine 键: 用于 VM 设置与硬件操作的 API 区分
• REST API 身份验证: 所有 API 调用均需要 Bearer 令牌身份验证
• 资源组: 基于 UUID 的 API 参数，用于设备直通（GPU、PCI 设备）
• 存储层级: 可通过 API 配置的性能级别（1-5），用于磁盘放置
• HTTP 方法: 用于完整 VM 生命周期管理的 GET、POST、PUT、DELETE 操作

主要 API 端点

API 操作	HTTP 方法	REST 端点	用途
创建 VM	POST	/api/v4/vms	创建新的虚拟机
VM 操作	POST	/api/v4/vm_actions	电源操作、克隆、快照
更新 VM	PUT	/api/v4/vms/{id}	修改 VM 配置
添加存储	POST	/api/v4/machine_drives	将磁盘附加到 VM
添加网络	POST	/api/v4/machine_nics	配置网络接口
添加设备	POST	/api/v4/machine_devices	附加 GPU/PCI 设备
删除 VM	DELETE	/api/v4/vms/{id}	移除虚拟机
VM 状态	GET	/api/v4/vms/{id}	查询 VM 信息
电源状态	GET	/api/v4/machine_status/{id}	检查运行时状态

按阶段划分的 API 快速参考

阶段	主要操作	关键端点	文档记录
创建	创建 VM、添加磁盘、添加 NIC、添加设备	POST /api/v4/vms, POST /api/v4/machine_*	VM 创建
电源	启动、停止、重启、监控	POST /api/v4/vm_actions, GET /api/v4/machine_status	VM 电源管理
配置	更新 CPU/RAM、管理磁盘、管理 NIC	PUT /api/v4/vms, POST/PUT/DELETE /api/v4/machine_*	VM 配置
高级	克隆、快照、删除、排障	POST /api/v4/vm_actions, DELETE /api/v4/vms	VM 高级操作

常见 API 错误场景

• 身份验证问题: 无效的 API 密钥、令牌过期、权限不足
• 资源限制: 存储不足、内存限制、CPU 配额超限
• 配置错误: 参数无效、缺少必填字段、JSON 格式错误
• 状态冲突: VM 已在运行、操作进行中、资源被锁定
• 网络问题: API 超时、连接被拒绝、服务不可用
• 验证错误: VM 名称无效、不受支持的配置、违反约束

API 快速入门指南

1. 创建 VM - 用于创建虚拟机的 REST API 调用
2. 电源控制 - 用于启动、停止和管理 VM 的 API 端点
3. 配置 VM - 用于修改 VM 设置和硬件的 API 方法
4. 高级操作 - 用于克隆、备份和排障的 API 调用

常见 API 使用场景

• 自动化 VM 部署: 以编程方式创建 VM，用于云自动化
• 基础设施即代码: 通过 API 调用管理虚拟机基础设施
• DevOps 集成: 使用 REST API 将 VM 管理集成到 CI/CD 流水线中
• 监控与告警: 通过 API 端点查询 VM 状态和电源状态
• 备份与恢复: 通过 API 操作自动执行 VM 快照和克隆
• 资源管理: 以编程方式管理 VM 的 CPU、内存和存储分配

API 身份验证

所有 VM 生命周期 API 端点都需要身份验证：

curl -H "Authorization: Bearer YOUR_API_KEY" \\
     -H "Content-Type: application/json" \\
     https://your-vergeos.example.com/api/v4/vms

从 VM 创建 API 文档开始，开启自动化你的虚拟机管理工作流。