虚拟机配置 API

VergeOS 中修改虚拟机配置的完整指南，包括 CPU/RAM 更新、备注、磁盘管理和网络接口管理。

要点

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

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

阶段: VM 配置（第 3/4 部分） 输入: VM key (42) + Machine key (54)，配置更改 输出: 已更新 VM 设置，已修改硬件 上一页: VM 已开机 → VM 电源管理 常见下一步:

• 高级操作 → VM 高级操作
• 为更改执行电源循环 → VM 电源管理

本文档适用于

• "如何更改 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

身份验证

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

前提条件

必须先创建虚拟机 → 参见 VM 创建

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 键（不是机器键）。

请求体示例:

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

完整 API 调用:

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"）	是

VM 键与 Machine 键

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

配置更改

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

向 VM 添加备注

POST /api/v4/note_actions

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

请求体:

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

完整 API 调用:

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	字符串	是	备注文本内容

VM 备注

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

磁盘管理

添加新磁盘

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

POST /api/v4/machine_drives

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

完整 API 调用:

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}

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

{
  "disksize": 1073741824000
}

完整 API 调用:

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
  }'

磁盘调整大小

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

移除磁盘

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

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

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}

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

磁盘管理示例

添加 CDROM/ISO

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

添加导入磁盘

{
  "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

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

完整 API 调用:

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}

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

完整 API 调用:

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}

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 启用状态

虚拟网络键

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

完整配置工作流

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

# 步骤 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. 监控性能: 留意任何性能影响

热插拔注意事项

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

热插拔支持

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

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

参见 VM 热插拔能力 以获取完整详情。

错误处理

常见配置错误

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

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

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

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

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

错误: 507 存储空间不足

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

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

相关操作

• VM 创建：参见 VM 创建 用于初始虚拟机设置
• 电源管理：参见 VM 电源管理 用于启动/停止操作
• 高级操作：参见 VM 高级操作 用于克隆和快照

需要帮助吗？

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

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