VergeOS CLI (vrg)

vrg là giao diện dòng lệnh chính thức của VergeOS, cung cấp hơn 200 lệnh để quản lý máy ảo, mạng, tenant, NAS và nhiều hơn nữa từ terminal hoặc pipeline tự động hóa.

Tổng quan

vrg là giao diện dòng lệnh chính thức cho VergeOS. Nó cung cấp hơn 200 lệnh trên các mảng compute, networking, tenants, NAS, identity, automation và monitoring, cùng với cấu hình khai báo .vrg.yaml các mẫu VM để cấp phát có thể lặp lại, có kiểm soát phiên bản. Dùng cho quản trị ưu tiên terminal, viết script shell và các pipeline CI/CD.

Yêu cầu

Python 3.10 hoặc mới hơn (khi cài đặt qua pip, pipx, hoặc uv)
Một tài khoản người dùng hoặc khóa API với quyền phù hợp trên phiên bản VergeOS

Cài đặt

vrg có thể được cài đặt theo nhiều cách. pipx được khuyến nghị vì nó cô lập CLI trong môi trường ảo riêng của nó.

pipx (khuyến nghị)

pipx install vrg

pip

pip install vrg

uv

uv tool install vrg

Homebrew

brew install verge-io/tap/vrg

Tệp nhị phân độc lập

Tải xuống một tệp nhị phân dựng sẵn từ bản phát hành mới nhất rồi đặt nó vào PATH. Các tệp nhị phân có sẵn cho Linux (x86_64), macOS (ARM64) và Windows (x86_64).

Cách ly trên macOS

Trên macOS, tệp nhị phân độc lập có thể bị Gatekeeper cách ly. Hãy xóa thuộc tính trước khi chạy:

xattr -d com.apple.quarantine ./vrg

Sau khi cài đặt, xác minh bằng:

vrg --version

Nâng cấp

Phương thức cài đặt

Lệnh nâng cấp

pipx

pipx upgrade vrg

pip

pip install --upgrade vrg

uv

uv tool upgrade vrg

Homebrew

brew upgrade vrg

Độc lập

Tải lại từ trang phát hành

Bắt đầu nhanh

# 1. Cấu hình thông tin xác thực (trình hướng dẫn tương tác)
vrg configure setup

# 2. Xác minh kết nối
vrg system info

# 3. Khám phá lệnh khi bạn sử dụng — mọi lệnh đều hỗ trợ --help
vrg --help
vrg vm --help

# 4. Liệt kê các VM của bạn
vrg vm list

vrg configure setup là một trình hướng dẫn tương tác yêu cầu URL máy chủ, phương thức xác thực và định dạng đầu ra mặc định. Nó lưu kết quả vào ~/.vrg/config.toml. Xem Xác thực để biết chi tiết về từng phương thức và cách viết kịch bản cho thông tin xác thực.

Xác thực

vrg hỗ trợ bốn phương thức xác thực. Cả bốn đều có thể được cung cấp thông qua trình hướng dẫn tương tác, biến môi trường, cờ dòng lệnh hoặc hồ sơ trong ~/.vrg/config.toml.

Phương thức

Phù hợp nhất cho

Cách cung cấp

Mã thông báo Bearer

pipeline CI, tập lệnh

--token cờ hoặc VERGE_TOKEN biến môi trường

Khóa API

Tự động hóa dịch vụ dài hạn

--api-key cờ

Tên người dùng + mật khẩu

Phiên tương tác, tác vụ một lần

--username / --password hoặc lời nhắc của trình hướng dẫn

Hồ sơ

Nhiều phiên bản

--profile <name> sau khi chạy vrg configure setup

Tạo khóa API

Khóa API được quản lý cả trong giao diện VergeOS (System → API Keys) và ngay trong chính CLI sau khi bạn đã xác thực bằng một phương thức khác:

# Sau lần đăng nhập tương tác đầu tiên, tạo một khóa dài hạn cho CI
vrg api-key create --name ci-pipeline
vrg api-key list

Hãy coi giá trị trả về như một bí mật — lưu nó trong trình quản lý bí mật của nhà cung cấp CI của bạn, không bao giờ đưa vào kiểm soát mã nguồn.

Biến môi trường

Biến môi trường ghi đè giá trị trong tệp cấu hình, nên chúng rất phù hợp cho CI/CD:

export VERGE_HOST=https://verge.example.com
export VERGE_TOKEN=eyJhbGc...
vrg vm list

Hồ sơ

Hồ sơ cho phép bạn chuyển đổi giữa nhiều phiên bản VergeOS (sản xuất, staging, môi trường khách hàng):

vrg configure setup --profile prod   # Thiết lập một hồ sơ có tên
vrg configure list                   # Liệt kê các hồ sơ đã cấu hình
vrg configure show                   # Hiển thị hồ sơ đang hoạt động (che thông tin xác thực)
vrg --profile prod vm list           # Dùng một hồ sơ cụ thể cho một lệnh
vrg -p staging vm list               # Dạng rút gọn

Truy vấn qua nhiều hồ sơ

Dùng --all-profiles trên một lệnh liệt kê để chạy nó với mọi hồ sơ đã cấu hình. Mỗi hàng đầu ra bao gồm một hồ sơ cột hiển thị nó đến từ đâu.

Mẫu lệnh

Tất cả vrg lệnh tuân theo một cấu trúc nhất quán:

vrg [global-options] <domain> [sub-domain] <action> [arguments] [options]

Hầu hết tài nguyên triển khai các thao tác CRUD tiêu chuẩn: liệt kê, lấy, tạo, cập nhật, và xóa. Các thao tác phá hủy yêu cầu --yes để bỏ qua lời nhắc xác nhận.

Miền lệnh

Miền

Miền con

Điện toán

vm, ổ đĩa vm, nic vm, thiết bị vm, ảnh chụp nhanh vm, xuất vm, nhập vm

Mạng

mạng, quy tắc mạng, dns mạng, máy chủ mạng, bí danh mạng, chẩn đoán mạng, truy vấn mạng

Tenant

tenant, nút tenant, lưu trữ tenant, mạng tenant, ảnh chụp nhanh tenant, thống kê tenant, chia sẻ tenant, nhật ký tenant

NAS

dịch vụ nas, ổ lưu trữ nas, cifs nas, nfs nas, người dùng nas, đồng bộ nas, tệp nas

Hạ tầng

cụm, nút, lưu trữ

Ảnh chụp nhanh

ảnh chụp nhanh, hồ sơ snapshot

Trang web & Nhân bản

site, đồng bộ site đi, đồng bộ site đến

Danh tính & Truy cập

người dùng, nhóm, quyền, api-key, nguồn xác thực

Chứng chỉ & SSO

chứng chỉ, oidc

Tự động hóa

tác vụ, lịch tác vụ, trình kích hoạt tác vụ, sự kiện tác vụ, tập lệnh tác vụ

Công thức

công thức, phần công thức, câu hỏi công thức, phiên bản công thức, nhật ký công thức

Danh mục

danh mục, kho lưu trữ danh mục

Cập nhật

cập nhật, nguồn cập nhật, nhánh cập nhật, gói cập nhật, bản cập nhật khả dụng

Giám sát

cảnh báo, lịch sử cảnh báo, nhật ký

Gắn thẻ

thẻ, nhóm thẻ, nhóm tài nguyên

Hệ thống

hệ thống, cài đặt hệ thống, giấy phép hệ thống, chẩn đoán hệ thống, doctor, cấu hình, tệp, hoàn tất

Tài liệu tham chiếu đầy đủ được duy trì trong Tài liệu tham chiếu lệnh .

Ví dụ sử dụng

Liệt kê và kiểm tra VM

# Liệt kê tất cả VM
vrg vm list

# Kiểm tra một VM
vrg vm get web-server

# Trạng thái nguồn
vrg vm start web-server --wait    # --wait sẽ chặn cho đến khi VM đang chạy
vrg vm stop web-server --wait
vrg vm restart web-server

Tạo VM từ các cờ Shell

Cách dùng cờ shell phù hợp cho thử nghiệm nhanh. Để cấp phát có thể lặp lại, xem Mẫu VM.

# Tạo một VM (--ram tính bằng MB)
vrg vm create --name web-server --ram 4096 --cpu 2

# Thêm một đĩa 50 GB và gắn một NIC
vrg vm drive create web-server --size 50GB --name os-disk
vrg vm nic create web-server --network External

# Khởi động VM
vrg vm start web-server --wait

VM trống sẽ không khởi động

Một VM được tạo từ các cờ shell không gắn sẵn hệ điều hành. Để cài đặt, hãy khởi động từ ổ ISO (vrg vm drive create … --media cdrom), sao chép một VM hiện có (vrg vm clone), hoặc định nghĩa một ảnh hệ điều hành và cloud-init trong một .vrg.yaml mẫu.

Làm việc với mạng

# Tạo một mạng nội bộ với DHCP
vrg network create --name dev-net --cidr 10.0.0.0/24 --ip 10.0.0.1 --dhcp
vrg network start dev-net

# Cho phép SSH đến (--dest-ports chấp nhận một cổng đơn, dải "80-443", hoặc "80,443")
vrg network rule create dev-net \\
  --name allow-ssh --action accept --direction incoming \\
  --protocol tcp --dest-ports 22

# Áp dụng các thay đổi tường lửa đang chờ
vrg network apply-rules dev-net

Chẩn đoán mạng và nút

vrg cung cấp các truy vấn chẩn đoán chạy trên bộ định tuyến ảo của một mạng hoặc trực tiếp trên một nút vật lý:

# Kiểm tra kết nối mạng
vrg network query ping External 8.8.8.8
vrg network query traceroute External 8.8.8.8
vrg network query dns External example.com

# Kiểm tra phần cứng nút
vrg node query smartctl node1 /dev/sda
vrg node query ipmi-sensor node1
vrg node lldp list node1

Kiểm tra sức khỏe hệ thống

# Chạy tất cả các kiểm tra sức khỏe tích hợp
vrg doctor

# Chạy một tập con cụ thể
vrg doctor --check connectivity,clusters,nodes,storage

# Đầu ra JSON cho tự động hóa; mã thoát 0 = khỏe mạnh, 1 = lỗi
vrg -o json doctor | jq '.[] | select(.status == \"fail\")'

Mẫu VM

Định nghĩa VM dưới dạng .vrg.yaml các tệp để cấp phát có thể lặp lại, có kiểm soát phiên bản. Mẫu hỗ trợ biến, xem trước dry-run, ghi đè lúc chạy qua --set, cloud-init, và tạo hàng loạt với VirtualMachineSet.

Mẫu ví dụ

Lưu nội dung sau thành web-server.vrg.yaml:

apiVersion: v4
kind: VirtualMachine

vm:
  name: web-server-01
  os_family: linux
  cpu_cores: 4
  ram: 8GB
  machine_type: q35
  uefi: true
  guest_agent: true

  cloudinit:
    datasource: nocloud
    files:
      - name: user-data
        content: |
          #cloud-config
          hostname: web-server-01
          packages:
            - nginx
            - qemu-guest-agent
          runcmd:
            - systemctl enable --now nginx

  drives:
    - name: "Đĩa hệ điều hành"
      media: disk
      interface: virtio-scsi
      size: 50GB

  nics:
    - name: "Chính"
      interface: virtio
      network: External

Xác thực và tạo

# Xác thực mẫu so với schema
vrg vm validate -f web-server.vrg.yaml

# Xem trước thao tác mà không thực hiện thay đổi
vrg vm create -f web-server.vrg.yaml --dry-run

# Tạo VM
vrg vm create -f web-server.vrg.yaml

# Ghi đè một trường tại thời điểm chạy
vrg vm create -f web-server.vrg.yaml \\
  --set vm.name=web-server-02 --set vm.ram=16GB

Biến và giá trị mặc định

Hỗ trợ mẫu ${VAR} thay thế từ biến môi trường hoặc một vars: khối, cùng cú pháp giá trị mặc định (${VM_RAM:-4GB}). Điều này hữu ích để tham số hóa một mẫu duy nhất trên nhiều môi trường.

Để xem tài liệu tham chiếu đầy đủ cho trường mẫu, hãy xem Hướng dẫn Mẫu .

Định dạng đầu ra

Tất cả các lệnh hỗ trợ --output (hoặc -o) để thay đổi định dạng đầu ra và --query để trích xuất một trường bằng ký hiệu dấu chấm.

Định dạng

Trường hợp sử dụng

bảng

Đầu ra mặc định dễ đọc cho con người

rộng

Tất cả các cột có sẵn, bao gồm cả những cột bị ẩn trong chế độ xem mặc định

json

Đầu ra có thể đọc bằng máy để chuyển qua jq hoặc các công cụ khác

csv

Xuất thân thiện với bảng tính

# Tất cả các cột
vrg -o wide vm list

# JSON cho script
vrg -o json vm list | jq '.[].name'

# Xuất CSV
vrg -o csv vm list > vms.csv

# Trích xuất một trường duy nhất bằng ký hiệu dấu chấm (hỗ trợ đường dẫn lồng nhau)
vrg --query status vm get web-server
vrg --query nics[0].network vm get web-server

Tự động hoàn thành Shell

Hoàn thành bằng Tab có sẵn cho bash, zsh, fish và PowerShell. Cách nhanh nhất để bật là:

vrg --install-completion

zsh trên macOS: thư mục không an toàn

Nếu bạn thấy compinit: insecure directories sau khi cài đặt tính năng hoàn thành trên macOS, hãy sửa quyền thư mục Homebrew:

chmod 755 /opt/homebrew/share/zsh /opt/homebrew/share/zsh/site-functions

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

Tùy chọn

Viết tắt

Mô tả

--profile

-p

Hồ sơ cấu hình để sử dụng

--host

-H

URL máy chủ VergeOS (ghi đè)

--token

Mã thông báo Bearer để xác thực

--api-key

Khóa API để xác thực

--username

-u

Tên người dùng cho xác thực cơ bản

--password

Mật khẩu cho xác thực cơ bản

--output

-o

Định dạng đầu ra (bảng, rộng, json, csv)

--query

Trích xuất trường bằng ký hiệu dấu chấm

--all-profiles

Chạy các lệnh liệt kê trên mọi hồ sơ đã cấu hình

--verbose

-v

Tăng mức độ chi tiết (-v, -vv, -vvv)

--quiet

-q

Ẩn đầu ra không thiết yếu

--no-color

Tắt đầu ra có màu

--yes

Bỏ qua các lời nhắc xác nhận khi thực hiện hành động phá hủy

--version

-V

Hiển thị phiên bản

--help

Hiển thị trợ giúp

Mã thoát

vrg sử dụng các mã thoát có ý nghĩa cho việc viết script và tích hợp CI:

Mã

Ý nghĩa

Thành công

Lỗi chung

Tham số không hợp lệ

Lỗi cấu hình

Lỗi xác thực

Từ chối quyền truy cập

Không tìm thấy tài nguyên

Xung đột (ví dụ: trùng tên)

Lỗi xác thực dữ liệu

Hết thời gian chờ

Lỗi kết nối

Khắc phục sự cố

Triệu chứng

Nguyên nhân có thể

Khắc phục

Mã thoát 4

Xác thực thất bại

Chạy vrg configure setup và xác minh mã thông báo, khóa API hoặc thông tin đăng nhập

Mã thoát 3

Lỗi cấu hình

Kiểm tra ~/.vrg/config.toml hoặc chạy vrg configure show

Mã thoát 10

Lỗi kết nối

Xác minh VERGE_HOST có thể truy cập được và URL là chính xác

compinit: insecure directories (macOS)

Quyền của Homebrew

chmod 755 /opt/homebrew/share/zsh /opt/homebrew/share/zsh/site-functions

vrg bị chặn trên macOS

cách ly của Gatekeeper

xattr -d com.apple.quarantine ./vrg

Chọn công cụ phù hợp

vrg là một trong nhiều giao diện tự động hóa VergeOS. Hãy chọn dựa trên cách bạn làm việc:

Công cụ

Dùng khi

vrg CLI

Bạn làm việc chủ yếu trong terminal, muốn các mẫu VM khai báo, hoặc cần một script chạy một lần

Python SDK

Bạn đang viết ứng dụng Python, tự động hóa phức tạp, hoặc tích hợp với các công cụ Python khác

PowerShell Module

Bạn là môi trường ưu tiên Windows hoặc đã tự động hóa bằng PowerShell

Nhà cung cấp Terraform

Bạn quản lý VergeOS cùng với hạ tầng khác do Terraform quản lý

Go SDK

Bạn đang nhúng chức năng quản lý VergeOS vào một ứng dụng Go

Tài nguyên & Hỗ trợ

Kho lưu trữ GitHub — mã nguồn, vấn đề và bản phát hành
Tài liệu tham chiếu lệnh — mọi lệnh và cờ
Hướng dẫn Mẫu — đầy đủ .vrg.yaml tham chiếu trường
Sổ tay công thức — các công thức theo nhiệm vụ
Kiến trúc — thiết kế và nội bộ
Vấn đề đã biết — các hạn chế hiện tại và cách khắc phục tạm thời
Gói PyPI
Báo cáo vấn đề
Tài liệu API VergeOS

TrướcTích hợp Veeam với VergeOS

Tiếp theoCác phiên chat tương tác

Cập nhật lần cuối 1 tháng trước

Nội dung này có hữu ích không?