> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/knowledge-base/zh/automation-api/vm-lifecycle-management.md).

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

{% hint style="info" %}
**要点**

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

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

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

## 本文档适用于

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

## API 工作流阶段

### 1. VM 创建 API

使用 REST API 调用以编程方式创建带有磁盘、设备和网络接口的虚拟机。 **→ 参见：** [`VM 创建`](/knowledge-base/zh/automation-api/vm-creation-api.md)

### 2. VM 电源管理 API

通过 API 端点启动、停止、重启并监控 VM 的电源状态。 **→ 参见：** [`VM 电源管理`](/knowledge-base/zh/automation-api/vm-power-management.md)

### 3. VM 配置 API

通过 API 调用修改 CPU、RAM、存储磁盘和网络设置。 **→ 参见：** [`VM 配置`](/knowledge-base/zh/automation-api/vm-configuration.md)

### 4. 高级 VM 操作 API

使用 API 方法克隆 VM、创建快照、删除虚拟机并排查问题。 **→ 参见：** [`VM 高级操作`](/knowledge-base/zh/automation-api/vm-advanced-operations.md)

## 关键 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 创建`](/knowledge-base/zh/automation-api/vm-creation-api.md)          |
| **电源** | 启动、停止、重启、监控            | `POST /api/v4/vm_actions`, `GET /api/v4/machine_status` | [`VM 电源管理`](/knowledge-base/zh/automation-api/vm-power-management.md)    |
| **配置** | 更新 CPU/RAM、管理磁盘、管理 NIC | `PUT /api/v4/vms`, `POST/PUT/DELETE /api/v4/machine_*`  | [`VM 配置`](/knowledge-base/zh/automation-api/vm-configuration.md)         |
| **高级** | 克隆、快照、删除、排障            | `POST /api/v4/vm_actions`, `DELETE /api/v4/vms`         | [`VM 高级操作`](/knowledge-base/zh/automation-api/vm-advanced-operations.md) |

## 常见 API 错误场景

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

## API 快速入门指南

1. [`创建 VM`](/knowledge-base/zh/automation-api/vm-creation-api.md) - 用于创建虚拟机的 REST API 调用
2. [`电源控制`](/knowledge-base/zh/automation-api/vm-power-management.md) - 用于启动、停止和管理 VM 的 API 端点
3. [`配置 VM`](/knowledge-base/zh/automation-api/vm-configuration.md) - 用于修改 VM 设置和硬件的 API 方法
4. [`高级操作`](/knowledge-base/zh/automation-api/vm-advanced-operations.md) - 用于克隆、备份和排障的 API 调用

## 常见 API 使用场景

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

## API 身份验证

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

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

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/knowledge-base/zh/automation-api/vm-lifecycle-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.