> 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/vi/automation-api/vm-power-management.md).

# API quản lý nguồn VM

{% hint style="info" %}
**Các điểm chính**

* Điều khiển trạng thái nguồn của VM thông qua các endpoint REST API
* Hỗ trợ các thao tác nguồn nhẹ nhàng và cưỡng bức
* Giám sát trạng thái nguồn và trạng thái chạy thời gian thực của VM
* Hiểu sự khác nhau giữa VM key và Machine key cho các kiểm tra trạng thái khác nhau
  {% endhint %}

Hướng dẫn này bao gồm việc quản lý trạng thái nguồn của máy ảo trong VergeOS, bao gồm khởi động, dừng, khởi động lại và giám sát VM. API VergeOS cung cấp các khả năng quản lý nguồn toàn diện với cả thao tác nhẹ nhàng và cưỡng bức.

**Giai đoạn**: Quản lý nguồn VM (2/4) **Đầu vào**: VM key (42) từ lúc tạo, loại thao tác nguồn **Đầu ra**: Thay đổi trạng thái nguồn, trạng thái chạy thời gian thực **Trước**: VM đã tạo → [`Tạo VM`](/knowledge-base/vi/automation-api/vm-creation-api.md) **Các bước tiếp theo phổ biến**:

* Cấu hình cài đặt VM → [`Cấu hình VM`](/knowledge-base/vi/automation-api/vm-configuration.md)
* Thao tác nâng cao → [`Các thao tác nâng cao của VM`](/knowledge-base/vi/automation-api/vm-advanced-operations.md)

## Tài liệu này hỗ trợ

* "Cách khởi động/dừng VM qua API"
* "Kiểm tra trạng thái nguồn của VM"
* "Tắt VM nhẹ nhàng vs cưỡng bức"
* "Thao tác khởi động lại và reset VM"
* "Giám sát trạng thái nguồn của VM"
* "Tự động hóa quản lý nguồn"
* "Khắc phục sự cố khởi động VM"
* "Các thao tác nguồn theo lịch"
* "Tối ưu tài nguyên thông qua kiểm soát nguồn"

## Tham khảo nhanh

### Các endpoint chính

* **Các thao tác nguồn**: `POST /api/v4/vm_actions`
* **Trạng thái VM**: `GET /api/v4/vms/{id}`
* **Trạng thái nguồn điện**: `GET /api/v4/machine_status/{machine_id}`

### Các thao tác chính

* `poweron`: Khởi động VM
* `poweroff`: Tắt máy nhẹ nhàng (ACPI)
* `kill`: Buộc tắt nguồn
* `reset`: Khởi động lại VM

### Xác thực

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

### Điều kiện tiên quyết

VM phải được tạo trước → Xem [`Tạo VM`](/knowledge-base/vi/automation-api/vm-creation-api.md)

## Tham khảo nhanh API

| Thao tác              | Phương thức | Endpoint                      | Loại khóa   | Mục đích                       |
| --------------------- | ----------- | ----------------------------- | ----------- | ------------------------------ |
| Bật nguồn             | POST        | `/api/v4/vm_actions`          | VM key      | Khởi động máy ảo               |
| Tắt nguồn             | POST        | `/api/v4/vm_actions`          | VM key      | Tắt máy nhẹ nhàng (ACPI)       |
| Buộc tắt              | POST        | `/api/v4/vm_actions`          | VM key      | Kết thúc ngay lập tức          |
| Khởi động lại         | POST        | `/api/v4/vm_actions`          | VM key      | Khởi động lại VM               |
| Thông tin VM          | GET         | `/api/v4/vms/{id}`            | VM key      | Dữ liệu cấu hình               |
| Trạng thái nguồn điện | GET         | `/api/v4/machine_status/{id}` | Machine key | Trạng thái chạy thời gian thực |

## Chỉ mục khắc phục sự cố

* **409 Xung đột**: VM đã chạy, VM chưa chạy, trạng thái nguồn không khớp
* **507 Không đủ tài nguyên**: Không đủ tài nguyên cụm, bộ nhớ/CPU không khả dụng
* **403 Bị cấm**: Quyền khóa API, bị từ chối truy cập cụm, truy cập VM bị hạn chế
* **404 Không tìm thấy**: VM key không hợp lệ, VM đã bị xóa, không tìm thấy machine key
* **408 Hết thời gian chờ yêu cầu**: Hết thời gian chờ thao tác nguồn, VM không phản hồi, lỗi giao tiếp với cụm
* **500 Lỗi máy chủ nội bộ**: Sự cố hypervisor, sự cố node, lỗi lưu trữ

## Khởi động VM

### POST /api/v4/vm\_actions

**Mô tả**: Bật nguồn một máy ảo và chờ cho đến khi nó đạt trạng thái đang chạy.

**Yêu cầu bật nguồn**:

```json
{
  "action": "poweron",
  "params": {},
  "vm": "42"
}
```

**Lệnh API đầy đủ**:

```bash
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"
  }'
```

**Phản hồi**: `201 Đã tạo` khi hành động được khởi chạy.

{% hint style="success" %}
**Các phương pháp hay nhất**

* Luôn kiểm tra cấu hình VM trước khi bật nguồn
* Đảm bảo tất cả ổ đĩa và giao diện mạng bắt buộc đã được gắn
* Kiểm tra tính sẵn sàng của tài nguyên cụm
* Xác minh VM chưa chạy để tránh xung đột
  {% endhint %}

## Dừng VM

### Tắt nguồn nhẹ nhàng (ACPI)

**Mô tả**: Gửi tín hiệu tắt máy ACPI tới hệ điều hành khách, cho phép nó tắt sạch sẽ.

```json
{
  "action": "poweroff",
  "vm": "42"
}
```

**Lệnh API đầy đủ**:

```bash
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"
  }'
```

### Buộc tắt nguồn (Kill)

**Mô tả**: Kết thúc VM ngay lập tức mà không cho phép hệ điều hành khách tắt sạch sẽ. Chỉ dùng khi tắt máy nhẹ nhàng thất bại.

```json
{
  "action": "kill",
  "vm": "42"
}
```

**Lệnh API đầy đủ**:

```bash
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"
  }'
```

{% hint style="warning" %}
**Buộc tắt nguồn**

Sử dụng `kill` hành động này có thể gây mất dữ liệu hoặc hỏng dữ liệu. Luôn thử nhẹ nhàng `poweroff` trước và chỉ sử dụng `kill` khi cần thiết.
{% endhint %}

## Khởi động lại VM

### Khởi động lại nhẹ nhàng (ACPI)

**Mô tả**: Gửi tín hiệu reset ACPI tới hệ điều hành khách để khởi động lại sạch sẽ.

```json
{
  "action": "reset",
  "params": {
    "graceful": true
  },
  "vm": "42"
}
```

**Lệnh API đầy đủ**:

```bash
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"
  }'
```

### Hard Reset (Chu kỳ nguồn)

**Mô tả**: Khởi động lại VM ngay lập tức mà không cho phép hệ điều hành khách tắt sạch sẽ.

```json
{
  "action": "reset",
  "vm": "42"
}
```

**Lệnh API đầy đủ**:

```bash
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"
  }'
```

## Trạng thái và thông tin VM

### GET /api/v4/vms/{id}

**Mô tả**: Lấy cấu hình và siêu dữ liệu của VM bằng nhiều bộ lọc trường khác nhau.

**Lấy thông tin VM đầy đủ**:

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

**Ví dụ phản hồi**:

```json
{
  "$key": 42,
  "name": "test",
  "machine": 54,
  "description": "test vm",
  "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": "Đây là một VM thử nghiệm",
  "power_cycle_timeout": 0,
  "allow_export": true,
  "creator": "admin",
  "nested_virtualization": true,
  "disable_hypervisor": true,
  "usb_legacy": false
}
```

## Trạng thái nguồn và trạng thái chạy của VM

### GET /api/v4/machine\_status/{machine\_id}

**Mô tả**: Lấy trạng thái chạy thực tế và trạng thái nguồn của VM bằng machine key.

**Kiểm tra trạng thái nguồn của VM**:

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

### Ví dụ phản hồi của VM đã dừng

```json
{
  "$key": 54,
  "machine": 54,
  "running": false,
  "migratable": true,
  "node": null,
  "migrated_node": null,
  "migration_destination": null,
  "started": 1755993338,
  "local_time": 0,
  "status": "đã dừng",
  "status_info": "",
  "state": "ngoại tuyến",
  "powerstate": false,
  "last_update": 1755993358,
  "running_cores": 3,
  "running_ram": 16384,
  "agent_version": "",
  "agent_features": [],
  "agent_guest_info": []
}
```

### Ví dụ phản hồi của VM đang chạy

```json
{
  "$key": 44,
  "machine": 44,
  "running": true,
  "migratable": true,
  "node": 3,
  "migrated_node": null,
  "migration_destination": null,
  "started": 1755460982,
  "local_time": 0,
  "status": "đang chạy",
  "status_info": "",
  "state": "trực tuyến",
  "powerstate": true,
  "last_update": 1755993927,
  "running_cores": 6,
  "running_ram": 12288,
  "agent_version": "",
  "agent_features": [],
  "agent_guest_info": []
}
```

{% hint style="success" %}
**Trạng thái VM so với trạng thái máy**

* **Thông tin VM** (`/api/v4/vms/{vm_key}`): Cấu hình, cài đặt và siêu dữ liệu
* **Trạng thái nguồn điện** (`/api/v4/machine_status/{machine_key}`): Trạng thái chạy, trạng thái nguồn và mức sử dụng tài nguyên
* Luôn dùng machine key (không phải VM key) để kiểm tra trạng thái nguồn thực tế và trạng thái chạy
  {% endhint %}

{% hint style="success" %}
**Các trường trạng thái**

* `powerstate`: Giá trị boolean cho biết VM đã được bật nguồn hay chưa
* `running`: Giá trị boolean cho biết VM hiện có đang chạy hay không
* `status`: Trạng thái dạng văn bản ("running", "stopped", v.v.)
* `state`: Trạng thái tổng thể ("online", "offline")
* `node`: Node vật lý nào mà VM đang chạy trên đó (null nếu đã dừng)
  {% endhint %}

## Giám sát trạng thái nguồn

### Chỉ kiểm tra trạng thái nguồn

Để kiểm tra nhanh trạng thái nguồn, bạn có thể yêu cầu các trường cụ thể:

```bash
# Chỉ kiểm tra trạng thái nguồn
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,running,status" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Phản hồi**:

```json
{
  "powerstate": true,
  "running": true,
  "status": "đang chạy"
}
```

### Giám sát thay đổi trạng thái nguồn

```python
import time
import requests

def wait_for_power_state(machine_id, desired_state, max_retries=10):
    """Chờ VM đạt trạng thái nguồn mong muốn"""
    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)  # Chờ 5 giây giữa các lần kiểm tra
    
    return False

# Ví dụ sử dụng
if wait_for_power_state("54", True):
    print("VM hiện đang chạy")
else:
    print("VM không thể khởi động trong thời gian chờ")
```

## Các quy trình quản lý nguồn phổ biến

### Quy trình tắt VM an toàn

```bash
# Bước 1: Thử tắt máy nhẹ nhàng
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"}'

# Bước 2: Chờ và kiểm tra trạng thái (lặp lại khi cần)
sleep 30
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,status" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# Bước 3: Buộc tắt nếu tắt nhẹ nhàng thất bại (sau thời gian chờ hợp lý)
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"}'
```

### Quy trình khởi động lại VM

```bash
# Bước 1: Khởi động lại nhẹ nhàng
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"
  }'

# Bước 2: Theo dõi tiến trình khởi động lại
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,status,node" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Xử lý lỗi

### Các lỗi quản lý nguồn phổ biến

**Lỗi**: `409 Xung đột - VM đang chạy`

```json
{
  "error": "Cannot power on VM: already in running state"
}
```

**Giải pháp**: Kiểm tra trạng thái nguồn hiện tại trước khi gửi lệnh bật nguồn.

**Lỗi**: `409 Xung đột - VM chưa chạy`

```json
{
  "error": "Không thể tắt nguồn VM: không ở trạng thái đang chạy"
}
```

**Giải pháp**: Xác minh VM thực sự đang chạy trước khi thử tắt.

**Lỗi**: `507 Không đủ tài nguyên`

```json
{
  "error": "Không đủ tài nguyên cụm để khởi động VM"
}
```

**Giải pháp**: Kiểm tra tính sẵn sàng của tài nguyên cụm hoặc giảm yêu cầu tài nguyên của VM.

### Hết thời gian chờ thao tác

Đặt thời gian chờ phù hợp cho các thao tác nguồn:

* **Bật nguồn**: 30-60 giây
* **Tắt nhẹ nhàng**: 60-120 giây
* **Buộc tắt**: 10-30 giây
* **Khởi động lại**: 60-120 giây

{% hint style="info" %}
**Các thao tác liên quan**

* **Tạo VM**: xem [`Tạo VM`](/knowledge-base/vi/automation-api/vm-creation-api.md) để tạo VM
* **Cấu hình**: xem [`Cấu hình VM`](/knowledge-base/vi/automation-api/vm-configuration.md) để thay đổi CPU/RAM
* **Các thao tác nâng cao**: xem [`Các thao tác nâng cao của VM`](/knowledge-base/vi/automation-api/vm-advanced-operations.md) để sao chép và snapshot
  {% endhint %}

{% hint style="info" %}
**Cần trợ giúp?**

Để được hỗ trợ thêm về quản lý nguồn VM:

* Kiểm tra cổng tài liệu VergeOS
* Liên hệ bộ phận hỗ trợ VergeOS với các thông báo lỗi cụ thể
* Xem lại nhật ký hệ thống để biết thông tin lỗi chi tiết
* Tham khảo các diễn đàn cộng đồng 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/vi/automation-api/vm-power-management.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.