> 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-configuration.md).

# 虚拟机配置 API

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

* 通过 REST API 修改 CPU、RAM、控制台和显示等 VM 设置
* 使用缩放、添加和移除功能管理磁盘
* 更新网络接口及其配置
* 为虚拟机添加文档备注以便进行运维跟踪
  {% endhint %}

本指南介绍如何在创建后修改 VergeOS 中的虚拟机配置，包括 CPU/RAM 更新、磁盘管理、网络接口更改以及添加运维备注。

**阶段**: VM 配置（第 3/4 部分） **输入**: VM key (42) + Machine key (54)，配置更改 **输出**: 已更新 VM 设置，已修改硬件 **上一页**: VM 已开机 → [`VM 电源管理`](/knowledge-base/zh/automation-api/vm-power-management.md) **常见下一步**:

* 高级操作 → [`VM 高级操作`](/knowledge-base/zh/automation-api/vm-advanced-operations.md)
* 为更改执行电源循环 → [`VM 电源管理`](/knowledge-base/zh/automation-api/vm-power-management.md)

## 本文档适用于

* "如何更改 VM 的 CPU 和 RAM"
* "向现有虚拟机添加存储磁盘"
* "调整 VM 磁盘和存储大小"
* "管理 VM 网络接口"
* "向虚拟机添加备注和文档"
* "热插拔操作和在线更改"
* "VM 性能调优"
* "存储扩容工作流"
* "网络重新配置"

## 快速参考

### 主要端点

* **VM 设置**: `PUT /api/v4/vms/{id}`
* **VM 备注**: `POST /api/v4/note_actions`
* **磁盘管理**: `POST/PUT/DELETE /api/v4/machine_drives`
* **NIC 管理**: `POST/PUT/DELETE /api/v4/machine_nics`

### 关键概念

* **VM 键**: 用于 VM 设置（CPU、RAM、控制台）
* **Machine 键**: 用于硬件（磁盘、NIC、设备）
* **热插拔**: 某些更改需要重启 VM

### 身份验证

```bash
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
```

### 前提条件

必须先创建虚拟机 → 参见 [`VM 创建`](/knowledge-base/zh/automation-api/vm-creation-api.md)

## API 快速参考

| 操作     | 方法     | 端点                            | 键类型       | 用途            |
| ------ | ------ | ----------------------------- | --------- | ------------- |
| 更新 VM  | PUT    | `/api/v4/vms/{id}`            | VM 键      | CPU、RAM、控制台设置 |
| 添加备注   | POST   | `/api/v4/note_actions`        | VM 键      | 文档记录          |
| 添加磁盘   | POST   | `/api/v4/machine_drives`      | Machine 键 | 存储扩容          |
| 调整磁盘大小 | PUT    | `/api/v4/machine_drives/{id}` | 磁盘键       | 增加磁盘大小        |
| 移除磁盘   | DELETE | `/api/v4/machine_drives/{id}` | 磁盘键       | 存储移除          |
| 添加 NIC | POST   | `/api/v4/machine_nics`        | Machine 键 | 网络接口          |
| 更新 NIC | PUT    | `/api/v4/machine_nics/{id}`   | NIC 键     | 网络更改          |
| 移除 NIC | DELETE | `/api/v4/machine_nics/{id}`   | NIC 键     | 接口移除          |

## 故障排查索引

* **400 错误请求**: RAM 大小无效、CPU 数量无效、JSON 格式错误
* **409 冲突**: VM 必须已停止、不支持热插拔、资源正在使用中
* **507 存储空间不足**: 层已满、磁盘大小过大、超出配额
* **403 禁止访问**: API 密钥权限、虚拟机访问被拒、集群限制
* **422 无法处理的实体**: 磁盘无法缩小、接口类型无效
* **404 未找到**: 未找到 VM、未找到磁盘、未找到 NIC、vnet 无效

## CPU 和 RAM 更新

### PUT /api/v4/vms/{id}

**说明**: 更新 VM 配置。VM 级设置使用 VM 键（不是机器键）。

**请求体示例**:

```json
{
  "ram": 16384,
  "cpu_cores": 3,
  "console": "spice",
  "video": "qxl",
  "show_advanced": "true",
  "nested_virtualization": "true",
  "disable_hypervisor": "true"
}
```

**完整 API 调用**:

```bash
curl -X PUT "https://your-vergeos.example.com/api/v4/vms/42" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "ram": 16384,
    "cpu_cores": 3,
    "console": "spice",
    "video": "qxl",
    "show_advanced": "true",
    "nested_virtualization": "true",
    "disable_hypervisor": "true"
  }'
```

### 常见配置参数

| 参数                     | 类型  | 说明                             | 需要重启  |
| ---------------------- | --- | ------------------------------ | ----- |
| ram                    | 整数  | RAM（MB）                        | 通常需要  |
| cpu\_cores             | 整数  | CPU 核心数                        | 通常需要  |
| 控制台                    | 字符串 | 控制台类型（spice、vnc、none）          | 下次启动时 |
| video                  | 字符串 | 显示适配器（qxl、virtio、std、cirrus）   | 下次启动时 |
| nested\_virtualization | 字符串 | 启用嵌套虚拟化（"true"/"false"）        | 是     |
| disable\_hypervisor    | 字符串 | 禁用虚拟机管理程序（"true"/"false"）      | 是     |
| guest\_agent           | 字符串 | 启用 guest agent（"true"/"false"） | 下次启动时 |
| uefi                   | 字符串 | 启用 UEFI 启动（"true"/"false"）     | 是     |
| secure\_boot           | 字符串 | 启用安全启动（"true"/"false"）         | 是     |

{% hint style="success" %}
**VM 键与 Machine 键**

* **VM 设置** (CPU、RAM、控制台、显示)：使用 VM 键（例如， `42`) `/api/v4/vms/{vm_key}`
* **硬件更改** (磁盘、NIC、设备)：使用机器键（例如， `54`) `/api/v4/machine_*` 端点
  {% endhint %}

{% hint style="warning" %}
**配置更改**

* CPU 和 RAM 的更改通常需要重启 VM
* 控制台和显示更改会在 VM 下次启动时生效
* 嵌套虚拟化和虚拟机管理程序设置需要重启 VM
* 始终检查 `allow_hotplug` 以启用热添加功能的设置
  {% endhint %}

## 向 VM 添加备注

### POST /api/v4/note\_actions

**说明**: 在 VergeOS UI 中为 VM 添加或更新备注，用于文档记录。

**请求体**:

```json
{
  "owner": "vms/42",
  "action": "update",
  "params": {
    "text": "这是一个测试 VM"
  }
}
```

**完整 API 调用**:

```bash
curl -X POST "https://your-vergeos.example.com/api/v4/note_actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "owner": "vms/42",
    "action": "update",
    "params": {
      "text": "生产 Web 服务器 - 已更新 2025-08-24"
    }
  }'
```

**参数**:

| 名称          | 类型  | 必需 | 说明                        |
| ----------- | --- | -- | ------------------------- |
| owner       | 字符串 | 是  | 资源标识符（格式："vms/{vm\_key}"） |
| action      | 字符串 | 是  | 要执行的操作（"update"）          |
| params.text | 字符串 | 是  | 备注文本内容                    |

{% hint style="success" %}
**VM 备注**

备注会显示在 VergeOS UI 中，并有助于记录 VM 文档、维护计划或配置细节。owner 字段应使用 VM 键（不是机器键）。
{% endhint %}

## 磁盘管理

### 添加新磁盘

在创建 VM 后，使用 machine drives 端点添加存储：

#### POST /api/v4/machine\_drives

```json
{
  "machine": "54",
  "name": "数据磁盘",
  "interface": "virtio-scsi",
  "media": "disk",
  "disksize": 536870912000,
  "preferred_tier": "2"
}
```

**完整 API 调用**:

```bash
curl -X POST "https://your-vergeos.example.com/api/v4/machine_drives" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "machine": "54",
    "name": "数据磁盘",
    "interface": "virtio-scsi",
    "media": "disk",
    "disksize": 536870912000,
    "preferred_tier": "2"
  }'
```

### 调整磁盘大小

#### PUT /api/v4/machine\_drives/{drive\_id}

**说明**: 增加现有磁盘的大小。请注意，磁盘只能扩展，不能缩小。

```json
{
  "disksize": 1073741824000
}
```

**完整 API 调用**:

```bash
curl -X PUT "https://your-vergeos.example.com/api/v4/machine_drives/55" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "disksize": 1073741824000
  }'
```

{% hint style="warning" %}
**磁盘调整大小**

* 磁盘只能扩展，不能缩小
* 可能需要在来宾操作系统中进行配置，以识别新大小
* 某些文件系统在磁盘调整大小后需要手动扩展
  {% endhint %}

### 移除磁盘

在删除前，如果 VM 正在运行，磁盘必须先热拔插移除：

#### 步骤 1：热拔插移除磁盘（如果 VM 正在运行）

```bash
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "vm": "42",
    "action": "hotplugdrive",
    "params": {
      "device": "drive-id-here",
      "unplug": true
    }
  }'
```

#### 步骤 2：删除磁盘

#### DELETE /api/v4/machine\_drives/{drive\_id}

```bash
curl -X DELETE "https://your-vergeos.example.com/api/v4/machine_drives/55" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 磁盘管理示例

#### 添加 CDROM/ISO

```json
{
  "machine": "54",
  "media": "cdrom",
  "interface": "ahci",
  "media_source": "7"
}
```

#### 添加导入磁盘

```json
{
  "machine": "54",
  "name": "Ubuntu Server",
  "description": "Ubuntu 22.04 LTS",
  "interface": "virtio-scsi",
  "media": "import",
  "media_source": 123,
  "preferred_tier": "3"
}
```

## 网络接口管理

### 添加 NIC

#### POST /api/v4/machine\_nics

```json
{
  "machine": "54",
  "name": "辅助网络",
  "interface": "virtio",
  "vnet": "8",
  "enabled": true
}
```

**完整 API 调用**:

```bash
curl -X POST "https://your-vergeos.example.com/api/v4/machine_nics" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "machine": "54",
    "name": "辅助网络",
    "interface": "virtio",
    "vnet": "8",
    "enabled": true
  }'
```

### 更新 NIC 配置

#### PUT /api/v4/machine\_nics/{nic\_id}

```json
{
  "vnet": "10",
  "enabled": true
}
```

**完整 API 调用**:

```bash
curl -X PUT "https://your-vergeos.example.com/api/v4/machine_nics/78" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "vnet": "10",
    "enabled": true
  }'
```

### 移除 NIC

#### DELETE /api/v4/machine\_nics/{nic\_id}

```bash
curl -X DELETE "https://your-vergeos.example.com/api/v4/machine_nics/78" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### NIC 配置参数

| 参数        | 类型  | 必需 | 说明                             |
| --------- | --- | -- | ------------------------------ |
| machine   | 字符串 | 是  | Machine ID                     |
| vnet      | 字符串 | 是  | 虚拟网络 ID                        |
| name      | 字符串 | 否  | NIC 名称                         |
| interface | 字符串 | 否  | NIC 接口类型（virtio、e1000、rtl8139） |
| enabled   | 布尔值 | 否  | NIC 启用状态                       |

{% hint style="info" %}
**虚拟网络键**

该 `vnet` 该参数使用网络的键/ID。你可以通过 networks API 端点列出可用网络来查找网络键。
{% endhint %}

## 完整配置工作流

下面是更新 VM 完整配置的示例：

```bash
# 步骤 1：更新 VM 设置（CPU、RAM、控制台）
curl -X PUT "https://your-vergeos.example.com/api/v4/vms/42" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "ram": 32768,
    "cpu_cores": 8,
    "console": "spice",
    "video": "virtio"
  }'

# 步骤 2：添加运维备注
curl -X POST "https://your-vergeos.example.com/api/v4/note_actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "owner": "vms/42",
    "action": "update",
    "params": {
      "text": "已升级到 32GB RAM 和 8 核心，以应对更高负载 - 2025-08-24"
    }
  }'

# 步骤 3：添加额外存储
curl -X POST "https://your-vergeos.example.com/api/v4/machine_drives" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "machine": "54",
    "name": "应用数据",
    "interface": "virtio-scsi",
    "media": "disk",
    "disksize": 1073741824000,
    "preferred_tier": "2"
  }'

# 步骤 4：添加辅助网络接口
curl -X POST "https://your-vergeos.example.com/api/v4/machine_nics" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "machine": "54",
    "name": "管理网络",
    "interface": "virtio",
    "vnet": "5",
    "enabled": true
  }'
```

## 配置最佳实践

### 更改前

1. **检查 VM 状态**: 确保 VM 处于适合更改的状态
2. **备份重要数据**: 在重大更改前创建快照
3. **检查依赖项**: 考虑对运行中应用程序的影响
4. **规划停机时间**: 某些更改需要重启 VM

### 更改后

1. **验证配置**: 检查更改是否已正确应用
2. **测试功能**: 确保 VM 按预期运行
3. **更新文档**: 添加有关配置更改的备注
4. **监控性能**: 留意任何性能影响

### 热插拔注意事项

```bash
# 检查 VM 是否支持热插拔
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=allow_hotplug" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

{% hint style="success" %}
**热插拔支持**

该 `allow_hotplug` 此设置可启用热添加和热移除 **磁盘和 NIC** 在 VM 运行时：

* **驱动器**: 可在运行时动态添加/移除（来宾操作系统必须支持；推荐 Virtio-SCSI）
* **网卡**: 可在运行时动态添加/移除（被来宾操作系统广泛支持）
* **CPU/RAM**: 更改始终需要对 VM 进行一次电源循环

参见 [VM 热插拔能力](/knowledge-base/zh/tenants/vm-hotplug-capabilities.md) 以获取完整详情。
{% endhint %}

## 错误处理

### 常见配置错误

**错误**: `400 错误请求 - RAM 大小无效`

```json
{
  "error": "RAM 大小必须至少为 512 MB，最多为 1048576 MB"
}
```

**错误**: `409 冲突 - VM 必须已停止`

```json
{
  "error": "在 VM 运行且不支持热插拔时，无法修改 CPU 核心数"
}
```

**解决方案**: 在进行更改前，请停止 VM 或检查热插拔能力。

**错误**: `507 存储空间不足`

```json
{
  "error": "第 2 层中没有足够的存储空间来满足请求的磁盘大小"
}
```

**解决方案**: 选择不同的存储层或减小磁盘大小。

{% hint style="info" %}
**相关操作**

* **VM 创建**：参见 [`VM 创建`](/knowledge-base/zh/automation-api/vm-creation-api.md) 用于初始虚拟机设置
* **电源管理**：参见 [`VM 电源管理`](/knowledge-base/zh/automation-api/vm-power-management.md) 用于启动/停止操作
* **高级操作**：参见 [`VM 高级操作`](/knowledge-base/zh/automation-api/vm-advanced-operations.md) 用于克隆和快照
  {% endhint %}

{% hint style="info" %}
**需要帮助吗？**

如需有关 VM 配置的更多支持：

* 查看 VergeOS 文档门户
* 联系 VergeOS 支持并提供具体的错误信息
* 查看系统日志以获取详细的错误信息
* 查阅 VergeOS 社区论坛
  {% endhint %}


---

# 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-configuration.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.