> 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-advanced-operations.md).

# API thao tác nâng cao với VM

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

* Nhân bản VM với cấu hình đầy đủ và sao chép ổ đĩa
* Tạo và khôi phục ảnh chụp nhanh VM để sao lưu và phục hồi
* Xóa VM an toàn với tự động dọn dẹp tài nguyên
* Xử lý lỗi toàn diện và hướng dẫn khắc phục sự cố
  {% endhint %}

Hướng dẫn này bao gồm các thao tác máy ảo nâng cao trong VergeOS, bao gồm nhân bản, quản lý ảnh chụp nhanh, xóa và khắc phục sự cố. Các thao tác này cung cấp khả năng mạnh mẽ cho quản lý vòng đời VM và khôi phục sau thảm họa.

**Giai đoạn**: Thao tác VM nâng cao (4/4) **Đầu vào**: Khóa VM (42), loại thao tác, tham số **Đầu ra**: VM đã nhân bản, ảnh chụp nhanh, xác nhận dọn dẹp **Trước**: VM được cấu hình → [`Cấu hình VM`](/knowledge-base/vi/automation-api/vm-configuration.md) **Các thao tác phổ biến**:

* Nhân bản để tạo mẫu → Chu trình tạo VM mới
* Ảnh chụp nhanh để sao lưu → Quy trình phục hồi
* Xóa để dọn dẹp → Kết thúc vòng đời

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

* "Cách nhân bản VM qua API"
* "Tạo ảnh chụp nhanh và sao lưu VM"
* "Khôi phục VM từ ảnh chụp nhanh"
* "Xóa VM an toàn và dọn dẹp"
* "Khắc phục sự cố và chẩn đoán VM"
* "Quy trình tạo mẫu"
* "Các thao tác khôi phục sau thảm họa"
* "Quản lý VM hàng loạt"
* "Tự động hóa dọn dẹp tài nguyên"

## Tham khảo nhanh

### Các endpoint chính

* **Hành động VM**: `POST /api/v4/vm_actions`
* **Xóa VM**: `DELETE /api/v4/vms/{vm_key}`
* **Liệt kê VM**: `GET /api/v4/vms`

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

* `nhân bản`: Tạo bản sao VM đầy đủ
* `ảnh chụp nhanh`: Tạo ảnh chụp nhanh VM
* `khôi phục`: Khôi phục từ ảnh chụp nhanh

### 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 tồn tại → 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                  |
| ------------------------ | ----------- | ----------------------------- | ------------ | ------------------------- |
| Nhân bản VM              | POST        | `/api/v4/vm_actions`          | VM key       | Tạo bản sao đầy đủ        |
| Tạo ảnh chụp nhanh       | POST        | `/api/v4/vm_actions`          | VM key       | Sao lưu tại một thời điểm |
| Khôi phục ảnh chụp nhanh | POST        | `/api/v4/vm_actions`          | VM key       | Thao tác khôi phục        |
| Liệt kê ảnh chụp nhanh   | GET         | `/api/v4/vms`                 | Truy vấn lọc | Tìm ảnh chụp nhanh        |
| Xóa VM                   | DELETE      | `/api/v4/vms/{id}`            | VM key       | Xóa hoàn toàn             |
| Trạng thái VM            | GET         | `/api/v4/vms/{id}`            | VM key       | Kiểm tra cấu hình         |
| Trạng thái thao tác      | GET         | `/api/v4/machine_status/{id}` | Machine key  | Giám sát thời gian chạy   |

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

* **409 Xung đột**: Tên bản sao đã tồn tại, VM đang chạy, thao tác đang diễn ra
* **507 Không đủ dung lượng lưu trữ**: Không đủ dung lượng cho bản sao, bộ nhớ ảnh chụp nhanh đầy
* **403 Bị cấm**: Quyền của khóa API, bị từ chối truy cập VM, giới hạn cụm
* **404 Không tìm thấy**: Không tìm thấy VM, không tìm thấy ảnh chụp nhanh, khóa VM không hợp lệ
* **408 Hết thời gian chờ yêu cầu**: Thao tác nhân bản hết thời gian chờ, tạo ảnh chụp nhanh hết thời gian chờ
* **422 Không thể xử lý**: Tham số nhân bản không hợp lệ, xung đột khôi phục ảnh chụp nhanh
* **500 Lỗi máy chủ nội bộ**: Sự cố hệ thống lưu trữ, vấn đề hypervisor, lỗi cụm

## Nhân bản VM

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

**Mô tả**: Tạo một bản sao đầy đủ của VM bao gồm tất cả ổ đĩa và cấu hình.

### Nhân bản cơ bản

```json
{
  "params": {
    "name": "bản sao thử nghiệm",
    "quiesce": "true"
  },
  "action": "clone",
  "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 '{
    "params": {
      "name": "bản sao thử nghiệm",
      "quiesce": "true"
    },
    "action": "clone",
    "vm": "42"
  }'
```

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

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

### Tùy chọn nhân bản nâng cao

```json
{
  "params": {
    "name": "bản sao sản xuất",
    "description": "Bản sao máy chủ sản xuất để kiểm thử",
    "preserve_macs": "true",
    "preserve_device_uuids": "true",
    "quiesce": "true",
    "cluster": "2"
  },
  "action": "clone",
  "vm": "42"
}
```

### Tham số nhân bản

| Tham số                 | Loại  | Bắt buộc | Mô tả                                                                             |
| ----------------------- | ----- | -------- | --------------------------------------------------------------------------------- |
| name                    | chuỗi | Có       | Tên cho VM đã nhân bản                                                            |
| description             | chuỗi | Không    | Mô tả cho bản sao                                                                 |
| quiesce                 | chuỗi | Không    | Tạm dừng VM trước khi nhân bản ("true"/"false") để đảm bảo tính nhất quán dữ liệu |
| preserve\_macs          | chuỗi | Không    | Giữ nguyên địa chỉ MAC ("true"/"false")                                           |
| preserve\_device\_uuids | chuỗi | Không    | Giữ nguyên UUID thiết bị ("true"/"false")                                         |
| cluster                 | chuỗi | Không    | ID cụm đích                                                                       |

{% hint style="success" %}
**Tùy chọn nhân bản**

* **Tạm dừng**: Dùng `"quiesce": "true"` để đảm bảo tính nhất quán dữ liệu bằng cách tạm dừng VM trong thời gian ngắn
* **Giữ nguyên MAC**: Dùng `"preserve_macs": "true"` để giữ nguyên cùng địa chỉ MAC (có thể gây xung đột mạng)
* **Giữ nguyên UUID thiết bị**: Dùng `"preserve_device_uuids": "true"` để duy trì các định danh thiết bị
* **Liên cụm**: Chỉ định ID cụm khác để nhân bản sang cụm khác
  {% endhint %}

### Ví dụ quy trình nhân bản

```bash
# Bước 1: Tạo bản sao
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": "Bản sao sao lưu tự động",
      "quiesce": "true"
    },
    "action": "clone",
    "vm": "42"
  }'

# Bước 2: Xác minh việc tạo bản sao (dùng vmkey trả về)
curl "https://your-vergeos.example.com/api/v4/vms/43?fields=name,description,created" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# Bước 3: Kiểm tra trạng thái nguồn điện của bản sao
curl "https://your-vergeos.example.com/api/v4/machine_status/55?fields=powerstate,status" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Ảnh chụp nhanh VM

### Tạo ảnh chụp nhanh

```json
{
  "vm": "42",
  "action": "snapshot",
  "params": {
    "name": "ảnh chụp trước cập nhật",
    "description": "Trước khi cập nhật hệ thống"
  }
}
```

**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 '{
    "vm": "42",
    "action": "snapshot",
    "params": {
      "name": "ảnh chụp trước cập nhật",
      "description": "Trước khi cập nhật hệ thống - $(date)"
    }
  }'
```

### Khôi phục từ ảnh chụp nhanh

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

**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 '{
    "vm": "42",
    "action": "restore",
    "params": {
      "snapshot_id": "snapshot-67890"
    }
  }'
```

### Liệt kê ảnh chụp nhanh VM

#### GET /api/v4/vms

Dùng bộ lọc để tìm ảnh chụp nhanh:

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

**Tìm tất cả ảnh chụp nhanh cho một VM**:

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

### Quy trình quản lý ảnh chụp nhanh

```bash
# Bước 1: Tạo ảnh chụp nhanh trước khi bảo trì
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": "Ảnh chụp trước bảo trì"
    }
  }'

# Bước 2: Liệt kê ảnh chụp nhanh để tìm ID ảnh chụp nhanh
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"

# Bước 3: Khôi phục nếu cần (sau khi có sự cố bảo trì)
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"
    }
  }'
```

## Xóa VM và dọn dẹp

### Xóa hoàn toàn VM

#### DELETE /api/v4/vms/{vm\_key}

**Mô tả**: Xóa VM và tự động gỡ bỏ tất cả tài nguyên liên quan, bao gồm ổ đĩa, NIC, thiết bị và cấu hình.

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

**Phản hồi**: `200 OK` khi xóa thành công.

{% hint style="success" %}
**Tự động dọn dẹp**

Khi bạn xóa một VM bằng `DELETE /api/v4/vms/{vm_key}`, VergeOS tự động xóa:

* **Tất cả ổ đĩa** gắn vào VM
* **Tất cả giao diện mạng** (NIC)
* **Tất cả thiết bị** (GPU, PCI passthrough, USB, TPM, v.v.)
* **cấu hình VM** và siêu dữ liệu
* **Tệp cloud-init** và cấu hình
* **ghi chú VM** và tài liệu
* **các tài nguyên máy liên quan**
  {% endhint %}

### Các lưu ý trước khi xóa

Trước khi xóa VM, hãy cân nhắc:

1. **Sao lưu dữ liệu**: Đảm bảo dữ liệu quan trọng đã được sao lưu
2. **Ảnh chụp nhanh**: Ảnh chụp nhanh VM có thể bị xóa cùng với VM
3. **Các phụ thuộc**: Kiểm tra xem các hệ thống khác có phụ thuộc vào VM này không
4. **Cấu hình mạng**: Ghi chú mọi cấu hình mạng đặc biệt
5. **Bản quyền**: Cân nhắc các tác động liên quan đến cấp phép phần mềm

### Quy trình xóa an toàn

#### Bước 1: Tắt nguồn VM (Khuyến nghị)

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

#### Bước 2: Xác minh trạng thái nguồn

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

#### Bước 3: Tạo bản sao lưu cuối cùng (Tùy chọn)

```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 '{
    "params": {
      "name": "bản sao lưu cuối trước khi xóa",
      "description": "Bản sao lưu cuối cùng trước khi xóa VM"
    },
    "action": "clone",
    "vm": "42"
  }'
```

#### Bước 4: Xóa VM và toàn bộ tài nguyên

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

{% hint style="success" %}
**Cách dùng khóa VM**

Dùng khóa VM (ví dụ, `42`) từ phản hồi tạo VM hoặc danh sách VM, không phải machine key. Quy trình xóa sẽ tự động xử lý tất cả tài nguyên máy liên quan.
{% endhint %}

### Không cần dọn dẹp thủ công

Không giống một số nền tảng ảo hóa khác, VergeOS tự động xử lý việc dọn dẹp tài nguyên hoàn chỉnh. Bạn **không** không cần phải thủ công:

* Xóa từng ổ đĩa riêng lẻ
* Gỡ bỏ giao diện mạng
* Ngắt kết nối thiết bị
* Dọn dẹp các tệp cấu hình
* Xóa các mục trạng thái máy

Thao tác `DELETE /api/v4/vms/{vm_key}` duy nhất sẽ tự động xử lý toàn bộ việc dọn dẹp.

### Tìm tài nguyên mồ côi

```bash
# Tìm các ổ đĩa không có máy liên quan
curl "https://your-vergeos.example.com/api/v4/machine_drives?filter=machine%20eq%20null" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# Tìm các NIC không có máy liên quan
curl "https://your-vergeos.example.com/api/v4/machine_nics?filter=machine%20eq%20null" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Xử lý lỗi và khắc phục sự cố

### Các tình huống lỗi phổ biến

#### Lỗi tạo VM

**Lỗi**: `400 Yêu cầu không hợp lệ - Loại máy không hợp lệ`

```json
{
  "error": "Invalid machine_type 'invalid-type'. Valid options: pc, q35, pc-i440fx-*, pc-q35-*"
}
```

**Giải pháp**: Dùng các loại máy hợp lệ từ danh sách được hỗ trợ.

#### Xung đột trạng thái nguồ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.

#### Giới hạn tài nguyên

**Lỗi**: `507 Không đủ dung lượng lưu trữ`

```json
{
  "error": "Insufficient storage space in tier 3 for requested disk size"
}
```

**Giải pháp**: Chọn tầng lưu trữ khác hoặc giảm kích thước đĩa.

#### Lỗi nhân bản

**Lỗi**: `409 Xung đột - Tên bản sao đã tồn tại`

```json
{
  "error": "VM with name 'test clone' already exists"
}
```

**Giải pháp**: Dùng tên duy nhất cho các VM đã nhân bản.

### Giám sát các thao tác VM

#### Kiểm tra trạng thái thao tác

Nhiều thao tác VM là không đồng bộ. Theo dõi tiến trình bằng:

```bash
# Kiểm tra trạng thái VM
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=machine%23status" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# Kiểm tra trạng thái máy để lấy thông tin thời gian chạy
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=status,powerstate" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

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

Đặt thời gian chờ phù hợp cho các thao tác kéo dài:

* **Tạo VM**: 5-10 phút
* **Thao tác nhân bản**: 10-30 phút (tùy kích thước)
* **Tạo ảnh chụp nhanh**: 2-5 phút
* **Khôi phục ảnh chụp nhanh**: 5-15 phút
* **Thay đổi trạng thái nguồn**: 30-60 giây
* **Xóa VM**: 2-5 phút

### Logic thử lại

Triển khai logic thử lại cho các lỗi tạm thời:

```python
import time
import requests

def wait_for_operation_completion(vm_id, max_retries=20):
    """Chờ thao tác VM hoàn tất"""
    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)  # Chờ 10 giây giữa các lần kiểm tra
    
    return False

# Ví dụ sử dụng
if wait_for_operation_completion("42"):
    print("Thao tác hoàn tất thành công")
else:
    print("Thao tác đã hết thời gian chờ")
```

### Gỡ lỗi sự cố VM

#### Kiểm tra cấu hình VM

```bash
# Lấy cấu hình VM đầy đủ
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=most" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### Kiểm tra trạng thái máy

```bash
# Lấy trạng thái thời gian chạy và lỗi
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=most" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### Kiểm tra tài nguyên hệ thống

```bash
# Kiểm tra tài nguyên cụm
curl "https://your-vergeos.example.com/api/v4/clusters/1?fields=resources" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# Kiểm tra các tầng lưu trữ
curl "https://your-vergeos.example.com/api/v4/storage_tiers" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Các phương pháp hay nhất

1. **Luôn kiểm thử các thao tác** trước tiên trong môi trường phát triển
2. **Tạo ảnh chụp nhanh** trước các thay đổi lớn
3. **Theo dõi mức sử dụng tài nguyên** trong quá trình thao tác
4. **Triển khai xử lý lỗi đúng cách** trong các tập lệnh tự động hóa
5. **Dùng tên mô tả rõ ràng** cho các bản sao và ảnh chụp nhanh
6. **Dọn dẹp các tài nguyên không dùng** thường xuyên
7. **Ghi lại các quy trình vận hành** cho nhóm của bạn

{% 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) cho quá trình thiết lập VM ban đầu
* **Quản lý nguồn điện**: xem [`Quản lý nguồn VM`](/knowledge-base/vi/automation-api/vm-power-management.md) cho các thao tác khởi động/dừng
* **Cấu hình**: xem [`Cấu hình VM`](/knowledge-base/vi/automation-api/vm-configuration.md) để thay đổi CPU/RAM
  {% endhint %}

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

Để được hỗ trợ thêm về các thao tác VM nâng cao:

* 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-advanced-operations.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.