虚拟机电源管理 API

VergeOS 中管理虚拟机电源状态的完整指南，包括启动、停止、重启和监控电源状态。

要点

通过 REST API 端点控制虚拟机电源状态
支持优雅关机和强制电源操作
监控虚拟机电源状态和运行时状态
了解虚拟机键与机器键在不同状态检查中的区别

本指南介绍在 VergeOS 中管理虚拟机电源状态，包括启动、停止、重启和监控虚拟机。VergeOS API 提供了全面的电源管理功能，支持优雅操作和强制操作。

阶段：虚拟机电源管理（4 之 2）输入：从创建开始的虚拟机键（42）、电源操作类型输出：电源状态变化、运行时状态 上一页：虚拟机已创建 → VM 创建 常见下一步:

配置虚拟机设置 → VM 配置
高级操作 → VM 高级操作

本文档适用于

“如何通过 API 启动/停止虚拟机”
“检查虚拟机电源状态”
“优雅关机与强制关机”
“虚拟机重启和重置操作”
“监控虚拟机电源状态”
“电源管理自动化”
“虚拟机启动故障排查”
“计划的电源操作”
“通过电源控制实现资源优化”

快速参考

主要端点

电源操作: POST /api/v4/vm_actions
VM 状态: GET /api/v4/vms/{id}
电源状态: GET /api/v4/machine_status/{machine_id}

关键操作

poweron：启动虚拟机
poweroff：优雅关机（ACPI）
kill：强制断电
reset：重启虚拟机

身份验证

-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 键

优雅关机（ACPI）

强制关闭

POST

/api/v4/vm_actions

VM 键

立即终止

重新启动

POST

/api/v4/vm_actions

VM 键

重启虚拟机

虚拟机信息

GET

/api/v4/vms/{id}

VM 键

配置数据

电源状态

GET

/api/v4/machine_status/{id}

Machine 键

运行时状态

故障排查索引

409 冲突：虚拟机已在运行、虚拟机未运行、电源状态不匹配
507 资源不足：集群资源不足，内存/CPU 不可用
403 禁止访问：API 密钥权限不足、集群访问被拒绝、虚拟机访问受限
404 未找到：虚拟机键无效、虚拟机已删除、未找到机器键
408 请求超时：电源操作超时、虚拟机无响应、集群通信失败
500 内部服务器错误：虚拟机管理程序问题、节点问题、存储故障

启动虚拟机

POST /api/v4/vm_actions

说明：为虚拟机通电并等待其进入运行状态。

通电请求:

{
  "action": "poweron",
  "params": {},
  "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 '{
    "action": "poweron",
    "params": {},
    "vm": "42"
  }'

响应: 201 已创建 当操作被发起时。

最佳实践

通电前始终验证虚拟机配置
确保所有必需的磁盘和网络接口都已连接
检查集群资源可用性
确认虚拟机尚未运行，以避免冲突

停止虚拟机

优雅断电（ACPI）

说明：向来宾操作系统发送 ACPI 关机信号，使其可以正常关闭。

{
  "action": "poweroff",
  "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 '{
    "action": "poweroff",
    "vm": "42"
  }'

强制断电（Kill）

说明：立即终止虚拟机，不允许来宾操作系统正常关闭。仅在优雅关机失败时使用。

{
  "action": "kill",
  "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 '{
    "action": "kill",
    "vm": "42"
  }'

强制断电

使用 kill 操作可能导致数据丢失或损坏。始终先尝试优雅 poweroff ，只有在必要时才使用 kill 。

重启虚拟机

优雅重启（ACPI）

说明：向来宾操作系统发送 ACPI 重置信号，以便干净地重新启动。

{
  "action": "reset",
  "params": {
    "graceful": true
  },
  "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 '{
    "action": "reset",
    "params": {
      "graceful": true
    },
    "vm": "42"
  }'

硬重置（电源循环）

说明：立即重启虚拟机，不允许来宾操作系统正常关闭。

{
  "action": "reset",
  "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 '{
    "action": "reset",
    "vm": "42"
  }'

虚拟机状态和信息

GET /api/v4/vms/{id}

说明：使用各种字段过滤器检索虚拟机配置和元数据。

获取完整虚拟机信息:

curl "https://your-vergeos.example.com/api/v4/vms/42?fields=most" \\
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例:

{
  "$key": 42,
  "name": "test",
  "machine": 54,
  "description": "测试虚拟机",
  "enabled": true,
  "created": 1755991665,
  "modified": 1755993248,
  "is_snapshot": false,
  "machine_type": "pc-q35-9.0",
  "allow_hotplug": true,
  "guest_agent": true,
  "cpu_cores": 3,
  "cpu_type": "host",
  "ram": 16384,
  "console": "spice",
  "video": "qxl",
  "sound": "none",
  "os_family": "linux",
  "rtc_base": "utc",
  "boot_order": "cd",
  "console_pass_enabled": false,
  "usb_tablet": true,
  "uefi": true,
  "secure_boot": false,
  "serial_port": false,
  "boot_delay": 5,
  "uuid": "821e96ec-2479-7cc4-7c14-c623557bdd2b",
  "need_restart": false,
  "console_status": 42,
  "cloudinit_datasource": "none",
  "imported": false,
  "created_from": "custom",
  "migration_method": "auto",
  "note": "这是一台测试虚拟机",
  "power_cycle_timeout": 0,
  "allow_export": true,
  "creator": "admin",
  "nested_virtualization": true,
  "disable_hypervisor": true,
  "usb_legacy": false
}

虚拟机电源状态和运行时状态

GET /api/v4/machine_status/{machine_id}

说明：使用机器键检索虚拟机的实际运行时状态和电源状态。

检查虚拟机电源状态:

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

已停止虚拟机响应示例

{
  "$key": 54,
  "machine": 54,
  "running": false,
  "migratable": true,
  "node": null,
  "migrated_node": null,
  "migration_destination": null,
  "started": 1755993338,
  "local_time": 0,
  "status": "stopped",
  "status_info": "",
  "state": "offline",
  "powerstate": false,
  "last_update": 1755993358,
  "running_cores": 3,
  "running_ram": 16384,
  "agent_version": "",
  "agent_features": [],
  "agent_guest_info": []
}

运行中虚拟机响应示例

{
  "$key": 44,
  "machine": 44,
  "running": true,
  "migratable": true,
  "node": 3,
  "migrated_node": null,
  "migration_destination": null,
  "started": 1755460982,
  "local_time": 0,
  "status": "running",
  "status_info": "",
  "state": "online",
  "powerstate": true,
  "last_update": 1755993927,
  "running_cores": 6,
  "running_ram": 12288,
  "agent_version": "",
  "agent_features": [],
  "agent_guest_info": []
}

虚拟机与机器状态

虚拟机信息 (/api/v4/vms/{vm_key}）：配置、设置和元数据
电源状态 (/api/v4/machine_status/{machine_key}）：运行时状态、电源状态和资源使用情况
始终使用机器键（而不是虚拟机键）来检查实际电源状态和运行时状态

状态字段

powerstate：表示虚拟机是否已通电的布尔值
running：表示虚拟机当前是否正在运行的布尔值
status：文本状态（“running”、“stopped”等）
state：整体状态（“online”、“offline”）
node：虚拟机运行所在的物理节点（停止时为 null）

电源状态监控

仅检查电源状态

对于快速检查电源状态，你可以请求特定字段：

# 仅检查电源状态
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,running,status" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应:

{
  "powerstate": true,
  "running": true,
  "status": "running"
}

监控电源状态变化

import time
import requests

def wait_for_power_state(machine_id, desired_state, max_retries=10):
    """等待虚拟机达到期望的电源状态"""
    for attempt in range(max_retries):
        response = requests.get(
            f"https://your-vergeos.example.com/api/v4/machine_status/{machine_id}",
            params={"fields": "powerstate,running,status"},
            headers={"Authorization": "Bearer YOUR_API_KEY"}
        )
        
        data = response.json()
        if data.get("powerstate") == desired_state:
            return True
            
        time.sleep(5)  # 每次检查之间等待 5 秒
    
    return False

# 示例用法
if wait_for_power_state("54", True):
    print("虚拟机现在正在运行")
else:
    print("虚拟机未能在超时时间内启动")

常见电源管理工作流

安全关闭虚拟机工作流

# 第 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": "poweroff", "vm": "42"}'

# 第 2 步：等待并检查状态（按需重复）
sleep 30
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,status" \
  -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 '{"action": "kill", "vm": "42"}'

虚拟机重启工作流

# 第 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": "reset",
    "params": {"graceful": true},
    "vm": "42"
  }'

# 第 2 步：监控重启进度
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,status,node" \
  -H "Authorization: Bearer YOUR_API_KEY"

错误处理

常见电源管理错误

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

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

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

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

{
  "error": "无法关闭虚拟机：未处于运行状态"
}

解决方案：在尝试关机前，验证虚拟机是否确实正在运行。

错误: 507 资源不足

{
  "error": "启动虚拟机所需的集群资源不足"
}

解决方案：检查集群资源可用性，或降低虚拟机资源需求。

操作超时

为电源操作设置适当的超时时间：

开机: 30-60 秒
优雅关机：60-120 秒
强制关机：10-30 秒
重新启动：60-120 秒

相关操作

VM 创建：参见 VM 创建 用于创建虚拟机
配置：参见 VM 配置 用于 CPU/RAM 更改
高级操作：参见 VM 高级操作 用于克隆和快照

需要帮助吗？

如需有关虚拟机电源管理的更多支持：

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

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

下一页系统管理

最后更新于 2个月前

这有帮助吗？