Version: TOS 7

VMs CLI

Giới thiệu

VMs CLI là công cụ quản lý dòng lệnh của ứng dụng ảo hóa VMs TerraMaster, cung cấp khả năng truy vấn và vận hành nhất quán với giao diện quản lý web. CLI giao tiếp với dịch vụ VMs thông qua unix socket cục bộ, sử dụng giao diện lệnh chuẩn hóa và định dạng đầu ra JSON, có thể tích hợp vào script, vận hành tự động và quy trình phát triển thứ cấp.

Tính năng chính

Sẵn sàng sử dụng: được cài đặt cùng với ứng dụng VMs, không cần cài đặt thêm
Cách gọi linh hoạt: hỗ trợ nhiều kênh gọi khác nhau như terminal cục bộ, SSH từ xa, script, công cụ AI
Chế độ tương tác và phi tương tác: phù hợp cho cả bảo trì hàng ngày của quản trị viên lẫn script và tác vụ tự động hóa
Hỗ trợ đầu ra JSON: thuận tiện cho việc phân tích bằng chương trình và tích hợp tự động hóa
Giao tiếp cục bộ: chỉ giao tiếp với dịch vụ VMs qua unix socket cục bộ, không mở cổng ra bên ngoài
Xác nhận lần hai cho thao tác nguy hiểm: các thao tác như xóa máy ảo, xóa mạng mặc định yêu cầu xác nhận

Bắt đầu nhanh

# 在终端中执行（可通过本地终端、SSH、脚本、AI 工具等任意命令行途径）
vms --help

# 查看虚拟机列表
vms vm list

# 查看虚拟机详情
vms vm get <id>

# 以 JSON 格式输出（便于脚本解析）
vms vm list --json

Ví dụ đầu ra vms vm list:

NAME     GUEST ID                              STATUS    VCPU NUM  VRAM SIZE  IP
145      09fd98ee-4e2d-4c7a-a95c-8bacab80d322  shutdown  4         2097152    -
win10    9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1  shutdown  4         2097152    -
1454486  5a0391f2-c545-45eb-8eed-0a104972229b  shutdown  4         2097152    -
win101   32ee5a74-de8b-47a9-959d-1725c881ceab  shutdown  4         2097152    -

Tùy chọn toàn cục

Các tùy chọn sau áp dụng cho tất cả các lệnh:

Tùy chọn	Viết tắt	Mô tả
`--help`	`-h`	Hiển thị thông tin trợ giúp của lệnh
`--version`	`-v`	Hiển thị số phiên bản (có thể kết hợp với `--json` để xuất thông tin có cấu trúc)
`--json`	-	Xuất ở định dạng JSON
`--yes`	`-y`	Bỏ qua lời nhắc xác nhận cho thao tác nguy hiểm (bắt buộc dùng ở chế độ phi tương tác)
`--debug`	-	Bật đầu ra gỡ lỗi, hiển thị quá trình thực thi chi tiết
`--socket <path>`	-	Đường dẫn unix socket của VMs, mặc định `/var/api/VMs.sock`
`--timeout <duration>`	-	Thời gian chờ yêu cầu, mặc định 30s

Ví dụ thông tin phiên bản

vms --version

vms CLI v1.0.058

vms --version --json

{
  "build": "20260911",
  "cli_version": "v1.0.058"
}

Môi trường chạy

VMs CLI được cài đặt cùng với ứng dụng VMs. Khi ứng dụng được kích hoạt, nó sẽ liên kết CLI vào thư mục PATH mặc định của hệ thống, có thể sử dụng trực tiếp sau khi đăng nhập SSH.

Mục	Mô tả
Tệp CLI	`/Volume1/@apps/VMs/bin/vms`
Đường dẫn lệnh	`/usr/local/sbin/vms`（đã có trong PATH của hệ thống）
Phương thức giao tiếp	unix socket cục bộ, mặc định `/var/api/VMs.sock`
Đối tượng áp dụng	Quản trị viên đăng nhập vào máy cục bộ

Lưu ý:

CLI dùng để quản lý máy ảo trên máy cục bộ, không hỗ trợ quản lý từ xa các thiết bị khác thông qua CLI.
Phần phụ trợ luôn trả về HTTP 200; lệnh thành công hay không căn cứ vào trường code trong phần thân phản hồi, CLI sẽ chuyển đổi thành mã thoát dựa trên đó.
Các thao tác nguy hiểm (xóa máy ảo, xóa mạng, xóa ảnh, xóa không gian lưu trữ) sẽ yêu cầu xác nhận ở chế độ tương tác, và ở chế độ phi tương tác phải truyền rõ ràng --yes.

Bảng tổng hợp lệnh

Sau đây là bảng tóm tắt tham khảo nhanh cho tất cả các lệnh vms:

Lệnh cha	Lệnh con	Mô tả chức năng	Cần xác nhận	Rủi ro cao
vms	--version	Hiển thị thông tin phiên bản	Không	Không
vms vm	list	Liệt kê tất cả máy ảo	Không	Không
vms vm	get	Xem chi tiết máy ảo được chỉ định	Không	Không
vms vm	list-resource	Liệt kê tài nguyên khả dụng để tạo máy ảo	Không	Không
vms vm	logs	Xem nhật ký thao tác của máy ảo	Không	Không
vms vm	poweron	Khởi động máy ảo	Không	Không
vms vm	poweroff	Tắt máy ảo (tắt máy bình thường)	Có	Không
vms vm	force-poweroff	Buộc tắt máy ảo	Có	✅
vms vm	reboot	Khởi động lại máy ảo	Không	Không
vms vm	pause	Tạm dừng máy ảo	Không	Không
vms vm	resume	Phục hồi máy ảo đã tạm dừng	Không	Không
vms vm	autorun	Đặt tự khởi động khi khởi động	Không	Không
vms vm	clone	Nhân bản máy ảo	Không	Không
vms vm	export	Xuất máy ảo thành tệp OVA	Không	Không
vms vm	delete	Xóa máy ảo	Có	✅
vms vm disk	list	Xem đĩa ảo của máy ảo	Không	Không
vms vm snapshot	list	Liệt kê ảnh chụp nhanh của máy ảo	Không	Không
vms vm snapshot	create	Tạo ảnh chụp nhanh	Không	Không
vms vm snapshot	edit	Chỉnh sửa mô tả và trạng thái khóa của ảnh chụp nhanh	Không	Không
vms vm snapshot	config	Xem cấu hình máy ảo được lưu trong ảnh chụp nhanh	Không	Không
vms vm snapshot	consistency	Xem trước tính nhất quán của ảnh chụp nhanh	Không	Không
vms vm	link	Lấy thông tin kết nối bảng điều khiển VNC	Không	Không
vms network	list	Liệt kê mạng ảo	Không	Không
vms network	get	Xem chi tiết mạng ảo	Không	Không
vms network	create	Tạo mạng ảo	Không	Không
vms network	update	Cập nhật mạng ảo	Không	Không
vms network	delete	Xóa mạng ảo	Có	✅
vms network	list-interfaces	Liệt kê giao diện mạng theo loại được chỉ định	Không	Không
vms network	list-vnics	Liệt kê card mạng ảo trên mạng	Không	Không
vms network	ovsinfo	Xem OVS có được bật hay không	Không	Không
vms image	list	Liệt kê ảnh	Không	Không
vms image	edit	Chỉnh sửa thông tin ảnh	Không	Không
vms image	delete	Xóa ảnh	Có	✅
vms image	list-vms	Xem các máy ảo đang dùng ảnh này	Không	Không
vms repo	list	Liệt kê không gian lưu trữ	Không	Không
vms repo	get	Xem chi tiết không gian lưu trữ	Không	Không
vms repo	update	Cập nhật cấu hình không gian lưu trữ	Không	Không
vms repo	delete	Xóa không gian lưu trữ	Có	✅
vms repo	list-volumes	Liệt kê các ổ đĩa khả dụng	Không	Không
vms repo	list-vms	Liệt kê máy ảo trong không gian lưu trữ	Không	Không
vms repo	check-running	Kiểm tra máy ảo đang chạy trên không gian lưu trữ	Không	Không
vms repo	whether-exist-data	Kiểm tra không gian lưu trữ có dữ liệu hay không	Không	Không
vms setting	get	Xem cài đặt toàn cục	Không	Không
vms collectd	hostinfo	Xem thông tin giám sát máy chủ	Không	Không
vms collectd	vminfo	Xem thông tin giám sát máy ảo	Không	Không
vms collectd	storageinfo	Xem thông tin giám sát lưu trữ	Không	Không

Tham chiếu lệnh

Trong các lệnh, <id> là ID máy ảo, tương ứng với GUEST ID trong đầu ra danh sách máy ảo; <network_id>, <image_id>, <repo_id> tương tự, có thể lấy được lần lượt qua vms network list, vms image list, vms repo list.

Về ví dụ đầu ra: Đầu ra dạng bảng của vms sẽ cắt ngắn giá trị trường quá dài theo chiều rộng cố định (kết thúc bằng dấu ba chấm, không liên quan đến chiều rộng terminal), ví dụ VDISKS, VNICS, ISO IMAGES trong cấu hình máy ảo, cũng như tên ảnh. Do đó, trong tài liệu này, các lệnh liên quan đến trường dài đều cung cấp ví dụ đầu ra --json đầy đủ, các lệnh còn lại cung cấp ví dụ đầu ra dạng bảng. Khi xử lý bằng script cũng nên dùng thống nhất --json.

I. Truy vấn máy ảo

vms vm list – Liệt kê máy ảo

Liệt kê tất cả máy ảo trên máy cục bộ và trạng thái cơ bản của chúng.

vms vm list [--limit N] [--offset N] [--json]

--limit, --offset là tham số phân trang
Các cột đầu ra: tên, ID máy ảo, trạng thái chạy, số nhân CPU, dung lượng bộ nhớ (đơn vị KB), địa chỉ IP

Ví dụ đầu ra:

NAME     GUEST ID                              STATUS    VCPU NUM  VRAM SIZE  IP
145      09fd98ee-4e2d-4c7a-a95c-8bacab80d322  shutdown  4         2097152    -
win10    9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1  shutdown  4         2097152    -
1454486  5a0391f2-c545-45eb-8eed-0a104972229b  shutdown  4         2097152    -
win101   32ee5a74-de8b-47a9-959d-1725c881ceab  shutdown  4         2097152    -

Các giá trị thường gặp của STATUS:

Trạng thái	Mô tả
running	Đang chạy
shutdown	Đã tắt máy
saved	Đã tạm dừng (trạng thái chạy đã được lưu vào đĩa)

vms vm get – Xem chi tiết máy ảo

Xem cấu hình đầy đủ và trạng thái chạy của máy ảo được chỉ định.

vms vm get <id> --json

Đầu ra bao gồm tất cả các trường cấu hình và trạng thái chạy của máy ảo
Các giá trị rỗng như không có mô tả, không có IP được hiển thị dưới dạng chuỗi rỗng
Khi máy ảo không tồn tại, lệnh trả về lỗi và xuất thông tin lỗi

Ví dụ đầu ra:

{
  "iso_images": [
    "c93083a5-2b39-4f32-b19f-1ad97c6b4de4",
    "9b3f2fdd-9173-4611-a84c-0cc9ce88293c"
  ],
  "image_paths": [
    "",
    ""
  ],
  "autorun": 0,
  "boot_from": "cdrom",
  "bios": "bios",
  "kb_layout": "en-us",
  "serial_console": true,
  "usb_version": 2,
  "usb_device_name": [
    "USB - Integrated Technology Express, Inc. Disk 2.0"
  ],
  "usbs": [
    ":3:3:048d:1234"
  ],
  "use_ovmf": false,
  "vnics": [
    {
      "prefer_sriov": false,
      "vnic_type": 3,
      "mac": "1a:e2:ae:95:4a:51",
      "network_id": "b364a1ec-f60c-4971-9ea2-f7a002f09fa3",
      "virtual_interface_id": "fe972ef5-b066-4967-89fa-8e85e43c8808"
    }
  ],
  "operating_system_type": 0,
  "vdisks": [
    {
      "vdisk_mode": 1,
      "name": "",
      "unmap": false,
      "iops_enable": false,
      "dev_limit": 0,
      "dev_reservation": 0,
      "dev_weight": 3,
      "vdisk_size": 1024,
      "idx": 0,
      "vdisk_id": "f4ed4eae-1512-4273-963b-79ebd93a0932",
      "disk_image_type": "",
      "disk_image_id": ""
    }
  ],
  "name": "win10",
  "vcpu_num": 4,
  "vcpu_usage": 0,
  "vram_size": 2097152,
  "video_card": "vga",
  "machine_type": "1",
  "cpu_weight": 3,
  "ip": "",
  "desc": "",
  "cpu_passthru": false,
  "hyperv_enlighten": true,
  "cpu_pin_num": 0,
  "repo_id": "735ef7f7-5d8d-4102-9377-8a7b8c33cda6",
  "repo_name": "VM-Storage01",
  "poweron_after_create": false,
  "guest_id": "9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1",
  "increaseAllocatedSize": 0,
  "host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
  "host_name": "",
  "snap_num": 0,
  "has_guest_agent": false,
  "status": "shutdown",
  "status_code": 0,
  "status_desc": "",
  "host_ram_size": 0,
  "total_throughput": 0,
  "total_iops": 0,
  "total_io_latency": 0,
  "total_rx_bytes": 0,
  "total_tx_bytes": 0,
  "memory_usage": 0,
  "cpu_usage": 0,
  "vm_status_progress": 0
}

vms vm list-resource – Liệt kê tài nguyên khả dụng để tạo máy ảo

Xem các tài nguyên mà máy chủ có thể cung cấp như loại firmware, ảnh, CPU, bộ nhớ, mạng, không gian lưu trữ, thiết bị có thể passthrough, dùng để đánh giá trước khi tạo máy ảo.

vms vm list-resource --json

Các trường trả về: max_cpu_num, max_ram_size, usbs, pci_devices, networks, repos, images, video_cards, firmware, keyboard_layout.

Ví dụ đầu ra:

{
  "max_cpu_num": 4,
  "max_ram_size": 16503336960,
  "usbs": [
    {
      "product_name": "4-Port USB 2.0 Hub",
      "usb_id": ":3:3:0x0bda:0x5423",
      "version": ""
    },
    {
      "product_name": "4-Port USB 3.2 Hub",
      "usb_id": ":4:2:0x0bda:0x0423",
      "version": ""
    },
    {
      "product_name": "Flash Drive",
      "usb_id": ":3:2:0x058f:0x6387",
      "version": ""
    }
  ],
  "pci_devices": [
    {
      "device_name": "",
      "bdf": "0000:02:00.0",
      "vendor_id": "0x10ec",
      "product_id": "0x8126",
      "class_id": "0x020000",
      "iommu_group": 13,
      "iommu_group_bdfs": [
        "0x0000:0x02:0x00.0x0"
      ],
      "driver": "r8169",
      "type": "Network Controller"
    },
    {
      "device_name": "",
      "bdf": "0000:00:0d.0",
      "vendor_id": "0x8086",
      "product_id": "0x464e",
      "class_id": "0x0c0330",
      "iommu_group": 2,
      "iommu_group_bdfs": [
        "0x0000:0x00:0x0d.0x0"
      ],
      "driver": "xhci_hcd",
      "type": "USB Controller"
    },
    {
      "device_name": "",
      "bdf": "0000:03:00.0",
      "vendor_id": "0x10ec",
      "product_id": "0x8126",
      "class_id": "0x020000",
      "iommu_group": 14,
      "iommu_group_bdfs": [
        "0x0000:0x03:0x00.0x0"
      ],
      "driver": "r8169",
      "type": "Network Controller"
    },
    {
      "device_name": "",
      "bdf": "0000:00:14.0",
      "vendor_id": "0x8086",
      "product_id": "0x54ed",
      "class_id": "0x0c0330",
      "iommu_group": 3,
      "iommu_group_bdfs": [
        "0x0000:0x00:0x14.0x2",
        "0x0000:0x00:0x14.0x0"
      ],
      "driver": "xhci_hcd",
      "type": "USB Controller"
    },
    {
      "device_name": "",
      "bdf": "0000:00:14.2",
      "vendor_id": "0x8086",
      "product_id": "0x54ef",
      "class_id": "0x050000",
      "iommu_group": 3,
      "iommu_group_bdfs": [
        "0x0000:0x00:0x14.0x2",
        "0x0000:0x00:0x14.0x0"
      ],
      "driver": "",
      "type": "IOMMU Group Device"
    }
  ],
  "networks": [
    {
      "name": "VM-Network04",
      "network_id": "ce9807c9-47b3-4258-9a80-ea8db1fd785d",
      "support_sriov": false
    },
    {
      "name": "VM-Network05",
      "network_id": "b56c2f7b-e3f0-4b68-8a3b-245c90a8f8b5",
      "support_sriov": false
    },
    {
      "name": "VM-Network01",
      "network_id": "b364a1ec-f60c-4971-9ea2-f7a002f09fa3",
      "support_sriov": false
    },
    {
      "name": "VM-Network02",
      "network_id": "6c9fffd8-c7c4-4968-9b50-6890a640ec94",
      "support_sriov": false
    },
    {
      "name": "VM-Network03",
      "network_id": "4c05b2a2-dd49-4588-ac5c-64975c92d2d3",
      "support_sriov": false
    }
  ],
  "repos": [
    {
      "name": "VM-Storage01",
      "free_size": 941970767872,
      "repo_id": "735ef7f7-5d8d-4102-9377-8a7b8c33cda6",
      "volume_size": 1099511627776,
      "file_system": "btrfs",
      "status": ""
    },
    {
      "name": "VM-Storage02",
      "free_size": 445785296896,
      "repo_id": "517571ba-f7f7-49e1-9a62-7eb6ddfd9c78",
      "volume_size": 536870912000,
      "file_system": "btrfs",
      "status": ""
    }
  ],
  "images": [
    {
      "id": "c93083a5-2b39-4f32-b19f-1ad97c6b4de4",
      "name": "cn_windows_10_consumer_editions_version_1909_updated_jan_2020_x86_dvd_9c50652f",
      "status": "available",
      "type": "iso",
      "used_size": 3884539904
    },
    {
      "id": "9b3f2fdd-9173-4611-a84c-0cc9ce88293c",
      "name": "virtio-win-0.1.285pro",
      "status": "available",
      "type": "iso",
      "used_size": 789645312
    },
    {
      "id": "efd6da18-9475-44cf-8fb0-e2513421e68a",
      "name": "haos_ova-18.2",
      "status": "available",
      "type": "qcow2",
      "used_size": 1091698688,
      "virtual_size": 34359738368
    },
    {
      "id": "cb9d929a-d673-4e46-ac86-9488bbef19b9",
      "name": "cn_windows_11_consumer_editions_version_21h2_updated_july_2022_x64_dvd_50ad4acf",
      "status": "available",
      "type": "iso",
      "used_size": 5858816000
    }
  ],
  "video_cards": [
    "cirrus",
    "vga",
    "vmvga"
  ],
  "firmware": [
    "Legacy BIOS",
    "UEFI"
  ],
  "keyboard_layout": [
    "fr-be",
    "ar",
    "bepo",
    "cz",
    "da",
    "de",
    "de-ch",
    "en-gb",
    "en-us",
    "es",
    "et",
    "fo",
    "fr",
    "fr-be",
    "fr-ca",
    "fr-ch",
    "hr",
    "hu",
    "is",
    "it",
    "ja",
    "lt",
    "lv",
    "mk",
    "nl",
    "nl-be",
    "no",
    "pl",
    "pt",
    "pt-br",
    "ru",
    "sl",
    "sv",
    "th",
    "tr"
  ]
}

vms vm logs – Xem nhật ký thao tác máy ảo

Xem nhật ký thao tác liên quan đến máy ảo được chỉ định (bật/tắt máy, ảnh chụp nhanh, chỉnh sửa, nhập/xuất, v.v.).

vms vm logs <id> --json [--limit N] [--desc]

--limit chỉ định số bản ghi trả về, mặc định 50
--desc sắp xếp theo thời gian giảm dần (mặc định bật)
Mỗi bản ghi nhật ký bao gồm thời gian, mức độ, danh mục, người dùng thao tác và mô tả sự kiện; mô tả sự kiện là văn bản đầy đủ
Mô tả sự kiện (event) được dịch vụ VMs bản địa hóa theo ngôn ngữ hệ thống của thiết bị; ví dụ trong tài liệu này thống nhất dùng tiếng Anh

Ví dụ đầu ra:

[
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:44:09.176535374+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) shutdown successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:43:10.597187659+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) started successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:40:32.74904922+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) shutdown successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:39:55.916718004+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) started successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:39:43.341421576+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) shutdown successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:38:31.518259486+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) shutdown successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:38:07.98065689+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) started successfully"
  },
  {
    "id": 0,
    "level": "Error",
    "time": "2026-09-02T11:32:35.01952111+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine (win10) export failed (Error:stat : no such file or directory)"
  }
]

II. Quản lý nguồn máy ảo

vms vm poweron – Khởi động máy ảo

vms vm poweron <id>

Máy ảo phải ở trạng thái đã tắt máy, nếu không sẽ trả về lỗi xung đột trạng thái
Đầu ra: VM powered on: <id>

vms vm poweroff – Tắt máy ảo

Gửi yêu cầu tắt máy bình thường đến máy ảo, để hệ thống tắt một cách êm ái.

vms vm poweroff <id> [--yes]

Thuộc thao tác nguy hiểm: chế độ tương tác sẽ hỏi xác nhận, chế độ phi tương tác phải thêm --yes
Máy ảo phải ở trạng thái đang chạy, nếu không sẽ trả về lỗi xung đột trạng thái

Lời nhắc xác nhận ở chế độ tương tác:

This action will powered off VM "9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1". Do you want to continue? [y/N]: 

Đầu ra: VM powered off: <id>

vms vm force-poweroff – Buộc tắt máy ảo (rủi ro cao)

Buộc tắt máy ảo, tương đương với việc ngắt nguồn trực tiếp.

vms vm force-poweroff <id> [--yes]

Thuộc thao tác rủi ro cao: chế độ tương tác sẽ hỏi xác nhận, chế độ phi tương tác phải thêm --yes
Có thể gây mất dữ liệu trong máy ảo, khuyến nghị chỉ dùng khi máy ảo không phản hồi

Lời nhắc xác nhận ở chế độ tương tác:

This action will force powered off VM "9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1". Do you want to continue? [y/N]: 

Đầu ra: VM force powered off: <id>

vms vm reboot – Khởi động lại máy ảo

vms vm reboot <id>

Đầu ra: VM rebooted: <id>

vms vm pause – Tạm dừng máy ảo

Đóng băng trạng thái chạy của máy ảo và lưu trạng thái hiện tại vào đĩa.

vms vm pause <id>

Máy ảo phải ở trạng thái đang chạy, nếu không sẽ trả về lỗi xung đột trạng thái
Sau khi tạm dừng, trạng thái máy ảo hiển thị là saved
Đầu ra: VM paused: <id>

vms vm resume – Phục hồi máy ảo

Khôi phục máy ảo từ trạng thái tạm dừng về trạng thái đang chạy.

vms vm resume <id>

Máy ảo phải ở trạng thái tạm dừng, nếu không sẽ trả về lỗi xung đột trạng thái
Đầu ra: VM resumed: <id>

vms vm autorun – Đặt tự khởi động khi khởi động

Đặt xem máy ảo có tự khởi động cùng máy chủ hay không.

vms vm autorun <id> <true|false>

Tham số thứ hai phải là true hoặc false
Lệnh sẽ đọc cấu hình hiện tại và chỉ sửa công tắc tự khởi động, các cấu hình khác không bị ảnh hưởng
Đầu ra: Auto-start enabled for VM <id> hoặc Auto-start disabled for VM <id>

III. Nhân bản, xuất và xóa máy ảo

vms vm clone – Nhân bản máy ảo

Sao chép một máy ảo mới bằng cách dùng máy ảo hiện có làm mẫu.

vms vm clone --body '{"guest_id":"<source_id>","name":"my-clone"}'
vms vm clone --file clone.json

Trong phần thân yêu cầu, guest_id là ID máy ảo nguồn, name (hoặc guest_name) là tên máy ảo mới
Máy ảo nguồn phải ở trạng thái đã tắt máy
--body truyền trực tiếp phần thân yêu cầu dưới dạng chuỗi JSON, --file đọc phần thân yêu cầu từ tệp

vms vm export – Xuất máy ảo

Xuất máy ảo thành tệp OVA, thuận tiện cho sao lưu hoặc di chuyển sang nền tảng ảo hóa khác.

vms vm export --body '{"guest_id":"<source_id>","target_ova_path":"/Volume1/export/my-vm.ova"}'
vms vm export --file export.json

Trong phần thân yêu cầu, guest_id là ID máy ảo nguồn, target_ova_path là đường dẫn tệp đích, ova_mode là chế độ tương thích VMware tùy chọn
Máy ảo nguồn phải ở trạng thái đã tắt máy
Xuất là tác vụ tốn thời gian; máy ảo dung lượng lớn mất nhiều thời gian để xuất

vms vm delete – Xóa máy ảo (rủi ro cao)

Xóa vĩnh viễn máy ảo.

vms vm delete <id> [--yes]

Thuộc thao tác rủi ro cao: chế độ tương tác sẽ hỏi xác nhận, chế độ phi tương tác phải thêm --yes
Sau khi xóa không thể khôi phục, vui lòng xác nhận trước rằng dữ liệu trong máy ảo đã được sao lưu

Lời nhắc xác nhận ở chế độ tương tác:

This action will permanently delete VM "5a0391f2-c545-45eb-8eed-0a104972229b". Do you want to continue? [y/N]: 

Đầu ra: VM deleted: <id>

IV. Đĩa ảo

vms vm disk list – Xem đĩa ảo

Liệt kê tất cả đĩa ảo của máy ảo được chỉ định.

vms vm disk list <id> [--json]

Ví dụ đầu ra:

NAME  VDISK ID                              VDISK SIZE  VDISK MODE  IDX
-     f4ed4eae-1512-4273-963b-79ebd93a0932  1024        1           0

VDISK MODE là số loại bộ điều khiển đĩa ảo, 1 nghĩa là IDE
Đĩa ảo không có tên hiển thị là - ở cột NAME

V. Quản lý ảnh chụp nhanh

vms vm snapshot list – Liệt kê ảnh chụp nhanh

vms vm snapshot list <id> [--json]

Ví dụ đầu ra:

NAME                                    GUEST ID                              DESCRIPTION      LOCKED  CREATED AT                 VM STATE  ACTUAL CONSISTENCY
snapshot_2026-09-02T11-43-51.183703274  9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1  cli-test-edited  false   2026-09-02T11:43:51+08:00  running   crash
snapshot_2026-05-15T17-13-48.986448711  9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1  -                false   2026-05-15T17:13:48+08:00  shutdown  filesystem

VM STATE là trạng thái chạy của máy ảo tại thời điểm tạo ảnh chụp nhanh
ACTUAL CONSISTENCY là loại nhất quán của ảnh chụp nhanh; filesystem nghĩa là nhất quán hệ thống tệp, crash nghĩa là nhất quán khi sự cố

vms vm snapshot create – Tạo ảnh chụp nhanh

Tạo ảnh chụp nhanh cho máy ảo, dùng để khôi phục nhanh hoặc sao lưu trạng thái hiện tại.

vms vm snapshot create <id>
vms vm snapshot create <id> --body '{"description":"before-upgrade","locked":false}'

Phần thân yêu cầu tùy chọn: description là mô tả ảnh chụp nhanh, locked là có khóa hay không
Tên ảnh chụp nhanh được hệ thống tự động tạo theo thời gian tạo
Ảnh chụp nhanh chiếm dung lượng lưu trữ; nếu lâu ngày không dọn dẹp có thể làm đầy không gian lưu trữ, khuyến nghị dọn dẹp định kỳ

vms vm snapshot edit – Chỉnh sửa ảnh chụp nhanh

Sửa mô tả hoặc trạng thái khóa của ảnh chụp nhanh.

vms vm snapshot edit <id> <snapshot_name> --body '{"description":"updated description"}'
vms vm snapshot edit <id> <snapshot_name> --body '{"locked":true}'

Chỉ sửa các trường xuất hiện trong phần thân yêu cầu; các trường không xuất hiện giữ nguyên giá trị gốc; chỉ sửa mô tả sẽ không thay đổi trạng thái khóa và ngược lại

Ví dụ đầu ra:

PROPERTY            VALUE
ACTUAL CONSISTENCY  crash
CREATED AT          2026-09-02T11:43:51+08:00
DESCRIPTION         cli-test-edited
GUEST ID            9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1
LOCKED              false
NAME                snapshot_2026-09-02T11-43-51.183703274
VM STATE            running

vms vm snapshot config – Xem cấu hình máy ảo của ảnh chụp nhanh

Xem cấu hình máy ảo được lưu trong ảnh chụp nhanh.

vms vm snapshot config <id> <snapshot_name>

<id> là ID máy ảo, <snapshot_name> là tên ảnh chụp nhanh, có thể lấy qua vms vm snapshot list <id>.

Ví dụ đầu ra:

PROPERTY                VALUE
CPU COMPATIBILITY MODE  true
CPU PASSTHRU            false
HYPERV ENLIGHTEN        true
REPO NAME               VM-Storage01
USB DEVICE NAME         ["USB - Integrated Technology Express, Inc. Disk 2.0"]
USB VERSION             2
USBS                    [":3:3:048d:1234"]
VCPU NUM                4
VDISK NUM               1
VDISK TOTAL SIZE        1024
VDISKS                  [{"name":"disk1","type":"ide","vdisk_size":1024}]
VIDEO CARD              vga
VRAM SIZE               2097152

vms vm snapshot consistency – Xem trước tính nhất quán của ảnh chụp nhanh

Xem trước loại nhất quán có thể đạt được trước khi tạo ảnh chụp nhanh, giúp đánh giá liệu hiện tại có phù hợp để tạo ảnh chụp nhanh hay không.

vms vm snapshot consistency <id>

Ví dụ đầu ra:

PROPERTY          VALUE
CONSISTENCY TYPE  filesystem
REASON            vm_shutdown
VM STATE          shutdown

Tạo ảnh chụp nhanh khi máy ảo đã tắt máy sẽ có được ảnh chụp nhất quán hệ thống tệp; khi đang chạy thường chỉ có thể có được ảnh chụp nhất quán khi sự cố.

VI. Bảng điều khiển từ xa

vms vm link – Lấy thông tin kết nối VNC

Lấy thông tin kết nối của bảng điều khiển VNC máy ảo, dùng để mở bảng điều khiển từ xa trong trình duyệt.

vms vm link <id> --json

Máy ảo phải ở trạng thái đang chạy hoặc tạm dừng, nếu không sẽ trả về lỗi xung đột trạng thái

Ví dụ đầu ra:

{
  "url": "VMs/noVNC/vnc.html?autoconnect=true\u0026reconnect=true\u0026path=utils/websockify/?token=09fd98ee-4e2d-4c7a-a95c-8bacab80d322\u0026title=145",
  "port": 8181,
  "https": false
}

url là đường dẫn bảng điều khiển tương đối so với địa chỉ quản lý NAS, port là cổng dịch vụ bảng điều khiển, https cho biết có cần truy cập qua HTTPS hay không
Trong đầu ra JSON, ký tự & trong URL sẽ được thoát thành \u0026

VII. Quản lý mạng ảo

Loại mạng được chia thành hai loại:

Loại	Mô tả
Riêng tư (private)	Mạng nội bộ chỉ dành cho giao tiếp giữa các máy ảo trên máy cục bộ, không liên kết với card mạng vật lý
Bên ngoài (external)	Mạng liên kết với card mạng vật lý, máy ảo có thể giao tiếp với bên ngoài qua mạng này

vms network list – Liệt kê mạng ảo

vms network list [--limit N] [--offset N] [--json]

Ví dụ đầu ra:

NAME          NETWORK ID                            TYPE      VLAN ID  NUM GUESTS  NUM HOSTS  NUM INTERFACES  HOST NAME
VM-Network04  ce9807c9-47b3-4258-9a80-ea8db1fd785d  external  0        0           1          1               A-eae4
VM-Network01  b364a1ec-f60c-4971-9ea2-f7a002f09fa3  external  0        2           1          1               A-eae4

NUM GUESTS là số máy ảo kết nối vào mạng này, NUM INTERFACES là số card mạng vật lý đã chọn

vms network get – Xem chi tiết mạng ảo

vms network get <network_id> --json

Ví dụ đầu ra:

{
  "metadata": {
    "createdAt": "2026-05-15T16:46:08.415062294+08:00",
    "updatedAt": "2026-05-15T16:46:08.415062415+08:00"
  },
  "network_id": "b364a1ec-f60c-4971-9ea2-f7a002f09fa3",
  "name": "VM-Network01",
  "host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
  "host_name": "A-eae4",
  "interfaces": {
    "15341593-7f43-49f4-9523-6ac750a63a8a": {
      "totalCount": 1,
      "items": [
        {
          "checked": false,
          "host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
          "host_name": "A-eae4",
          "interface_id": "/00000000-0000-0000-0000-6cbfb504eae5",
          "interface_name": "LAN 2",
          "ip": [
            "192.168.2.121"
          ],
          "mask": [
            "ffffff00"
          ],
          "speed_mbs": 1000,
          "status": "connected",
          "tx_kbps": 0,
          "rx_kbps": 0
        },
        {
          "checked": true,
          "host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
          "host_name": "A-eae4",
          "interface_id": "/00000000-0000-0000-0000-6cbfb504eae4",
          "interface_name": "LAN 1",
          "ip": [
            "10.18.8.95"
          ],
          "mask": [
            "ffffff00"
          ],
          "speed_mbs": 1000,
          "status": "connected",
          "tx_kbps": 2.5458984375,
          "rx_kbps": 11.45458984375
        }
      ]
    }
  },
  "num_guests": 0,
  "num_hosts": 1,
  "num_interfaces": 1,
  "type": "external",
  "vlan_id": 0
}

interfaces là thông tin card mạng được liên kết với mạng này, được tổ chức theo ID máy chủ, checked cho biết card mạng đó đã được chọn hay chưa
metadata ghi lại thời gian tạo và cập nhật của mạng

vms network create – Tạo mạng ảo

vms network create --body '{"name":"net1","type":"private","host_name":"TNAS"}' --json
vms network create --body '{"name":"net1","type":"external","vlan_id":100,"host_name":"TNAS","interface_name":"LAN 1"}' --json

Tạo mạng riêng tư:

Phần thân yêu cầu cần chứa name, type (private), host_name hoặc host_id, chỉ định mạng được tạo trên máy chủ nào
Trước khi tạo có thể xem các máy chủ khả dụng qua vms network list-interfaces private

Tạo mạng bên ngoài:

Phần thân yêu cầu cần chứa name, type (external), vlan_id, và chỉ định ít nhất một card mạng vật lý
Có thể chỉ định card mạng qua interface_name (như LAN 1) hoặc interface_id; khi tên card mạng không duy nhất giữa các máy chủ thì cần dùng kèm host_name
Trước khi tạo có thể xem các card mạng khả dụng qua vms network list-interfaces external

Đầu ra là thông tin mạng sau khi tạo, nhất quán với cấu trúc của vms network get:

{
  "metadata": {
    "createdAt": "2026-09-17T16:57:32.064720576+08:00",
    "updatedAt": "2026-09-17T16:57:32.064720634+08:00"
  },
  "network_id": "27047bd1-eeeb-4762-82ae-45094dea4854",
  "name": "cli-demo-net",
  "host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
  "host_name": "A-eae4",
  "interfaces": {
    "15341593-7f43-49f4-9523-6ac750a63a8a": {
      "totalCount": 1,
      "items": [
        {
          "checked": true,
          "host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
          "host_name": "A-eae4",
          "interface_id": "",
          "interface_name": "PNdea4854",
          "ip": null,
          "mask": null,
          "speed_mbs": 0,
          "status": ""
        }
      ]
    }
  },
  "num_guests": 0,
  "num_hosts": 1,
  "num_interfaces": 1,
  "type": "private",
  "vlan_id": 0
}

Khi không chỉ định card mạng, lệnh sẽ đưa ra gợi ý:

network create (type "external") requires selecting at least one interface; add "interface_name" (optionally scoped with "host_name") or "interface_id" to the body, e.g. {"name":"net1","type":"external","vlan_id":100,"host_name":"TNAS","interface_name":"LAN 1"}. Run "vms network list-interfaces external" to see available interfaces. Example available interface: LAN 2 on A-eae4 (host_id=15341593-7f43-49f4-9523-6ac750a63a8a, interface_id=/00000000-0000-0000-0000-6cbfb504eae5)

vms network update – Cập nhật mạng ảo

Chỉ gửi các trường cần sửa; các trường không gửi giữ nguyên giá trị gốc.

vms network update --body '{"network_id":"<network_id>","name":"renamed"}'
vms network update --body '{"network_id":"<network_id>","vlan_id":200}'

Phần thân yêu cầu phải chứa network_id
Lệnh sẽ đọc cấu hình mạng hiện tại trước rồi hợp nhất các trường đã gửi; tên mạng và card mạng đã chọn sẽ không bị xóa
Đầu ra là thông tin mạng sau khi cập nhật

vms network delete – Xóa mạng ảo (rủi ro cao)

vms network delete <network_id> [--yes]

Thuộc thao tác rủi ro cao: chế độ tương tác sẽ hỏi xác nhận, chế độ phi tương tác phải thêm --yes
Xóa mạng sẽ ngắt kết nối tất cả máy ảo đang kết nối vào mạng đó
Khuyến nghị trước tiên xác nhận các máy ảo đang kết nối qua vms network list-vnics <network_id>

Lời nhắc xác nhận ở chế độ tương tác:

This action will delete network "b364a1ec-f60c-4971-9ea2-f7a002f09fa3". Do you want to continue? [y/N]: 

Đầu ra: Network deleted: <network_id>

vms network list-interfaces – Liệt kê giao diện mạng

Liệt kê giao diện mạng theo loại được chỉ định.

vms network list-interfaces external [--limit N] [--offset N]
vms network list-interfaces private [--limit N] [--offset N]

external trả về các card mạng vật lý khả dụng trên máy chủ
private trả về thông tin máy chủ khả dụng để tạo mạng riêng tư

Ví dụ đầu ra (external):

INTERFACE NAME  INTERFACE ID                           HOST NAME  STATUS        IP              SPEED MBS
LAN 2           /00000000-0000-0000-0000-6cbfb504eae5  A-eae4     disconnected  -               -1
LAN 1           /00000000-0000-0000-0000-6cbfb504eae4  A-eae4     connected     ["10.18.8.73"]  1000

Ví dụ đầu ra (private):

INTERFACE NAME  INTERFACE ID  HOST NAME  STATUS  IP  SPEED MBS
-               -             A-eae4     -       -   0

vms network list-vnics – Liệt kê card mạng ảo trên mạng

vms network list-vnics <network_id> [--limit N] [--offset N] [--json]

Ví dụ đầu ra:

GUEST NAME  GUEST ID                              MAC ADDRESS        VIRTUAL INTERFACE ID                  NETWORK NAME  STATUS  PREFER SRIOV
win10       9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1  1a:e2:ae:95:4a:51  fe972ef5-b066-4967-89fa-8e85e43c8808  VM-Network01  -       false
win101      32ee5a74-de8b-47a9-959d-1725c881ceab  1a:f6:db:fb:3d:79  f93bf16c-01ca-4b60-b164-8a3083fb5f03  VM-Network01  -       false

vms network ovsinfo – Xem trạng thái OVS

Xác nhận switch ảo Open vSwitch đã được bật hay chưa.

vms network ovsinfo [--json]

Ví dụ đầu ra:

PROPERTY  VALUE
RESULT    true

VALUE là true nghĩa là OVS đã được bật.

VIII. Quản lý ảnh

vms image list – Liệt kê ảnh

Liệt kê các tệp ảnh hệ thống khả dụng để tạo máy ảo.

vms image list --json

image_name là tên ảnh, file_name là tên tệp tương ứng
type là định dạng ảnh, như iso, qcow2
status là trạng thái ảnh, available nghĩa là khả dụng
repos là không gian lưu trữ chứa ảnh này
progress là tiến độ tác vụ xử lý ảnh, 0 nghĩa là không có tác vụ nào đang thực hiện

Ví dụ đầu ra:

{
  "totalCount": 4,
  "items": [
    {
      "image_name": "cn_windows_10_consumer_editions_version_1909_updated_jan_2020_x86_dvd_9c50652f",
      "image_id": "c93083a5-2b39-4f32-b19f-1ad97c6b4de4",
      "file_name": "cn_windows_10_consumer_editions_version_1909_updated_jan_2020_x86_dvd_9c50652f.iso",
      "type": "iso",
      "file_size": 3884539904,
      "status": "available",
      "status_code": 0,
      "status_reason": "",
      "create_time": 1778835784,
      "repos": [
        {
          "repo_name": "VM-Storage01",
          "repo_id": "735ef7f7-5d8d-4102-9377-8a7b8c33cda6"
        }
      ],
      "progress": 0,
      "task_id": 0,
      "virtual_size": 0
    },
    {
      "image_name": "cn_windows_11_consumer_editions_version_21h2_updated_july_2022_x64_dvd_50ad4acf",
      "image_id": "cb9d929a-d673-4e46-ac86-9488bbef19b9",
      "file_name": "cn_windows_11_consumer_editions_version_21h2_updated_july_2022_x64_dvd_50ad4acf.iso",
      "type": "iso",
      "file_size": 5858816000,
      "status": "available",
      "status_code": 0,
      "status_reason": "",
      "create_time": 1778835784,
      "repos": [
        {
          "repo_name": "VM-Storage01",
          "repo_id": "735ef7f7-5d8d-4102-9377-8a7b8c33cda6"
        }
      ],
      "progress": 0,
      "task_id": 0,
      "virtual_size": 0
    },
    {
      "image_name": "virtio-win-0.1.285pro",
      "image_id": "9b3f2fdd-9173-4611-a84c-0cc9ce88293c",
      "file_name": "virtio-win-0.1.285.iso",
      "type": "iso",
      "file_size": 789645312,
      "status": "available",
      "status_code": 0,
      "status_reason": "",
      "create_time": 1778836128,
      "repos": [
        {
          "repo_name": "VM-Storage01",
          "repo_id": "735ef7f7-5d8d-4102-9377-8a7b8c33cda6"
        }
      ],
      "progress": 0,
      "task_id": 0,
      "virtual_size": 0
    },
    {
      "image_name": "haos_ova-18.2",
      "image_id": "efd6da18-9475-44cf-8fb0-e2513421e68a",
      "file_name": "haos_ova-18.2.qcow2",
      "type": "qcow2",
      "file_size": 1091698688,
      "status": "available",
      "status_code": 0,
      "status_reason": "",
      "create_time": 1787191833,
      "repos": [
        {
          "repo_name": "VM-Storage02",
          "repo_id": "517571ba-f7f7-49e1-9a62-7eb6ddfd9c78"
        }
      ],
      "progress": 0,
      "task_id": 0,
      "virtual_size": 0
    }
  ]
}

vms image edit – Chỉnh sửa ảnh

Sửa tên ảnh hoặc điều chỉnh không gian lưu trữ chứa ảnh.

vms image edit --body '{"image_id":"<image_id>","repos":["<repo_id>"]}'
vms image edit --body '{"image_id":"<image_id>","repos":["<repo_id_1>","<repo_id_2>"],"image_name":"renamed.iso"}'

Phần thân yêu cầu phải chứa image_id và repos; repos là danh sách không gian lưu trữ đích đầy đủ của ảnh này, không được để trống
image_name, file_name, type, file_size là các trường tùy chọn; khi không cung cấp sẽ dùng giá trị hiện tại
repos rỗng sẽ khiến ảnh bị xóa khỏi tất cả không gian lưu trữ; lệnh sẽ từ chối yêu cầu đó trước khi thực thi
Đầu ra: Image updated

vms image delete – Xóa ảnh (rủi ro cao)

vms image delete --image-id <image_id> [--yes]

--image-id là bắt buộc
Thuộc thao tác rủi ro cao: chế độ tương tác sẽ hỏi xác nhận, chế độ phi tương tác phải thêm --yes
Xóa ảnh không ảnh hưởng đến các máy ảo đã tạo, nhưng sẽ ảnh hưởng đến việc tạo máy ảo dựa trên ảnh này sau đó
Khuyến nghị trước tiên xác nhận tình trạng sử dụng qua vms image list-vms --image-id <image_id>

Lời nhắc xác nhận ở chế độ tương tác:

This action will permanently delete image "efd6da18-9475-44cf-8fb0-e2513421e68a". Do you want to continue? [y/N]: 

Đầu ra: Image deleted: <image_id>

vms image list-vms – Xem các máy ảo đang dùng ảnh này

vms image list-vms --image-id <image_id> [--json]

Ví dụ đầu ra:

GUEST NAME
1454486

Trước khi xóa ảnh có thể chạy lệnh này để xác nhận phạm vi ảnh hưởng; khi không có máy ảo nào dùng ảnh này thì đầu ra trống.

IX. Quản lý không gian lưu trữ

vms repo list – Liệt kê không gian lưu trữ

vms repo list [--json]

Ví dụ đầu ra:

NAME          REPO ID                               STATUS  USED          PERCENT USED        TOTAL SIZE     FILE SYSTEM  HOST NAME
VM-Storage01  735ef7f7-5d8d-4102-9377-8a7b8c33cda6  -       155583651840  14.150249481201172  1097552691200  btrfs        -
VM-Storage02  517571ba-f7f7-49e1-9a62-7eb6ddfd9c78  normal  89361494016   16.64487648010254   535146790912   btrfs        A-eae4

vms repo get – Xem chi tiết không gian lưu trữ

vms repo get <repo_id> [--json]

Ví dụ đầu ra:

PROPERTY              VALUE
ENABLE LOWER NOTIFY   false
FILE SYSTEM           btrfs
HARD LIMIT            2
HOST ID               15341593-7f43-49f4-9523-6ac750a63a8a
HOST NAME             A-eae4
LAST NOTIFY TRESHOLD  -
LOCATION VOLUME       /Volume2
NAME                  VM-Storage02
REPO ID               517571ba-f7f7-49e1-9a62-7eb6ddfd9c78
SOFT LIMIT            10
STATUS                normal
TOTAL SIZE            534760128512

LOCATION VOLUME là ổ đĩa chứa không gian lưu trữ
SOFT LIMIT, HARD LIMIT là ngưỡng cảnh báo dung lượng (phần trăm)
ENABLE LOWER NOTIFY là có bật nhắc nhở thiếu dung lượng hay không

vms repo update – Cập nhật không gian lưu trữ

Chỉ gửi các trường cần sửa; các trường không gửi giữ nguyên giá trị gốc.

vms repo update --body '{"repo_id":"<repo_id>","name":"new-name"}'
vms repo update --body '{"repoId":"<repo_id>","enable_lower_notify":true}'

ID không gian lưu trữ có thể truyền qua repo_id hoặc repoId
Lệnh sẽ đọc cấu hình hiện tại trước rồi hợp nhất các trường đã gửi; các cài đặt khác sẽ không bị mất
Đầu ra là thông tin không gian lưu trữ sau khi cập nhật

vms repo delete – Xóa không gian lưu trữ (rủi ro cao)

vms repo delete <repo_id> <true|false> [--yes]

Tham số thứ hai là need_save_data: true nghĩa là giữ lại các tệp dữ liệu trên đĩa, false nghĩa là xóa cả dữ liệu
Thuộc thao tác rủi ro cao: chế độ tương tác sẽ hỏi xác nhận, chế độ phi tương tác phải thêm --yes
Xóa không gian lưu trữ sẽ đồng thời xóa máy ảo và ảnh trong đó; khuyến nghị chạy trước vms repo check-running và vms repo whether-exist-data để xác nhận phạm vi ảnh hưởng

Lời nhắc xác nhận ở chế độ tương tác:

This action will delete repository "735ef7f7-5d8d-4102-9377-8a7b8c33cda6" (save data: true). Do you want to continue? [y/N]: 

Đầu ra: Repository deleted: <repo_id>

vms repo list-volumes – Liệt kê các ổ đĩa khả dụng

Liệt kê các ổ đĩa khả dụng để tạo không gian lưu trữ.

vms repo list-volumes [--json]

Ví dụ đầu ra:

NAME  UUID                                  DEVICE               FILESYSTEM  STATUS  VOLUME TYPE  TOTAL                            USED                           AVAILABLE                        USAGE
lv3   00000004-2608-1311-3025-6cbfb504eae4  /dev/mapper/vg0-lv3  ext4        -       -            {"unit":"KB","value":102626232}  {"unit":"KB","value":52}       {"unit":"KB","value":101561220}  0.000051200619070623694
lv2   00000003-2606-2215-3256-6cbfb504eae4  /dev/mapper/vg0-lv2  btrfs       -       -            {"unit":"KB","value":104857600}  {"unit":"KB","value":9715824}  {"unit":"KB","value":93096464}   9.450061066630479

vms repo list-vms – Liệt kê máy ảo trong không gian lưu trữ

vms repo list-vms --body '{"repo_id":"<repo_id>"}'

ID không gian lưu trữ có thể truyền qua repo_id hoặc repoId
Lệnh sẽ lấy đối tượng không gian lưu trữ trước rồi truy vấn máy ảo của nó, kết quả đáng tin cậy hơn

vms repo check-running – Kiểm tra máy ảo đang chạy trên không gian lưu trữ

vms repo check-running <repo_id> [--json]

Chạy trước khi xóa không gian lưu trữ để xác nhận không có máy ảo nào đang chạy; khi không có máy ảo đang chạy thì đầu ra trống.

vms repo whether-exist-data – Kiểm tra không gian lưu trữ có dữ liệu hay không

vms repo whether-exist-data --body '{"repo_id":"<repo_id>"}'

Chạy trước khi xóa không gian lưu trữ để xác nhận không gian lưu trữ còn dữ liệu hay không; nhất quán với kiểm tra trước khi xóa không gian lưu trữ trên giao diện web.

X. Cài đặt toàn cục

vms setting get – Xem cài đặt toàn cục

Xem cấu hình toàn cục của ứng dụng VMs.

vms setting get [--json]

Ví dụ đầu ra:

PROPERTY                VALUE
HOST SHUTDOWN BEHAVIOR  1
KB LAYOUT               en-us
SHOW VIRTIO BLK VDISK   false

HOST SHUTDOWN BEHAVIOR là cách xử lý máy ảo khi máy chủ tắt nguồn
KB LAYOUT là bố cục bàn phím của máy ảo

XI. Truy vấn thông tin giám sát

vms collectd hostinfo – Xem thông tin giám sát máy chủ

vms collectd hostinfo [--limit N] [--offset N] [--json]

Ví dụ đầu ra:

NAME    ID  STATUS   TYPE     CPU USAGE  RAM USAGE  DESC
A-eae4  -   running  healthy  2.53       15.66      Info

vms collectd vminfo – Xem thông tin giám sát máy ảo

vms collectd vminfo [--limit N] [--offset N] [--json]

Ví dụ đầu ra:

NAME     ID                                    STATUS    TYPE     CPU USAGE  RAM USAGE  DESC
145      09fd98ee-4e2d-4c7a-a95c-8bacab80d322  shutdown  healthy  0          0          info
win10   9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1  shutdown  healthy  0          0          info
win101   32ee5a74-de8b-47a9-959d-1725c881ceab  shutdown  healthy  0          0          info

vms collectd storageinfo – Xem thông tin giám sát lưu trữ

vms collectd storageinfo [--limit N] [--offset N] [--json]

Ví dụ đầu ra:

NAME          ID                                    HOST NAME  STATUS  TYPE     SIZE           USED          PERCENT USED        PERCENT FREE
VM-Storage01  735ef7f7-5d8d-4102-9377-8a7b8c33cda6  A-eae4     none    healthy  1097552691200  155583651840  14.328414916992188  85.67158508300781
VM-Storage02  517571ba-f7f7-49e1-9a62-7eb6ddfd9c78  A-eae4     none    healthy  535146790912   89361494016   16.966018676757812  83.03398132324219

Chế độ tương tác và chế độ phi tương tác

CLI sẽ xác định xem hiện tại có đang chạy trong môi trường terminal hay không và áp dụng các hành vi khác nhau:

Chế độ tương tác (môi trường terminal)

Thao tác nguy hiểm hiển thị lời nhắc xác nhận, tùy chọn mặc định là No
Nhập y hoặc Y để tiếp tục thực thi, nhập n hoặc nhấn Enter trực tiếp để hủy
Khi hủy thao tác sẽ xuất Operation cancelled, mã thoát là 99

Chế độ phi tương tác (script/tự động hóa)

Thao tác nguy hiểm phải dùng --yes để bỏ qua xác nhận, nếu không lệnh sẽ báo lỗi trực tiếp và trả về mã thoát 1
Khi không có môi trường terminal sẽ không chờ nhập liệu, phù hợp cho script và tác vụ định kỳ
Khuyến nghị xử lý rõ ràng mã thoát trong script để phân biệt thành công, thất bại và xung đột trạng thái

Định dạng đầu ra JSON

Các lệnh dạng truy vấn hỗ trợ tham số --json, xuất dữ liệu JSON đã chuẩn hóa, thuận tiện cho việc phân tích bằng chương trình.

Quy ước định dạng:

Tên trường dùng snake_case
Giá trị boolean là true/false
Thời gian dùng định dạng ISO 8601, bao gồm độ chính xác nano giây và độ lệch múi giờ UTC+8 (như 2026-09-02T11:43:51.176535374+08:00)
JSON xuất ra stdout, thông tin lỗi xuất ra stderr
Các trường dài bị cắt ngắn trong đầu ra dạng bảng sẽ là giá trị đầy đủ trong đầu ra JSON

Ví dụ:

vms setting get --json

{
  "host_shutdown_behavior": 1,
  "kb_layout": "en-us",
  "show_virtio_blk_vdisk": false
}

Cấu trúc JSON của các lệnh khác nhau có chút khác biệt: vms vm list, vms vm snapshot list, vms vm logs xuất trực tiếp một mảng; các lệnh dạng danh sách còn lại xuất một đối tượng chứa totalCount và trường dữ liệu; tên trường dữ liệu khác nhau tùy tài nguyên (như items, hosts, vms, storage). Ví dụ vms repo list --json:

{
  "totalCount": 2,
  "items": {
    "517571ba-f7f7-49e1-9a62-7eb6ddfd9c78": {
      "name": "VM-Storage02",
      "repo_id": "517571ba-f7f7-49e1-9a62-7eb6ddfd9c78",
      "status": "normal",
      "used": 89361494016,
      "percent_used": 16.64487648010254,
      "location_volume": "/Volume2",
      "total_size": 535146790912,
      "hard_limit": 2,
      "soft_limit": 10,
      "enable_lower_notify": false,
      "file_system": "btrfs"
    }
  }
}

Đầu ra JSON của một số lệnh là giá trị đơn giản, ví dụ vms network ovsinfo --json xuất true, vms vm pause --json xuất null.

Mô tả mã thoát

Mã thoát	Ý nghĩa	Tình huống điển hình
0	Thành công	Lệnh hoàn thành bình thường
1	Lỗi tham số	Thiếu tham số bắt buộc, định dạng tham số sai, chưa thêm `--yes`
3	Tài nguyên không tồn tại	Kiểm tra tiên quyết của lệnh không đạt, ví dụ ảnh được chỉ định không tồn tại
4	Xung đột trạng thái	Trạng thái hiện tại của máy ảo không cho phép thao tác đó (như tắt máy với máy ảo đã tắt)
6	Lỗi kết nối	Không thể kết nối đến dịch vụ VMs, hoặc đường dẫn socket không đúng
7	Hết thời gian chờ	Yêu cầu quá thời gian chờ, có thể điều chỉnh qua `--timeout`
9	Lỗi thực thi	Phần phụ trợ trả về lỗi (thông tin lỗi bao gồm code_num và mô tả lỗi)
99	Người dùng hủy	Chọn No hoặc nhấn Enter trực tiếp khi xác nhận tương tác

Ví dụ:

# 退出码 1（参数错误）
vms vm poweroff <id>
# Confirmation required. Re-run with --yes to continue.

# 退出码 4（状态冲突）
vms vm pause <id>
# cannot pause a virtual machine: VM must be running (current status: shutdown)

# 退出码 9（执行错误）
vms vm get <id>
# vm check configure error: vdisk check - vm not exist: key not found (code_num=2001, vm check configure error)

# 退出码 6（连接错误）
vms vm list --socket /tmp/nope.sock
# failed to connect to VMs daemon (socket /tmp/nope.sock): dial unix /tmp/nope.sock: connect: no such file or directory

Ví dụ tình huống sử dụng

Vận hành hàng ngày

# 查看所有虚拟机状态
vms vm list

# 查看某台虚拟机的配置与运行状态
vms vm get <id>

# 查看虚拟机的操作日志
vms vm logs <id> --limit 20

# 开机、关机与重启
vms vm poweron <id>
vms vm poweroff <id> --yes
vms vm reboot <id>

Thao tác hàng loạt bằng script

# 批量启动所有已关机的虚拟机
vms vm list --json | jq -r '.[] | select(.status == "shutdown") | .guest_id' | while read -r id; do
    vms vm poweron "$id"
done

# 批量关闭所有运行中的虚拟机
vms vm list --json | jq -r '.[] | select(.status == "running") | .guest_id' | while read -r id; do
    vms vm poweroff "$id" --yes
done

# 存储空间容量检查，超过 80% 时输出告警
vms collectd storageinfo --json | jq -r '.storage[] | select(.percent_used > 80) | .name'

Sao lưu và kiểm tra

# 关机后为虚拟机创建快照
vms vm poweroff <id> --yes
vms vm snapshot consistency <id>
vms vm snapshot create <id> --body '{"description":"weekly-backup"}'

# 查看快照列表与详情
vms vm snapshot list <id>
vms vm snapshot config <id> <snapshot_name>

# 导出虚拟机为 OVA 文件，用于异地备份
vms vm export --body '{"guest_id":"<id>","target_ova_path":"/Volume1/backup/my-vm.ova"}'

Kiểm tra trước khi xóa

# 删除存储空间前，先确认是否有虚拟机正在运行、是否存在数据
vms repo check-running <repo_id>
vms repo whether-exist-data --body '{"repo_id":"<repo_id>"}'

# 删除映像前，先确认有哪些虚拟机在使用
vms image list-vms --image-id <image_id>

# 删除网络前，先确认接入的虚拟机
vms network list-vnics <network_id>

Gọi bằng công cụ AI

# AI 工具可通过命令行调用 vms 命令
# 例如：获取虚拟机与宿主机状态供 AI 分析
vms vm list --json
vms collectd hostinfo --json

# AI 可解析 JSON 输出并作出决策
vms vm list-resource --json

Phát triển nội bộ và tích hợp hệ thống

# 开发人员可通过 CLI 封装内部运维工具
# 示例：封装虚拟机健康检查函数
check_vm_health() {
    vms collectd vminfo --json | jq -r '.vms[] | select(.status != "running") | .name'
}

# 将 CLI 集成到内部监控平台
vms collectd storageinfo --json | curl -X POST https://monitor.example.com/api/report -d @-

Câu hỏi thường gặp

Q: CLI có cần cài đặt thêm không?

Không. CLI được cài đặt cùng với ứng dụng VMs; sau khi ứng dụng được kích hoạt, chỉ cần thực thi lệnh vms là dùng được.

Q: CLI có bắt buộc dùng qua SSH không?

Không. CLI có thể được gọi qua bất kỳ terminal dòng lệnh nào, bao gồm terminal cục bộ, SSH từ xa, script, công cụ AI, v.v.

Q: CLI có thể quản lý máy ảo trên thiết bị khác không?

Không thể. CLI giao tiếp với dịch vụ VMs qua unix socket cục bộ, chỉ dùng để quản lý máy ảo trên máy cục bộ.

Q: Tại sao một số lệnh nhắc xác nhận còn một số thì không?

Các thao tác như xóa máy ảo, xóa mạng, xóa ảnh, xóa không gian lưu trữ và tắt máy (poweroff, force-poweroff) sẽ ảnh hưởng đến dữ liệu hoặc dịch vụ, nên mặc định yêu cầu xác nhận; các lệnh khởi động, khởi động lại, tạm dừng, phục hồi và dạng truy vấn không có giới hạn này.

Q: Làm thế nào để xác nhận thao tác nguy hiểm ở chế độ phi tương tác?

Tất cả thao tác nguy hiểm phải thêm tham số --yes, nếu không lệnh sẽ báo lỗi và thoát (mã thoát 1).

Q: Làm thế nào để đánh giá trong script liệu lệnh có thực thi thành công hay không?

Đánh giá qua mã thoát: 0 nghĩa là thành công, khác 0 nghĩa là thất bại. Cũng có thể phân tích nội dung đầu ra của --json.

Q: Tại sao danh sách đầu ra của --json lại là một đối tượng?

Đầu ra JSON của một số lệnh được tổ chức thành đối tượng theo ID, kèm trường totalCount, thuận tiện để truy cập trực tiếp theo ID.

Trợ giúp thêm

Mỗi lệnh đều hỗ trợ --help để xem cách dùng chi tiết:

vms --help
vms vm --help
vms vm poweroff --help
vms network create --help

Giới thiệu​

Tính năng chính​

Bắt đầu nhanh​

Tùy chọn toàn cục​

Ví dụ thông tin phiên bản​

Môi trường chạy​

Bảng tổng hợp lệnh​

Tham chiếu lệnh​

I. Truy vấn máy ảo​

vms vm list – Liệt kê máy ảo​

vms vm get – Xem chi tiết máy ảo​

vms vm list-resource – Liệt kê tài nguyên khả dụng để tạo máy ảo​

vms vm logs – Xem nhật ký thao tác máy ảo​

II. Quản lý nguồn máy ảo​

vms vm poweron – Khởi động máy ảo​

vms vm poweroff – Tắt máy ảo​

vms vm force-poweroff – Buộc tắt máy ảo (rủi ro cao)​

vms vm reboot – Khởi động lại máy ảo​

vms vm pause – Tạm dừng máy ảo​

vms vm resume – Phục hồi máy ảo​

vms vm autorun – Đặt tự khởi động khi khởi động​

III. Nhân bản, xuất và xóa máy ảo​

vms vm clone – Nhân bản máy ảo​

vms vm export – Xuất máy ảo​

vms vm delete – Xóa máy ảo (rủi ro cao)​

IV. Đĩa ảo​

vms vm disk list – Xem đĩa ảo​

V. Quản lý ảnh chụp nhanh​

vms vm snapshot list – Liệt kê ảnh chụp nhanh​

vms vm snapshot create – Tạo ảnh chụp nhanh​

vms vm snapshot edit – Chỉnh sửa ảnh chụp nhanh​

vms vm snapshot config – Xem cấu hình máy ảo của ảnh chụp nhanh​

vms vm snapshot consistency – Xem trước tính nhất quán của ảnh chụp nhanh​

VI. Bảng điều khiển từ xa​

vms vm link – Lấy thông tin kết nối VNC​

VII. Quản lý mạng ảo​

vms network list – Liệt kê mạng ảo​

vms network get – Xem chi tiết mạng ảo​

vms network create – Tạo mạng ảo​

vms network update – Cập nhật mạng ảo​

vms network delete – Xóa mạng ảo (rủi ro cao)​

vms network list-interfaces – Liệt kê giao diện mạng​

vms network list-vnics – Liệt kê card mạng ảo trên mạng​

vms network ovsinfo – Xem trạng thái OVS​

VIII. Quản lý ảnh​

vms image list – Liệt kê ảnh​

vms image edit – Chỉnh sửa ảnh​

vms image delete – Xóa ảnh (rủi ro cao)​

vms image list-vms – Xem các máy ảo đang dùng ảnh này​

IX. Quản lý không gian lưu trữ​

vms repo list – Liệt kê không gian lưu trữ​

vms repo get – Xem chi tiết không gian lưu trữ​

vms repo update – Cập nhật không gian lưu trữ​

vms repo delete – Xóa không gian lưu trữ (rủi ro cao)​

vms repo list-volumes – Liệt kê các ổ đĩa khả dụng​

vms repo list-vms – Liệt kê máy ảo trong không gian lưu trữ​

vms repo check-running – Kiểm tra máy ảo đang chạy trên không gian lưu trữ​

vms repo whether-exist-data – Kiểm tra không gian lưu trữ có dữ liệu hay không​

X. Cài đặt toàn cục​

vms setting get – Xem cài đặt toàn cục​

XI. Truy vấn thông tin giám sát​

vms collectd hostinfo – Xem thông tin giám sát máy chủ​

vms collectd vminfo – Xem thông tin giám sát máy ảo​

vms collectd storageinfo – Xem thông tin giám sát lưu trữ​

Chế độ tương tác và chế độ phi tương tác​

Chế độ tương tác (môi trường terminal)​

Chế độ phi tương tác (script/tự động hóa)​

Định dạng đầu ra JSON​

Mô tả mã thoát​

Ví dụ tình huống sử dụng​

Vận hành hàng ngày​

Thao tác hàng loạt bằng script​

Sao lưu và kiểm tra​

Kiểm tra trước khi xóa​

Gọi bằng công cụ AI​

Phát triển nội bộ và tích hợp hệ thống​

Câu hỏi thường gặp​

Trợ giúp thêm​

Giới thiệu

Tính năng chính

Bắt đầu nhanh

Tùy chọn toàn cục

Ví dụ thông tin phiên bản

Môi trường chạy

Bảng tổng hợp lệnh

Tham chiếu lệnh

I. Truy vấn máy ảo

vms vm list – Liệt kê máy ảo

vms vm get – Xem chi tiết máy ảo

vms vm list-resource – Liệt kê tài nguyên khả dụng để tạo máy ảo

vms vm logs – Xem nhật ký thao tác máy ảo

II. Quản lý nguồn máy ảo

vms vm poweron – Khởi động máy ảo

vms vm poweroff – Tắt máy ảo

vms vm force-poweroff – Buộc tắt máy ảo (rủi ro cao)

vms vm reboot – Khởi động lại máy ảo

vms vm pause – Tạm dừng máy ảo

vms vm resume – Phục hồi máy ảo

vms vm autorun – Đặt tự khởi động khi khởi động

III. Nhân bản, xuất và xóa máy ảo

vms vm clone – Nhân bản máy ảo

vms vm export – Xuất máy ảo

vms vm delete – Xóa máy ảo (rủi ro cao)

IV. Đĩa ảo

vms vm disk list – Xem đĩa ảo

V. Quản lý ảnh chụp nhanh

vms vm snapshot list – Liệt kê ảnh chụp nhanh

vms vm snapshot create – Tạo ảnh chụp nhanh

vms vm snapshot edit – Chỉnh sửa ảnh chụp nhanh

vms vm snapshot config – Xem cấu hình máy ảo của ảnh chụp nhanh

vms vm snapshot consistency – Xem trước tính nhất quán của ảnh chụp nhanh

VI. Bảng điều khiển từ xa

vms vm link – Lấy thông tin kết nối VNC

VII. Quản lý mạng ảo

vms network list – Liệt kê mạng ảo

vms network get – Xem chi tiết mạng ảo

vms network create – Tạo mạng ảo

vms network update – Cập nhật mạng ảo

vms network delete – Xóa mạng ảo (rủi ro cao)

vms network list-interfaces – Liệt kê giao diện mạng

vms network list-vnics – Liệt kê card mạng ảo trên mạng

vms network ovsinfo – Xem trạng thái OVS

VIII. Quản lý ảnh

vms image list – Liệt kê ảnh

vms image edit – Chỉnh sửa ảnh

vms image delete – Xóa ảnh (rủi ro cao)

vms image list-vms – Xem các máy ảo đang dùng ảnh này

IX. Quản lý không gian lưu trữ

vms repo list – Liệt kê không gian lưu trữ

vms repo get – Xem chi tiết không gian lưu trữ

vms repo update – Cập nhật không gian lưu trữ

vms repo delete – Xóa không gian lưu trữ (rủi ro cao)

vms repo list-volumes – Liệt kê các ổ đĩa khả dụng

vms repo list-vms – Liệt kê máy ảo trong không gian lưu trữ

vms repo check-running – Kiểm tra máy ảo đang chạy trên không gian lưu trữ

vms repo whether-exist-data – Kiểm tra không gian lưu trữ có dữ liệu hay không

X. Cài đặt toàn cục

vms setting get – Xem cài đặt toàn cục

XI. Truy vấn thông tin giám sát

vms collectd hostinfo – Xem thông tin giám sát máy chủ

vms collectd vminfo – Xem thông tin giám sát máy ảo

vms collectd storageinfo – Xem thông tin giám sát lưu trữ

Chế độ tương tác và chế độ phi tương tác

Chế độ tương tác (môi trường terminal)

Chế độ phi tương tác (script/tự động hóa)

Định dạng đầu ra JSON

Mô tả mã thoát

Ví dụ tình huống sử dụng

Vận hành hàng ngày

Thao tác hàng loạt bằng script

Sao lưu và kiểm tra

Kiểm tra trước khi xóa

Gọi bằng công cụ AI

Phát triển nội bộ và tích hợp hệ thống

Câu hỏi thường gặp

Trợ giúp thêm