> 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/force-power-off-vm-using-api.md).

# 使用 API 强制关闭虚拟机

## 概述

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

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

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

## 前提条件

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

{% hint style="warning" %}
**重要提示**

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

## 步骤

### 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：

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

4. 点击 **执行**

### 6. 验证关机

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

## 故障排除

{% hint style="warning" %}
**常见问题**

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

## 附加说明

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

***

## 反馈

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

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

***

{% hint style="info" %}
**文档信息**

* 最后更新：2024-01-28
* 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/force-power-off-vm-using-api.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.