虚拟机高级操作 API

VergeOS 中虚拟机高级操作的完整指南，包括克隆、快照、删除和故障排除。

要点

克隆虚拟机并完整复制配置和磁盘
创建并恢复虚拟机快照以用于备份和恢复
通过自动资源清理安全删除虚拟机
全面的错误处理和故障排除指南

本指南介绍 VergeOS 中的高级虚拟机操作，包括克隆、快照管理、删除和故障排除。这些操作为虚拟机生命周期管理和灾难恢复提供了强大的能力。

阶段: 虚拟机高级操作（4/4）输入: VM 键（42）、操作类型、参数输出: 已克隆的虚拟机、快照、清理确认 上一页: 虚拟机已配置 → VM 配置 常见操作:

用于模板的克隆 → 新建虚拟机创建周期
用于备份的快照 → 恢复工作流
用于清理的删除 → 生命周期结束

本文档适用于

"如何通过 API 克隆虚拟机"
"创建虚拟机快照和备份"
"从快照恢复虚拟机"
"安全删除虚拟机和清理"
"虚拟机故障排除和诊断"
"模板创建工作流"
"灾难恢复操作"
"批量虚拟机管理"
"资源清理自动化"

快速参考

主要端点

VM 操作: POST /api/v4/vm_actions
虚拟机删除: DELETE /api/v4/vms/{vm_key}
虚拟机列表: GET /api/v4/vms

关键操作

克隆: 创建虚拟机完整副本
快照: 创建虚拟机快照
恢复: 从快照恢复

身份验证

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

前提条件

虚拟机必须存在 → 参见 VM 创建

API 快速参考

操作

方法

端点

键类型

用途

克隆虚拟机

POST

/api/v4/vm_actions

VM 键

创建完整副本

创建快照

POST

/api/v4/vm_actions

VM 键

时间点备份

恢复快照

POST

/api/v4/vm_actions

VM 键

恢复操作

列出快照

GET

/api/v4/vms

筛选查询

查找快照

删除 VM

DELETE

/api/v4/vms/{id}

VM 键

完整移除

VM 状态

GET

/api/v4/vms/{id}

VM 键

配置检查

操作状态

GET

/api/v4/machine_status/{id}

Machine 键

运行时监控

故障排查索引

409 冲突: 克隆名称已存在，虚拟机已在运行，操作正在进行
507 存储空间不足: 克隆空间不足，快照存储已满
403 禁止访问: API 密钥权限、虚拟机访问被拒、集群限制
404 未找到: 未找到虚拟机、未找到快照、虚拟机键无效
408 请求超时: 克隆操作超时，快照创建超时
422 无法处理的实体: 克隆参数无效，快照恢复冲突
500 内部服务器错误: 存储系统问题、虚拟机监控器问题、集群故障

虚拟机克隆

POST /api/v4/vm_actions

说明: 创建虚拟机的完整副本，包括所有磁盘和配置。

基础克隆

{
  "params": {
    "name": "测试克隆",
    "quiesce": "true"
  },
  "action": "clone",
  "vm": "42"
}

完整 API 调用:

curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "params": {
      "name": "测试克隆",
      "quiesce": "true"
    },
    "action": "clone",
    "vm": "42"
  }'

响应示例:

{
  "response": {
    "vmkey": "43",
    "machinekey": "55",
    "machinestatuskey": "55",
    "clusterkey": "1"
  }
}

高级克隆选项

{
  "params": {
    "name": "production-clone",
    "description": "用于测试的生产服务器克隆",
    "preserve_macs": "true",
    "preserve_device_uuids": "true",
    "quiesce": "true",
    "cluster": "2"
  },
  "action": "clone",
  "vm": "42"
}

克隆参数

参数

类型

必需

说明

name

字符串

是

克隆后的虚拟机名称

description

字符串

否

克隆描述

静默

字符串

否

克隆前使虚拟机静默（"true"/"false"），以确保数据一致性

preserve_macs

字符串

否

保留 MAC 地址（"true"/"false"）

preserve_device_uuids

字符串

否

保留设备 UUID（"true"/"false"）

cluster

字符串

否

目标集群 ID

克隆选项

静默: 使用 "quiesce": "true" 通过短暂暂停虚拟机来确保数据一致性
保留 MAC: 使用 "preserve_macs": "true" 以保持相同的 MAC 地址（可能导致网络冲突）
保留设备 UUID: 使用 "preserve_device_uuids": "true" 以保持设备标识符
跨集群: 指定不同的集群 ID 以克隆到另一个集群

克隆工作流示例

# 步骤 1：创建克隆
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "params": {
      "name": "backup-clone-$(date +%Y%m%d)",
      "description": "自动备份克隆",
      "quiesce": "true"
    },
    "action": "clone",
    "vm": "42"
  }'

# 步骤 2：验证克隆创建（使用返回的 vmkey）
curl "https://your-vergeos.example.com/api/v4/vms/43?fields=name,description,created" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# 步骤 3：检查克隆电源状态
curl "https://your-vergeos.example.com/api/v4/machine_status/55?fields=powerstate,status" \\
  -H "Authorization: Bearer YOUR_API_KEY"

虚拟机快照

创建快照

{
  "vm": "42",
  "action": "snapshot",
  "params": {
    "name": "pre-update-snapshot",
    "description": "系统更新前"
  }
}

完整 API 调用:

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": "snapshot",
    "params": {
      "name": "pre-update-snapshot",
      "description": "系统更新前 - $(date)"
    }
  }'

从快照恢复

{
  "vm": "42",
  "action": "restore",
  "params": {
    "snapshot_id": "snapshot-67890"
  }
}

完整 API 调用:

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": "restore",
    "params": {
      "snapshot_id": "snapshot-67890"
    }
  }'

列出虚拟机快照

GET /api/v4/vms

使用筛选条件查找快照：

curl "https://your-vergeos.example.com/api/v4/vms?filter=is_snapshot%20eq%20true%20and%20name%20contains%20'web-server'" \\
  -H "Authorization: Bearer YOUR_API_KEY"

查找某虚拟机的所有快照:

curl "https://your-vergeos.example.com/api/v4/vms?filter=is_snapshot%20eq%20true%20and%20parent_vm%20eq%2042" \\
  -H "Authorization: Bearer YOUR_API_KEY"

快照管理工作流

# 步骤 1：维护前创建快照
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": "snapshot",
    "params": {
      "name": "maintenance-snapshot-$(date +%Y%m%d-%H%M)",
      "description": "维护前快照"
    }
  }'

# 步骤 2：列出快照以查找快照 ID
curl "https://your-vergeos.example.com/api/v4/vms?filter=is_snapshot%20eq%20true%20and%20parent_vm%20eq%2042&fields=name,description,created" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# 步骤 3：如有需要则恢复（维护问题之后）
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": "restore",
    "params": {
      "snapshot_id": "found-snapshot-id"
    }
  }'

虚拟机删除与清理

完整删除虚拟机

DELETE /api/v4/vms/{vm_key}

说明: 删除虚拟机并自动移除所有关联资源，包括磁盘、NIC、设备和配置。

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

响应: 200 OK 在删除成功时。

自动清理

当你使用 DELETE /api/v4/vms/{vm_key}删除虚拟机时，VergeOS 会自动移除：

所有磁盘 挂载到虚拟机上的
所有网络接口 （NIC）
所有设备 （GPU、PCI 直通、USB、TPM 等）
虚拟机配置 及元数据
Cloud-init 文件 及配置
虚拟机备注 及文档
关联的机器资源

删除前注意事项

删除虚拟机前，请考虑：

数据备份: 确保重要数据已备份
快照: 虚拟机快照可能会随虚拟机一起删除
依赖项: 检查其他系统是否依赖该虚拟机
网络配置: 记录任何特殊网络配置
许可: 考虑软件许可影响

安全删除流程

步骤 1：关闭虚拟机（推荐）

curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "action": "kill",
    "vm": "42"
  }'

步骤 2：验证电源状态

curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate" \\
  -H "Authorization: Bearer YOUR_API_KEY"

步骤 3：创建最终备份（可选）

curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "params": {
      "name": "final-backup-before-deletion",
      "description": "删除虚拟机前的最终备份"
    },
    "action": "clone",
    "vm": "42"
  }'

步骤 4：删除虚拟机及所有资源

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

VM 键用法

使用 VM 键（例如， 42）来自 VM 创建响应或 VM 列表，而不是 machine key。删除过程会自动处理所有关联的机器资源。

无需手动清理

与某些虚拟化平台不同，VergeOS 会自动完成完整的资源清理。你不未需要手动：

删除单个磁盘
移除网络接口
分离设备
清理配置文件
移除机器状态条目

单个 DELETE /api/v4/vms/{vm_key} 操作会自动处理所有清理。

查找孤立资源

# 查找没有关联机器的磁盘
curl "https://your-vergeos.example.com/api/v4/machine_drives?filter=machine%20eq%20null" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# 查找没有关联机器的 NIC
curl "https://your-vergeos.example.com/api/v4/machine_nics?filter=machine%20eq%20null" \\
  -H "Authorization: Bearer YOUR_API_KEY"

错误处理与故障排除

常见错误场景

虚拟机创建失败

错误: 400 错误请求 - 无效的机器类型

{
  "error": "无效的 machine_type 'invalid-type'。有效选项：pc, q35, pc-i440fx-*, pc-q35-*"
}

解决方案: 使用受支持列表中的有效机器类型。

电源状态冲突

错误: 409 冲突 - 虚拟机已在运行

{
  "error": "无法启动虚拟机：已处于运行状态"
}

解决方案: 在发出电源命令前检查当前电源状态。

资源限制

错误: 507 存储空间不足

{
  "error": "第 3 层可用存储空间不足，无法满足请求的磁盘大小"
}

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

克隆失败

错误: 409 冲突 - 克隆名称已存在

{
  "error": "名为 'test clone' 的虚拟机已存在"
}

解决方案: 为克隆的虚拟机使用唯一名称。

监控虚拟机操作

检查操作状态

许多虚拟机操作是异步的。使用以下方式监控进度：

# 检查虚拟机状态
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=machine%23status" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# 检查机器状态以获取运行时信息
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=status,powerstate" \\
  -H "Authorization: Bearer YOUR_API_KEY"

操作超时

为长时间运行的操作设置合适的超时：

VM 创建: 5-10 分钟
克隆操作: 10-30 分钟（取决于大小）
快照创建: 2-5 分钟
快照恢复: 5-15 分钟
电源状态更改: 30-60 秒
虚拟机删除: 2-5 分钟

重试逻辑

为瞬时故障实现重试逻辑：

import time
import requests

def wait_for_operation_completion(vm_id, max_retries=20):
    """等待虚拟机操作完成"""
    for attempt in range(max_retries):
        response = requests.get(
            f"https://your-vergeos.example.com/api/v4/vms/{vm_id}",
            params={"fields": "machine#status#status as operation_status"},
            headers={"Authorization": "Bearer YOUR_API_KEY"}
        )
        
        status = response.json().get("operation_status", "")
        if status not in ["cloning", "snapshotting", "restoring"]:
            return True
            
        time.sleep(10)  # 每次检查之间等待 10 秒
    
    return False

# 示例用法
if wait_for_operation_completion("42"):
    print("操作成功完成")
else:
    print("操作超时")

调试虚拟机问题

检查虚拟机配置

# 获取完整虚拟机配置
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=most" \\
  -H "Authorization: Bearer YOUR_API_KEY"

检查机器状态

# 获取运行时状态和错误
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=most" \\
  -H "Authorization: Bearer YOUR_API_KEY"

检查系统资源

# 检查集群资源
curl "https://your-vergeos.example.com/api/v4/clusters/1?fields=resources" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# 检查存储层
curl "https://your-vergeos.example.com/api/v4/storage_tiers" \\
  -H "Authorization: Bearer YOUR_API_KEY"

最佳实践

始终先测试操作 在开发环境中进行
创建快照 在重大更改前
监控资源使用情况 在操作期间
实施适当的错误处理 在自动化脚本中
使用描述性名称 用于克隆和快照
清理未使用的资源 定期
记录操作流程 供你的团队使用

相关操作

VM 创建：参见 VM 创建 用于初始虚拟机设置
电源管理：参见 VM 电源管理 用于启动/停止操作
配置：参见 VM 配置 用于 CPU/RAM 更改

需要帮助吗？

如需虚拟机高级操作的更多支持：

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

上一页Terraform VergeIO 提供程序

下一页虚拟机配置 API

最后更新于 2个月前

这有帮助吗？