使用 API 强制关闭虚拟机电源

使用 VergeOS API 和 Swagger 界面强制关闭无响应虚拟机的分步说明，包括如何查找虚拟机 ID、验证状态并发出关机命令。

概述

要点

• 使用 VergeOS API 强制关闭卡死的虚拟机
• 需要 API/Swagger 访问权限
• 该流程涉及多次 API 调用，以确保目标定位准确
• 仅应在常规关机方法失败时使用

本指南说明在标准关机方法无效时，如何使用 VergeOS API 强制关闭无响应的虚拟机（VM）。

前提条件

• 具有管理员权限的 VergeOS UI 访问权限
• 卡死/无响应的虚拟机名称
• 对 API 操作有基本了解

重要提示

此流程仅应在标准关机方法失败时使用。不谨慎使用时，强制关闭虚拟机可能导致数据丢失或损坏。

步骤

1. 访问 API 文档

1. 导航到 系统 在 VergeOS UI 中
2. 点击 API Documentation （也称为 Swagger）

2. 找到 VM ID

1. 在 API 界面中，找到并展开 虚拟机 表
2. 点击蓝色的 GET 按钮
3. 在参数部分：

   • 使用过滤条件 name eq your_vm_name 来查找特定虚拟机
4. 点击 执行
5. 记下 机器 响应中的编号

3. 获取机器状态 ID

1. 导航到 machines 表
2. 点击蓝色的 GEt /machines/{id}
3. 在参数中：

   • 设置 id 到 上一条响应中的机器编号
   • 设置 fields 更改为 status
4. 点击 执行
5. 从响应中，记下 status 值

4. 验证机器状态

1. 前往 machine_status 表
2. 点击蓝色的 GET /machine_stats/{id}
3. 在参数中：

   • 设置 id 更改为 status_number （使用第 3 步中的状态值）
   • 设置 fields 更改为 most
4. 点击 执行
5. 通过检查以下内容，确认这是一台正确的虚拟机：

   • CPU 核心数
   • RAM 分配
   • 状态信息
   • 机器编号

5. 强制关机

1. 在 machine_status 表，点击 PUT
2. 将状态编号输入为 id 资源 ID
3. 在请求正文中，输入以下 JSON：

{
    "running": false,
    "migratable": true,
    "status": "stopped",
    "state": "offline"
}

1. 点击 执行

6. 验证关机

1. 返回 VergeOS UI
2. 确认该虚拟机显示为已关机

故障排除

常见问题

• 如果在 API 调用后虚拟机没有显示为已关机，请等待几分钟让状态更新
• 如果状态没有更新，请确认前面步骤中的所有 ID 是否正确
• 如有错误，请查看 API 响应中的具体错误信息

附加说明

• 在进行更改之前，务必记录虚拟机的 ID 和状态值
• 如果可能，考虑在强制关机前为虚拟机创建快照
• 强制关机后监控虚拟机，确保在需要时能正常启动

---

反馈

需要帮助吗？

如果您对该流程不太熟悉，请联系我们的支持团队寻求帮助。

---

文档信息

• 最后更新：2024-01-28
• VergeOS 版本：全部