> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/automate-protect-and-extend/vi/tich-hop-va-api/vrg-cli.md). # VergeOS CLI (vrg) ## 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ị) ```bash pipx install vrg ``` ### pip ```bash pip install vrg ``` ### uv ```bash uv tool install vrg ``` ### Homebrew ```bash 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](https://github.com/verge-io/vrg/releases/latest) 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). {% hint style="warning" %} **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: ```bash xattr -d com.apple.quarantine ./vrg ``` {% endhint %} Sau khi cài đặt, xác minh bằng: ```bash 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](https://github.com/verge-io/vrg/releases/latest) | ## Bắt đầu nhanh ```bash # 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](#authentication) để 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 ` 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: ```bash # 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: ```bash 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): ```bash 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 ``` {% hint style="success" %} **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. {% endhint %} ## 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] [sub-domain] [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](https://github.com/verge-io/vrg/blob/main/docs/COMMANDS.md) . ## Ví dụ sử dụng ### Liệt kê và kiểm tra VM ```bash # 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](#vm-templates). ```bash # 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 ``` {% hint style="info" %} **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. {% endhint %} ### Làm việc với mạng ```bash # 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ý: ```bash # 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 ```bash # 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`: ```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 ```bash # 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 ``` {% hint style="success" %} **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. {% endhint %} Để xem tài liệu tham chiếu đầy đủ cho trường mẫu, hãy xem [Hướng dẫn Mẫu](https://github.com/verge-io/vrg/blob/main/docs/TEMPLATES.md) . ## Đị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 | ```bash # 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à: ```bash vrg --install-completion ``` {% hint style="warning" %} **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: ```bash chmod 755 /opt/homebrew/share/zsh /opt/homebrew/share/zsh/site-functions ``` {% endhint %} ## 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 | | -- | --------------------------- | | 0 | Thành công | | 1 | Lỗi chung | | 2 | Tham số không hợp lệ | | 3 | Lỗi cấu hình | | 4 | Lỗi xác thực | | 5 | Từ chối quyền truy cập | | 6 | Không tìm thấy tài nguyên | | 7 | Xung đột (ví dụ: trùng tên) | | 8 | Lỗi xác thực dữ liệu | | 9 | Hết thời gian chờ | | 10 | 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](/automate-protect-and-extend/vi/tich-hop-va-api/python-sdk.md) | 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](/automate-protect-and-extend/vi/tich-hop-va-api/powershell-module.md) | 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](/automate-protect-and-extend/vi/tich-hop-va-api/terraform-provider.md) | Bạn quản lý VergeOS cùng với hạ tầng khác do Terraform quản lý | | [Go SDK](/automate-protect-and-extend/vi/tich-hop-va-api/go-sdk.md) | 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](https://github.com/verge-io/vrg) — mã nguồn, vấn đề và bản phát hành * [Tài liệu tham chiếu lệnh](https://github.com/verge-io/vrg/blob/main/docs/COMMANDS.md) — mọi lệnh và cờ * [Hướng dẫn Mẫu](https://github.com/verge-io/vrg/blob/main/docs/TEMPLATES.md) — đầy đủ `.vrg.yaml` tham chiếu trường * [Sổ tay công thức](https://github.com/verge-io/vrg/blob/main/docs/COOKBOOK.md) — các công thức theo nhiệm vụ * [Kiến trúc](https://github.com/verge-io/vrg/blob/main/docs/ARCHITECTURE.md) — thiết kế và nội bộ * [Vấn đề đã biết](https://github.com/verge-io/vrg/blob/main/docs/KNOWN_ISSUES.md) — các hạn chế hiện tại và cách khắc phục tạm thời * [Gói PyPI](https://pypi.org/project/vrg/) * [Báo cáo vấn đề](https://github.com/verge-io/vrg/issues) * [Tài liệu API VergeOS](/knowledge-base/vi/automation-api/verge-api-guide.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verge.io/automate-protect-and-extend/vi/tich-hop-va-api/vrg-cli.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.