Version: TOS 7

VMs CLI

مقدمة

VMs CLI هي أداة إدارة سطر الأوامر لتطبيق TerraMaster VMs للمحاكاة الافتراضية، وتوفّر قدرات الاستعلام والصيانة المطابقة لواجهة الإدارة الرسومية. يتواصل CLI مع خدمة VMs عبر unix socket المحلي، ويعتمد واجهة أوامر موحّدة وتنسيق إخراج JSON، ويمكن دمجه في النصوص البرمجية والعمليات الآلية وسير عمل التطوير الثانوي.

الميزات الرئيسية

جاهز للاستخدام مباشرة: يُثبَّت مع تطبيق VMs دون حاجة إلى تثبيت إضافي
طرق استدعاء مرنة: يدعم الطرفية المحلية وSSH عن بُعد والنصوص البرمجية وأدوات AI ووسائل استدعاء أخرى متعددة
وضعان تفاعلي وغير تفاعلي: مناسب للصيانة اليومية للمسؤول وأيضًا للنصوص البرمجية والمهام الآلية
دعم إخراج JSON: يسهّل التحليل البرمجي والدمج الآلي
الاتصال المحلي: يتواصل مع خدمة VMs فقط عبر unix socket المحلي، ولا يفتح منافذ خارجية
تأكيد ثانٍ للعمليات الخطرة: تتطلب عمليات مثل حذف الأجهزة الافتراضية وحذف الشبكات تأكيدًا افتراضيًا

البدء السريع

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

# 查看虚拟机列表
vms vm list

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

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

مثال على إخراج 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    -

الخيارات العامة

تنطبق الخيارات التالية على جميع الأوامر:

الخيار	المختصر	الوصف
`--help`	`-h`	يعرض معلومات مساعدة الأمر
`--version`	`-v`	يعرض رقم الإصدار (يمكن استخدام `--json` لإخراج معلومات منظّمة)
`--json`	-	يُخرج بتنسيق JSON
`--yes`	`-y`	يتخطى رسالة تأكيد العمليات الخطرة (يجب استخدامه في الوضع غير التفاعلي)
`--debug`	-	يفعّل إخراج التصحيح ويعرض تفاصيل عملية التنفيذ
`--socket <path>`	-	مسار unix socket الخاص بـ VMs، الافتراضي `/var/api/VMs.sock`
`--timeout <duration>`	-	مهلة الطلب، الافتراضي 30s

مثال على معلومات الإصدار

vms --version

vms CLI v1.0.058

vms --version --json

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

بيئة التشغيل

يُثبَّت VMs CLI مع تطبيق VMs. عند تفعيل التطبيق يقوم بربط CLI بدليل PATH الافتراضي للنظام، ويمكن استخدامه مباشرة بعد تسجيل الدخول عبر SSH.

البند	الوصف
ملف CLI	`/Volume1/@apps/VMs/bin/vms`
مسار الأمر	`/usr/local/sbin/vms` (موجود في PATH الخاص بالنظام)
وسيلة الاتصال	unix socket المحلي، الافتراضي `/var/api/VMs.sock`
الفئة المستهدفة	المسؤول المسجّل الدخول إلى هذا الجهاز

ملاحظات:

CLI مخصص لإدارة الأجهزة الافتراضية المحلية، ولا يدعم الإدارة عن بُعد لأجهزة أخرى عبر CLI.
تُرجع الواجهة الخلفية دائمًا HTTP 200، ويُحدَّد نجاح الأمر من الحقل code في جسم الاستجابة، ويحوّله CLI إلى رمز خروج بناءً على ذلك.
العمليات الخطرة (حذف الجهاز الافتراضي، حذف الشبكة، حذف الصورة، حذف مساحة التخزين) تطلب تأكيدًا في الوضع التفاعلي، ويجب تمرير --yes صراحةً في الوضع غير التفاعلي.

جدول ملخّص الأوامر

فيما يلي ملخّص مرجعي سريع لجميع أوامر vms:

الأمر الأصل	الأمر الفرعي	وصف الوظيفة	يحتاج تأكيدًا	خطر مرتفع
vms	--version	يعرض معلومات الإصدار	لا	لا
vms vm	list	يسرد جميع الأجهزة الافتراضية	لا	لا
vms vm	get	يعرض تفاصيل جهاز افتراضي محدّد	لا	لا
vms vm	list-resource	يسرد الموارد المتاحة لإنشاء جهاز افتراضي	لا	لا
vms vm	logs	يعرض سجلات عمليات الجهاز الافتراضي	لا	لا
vms vm	poweron	يشغّل الجهاز الافتراضي	لا	لا
vms vm	poweroff	يغلق الجهاز الافتراضي (إغلاق عادي)	نعم	لا
vms vm	force-poweroff	يغلق الجهاز الافتراضي قسريًا	نعم	✅
vms vm	reboot	يعيد تشغيل الجهاز الافتراضي	لا	لا
vms vm	pause	يوقف الجهاز الافتراضي مؤقتًا	لا	لا
vms vm	resume	يستأنف الجهاز الافتراضي المتوقف مؤقتًا	لا	لا
vms vm	autorun	يضبط التشغيل التلقائي عند بدء التشغيل	لا	لا
vms vm	clone	يستنسخ الجهاز الافتراضي	لا	لا
vms vm	export	يصدّر الجهاز الافتراضي كملف OVA	لا	لا
vms vm	delete	يحذف الجهاز الافتراضي	نعم	✅
vms vm disk	list	يعرض الأقراص الصلبة الافتراضية للجهاز الافتراضي	لا	لا
vms vm snapshot	list	يسرد لقطات الجهاز الافتراضي	لا	لا
vms vm snapshot	create	ينشئ لقطة	لا	لا
vms vm snapshot	edit	يعدّل وصف اللقطة وحالة القفل	لا	لا
vms vm snapshot	config	يعرض إعدادات الجهاز الافتراضي المحفوظة في اللقطة	لا	لا
vms vm snapshot	consistency	يعاين تناسق اللقطة	لا	لا
vms vm	link	يحصل على معلومات اتصال وحدة تحكم VNC	لا	لا
vms network	list	يسرد الشبكات الافتراضية	لا	لا
vms network	get	يعرض تفاصيل الشبكة الافتراضية	لا	لا
vms network	create	ينشئ شبكة افتراضية	لا	لا
vms network	update	يحدّث الشبكة الافتراضية	لا	لا
vms network	delete	يحذف الشبكة الافتراضية	نعم	✅
vms network	list-interfaces	يسرد واجهات الشبكة من نوع محدّد	لا	لا
vms network	list-vnics	يسرد بطاقات الشبكة الافتراضية على الشبكة	لا	لا
vms network	ovsinfo	يعرض ما إذا كان OVS مفعّلًا	لا	لا
vms image	list	يسرد الصور	لا	لا
vms image	edit	يعدّل معلومات الصورة	لا	لا
vms image	delete	يحذف الصورة	نعم	✅
vms image	list-vms	يعرض الأجهزة الافتراضية التي تستخدم هذه الصورة	لا	لا
vms repo	list	يسرد مساحات التخزين	لا	لا
vms repo	get	يعرض تفاصيل مساحة التخزين	لا	لا
vms repo	update	يحدّث إعدادات مساحة التخزين	لا	لا
vms repo	delete	يحذف مساحة التخزين	نعم	✅
vms repo	list-volumes	يسرد وحدات التخزين المتاحة	لا	لا
vms repo	list-vms	يسرد الأجهزة الافتراضية داخل مساحة التخزين	لا	لا
vms repo	check-running	يتحقق من الأجهزة الافتراضية العاملة على مساحة التخزين	لا	لا
vms repo	whether-exist-data	يتحقق من وجود بيانات داخل مساحة التخزين	لا	لا
vms setting	get	يعرض الإعدادات العامة	لا	لا
vms collectd	hostinfo	يعرض معلومات مراقبة المضيف	لا	لا
vms collectd	vminfo	يعرض معلومات مراقبة الأجهزة الافتراضية	لا	لا
vms collectd	storageinfo	يعرض معلومات مراقبة التخزين	لا	لا

مرجع الأوامر

يشير <id> في الأوامر إلى معرّف الجهاز الافتراضي، ويقابل GUEST ID في إخراج قائمة الأجهزة الافتراضية؛ وبالمثل <network_id> و<image_id> و<repo_id>، ويمكن الحصول عليها على التوالي عبر vms network list وvms image list وvms repo list.

بخصوص أمثلة الإخراج: يقوم إخراج الجدول في vms باقتطاع القيم الطويلة جدًا بعرض ثابت (تنتهي بعلامة حذف، وبمعزل عن عرض الطرفية)، مثل VDISKS وVNICS وISO IMAGES في إعدادات الجهاز الافتراضي، وأسماء الصور. لذلك، توفّر هذه الوثيقة للأوامر التي تتضمن حقولًا طويلة أمثلة إخراج --json كاملة بشكل موحّد، بينما توفّر الأوامر الأخرى أمثلة إخراج جدولية. ويُنصح أيضًا باستخدام --json بشكل موحّد عند المعالجة بالنصوص البرمجية.

1. الاستعلام عن الأجهزة الافتراضية

vms vm list – سرد الأجهزة الافتراضية

يسرد جميع الأجهزة الافتراضية على هذا الجهاز وحالتها الأساسية.

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

--limit و--offset هما معلمتا ترقيم الصفحات
أعمدة الإخراج: الاسم، معرّف الجهاز الافتراضي، حالة التشغيل، عدد أنوية CPU، حجم الذاكرة (بالوحدة KB)، عنوان IP

مثال على الإخراج:

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    -

القيم الشائعة لـ STATUS:

الحالة	الوصف
running	قيد التشغيل
shutdown	مغلق
saved	متوقف مؤقتًا (حُفظت حالة التشغيل على القرص)

vms vm get – عرض تفاصيل الجهاز الافتراضي

يعرض الإعدادات الكاملة وحالة التشغيل لجهاز افتراضي محدّد.

vms vm get <id> --json

يتضمن الإخراج جميع حقول إعدادات الجهاز الافتراضي وحالة تشغيله
تُعرض القيم الفارغة مثل عدم وجود وصف أو IP كسلسلة نصية فارغة
إذا لم يكن الجهاز الافتراضي موجودًا، يُرجع الأمر خطأً ويخرج رسالة خطأ

مثال على الإخراج:

{
  "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 – سرد الموارد المتاحة لإنشاء جهاز افتراضي

يعرض الموارد التي يمكن للمضيف توفيرها مثل أنواع البرامج الثابتة والصور وCPU والذاكرة والشبكة ومساحات التخزين والأجهزة القابلة للتمرير المباشر، وذلك للتقييم قبل إنشاء جهاز افتراضي.

vms vm list-resource --json

الحقول المُرجعة: max_cpu_num وmax_ram_size وusbs وpci_devices وnetworks وrepos وimages وvideo_cards وfirmware وkeyboard_layout.

مثال على الإخراج:

{
  "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 – عرض سجلات عمليات الجهاز الافتراضي

يعرض سجلات العمليات المتعلقة بجهاز افتراضي محدّد (التشغيل/الإغلاق، اللقطات، التعديل، الاستيراد/التصدير، إلخ).

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

--limit يحدّد عدد السجلات المُرجعة، الافتراضي 50
--desc بترتيب زمني تنازلي (مفعّل افتراضيًا)
يتضمن كل سجل الوقت والمستوى والفئة والمستخدم المنفّذ ووصف الحدث، ووصف الحدث نص كامل
يُخرج وصف الحدث (event) من خدمة VMs مترجمًا وفق لغة نظام الجهاز، وتستخدم أمثلة هذه الوثيقة الإنجليزية بشكل موحّد

مثال على الإخراج:

[
  {
    "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)"
  }
]

2. إدارة طاقة الأجهزة الافتراضية

vms vm poweron – تشغيل الجهاز الافتراضي

vms vm poweron <id>

يجب أن يكون الجهاز الافتراضي في حالة إغلاق، وإلا يُرجع خطأ تضارب الحالة
الإخراج: VM powered on: <id>

vms vm poweroff – إغلاق الجهاز الافتراضي

يرسل طلب إغلاق عادي إلى الجهاز الافتراضي ليقوم النظام بالإغلاق اللطيف.

vms vm poweroff <id> [--yes]

عملية خطرة: يطلب تأكيدًا في الوضع التفاعلي، ويجب إضافة --yes في الوضع غير التفاعلي
يجب أن يكون الجهاز الافتراضي في حالة تشغيل، وإلا يُرجع خطأ تضارب الحالة

رسالة تأكيد الوضع التفاعلي:

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

الإخراج: VM powered off: <id>

vms vm force-poweroff – إغلاق الجهاز الافتراضي قسريًا (خطر مرتفع)

يغلق الجهاز الافتراضي قسريًا، وهو مكافئ لقطع التيار مباشرة.

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

عملية عالية الخطورة: يطلب تأكيدًا في الوضع التفاعلي، ويجب إضافة --yes في الوضع غير التفاعلي
قد يؤدي إلى فقدان البيانات داخل الجهاز الافتراضي، ويُنصح باستخدامه فقط عندما لا يستجيب الجهاز الافتراضي

رسالة تأكيد الوضع التفاعلي:

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

الإخراج: VM force powered off: <id>

vms vm reboot – إعادة تشغيل الجهاز الافتراضي

vms vm reboot <id>

الإخراج: VM rebooted: <id>

vms vm pause – إيقاف الجهاز الافتراضي مؤقتًا

يجمّد حالة تشغيل الجهاز الافتراضي ويحفظ الحالة الحالية على القرص.

vms vm pause <id>

يجب أن يكون الجهاز الافتراضي في حالة تشغيل، وإلا يُرجع خطأ تضارب الحالة
بعد الإيقاف المؤقت تُعرض حالة الجهاز الافتراضي كـ saved
الإخراج: VM paused: <id>

vms vm resume – استئناف الجهاز الافتراضي

يعيد الجهاز الافتراضي من حالة الإيقاف المؤقت إلى حالة التشغيل.

vms vm resume <id>

يجب أن يكون الجهاز الافتراضي في حالة إيقاف مؤقت، وإلا يُرجع خطأ تضارب الحالة
الإخراج: VM resumed: <id>

vms vm autorun – ضبط التشغيل التلقائي عند بدء التشغيل

يضبط ما إذا كان الجهاز الافتراضي سيبدأ تلقائيًا مع بدء تشغيل المضيف.

vms vm autorun <id> <true|false>

يجب أن تكون المعلمة الثانية true أو false
يقرأ الأمر الإعدادات الحالية ويعدّل فقط مفتاح التشغيل التلقائي، ولا تتأثر الإعدادات الأخرى
الإخراج: Auto-start enabled for VM <id> أو Auto-start disabled for VM <id>

3. نسخ الجهاز الافتراضي وتصديره وحذفه

vms vm clone – استنساخ الجهاز الافتراضي

ينشئ جهازًا افتراضيًا جديدًا بناءً على جهاز افتراضي موجود كقالب.

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

في جسم الطلب، guest_id هو معرّف الجهاز الافتراضي المصدر، وname (أو guest_name) هو اسم الجهاز الافتراضي الجديد
يجب أن يكون الجهاز الافتراضي المصدر في حالة إغلاق
--body يمرّر جسم الطلب مباشرة كسلسلة JSON، و--file يقرأ جسم الطلب من ملف

vms vm export – تصدير الجهاز الافتراضي

يصدّر الجهاز الافتراضي كملف OVA، لتسهيل النسخ الاحتياطي أو الترحيل إلى منصة محاكاة افتراضية أخرى.

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

في جسم الطلب، guest_id هو معرّف الجهاز الافتراضي المصدر، وtarget_ova_path هو مسار الملف الهدف، وova_mode هو وضع توافق VMware الاختياري
يجب أن يكون الجهاز الافتراضي المصدر في حالة إغلاق
التصدير مهمة مستهلكة للوقت، ويستغرق التصدير وقتًا أطول للأجهزة الافتراضية ذات السعة الكبيرة

vms vm delete – حذف الجهاز الافتراضي (خطر مرتفع)

يحذف الجهاز الافتراضي بشكل دائم.

vms vm delete <id> [--yes]

عملية عالية الخطورة: يطلب تأكيدًا في الوضع التفاعلي، ويجب إضافة --yes في الوضع غير التفاعلي
لا يمكن الاستعادة بعد الحذف، لذا يُرجى التأكد مسبقًا من نسخ بيانات الجهاز الافتراضي احتياطيًا

رسالة تأكيد الوضع التفاعلي:

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

الإخراج: VM deleted: <id>

4. الأقراص الصلبة الافتراضية

vms vm disk list – عرض الأقراص الصلبة الافتراضية

يسرد جميع الأقراص الصلبة الافتراضية لجهاز افتراضي محدّد.

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

مثال على الإخراج:

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

VDISK MODE هو رقم نوع وحدة تحكم القرص الصلب الافتراضي، و1 يعني IDE
يُعرض القرص الصلب الافتراضي غير المسمّى كـ - في العمود NAME

5. إدارة اللقطات

vms vm snapshot list – سرد اللقطات

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

مثال على الإخراج:

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 هو حالة تشغيل الجهاز الافتراضي عند إنشاء اللقطة
ACTUAL CONSISTENCY هو نوع تناسق اللقطة، وfilesystem يعني تناسق نظام الملفات، وcrash يعني تناسق الانهيار

vms vm snapshot create – إنشاء لقطة

ينشئ لقطة للجهاز الافتراضي، تُستخدم للاسترجاع السريع أو النسخ الاحتياطي للحالة الحالية.

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

جسم الطلب اختياري: description هو وصف اللقطة، وlocked هو ما إذا كانت مقفلة
يُنشئ النظام اسم اللقطة تلقائيًا وفق وقت الإنشاء
تشغل اللقطات مساحة تخزين، وقد يؤدي عدم تنظيفها لفترة طويلة إلى امتلاء مساحة التخزين، ويُنصح بترتيبها دوريًا

vms vm snapshot edit – تعديل اللقطة

يعدّل وصف اللقطة أو حالة القفل.

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

تُعدّل الحقول الواردة في جسم الطلب فقط، وتحتفظ الحقول غير الواردة بقيمها الأصلية؛ تعديل الوصف وحده لا يغيّر حالة القفل، والعكس صحيح

مثال على الإخراج:

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 – عرض إعدادات الجهاز الافتراضي في اللقطة

يعرض إعدادات الجهاز الافتراضي المحفوظة في اللقطة.

vms vm snapshot config <id> <snapshot_name>

<id> هو معرّف الجهاز الافتراضي، و<snapshot_name> هو اسم اللقطة، ويمكن الحصول عليه عبر vms vm snapshot list <id>.

مثال على الإخراج:

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 – معاينة تناسق اللقطة

يعاين نوع التناسق المحتمل الحصول عليه قبل إنشاء اللقطة، ويساعد في تحديد ما إذا كانت الحالة الحالية مناسبة لإنشاء لقطة.

vms vm snapshot consistency <id>

مثال على الإخراج:

PROPERTY          VALUE
CONSISTENCY TYPE  filesystem
REASON            vm_shutdown
VM STATE          shutdown

عند إنشاء لقطة والجهاز الافتراضي مغلق يمكن الحصول على لقطة متناسقة مع نظام الملفات؛ وفي حالة التشغيل عادةً لا يمكن الحصول إلا على لقطة متناسقة مع الانهيار.

6. وحدة التحكم عن بُعد

vms vm link – الحصول على معلومات اتصال VNC

يحصل على معلومات اتصال وحدة تحكم VNC للجهاز الافتراضي، وتُستخدم لفتح وحدة التحكم عن بُعد في المتصفح.

vms vm link <id> --json

يجب أن يكون الجهاز الافتراضي في حالة تشغيل أو إيقاف مؤقت، وإلا يُرجع خطأ تضارب الحالة

مثال على الإخراج:

{
  "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 هو مسار وحدة التحكم نسبةً إلى عنوان إدارة NAS، وport هو منفذ خدمة وحدة التحكم، وhttps يشير إلى ما إذا كان الوصول عبر HTTPS مطلوبًا
في إخراج JSON يُهرَّب الرمز & داخل URL إلى \u0026

7. إدارة الشبكات الافتراضية

تنقسم أنواع الشبكات إلى نوعين:

النوع	الوصف
خاص (private)	شبكة داخلية للتواصل بين الأجهزة الافتراضية على هذا الجهاز فقط، ولا تُربط ببطاقة شبكة فعلية
خارجي (external)	شبكة مرتبطة ببطاقة شبكة فعلية، ويمكن للأجهزة الافتراضية التواصل مع الخارج عبرها

vms network list – سرد الشبكات الافتراضية

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

مثال على الإخراج:

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 هو عدد الأجهزة الافتراضية المتصلة بهذه الشبكة، وNUM INTERFACES هو عدد بطاقات الشبكة الفعلية المحدّدة

vms network get – عرض تفاصيل الشبكة الافتراضية

vms network get <network_id> --json

مثال على الإخراج:

{
  "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 هي معلومات بطاقات الشبكة المرتبطة بهذه الشبكة، منظّمة حسب معرّف المضيف، ويشير checked إلى ما إذا كانت البطاقة محدّدة
metadata يسجّل وقت إنشاء الشبكة وتحديثها

vms network create – إنشاء شبكة افتراضية

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

إنشاء شبكة خاصة:

يجب أن يتضمن جسم الطلب name وtype (private) وhost_name أو host_id لتحديد المضيف الذي تُنشأ عليه الشبكة
قبل الإنشاء يمكن عرض المضيفين المتاحين عبر vms network list-interfaces private

إنشاء شبكة خارجية:

يجب أن يتضمن جسم الطلب name وtype (external) وvlan_id، وتحديد بطاقة شبكة فعلية واحدة على الأقل
يمكن تحديد بطاقة الشبكة عبر interface_name (مثل LAN 1) أو interface_id، وعندما لا يكون اسم البطاقة فريدًا عبر المضيفين يجب استخدامه مع host_name
قبل الإنشاء يمكن عرض بطاقات الشبكة المتاحة عبر vms network list-interfaces external

الإخراج هو معلومات الشبكة بعد الإنشاء، وهو مطابق لبنية 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
}

عند عدم تحديد بطاقة شبكة يعطي الأمر تنبيهًا:

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 – تحديث الشبكة الافتراضية

أرسل الحقول المطلوب تعديلها فقط، وتحتفظ الحقول غير المُرسلة بقيمها الأصلية.

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

يجب أن يتضمن جسم الطلب network_id
يقرأ الأمر أولًا إعدادات الشبكة الحالية ويدمج الحقول المُرسلة، ولا يُفرَّغ اسم الشبكة ولا بطاقات الشبكة المحدّدة
الإخراج هو معلومات الشبكة بعد التحديث

vms network delete – حذف الشبكة الافتراضية (خطر مرتفع)

vms network delete <network_id> [--yes]

عملية عالية الخطورة: يطلب تأكيدًا في الوضع التفاعلي، ويجب إضافة --yes في الوضع غير التفاعلي
حذف الشبكة يقطع اتصال جميع الأجهزة الافتراضية المتصلة بها
يُنصح أولًا بتأكيد الأجهزة الافتراضية المتصلة عبر vms network list-vnics <network_id>

رسالة تأكيد الوضع التفاعلي:

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

الإخراج: Network deleted: <network_id>

vms network list-interfaces – سرد واجهات الشبكة

يسرد واجهات الشبكة من نوع محدّد.

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

external يُرجع بطاقات الشبكة الفعلية المتاحة على المضيف
private يُرجع معلومات المضيف المتاحة لإنشاء شبكة خاصة

مثال على الإخراج (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

مثال على الإخراج (private):

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

vms network list-vnics – سرد بطاقات الشبكة الافتراضية على الشبكة

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

مثال على الإخراج:

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 – عرض حالة OVS

يتحقق من ما إذا كان مُبدّل Open vSwitch الافتراضي مفعّلًا.

vms network ovsinfo [--json]

مثال على الإخراج:

PROPERTY  VALUE
RESULT    true

كون VALUE يساوي true يعني أن OVS مفعّل.

8. إدارة الصور

vms image list – سرد الصور

يسرد ملفات صور النظام المتاحة لإنشاء الأجهزة الافتراضية.

vms image list --json

image_name هو اسم الصورة، وfile_name هو اسم الملف المقابل
type هو تنسيق الصورة، مثل iso وqcow2
status هو حالة الصورة، وavailable يعني متاحة
repos هي مساحات التخزين التي توجد فيها الصورة
progress هو تقدّم مهمة معالجة الصورة، و0 يعني عدم وجود مهمة جارية

مثال على الإخراج:

{
  "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 – تعديل الصورة

يعدّل اسم الصورة، أو يضبط مساحة التخزين التي توجد فيها الصورة.

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

يجب أن يتضمن جسم الطلب image_id وrepos، حيث repos هي قائمة مساحات التخزين الهدف الكاملة للصورة، ولا يمكن أن تكون فارغة
image_name وfile_name وtype وfile_size حقول اختيارية، وتُستخدم القيم الحالية عند عدم توفيرها
كون repos فارغة يؤدي إلى إخراج الصورة من جميع مساحات التخزين، ويرفض الأمر هذا الطلب قبل التنفيذ
الإخراج: Image updated

vms image delete – حذف الصورة (خطر مرتفع)

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

--image-id مطلوب
عملية عالية الخطورة: يطلب تأكيدًا في الوضع التفاعلي، ويجب إضافة --yes في الوضع غير التفاعلي
لا يؤثر حذف الصورة على الأجهزة الافتراضية المُنشأة، لكنه يؤثر على إنشاء أجهزة افتراضية لاحقًا بناءً على هذه الصورة
يُنصح أولًا بتأكيد الاستخدام عبر vms image list-vms --image-id <image_id>

رسالة تأكيد الوضع التفاعلي:

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

الإخراج: Image deleted: <image_id>

vms image list-vms – عرض الأجهزة الافتراضية التي تستخدم هذه الصورة

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

مثال على الإخراج:

GUEST NAME
1454486

يمكن تنفيذ هذا الأمر قبل حذف الصورة لتأكيد نطاق التأثير؛ وعند عدم وجود أجهزة افتراضية تستخدم الصورة يكون الإخراج فارغًا.

9. إدارة مساحات التخزين

vms repo list – سرد مساحات التخزين

vms repo list [--json]

مثال على الإخراج:

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 – عرض تفاصيل مساحة التخزين

vms repo get <repo_id> [--json]

مثال على الإخراج:

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 هي وحدة التخزين التي توجد فيها مساحة التخزين
SOFT LIMIT وHARD LIMIT هما عتبتا تنبيه السعة (بالنسبة المئوية)
ENABLE LOWER NOTIFY هو ما إذا كان تنبيه نقص السعة مفعّلًا

vms repo update – تحديث مساحة التخزين

أرسل الحقول المطلوب تعديلها فقط، وتحتفظ الحقول غير المُرسلة بقيمها الأصلية.

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

يمكن تمرير معرّف مساحة التخزين عبر repo_id أو repoId
يقرأ الأمر أولًا الإعدادات الحالية ويدمج الحقول المُرسلة، ولا تُفقد الإعدادات الأخرى
الإخراج هو معلومات مساحة التخزين بعد التحديث

vms repo delete – حذف مساحة التخزين (خطر مرتفع)

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

المعلمة الثانية هي need_save_data: true يعني الاحتفاظ بملفات البيانات على القرص، وfalse يعني الحذف مع البيانات
عملية عالية الخطورة: يطلب تأكيدًا في الوضع التفاعلي، ويجب إضافة --yes في الوضع غير التفاعلي
حذف مساحة التخزين يزيل أيضًا الأجهزة الافتراضية والصور الموجودة فيها، ويُنصح أولًا بتنفيذ vms repo check-running وvms repo whether-exist-data لتأكيد نطاق التأثير

رسالة تأكيد الوضع التفاعلي:

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

الإخراج: Repository deleted: <repo_id>

vms repo list-volumes – سرد وحدات التخزين المتاحة

يسرد وحدات التخزين المتاحة لإنشاء مساحات التخزين.

vms repo list-volumes [--json]

مثال على الإخراج:

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 – سرد الأجهزة الافتراضية داخل مساحة التخزين

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

يمكن تمرير معرّف مساحة التخزين عبر repo_id أو repoId
يقرأ الأمر أولًا كائن مساحة التخزين ثم يستعلم عن أجهزتها الافتراضية، وتكون النتيجة أكثر موثوقية

vms repo check-running – التحقق من الأجهزة الافتراضية العاملة على مساحة التخزين

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

يُنفَّذ قبل حذف مساحة التخزين للتأكد من عدم وجود أجهزة افتراضية قيد التشغيل؛ وعند عدم وجود أجهزة افتراضية عاملة يكون الإخراج فارغًا.

vms repo whether-exist-data – التحقق من وجود بيانات في مساحة التخزين

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

يُنفَّذ قبل حذف مساحة التخزين للتأكد من وجود بيانات في مساحة التخزين؛ وهو مطابق للفحص المسبق قبل حذف مساحة التخزين في الواجهة الرسومية.

10. الإعدادات العامة

vms setting get – عرض الإعدادات العامة

يعرض الإعدادات العامة لتطبيق VMs.

vms setting get [--json]

مثال على الإخراج:

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

HOST SHUTDOWN BEHAVIOR هو طريقة التعامل مع الأجهزة الافتراضية عند إغلاق المضيف
KB LAYOUT هو تخطيط لوحة المفاتيح للجهاز الافتراضي

11. الاستعلام عن معلومات المراقبة

vms collectd hostinfo – عرض معلومات مراقبة المضيف

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

مثال على الإخراج:

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

vms collectd vminfo – عرض معلومات مراقبة الأجهزة الافتراضية

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

مثال على الإخراج:

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 – عرض معلومات مراقبة التخزين

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

مثال على الإخراج:

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

الوضع التفاعلي والوضع غير التفاعلي

يحدّد CLI ما إذا كان يعمل حاليًا في بيئة طرفية، ويتّبع سلوكيات مختلفة:

الوضع التفاعلي (بيئة طرفية)

تعرض العمليات الخطرة رسالة تأكيد، والخيار الافتراضي هو No
أدخل y أو Y للمتابعة، أو n أو اضغط Enter مباشرةً للإلغاء
عند إلغاء العملية يُخرج Operation cancelled ويكون رمز الخروج 99

الوضع غير التفاعلي (نص برمجي/أتمتة)

يجب على العمليات الخطرة استخدام --yes لتخطي التأكيد، وإلا يُرجع الأمر خطأً مباشرة برمز خروج 1
عند عدم وجود بيئة طرفية لا ينتظر الإدخال، وهو مناسب للنصوص البرمجية والمهام المجدولة
يُنصح بمعالجة رمز الخروج صراحةً في النص البرمجي للتمييز بين النجاح والفشل وتضارب الحالة

تنسيق إخراج JSON

تدعم أوامر الاستعلام المعلمة --json، وتُخرج بيانات JSON موحّدة لتسهيل التحليل البرمجي.

اتفاقيات التنسيق:

تستخدم أسماء الحقول snake_case
القيم المنطقية هي true/false
يُستخدم الوقت بتنسيق ISO 8601 مع دقة النانوثانية وإزاحة UTC+8 (مثل 2026-09-02T11:43:51.176535374+08:00)
يُخرج JSON إلى stdout، وتُخرج رسائل الخطأ إلى stderr
الحقول الطويلة المقتطعة في إخراج الجدول تظهر بقيمها الكاملة في إخراج JSON

مثال:

vms setting get --json

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

تختلف بنية JSON قليلًا بين الأوامر المختلفة: تُخرج vms vm list وvms vm snapshot list وvms vm logs مصفوفة مباشرة؛ بينما تُخرج أوامر القوائم الأخرى كائنًا يتضمن totalCount وحقول البيانات، ويختلف اسم حقل البيانات حسب المورد (مثل items وhosts وvms وstorage). على سبيل المثال 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"
    }
  }
}

بعض الأوامر يكون إخراج JSON فيها قيمة بسيطة، مثل vms network ovsinfo --json الذي يُخرج true، وvms vm pause --json الذي يُخرج null.

شرح رموز الخروج

رمز الخروج	المعنى	الحالات النموذجية
0	النجاح	اكتمل الأمر بشكل طبيعي
1	خطأ في المعلمة	معلمة مطلوبة ناقصة، تنسيق معلمة خاطئ، عدم إضافة `--yes`
3	المورد غير موجود	فشل التحقق المسبق للأمر، مثل عدم وجود الصورة المحدّدة
4	تضارب الحالة	حالة الجهاز الافتراضي الحالية لا تسمح بهذه العملية (مثل إغلاق جهاز افتراضي مغلق)
6	خطأ الاتصال	تعذّر الاتصال بخدمة VMs، أو مسار socket غير صحيح
7	انتهاء المهلة	انتهت مهلة الطلب، ويمكن ضبطها عبر `--timeout`
9	خطأ التنفيذ	أرجعت الواجهة الخلفية خطأً (تتضمن رسالة الخطأ code_num ووصف الخطأ)
99	إلغاء المستخدم	اختيار No في التأكيد التفاعلي أو الضغط على Enter مباشرةً

مثال:

# 退出码 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

أمثلة سيناريوهات الاستخدام

الصيانة اليومية

# 查看所有虚拟机状态
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>

العمليات الدفعية بالنصوص البرمجية

# 批量启动所有已关机的虚拟机
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'

النسخ الاحتياطي والتفتيش

# 关机后为虚拟机创建快照
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"}'

التحقق قبل الحذف

# 删除存储空间前，先确认是否有虚拟机正在运行、是否存在数据
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>

استدعاء أدوات AI

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

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

التطوير الداخلي ودمج الأنظمة

# 开发人员可通过 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 @-

الأسئلة الشائعة

س: هل يحتاج CLI إلى تثبيت إضافي؟

لا. يُثبَّت CLI مع تطبيق VMs، ويمكن استخدامه مباشرة بعد تفعيل التطبيق عبر تنفيذ الأمر vms.

س: هل يجب استخدام CLI عبر SSH حصرًا؟

لا. يمكن استدعاء CLI من أي طرفية سطر أوامر، بما في ذلك الطرفية المحلية وSSH عن بُعد والنصوص البرمجية وأدوات AI وغيرها.

س: هل يمكن لـ CLI إدارة الأجهزة الافتراضية على أجهزة أخرى؟

لا. يتواصل CLI مع خدمة VMs عبر unix socket المحلي، ويُستخدم فقط لإدارة الأجهزة الافتراضية المحلية.

س: لماذا تطلب بعض الأوامر تأكيدًا وبعضها لا يطلبه؟

العمليات مثل حذف الجهاز الافتراضي وحذف الشبكة وحذف الصورة وحذف مساحة التخزين والإغلاق (poweroff، force-poweroff) تؤثر على البيانات أو الخدمات، لذا تتطلب تأكيدًا افتراضيًا؛ أما أوامر التشغيل وإعادة التشغيل والإيقاف المؤقت والاستئناف والاستعلام فلا تحتوي على هذا القيد.

س: كيف يتم تأكيد العمليات الخطرة في الوضع غير التفاعلي؟

يجب إضافة المعلمة --yes إلى جميع العمليات الخطرة، وإلا يُرجع الأمر خطأً (رمز الخروج 1).

س: كيف يتم تحديد ما إذا نجح تنفيذ الأمر في النص البرمجي؟

يُحدَّد عبر رمز الخروج: 0 يعني النجاح، وأي قيمة غير 0 تعني الفشل. كما يمكن تحليل محتوى إخراج --json.

س: لماذا تكون القائمة في إخراج --json كائنًا؟

تُنظَّم إخراجات JSON لبعض الأوامر ككائن حسب المعرّف مع إضافة حقل totalCount، لتسهيل الاستخدام المباشر حسب المعرّف.

مزيد من المساعدة

يدعم كل أمر --help لعرض الاستخدام التفصيلي:

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

مقدمة​

الميزات الرئيسية​

البدء السريع​

الخيارات العامة​

مثال على معلومات الإصدار​

بيئة التشغيل​

جدول ملخّص الأوامر​

مرجع الأوامر​

1. الاستعلام عن الأجهزة الافتراضية​

vms vm list – سرد الأجهزة الافتراضية​

vms vm get – عرض تفاصيل الجهاز الافتراضي​

vms vm list-resource – سرد الموارد المتاحة لإنشاء جهاز افتراضي​

vms vm logs – عرض سجلات عمليات الجهاز الافتراضي​

2. إدارة طاقة الأجهزة الافتراضية​

vms vm poweron – تشغيل الجهاز الافتراضي​

vms vm poweroff – إغلاق الجهاز الافتراضي​

vms vm force-poweroff – إغلاق الجهاز الافتراضي قسريًا (خطر مرتفع)​

vms vm reboot – إعادة تشغيل الجهاز الافتراضي​

vms vm pause – إيقاف الجهاز الافتراضي مؤقتًا​

vms vm resume – استئناف الجهاز الافتراضي​

vms vm autorun – ضبط التشغيل التلقائي عند بدء التشغيل​

3. نسخ الجهاز الافتراضي وتصديره وحذفه​

vms vm clone – استنساخ الجهاز الافتراضي​

vms vm export – تصدير الجهاز الافتراضي​

vms vm delete – حذف الجهاز الافتراضي (خطر مرتفع)​

4. الأقراص الصلبة الافتراضية​

vms vm disk list – عرض الأقراص الصلبة الافتراضية​

5. إدارة اللقطات​

vms vm snapshot list – سرد اللقطات​

vms vm snapshot create – إنشاء لقطة​

vms vm snapshot edit – تعديل اللقطة​

vms vm snapshot config – عرض إعدادات الجهاز الافتراضي في اللقطة​

vms vm snapshot consistency – معاينة تناسق اللقطة​

6. وحدة التحكم عن بُعد​

vms vm link – الحصول على معلومات اتصال VNC​

7. إدارة الشبكات الافتراضية​

vms network list – سرد الشبكات الافتراضية​

vms network get – عرض تفاصيل الشبكة الافتراضية​

vms network create – إنشاء شبكة افتراضية​

vms network update – تحديث الشبكة الافتراضية​

vms network delete – حذف الشبكة الافتراضية (خطر مرتفع)​

vms network list-interfaces – سرد واجهات الشبكة​

vms network list-vnics – سرد بطاقات الشبكة الافتراضية على الشبكة​

vms network ovsinfo – عرض حالة OVS​

8. إدارة الصور​

vms image list – سرد الصور​

vms image edit – تعديل الصورة​

vms image delete – حذف الصورة (خطر مرتفع)​

vms image list-vms – عرض الأجهزة الافتراضية التي تستخدم هذه الصورة​

9. إدارة مساحات التخزين​

vms repo list – سرد مساحات التخزين​

vms repo get – عرض تفاصيل مساحة التخزين​

vms repo update – تحديث مساحة التخزين​

vms repo delete – حذف مساحة التخزين (خطر مرتفع)​

vms repo list-volumes – سرد وحدات التخزين المتاحة​

vms repo list-vms – سرد الأجهزة الافتراضية داخل مساحة التخزين​

vms repo check-running – التحقق من الأجهزة الافتراضية العاملة على مساحة التخزين​

vms repo whether-exist-data – التحقق من وجود بيانات في مساحة التخزين​

10. الإعدادات العامة​

vms setting get – عرض الإعدادات العامة​

11. الاستعلام عن معلومات المراقبة​

vms collectd hostinfo – عرض معلومات مراقبة المضيف​

vms collectd vminfo – عرض معلومات مراقبة الأجهزة الافتراضية​

vms collectd storageinfo – عرض معلومات مراقبة التخزين​

الوضع التفاعلي والوضع غير التفاعلي​

الوضع التفاعلي (بيئة طرفية)​

الوضع غير التفاعلي (نص برمجي/أتمتة)​

تنسيق إخراج JSON​

شرح رموز الخروج​

أمثلة سيناريوهات الاستخدام​

الصيانة اليومية​

العمليات الدفعية بالنصوص البرمجية​

النسخ الاحتياطي والتفتيش​

التحقق قبل الحذف​

استدعاء أدوات AI​

التطوير الداخلي ودمج الأنظمة​

الأسئلة الشائعة​

مزيد من المساعدة​

مقدمة

الميزات الرئيسية

البدء السريع

الخيارات العامة

مثال على معلومات الإصدار

بيئة التشغيل

جدول ملخّص الأوامر

مرجع الأوامر

1. الاستعلام عن الأجهزة الافتراضية

vms vm list – سرد الأجهزة الافتراضية

vms vm get – عرض تفاصيل الجهاز الافتراضي

vms vm list-resource – سرد الموارد المتاحة لإنشاء جهاز افتراضي

vms vm logs – عرض سجلات عمليات الجهاز الافتراضي

2. إدارة طاقة الأجهزة الافتراضية

vms vm poweron – تشغيل الجهاز الافتراضي

vms vm poweroff – إغلاق الجهاز الافتراضي

vms vm force-poweroff – إغلاق الجهاز الافتراضي قسريًا (خطر مرتفع)

vms vm reboot – إعادة تشغيل الجهاز الافتراضي

vms vm pause – إيقاف الجهاز الافتراضي مؤقتًا

vms vm resume – استئناف الجهاز الافتراضي

vms vm autorun – ضبط التشغيل التلقائي عند بدء التشغيل

3. نسخ الجهاز الافتراضي وتصديره وحذفه

vms vm clone – استنساخ الجهاز الافتراضي

vms vm export – تصدير الجهاز الافتراضي

vms vm delete – حذف الجهاز الافتراضي (خطر مرتفع)

4. الأقراص الصلبة الافتراضية

vms vm disk list – عرض الأقراص الصلبة الافتراضية

5. إدارة اللقطات

vms vm snapshot list – سرد اللقطات

vms vm snapshot create – إنشاء لقطة

vms vm snapshot edit – تعديل اللقطة

vms vm snapshot config – عرض إعدادات الجهاز الافتراضي في اللقطة

vms vm snapshot consistency – معاينة تناسق اللقطة

6. وحدة التحكم عن بُعد

vms vm link – الحصول على معلومات اتصال VNC

7. إدارة الشبكات الافتراضية

vms network list – سرد الشبكات الافتراضية

vms network get – عرض تفاصيل الشبكة الافتراضية

vms network create – إنشاء شبكة افتراضية

vms network update – تحديث الشبكة الافتراضية

vms network delete – حذف الشبكة الافتراضية (خطر مرتفع)

vms network list-interfaces – سرد واجهات الشبكة

vms network list-vnics – سرد بطاقات الشبكة الافتراضية على الشبكة

vms network ovsinfo – عرض حالة OVS

8. إدارة الصور

vms image list – سرد الصور

vms image edit – تعديل الصورة

vms image delete – حذف الصورة (خطر مرتفع)

vms image list-vms – عرض الأجهزة الافتراضية التي تستخدم هذه الصورة

9. إدارة مساحات التخزين

vms repo list – سرد مساحات التخزين

vms repo get – عرض تفاصيل مساحة التخزين

vms repo update – تحديث مساحة التخزين

vms repo delete – حذف مساحة التخزين (خطر مرتفع)

vms repo list-volumes – سرد وحدات التخزين المتاحة

vms repo list-vms – سرد الأجهزة الافتراضية داخل مساحة التخزين

vms repo check-running – التحقق من الأجهزة الافتراضية العاملة على مساحة التخزين

vms repo whether-exist-data – التحقق من وجود بيانات في مساحة التخزين

10. الإعدادات العامة

vms setting get – عرض الإعدادات العامة

11. الاستعلام عن معلومات المراقبة

vms collectd hostinfo – عرض معلومات مراقبة المضيف

vms collectd vminfo – عرض معلومات مراقبة الأجهزة الافتراضية

vms collectd storageinfo – عرض معلومات مراقبة التخزين

الوضع التفاعلي والوضع غير التفاعلي

الوضع التفاعلي (بيئة طرفية)

الوضع غير التفاعلي (نص برمجي/أتمتة)

تنسيق إخراج JSON

شرح رموز الخروج

أمثلة سيناريوهات الاستخدام

الصيانة اليومية

العمليات الدفعية بالنصوص البرمجية

النسخ الاحتياطي والتفتيش

التحقق قبل الحذف

استدعاء أدوات AI

التطوير الداخلي ودمج الأنظمة

الأسئلة الشائعة

مزيد من المساعدة