> 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-configuration.md). # API cấu hình VM {% hint style="info" %} **Các điểm chính** * Sửa các cài đặt VM như CPU, RAM, console và video thông qua REST API * Quản lý ổ đĩa với khả năng thay đổi kích thước, thêm và xóa * Cập nhật các giao diện mạng và cấu hình của chúng * Thêm ghi chú tài liệu vào VM để theo dõi vận hành {% endhint %} Hướng dẫn này bao gồm việc sửa cấu hình máy ảo trong VergeOS sau khi tạo, bao gồm cập nhật CPU/RAM, quản lý ổ đĩa, thay đổi giao diện mạng và thêm ghi chú vận hành. **Giai đoạn**: Cấu hình VM (3/4) **Đầu vào**: Khóa VM (42) + Khóa máy (54), các thay đổi cấu hình **Đầu ra**: Cài đặt VM đã cập nhật, phần cứng đã sửa đổi **Trước**: VM đã bật nguồn → [`Quản lý nguồn VM`](/knowledge-base/vi/automation-api/vm-power-management.md) **Các bước tiếp theo phổ biến**: * 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) * Chu kỳ nguồn để áp dụng thay đổi → [`Quản lý nguồn VM`](/knowledge-base/vi/automation-api/vm-power-management.md) ## Tài liệu này hỗ trợ * "Cách thay đổi CPU và RAM của VM" * "Thêm ổ đĩa lưu trữ vào các VM hiện có" * "Thay đổi kích thước ổ đĩa và lưu trữ của VM" * "Quản lý giao diện mạng VM" * "Thêm ghi chú và tài liệu vào VM" * "Các thao tác hotplug và thay đổi trực tiếp" * "Tinh chỉnh hiệu năng VM" * "Quy trình mở rộng lưu trữ" * "Tái cấu hình mạng" ## Tham khảo nhanh ### Các endpoint chính * **Cài đặt VM**: `PUT /api/v4/vms/{id}` * **Ghi chú VM**: `POST /api/v4/note_actions` * **Quản lý ổ đĩa**: `POST/PUT/DELETE /api/v4/machine_drives` * **Quản lý NIC**: `POST/PUT/DELETE /api/v4/machine_nics` ### Các khái niệm chính * **VM key**: Dùng cho cài đặt VM (CPU, RAM, console) * **Machine key**: Dùng cho phần cứng (ổ đĩa, NIC, thiết bị) * **Hotplug**: Một số thay đổi yêu cầu 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 | | ------------------------- | ----------- | ----------------------------- | ----------- | ------------------------- | | Cập nhật VM | PUT | `/api/v4/vms/{id}` | VM key | cài đặt CPU, RAM, console | | Thêm ghi chú | POST | `/api/v4/note_actions` | VM key | Tài liệu | | Thêm ổ đĩa | POST | `/api/v4/machine_drives` | Machine key | Mở rộng lưu trữ | | Thay đổi kích thước ổ đĩa | PUT | `/api/v4/machine_drives/{id}` | Khóa ổ đĩa | Tăng dung lượng đĩa | | Xóa ổ đĩa | DELETE | `/api/v4/machine_drives/{id}` | Khóa ổ đĩa | Xóa lưu trữ | | Thêm NIC | POST | `/api/v4/machine_nics` | Machine key | Giao diện mạng | | Cập nhật NIC | PUT | `/api/v4/machine_nics/{id}` | Khóa NIC | Thay đổi mạng | | Xóa NIC | DELETE | `/api/v4/machine_nics/{id}` | Khóa NIC | Xóa giao diện | ## Chỉ mục khắc phục sự cố * **400 Yêu cầu không hợp lệ**: Kích thước RAM không hợp lệ, số CPU không hợp lệ, JSON sai định dạng * **409 Xung đột**: VM phải được tắt, không hỗ trợ hotplug, tài nguyên đang được sử dụng * **507 Không đủ dung lượng lưu trữ**: Bậc lưu trữ đầy, kích thước đĩa quá lớn, vượt hạn mức * **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 * **422 Không thể xử lý**: Không thể thu nhỏ ổ đĩa, loại giao diện không hợp lệ * **404 Không tìm thấy**: Không tìm thấy VM, không tìm thấy ổ đĩa, không tìm thấy NIC, vnet không hợp lệ ## Cập nhật CPU và RAM ### PUT /api/v4/vms/{id} **Mô tả**: Cập nhật cấu hình VM. Sử dụng khóa VM (không phải khóa máy) cho các cài đặt cấp VM. **Ví dụ nội dung yêu cầu**: ```json { "ram": 16384, "cpu_cores": 3, "console": "spice", "video": "qxl", "show_advanced": "true", "nested_virtualization": "true", "disable_hypervisor": "true" } ``` **Lệnh API đầy đủ**: ```bash curl -X PUT "https://your-vergeos.example.com/api/v4/vms/42" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ram": 16384, "cpu_cores": 3, "console": "spice", "video": "qxl", "show_advanced": "true", "nested_virtualization": "true", "disable_hypervisor": "true" }' ``` ### Các tham số cấu hình chung | Tham số | Loại | Mô tả | Yêu cầu khởi động lại | | ---------------------- | --------- | -------------------------------------------- | ------------------------- | | ram | số nguyên | RAM tính bằng MB | Thường là có | | cpu\_cores | số nguyên | Số lõi CPU | Thường là có | | console | chuỗi | Loại console (spice, vnc, none) | Ở lần khởi động tiếp theo | | video | chuỗi | Bộ điều hợp video (qxl, virtio, std, cirrus) | Ở lần khởi động tiếp theo | | nested\_virtualization | chuỗi | Bật ảo hóa lồng nhau ("true"/"false") | Có | | disable\_hypervisor | chuỗi | Tắt hypervisor ("true"/"false") | Có | | guest\_agent | chuỗi | Bật guest agent ("true"/"false") | Ở lần khởi động tiếp theo | | uefi | chuỗi | Bật khởi động UEFI ("true"/"false") | Có | | secure\_boot | chuỗi | Bật khởi động an toàn ("true"/"false") | Có | {% hint style="success" %} **VM Key so với Machine Key** * **cài đặt VM** (CPU, RAM, console, video): Dùng khóa VM (ví dụ, `42`) với `/api/v4/vms/{vm_key}` * **Thay đổi phần cứng** (ổ đĩa, NIC, thiết bị): Dùng khóa máy (ví dụ, `54`) với `/api/v4/machine_*` điểm cuối {% endhint %} {% hint style="warning" %} **Thay đổi cấu hình** * Thay đổi CPU và RAM thường yêu cầu khởi động lại VM * Thay đổi console và video có hiệu lực ở lần khởi động VM tiếp theo * Cài đặt ảo hóa lồng nhau và hypervisor yêu cầu khởi động lại VM * Luôn kiểm tra `allow_hotplug` cài đặt cho khả năng thêm nóng {% endhint %} ## Thêm ghi chú vào VM ### POST /api/v4/note\_actions **Mô tả**: Thêm hoặc cập nhật ghi chú cho một VM trong giao diện VergeOS nhằm phục vụ tài liệu. **Phần thân yêu cầu**: ```json { "owner": "vms/42", "action": "update", "params": { "text": "This is a test VM" } } ``` **Lệnh API đầy đủ**: ```bash curl -X POST "https://your-vergeos.example.com/api/v4/note_actions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "owner": "vms/42", "action": "update", "params": { "text": "Máy chủ web sản xuất - Đã cập nhật 2025-08-24" } }' ``` **Tham số**: | Tên | Loại | Bắt buộc | Mô tả | | ----------- | ----- | -------- | ------------------------------------------------- | | owner | chuỗi | Có | Định danh tài nguyên (định dạng: "vms/{vm\_key}") | | action | chuỗi | Có | Hành động cần thực hiện ("update") | | params.text | chuỗi | Có | Nội dung văn bản ghi chú | {% hint style="success" %} **Ghi chú VM** Ghi chú hiển thị trong giao diện VergeOS và giúp cho tài liệu VM, lịch bảo trì hoặc chi tiết cấu hình. Dùng khóa VM (không phải khóa máy) trong trường owner. {% endhint %} ## Quản lý ổ đĩa ### Thêm ổ đĩa mới Sử dụng điểm cuối machine drives để thêm lưu trữ sau khi tạo VM: #### POST /api/v4/machine\_drives ```json { "machine": "54", "name": "Data Drive", "interface": "virtio-scsi", "media": "disk", "disksize": 536870912000, "preferred_tier": "2" } ``` **Lệnh API đầy đủ**: ```bash curl -X POST "https://your-vergeos.example.com/api/v4/machine_drives" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "machine": "54", "name": "Data Drive", "interface": "virtio-scsi", "media": "disk", "disksize": 536870912000, "preferred_tier": "2" }' ``` ### Thay đổi kích thước ổ đĩa #### PUT /api/v4/machine\_drives/{drive\_id} **Mô tả**: Tăng kích thước của một ổ đĩa hiện có. Lưu ý rằng ổ đĩa chỉ có thể được mở rộng, không thể thu nhỏ. ```json { "disksize": 1073741824000 } ``` **Lệnh API đầy đủ**: ```bash curl -X PUT "https://your-vergeos.example.com/api/v4/machine_drives/55" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "disksize": 1073741824000 }' ``` {% hint style="warning" %} **Thay đổi kích thước ổ đĩa** * Ổ đĩa chỉ có thể được mở rộng, không bao giờ thu nhỏ * Hệ điều hành khách có thể cần được cấu hình để nhận diện kích thước mới * Một số hệ thống tệp yêu cầu mở rộng thủ công sau khi thay đổi kích thước ổ đĩa {% endhint %} ### Xóa ổ đĩa Trước khi xóa, ổ đĩa phải được tháo nóng nếu VM đang chạy: #### Bước 1: Tháo nóng ổ đĩa (nếu VM đang chạ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": "hotplugdrive", "params": { "device": "drive-id-here", "unplug": true } }' ``` #### Bước 2: Xóa ổ đĩa #### DELETE /api/v4/machine\_drives/{drive\_id} ```bash curl -X DELETE "https://your-vergeos.example.com/api/v4/machine_drives/55" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Ví dụ quản lý ổ đĩa #### Thêm CDROM/ISO ```json { "machine": "54", "media": "cdrom", "interface": "ahci", "media_source": "7" } ``` #### Thêm ổ đĩa nhập ```json { "machine": "54", "name": "Ubuntu Server", "description": "Ubuntu 22.04 LTS", "interface": "virtio-scsi", "media": "import", "media_source": 123, "preferred_tier": "3" } ``` ## Quản lý giao diện mạng ### Thêm NIC #### POST /api/v4/machine\_nics ```json { "machine": "54", "name": "Secondary Network", "interface": "virtio", "vnet": "8", "enabled": true } ``` **Lệnh API đầy đủ**: ```bash curl -X POST "https://your-vergeos.example.com/api/v4/machine_nics" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "machine": "54", "name": "Secondary Network", "interface": "virtio", "vnet": "8", "enabled": true }' ``` ### Cập nhật cấu hình NIC #### PUT /api/v4/machine\_nics/{nic\_id} ```json { "vnet": "10", "enabled": true } ``` **Lệnh API đầy đủ**: ```bash curl -X PUT "https://your-vergeos.example.com/api/v4/machine_nics/78" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "vnet": "10", "enabled": true }' ``` ### Xóa NIC #### DELETE /api/v4/machine\_nics/{nic\_id} ```bash curl -X DELETE "https://your-vergeos.example.com/api/v4/machine_nics/78" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Các tham số cấu hình NIC | Tham số | Loại | Bắt buộc | Mô tả | | --------- | ------- | -------- | ------------------------------------------- | | machine | chuỗi | Có | ID máy | | vnet | chuỗi | Có | ID mạng ảo | | name | chuỗi | Không | Tên NIC | | interface | chuỗi | Không | Loại giao diện NIC (virtio, e1000, rtl8139) | | đã bật | boolean | Không | Trạng thái bật của NIC | {% hint style="info" %} **Khóa mạng ảo** Tham số `vnet` tham số này dùng khóa/ID của mạng. Bạn có thể tìm khóa mạng bằng cách liệt kê các mạng khả dụng qua điểm cuối API networks. {% endhint %} ## Quy trình cấu hình hoàn chỉnh Đây là một ví dụ về việc cập nhật cấu hình đầy đủ của VM: ```bash # Bước 1: Cập nhật cài đặt VM (CPU, RAM, console) curl -X PUT "https://your-vergeos.example.com/api/v4/vms/42" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ram": 32768, "cpu_cores": 8, "console": "spice", "video": "virtio" }' # Bước 2: Thêm ghi chú vận hành curl -X POST "https://your-vergeos.example.com/api/v4/note_actions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "owner": "vms/42", "action": "update", "params": { "text": "Đã nâng cấp lên 32GB RAM và 8 lõi để tăng tải công việc - 2025-08-24" } }' # Bước 3: Thêm lưu trữ bổ sung curl -X POST "https://your-vergeos.example.com/api/v4/machine_drives" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "machine": "54", "name": "Application Data", "interface": "virtio-scsi", "media": "disk", "disksize": 1073741824000, "preferred_tier": "2" }' # Bước 4: Thêm giao diện mạng phụ curl -X POST "https://your-vergeos.example.com/api/v4/machine_nics" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "machine": "54", "name": "Management Network", "interface": "virtio", "vnet": "5", "enabled": true }' ``` ## Các thực hành tốt nhất về cấu hình ### Trước khi thực hiện thay đổi 1. **Kiểm tra trạng thái VM**: Đảm bảo VM ở trạng thái phù hợp để thay đổi 2. **Sao lưu dữ liệu quan trọng**: Tạo snapshot trước các thay đổi lớn 3. **Xem xét các phụ thuộc**: Cân nhắc tác động đến các ứng dụng đang chạy 4. **Lên kế hoạch thời gian ngừng dịch vụ**: Một số thay đổi yêu cầu khởi động lại VM ### Sau khi thực hiện thay đổi 1. **Xác minh cấu hình**: Kiểm tra xem các thay đổi đã được áp dụng đúng chưa 2. **Kiểm tra chức năng**: Đảm bảo VM hoạt động như mong đợi 3. **Cập nhật tài liệu**: Thêm ghi chú về các thay đổi cấu hình 4. **Theo dõi hiệu năng**: Theo dõi mọi ảnh hưởng đến hiệu năng ### Lưu ý về hotplug ```bash # Kiểm tra xem VM có hỗ trợ hotplug không curl "https://your-vergeos.example.com/api/v4/vms/42?fields=allow_hotplug" \ -H "Authorization: Bearer YOUR_API_KEY" ``` {% hint style="success" %} **Hỗ trợ hotplug** Tham số `allow_hotplug` cài đặt này cho phép thêm nóng và tháo nóng **ổ đĩa và NIC** khi VM đang chạy: * **Ổ đĩa**: Có thể thêm/xóa trực tiếp (hệ điều hành khách phải hỗ trợ; khuyến nghị Virtio-SCSI) * **NIC**: Có thể thêm/xóa trực tiếp (được hỗ trợ rộng rãi bởi các hệ điều hành khách) * **CPU/RAM**: Các thay đổi luôn yêu cầu chu kỳ nguồn VM Xem [Khả năng hot-plug của VM](/knowledge-base/vi/tenants/vm-hotplug-capabilities.md) để biết chi tiết đầy đủ. {% endhint %} ## Xử lý lỗi ### Các lỗi cấu hình thường gặp **Lỗi**: `400 Yêu cầu không hợp lệ - Kích thước RAM không hợp lệ` ```json { "error": "Kích thước RAM phải ít nhất 512 MB và nhiều nhất 1048576 MB" } ``` **Lỗi**: `409 Xung đột - VM phải được tắt` ```json { "error": "Không thể sửa các lõi CPU khi VM đang chạy mà không có hỗ trợ hotplug" } ``` **Giải pháp**: Dừng VM hoặc kiểm tra khả năng hotplug trước khi thực hiện thay đổi. **Lỗi**: `507 Không đủ dung lượng lưu trữ` ```json { "error": "Không đủ dung lượng lưu trữ ở bậc 2 cho kích thước đĩa được yêu cầu" } ``` **Giải pháp**: Chọn tầng lưu trữ khác hoặc giảm kích thước đĩa. {% 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á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ề cấu hình 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-configuration.md?ask=&goal= ``` `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.