> 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/typescript-sdk.md). # VergeOS TypeScript SDK (tsvergeos) ## Tổng quan tsvergeos là một SDK TypeScript để quản lý hạ tầng VergeOS thông qua REST API. Nó cung cấp một giao diện không phụ thuộc, có thể tree-shake, được gõ kiểu đầy đủ để tự động hóa vòng đời VM, mạng, lưu trữ, vận hành đa thuê bao và quản lý đa site, khiến nó lý tưởng cho các script tự động hóa, phát triển công cụ và tích hợp. ## Tính năng chính * **Không phụ thuộc**: Không có gì để kiểm tra, không có gì để hỏng * **Có thể Tree-Shake**: Chỉ import các dịch vụ bạn dùng; các dịch vụ không dùng sẽ bị loại bỏ như mã chết * **Phủ kiểu đầy đủ**: Mọi tài nguyên, tham số và phản hồi đều được gõ kiểu với tài liệu TSDoc * **93 dịch vụ**: Phủ đầy đủ mọi điểm cuối của API VergeOS * **Tích hợp đa site sẵn có**: Truy vấn và quản lý nhiều triển khai VergeOS từ một `SiteManager` * **Đa nền tảng**: Hoạt động trong Node.js 20+, Deno, Bun và các trình duyệt hiện đại * **Lọc**: Hỗ trợ bộ lọc OData với cả một `Filter` builder dạng fluent và một `buildFilter` viết tắt hàm ## Yêu cầu * Node.js 20+ (cũng hỗ trợ Deno và Bun) * VergeOS 6.x (API v4) ## Cài đặt ### Từ npm (Khuyến nghị) ```bash npm install @vergeio/tsvergeos ``` ### Dùng pnpm / yarn / bun ```bash pnpm add @vergeio/tsvergeos # hoặc yarn add @vergeio/tsvergeos # hoặc bun add @vergeio/tsvergeos ``` ## Xác thực SDK hỗ trợ nhiều phương thức xác thực: ### API Key (Khuyến nghị) ```typescript import { VergeClient } from "@vergeio/tsvergeos"; const client = await VergeClient.connect({ host: "192.168.1.100", apiKey: "your-api-key", verifySsl: false, // dành cho chứng chỉ tự ký }); ``` {% hint style="info" %} **Xác minh chứng chỉ SSL** {% endhint %} Đặt `verifySsl: false` chỉ cho các môi trường có chứng chỉ tự ký. Với môi trường sản xuất có chứng chỉ hợp lệ, hãy bỏ qua tham số này hoặc đặt nó thành `true`. ### Tên đăng nhập / Mật khẩu ```typescript const client = await VergeClient.connect({ host: "192.168.1.100", username: "admin", password: "secret", }); ``` ### Biến môi trường ```bash export VERGEOS_HOST=192.168.1.100 export VERGEOS_API_KEY=your-api-key # Tùy chọn: export VERGEOS_VERIFY_SSL=false export VERGEOS_TIMEOUT=60 ``` ```typescript const client = await VergeClient.connectFromEnv(); ``` {% hint style="success" %} **Khuyến nghị cho môi trường sản xuất** {% endhint %} Sử dụng biến môi trường giúp giữ thông tin xác thực ra khỏi mã nguồn của bạn và dễ dàng dùng các thông tin xác thực khác nhau giữa các môi trường. ## Đăng ký dịch vụ SDK sử dụng các import có thể tree-shake — các dịch vụ được đăng ký qua import tạo hiệu ứng phụ, nên các dịch vụ không dùng sẽ bị loại khỏi bundle của bạn. ### Ba mức import ```typescript // 1. Mặc định: ~48 dịch vụ dùng nhiều nhất (VM, mạng, tenant, lưu trữ, v.v.) import { VergeClient } from "@vergeio/tsvergeos"; // 2. Đầy đủ: toàn bộ 93 dịch vụ (cảnh báo, cài đặt cập nhật, tầng lưu trữ, v.v.) import { VergeClient } from "@vergeio/tsvergeos"; import "@vergeio/tsvergeos/full"; // 3. Riêng lẻ: chọn chính xác những gì bạn cần import { VergeClient } from "@vergeio/tsvergeos"; import "@vergeio/tsvergeos/services/alarm"; import "@vergeio/tsvergeos/services/storage-tier"; ``` {% hint style="warning" %} **Dịch vụ chưa đăng ký** {% endhint %} Import mặc định không bao gồm mọi dịch vụ. Nếu bạn truy cập một dịch vụ chưa được đăng ký (ví dụ: `client.alarms` mà không import nó), bạn sẽ nhận được `undefined`. Với dashboard, công cụ quản trị hoặc script backend nơi kích thước bundle không quan trọng, hãy dùng `import '@vergeio/tsvergeos/full'` để đăng ký tất cả. ### Chỉ import kiểu Import kiểu không ảnh hưởng đến bundle dù bất kỳ dịch vụ nào được đăng ký: ```typescript import type { VM, Alarm, Network, Tenant, Volume, } from "@vergeio/tsvergeos/types"; ``` ## Tài nguyên có sẵn SDK cung cấp quyền truy cập vào 93 dịch vụ bao phủ toàn bộ API VergeOS: | Danh mục | Tài nguyên | | ------------------ | ------------------------------------------------------------------------------------------- | | **Điện toán** | VM, ổ đĩa, thiết bị, NIC, snapshot máy, thống kê | | **Mạng** | Mạng, quy tắc, bí danh, địa chỉ, máy chủ, vùng/bản ghi/giao diện DNS | | **VPN** | Giao diện và peer WireGuard, kết nối và giai đoạn IPSec | | **Lưu trữ** | Volume, snapshot volume, chia sẻ CIFS/NFS, đồng bộ, trình duyệt, tầng lưu trữ | | **NAS** | Dịch vụ NAS, người dùng, tệp | | **Tenant** | Tenant, node, lưu trữ, snapshot, Layer 2 | | **Công thức** | Recipe VM và tenant, instance, danh mục, kho lưu trữ | | **Ảnh chụp nhanh** | Hồ sơ snapshot, chu kỳ, snapshot đám mây | | **Site** | API `sites` service — các đồng bộ vào/ra, các chu kỳ hồ sơ đồng bộ (khác với `SiteManager`) | | **Hệ thống** | Hệ thống, cụm, node, cài đặt, nhật ký, tác vụ | | **Giám sát** | Cảnh báo, loại cảnh báo, webhook, URL webhook | | **Xác thực** | Người dùng, nhóm, thành viên, quyền, khóa API | | **Thẻ** | Thẻ, danh mục, thành viên | | **Cập nhật** | Cài đặt cập nhật, nguồn, gói, nhánh | | **Khác** | Chứng chỉ, cloud-init, nhóm tài nguyên | ## Ví dụ sử dụng ### Quản lý máy ảo ```typescript import { VergeClient } from "@vergeio/tsvergeos"; import "@vergeio/tsvergeos/services/vm"; const client = await VergeClient.connect({ host: "192.168.1.100", apiKey: "your-api-key", }); // Liệt kê tất cả VM const vms = await client.vms.list(); for (const vm of vms) { console.log(`${vm.name}: ${vm.ram}MB RAM, ${vm.cpu_cores} lõi`); } // Lấy một VM cụ thể const vm = await client.vms.get(42); const vmByName = await client.vms.getByName("web-server"); // Tạo một VM const newVm = await client.vms.create({ name: "test-vm", machine_type: "q35", ram: 2048, cpu_cores: 2, os_family: "linux", }); // Các thao tác nguồn await client.vms.powerOn(newVm.$key); await client.vms.powerOff(newVm.$key); // tắt an toàn ACPI // Cập nhật một VM await client.vms.update(newVm.$key, { ram: 4096 }); // Xóa một VM await client.vms.delete(newVm.$key); ``` {% hint style="info" %} **Trạng thái nguồn đáng tin cậy** {% endhint %} Danh sách `powerstate` trường trên tài nguyên VM thường bị API bỏ qua. Để có trạng thái nguồn trực tiếp mang tính thẩm quyền, hãy truy vấn dịch vụ trạng thái máy: ```typescript import "@vergeio/tsvergeos/services/machine-status"; const status = await client.machineStatuses.getByMachine(newVm.$key); console.log(status.running, status.status); ``` ### Truy cập Console `getConsoleInfo()` trả về thông tin kết nối để mở console WebSocket trực tiếp tới một VM. Hỗ trợ ba phương thức xác thực — chọn theo nơi console được hiển thị: ```typescript // Tương thích trình duyệt: token nhúng trong URL WebSocket const info = await client.vms.getConsoleInfo(42, { username: "admin", password: "secret", }); if (info.isAvailable) { const rfb = new RFB(container, info.websocketUrl); } // Node / Deno / Bun: API key qua header Authorization const info = await client.vms.getConsoleInfo(42, { apiKey: "..." }); const ws = new WebSocket(info.websocketUrl, { headers: { Authorization: `Bearer ${info.apiKey}` }, }); ``` API `WebSocket` không hỗ trợ header tùy chỉnh — hãy dùng tên đăng nhập/mật khẩu hoặc một token sẵn có trong trình duyệt. Để đi tắt không cần gọi API tới console giao diện web, hãy dùng `client.vms.getConsoleURL(42)`. ### Lọc tài nguyên SDK hỗ trợ nhiều cách tiếp cận lọc: {% tabs %} {% tab title="Trình tạo bộ lọc fluent" %} ```typescript import { Filter } from "@vergeio/tsvergeos"; const filter = new Filter() .eq("status", "running") .like("name", "web*") .gt("cpu_cores", 2) .build(); const vms = await client.vms.list({ filter }); ``` {% endtab %} {% tab title="Viết tắt hàm" %} ```typescript import { buildFilter } from "@vergeio/tsvergeos"; const vms = await client.vms.list({ filter: buildFilter({ status: "running", name: "web*", cpu_cores: { gt: 2 }, }), }); ``` {% endtab %} {% tab title="Phân trang và chọn trường" %} ```typescript const page = await client.vms.list({ limit: 10, offset: 20, sort: "-created", fields: ["name", "status", "ram"], }); // Hoặc lặp qua tất cả các trang tự động (async generator) for await (const vm of client.vms.listAll()) { console.log(vm.name); } ``` {% endtab %} {% endtabs %} ### Quản lý đa site Quản lý nhiều triển khai VergeOS từ một điểm truy cập duy nhất: ```typescript import { SiteManager } from "@vergeio/tsvergeos"; import "@vergeio/tsvergeos/services/vm"; const manager = new SiteManager(); await manager.addSite({ name: "dc-east", host: "10.0.1.1", apiKey: "key-east", tags: ["production"], }); await manager.addSite({ name: "dc-west", host: "10.0.2.1", apiKey: "key-west", tags: ["production"], }); // Truy vấn một site cụ thể const eastVms = await manager.site("dc-east").vms.list(); // Phân tán các truy vấn đọc trên tất cả các site const allSiteVms = await manager.all.vms.list(); // → { data: SiteResource[], errors: SiteError[] } for (const item of allSiteVms.data) { console.log(`${item.site}: ${item.resource.name}`); } // Chỉ phân tán tới các site có một thẻ nhất định const prodVms = await manager.tagged("production").vms.list(); // Hoặc đăng ký đồng bộ một VergeClient dựng sẵn (không kiểm tra phiên bản) const existing = new VergeClient({ host: "10.0.3.1", apiKey: "key-edge" }); manager.addSite("edge-01", existing, ["edge"]); ``` {% hint style="success" %} **Truy vấn đa site** {% endhint %} Danh sách `SiteManager` phân tán các truy vấn đọc song song trên tất cả các site đã đăng ký và trả về kết quả tổng hợp cùng với mọi lỗi theo từng site. Dùng `manager.tagged(tag)` để giới hạn việc phân tán vào một tập con các site. Các thao tác ghi luôn đi qua một site có tên (`manager.site("dc-east").vms.create(...)`); proxy liên site chỉ hiển thị `list()`. ## Xử lý lỗi Tất cả lỗi đều kế thừa `VergeError` với các lớp con được gõ kiểu và các hàm kiểm tra kiểu: ```typescript import { isNotFoundError, isAuthError, isApiError, isValidationError, } from "@vergeio/tsvergeos"; try { const vm = await client.vms.get(999); } catch (err) { if (isNotFoundError(err)) { console.log("Không tìm thấy VM"); } else if (isAuthError(err)) { console.log("Xác thực thất bại"); } else if (isApiError(err)) { console.log(`Lỗi API ${err.statusCode}: ${err.message}`); } } ``` {% hint style="info" %} **Các kiểu lỗi có sẵn** {% endhint %} | Lớp lỗi | Mô tả | | ------------------------- | ---------------------------------------- | | `VergeError` | Lỗi cơ sở cho tất cả lỗi SDK | | `ApiError` | Bất kỳ lỗi HTTP nào từ API | | `NotFoundError` | Không tìm thấy tài nguyên (404) | | `AuthError` | Xác thực thất bại (401/403) | | `ConflictError` | Xung đột trạng thái tài nguyên (409) | | `ValidationError` | Dữ liệu đầu vào phía client không hợp lệ | | `UnsupportedVersionError` | Phiên bản máy chủ quá cũ | | `TaskError` | Tác vụ bất đồng bộ thất bại | | `TaskTimeoutError` | Tác vụ vượt quá thời gian chờ | | `SiteError` | Lỗi thao tác đa site | ## Cấu hình Client Toàn bộ tập tùy chọn cấu hình: ```typescript interface ClientConfig { host: string; // Tên máy chủ hoặc URL apiKey?: string; // API key cho xác thực bearer username?: string; // Tên đăng nhập cho xác thực basic password?: string; // Mật khẩu cho xác thực basic verifySsl?: boolean; // Xác minh TLS (mặc định: true) timeout?: number; // Thời gian chờ request tính bằng ms (mặc định: 30000) retries?: number; // Số lần thử lại (mặc định: 3) retryBackoff?: number; // Thời gian chờ giữa các lần thử lại tính bằng ms (mặc định: 1000) fetch?: typeof fetch; // Triển khai fetch tùy chỉnh signal?: AbortSignal; // Tín hiệu hủy } ``` ## Các trường hợp sử dụng phổ biến * **Tự động hóa hạ tầng**: Cấp phát VM, mạng và lưu trữ bằng chương trình * **Tích hợp CI/CD**: Tạo và hủy môi trường thử nghiệm trong pipeline * **Giám sát và báo cáo**: Truy vấn trạng thái tài nguyên và tạo báo cáo kiểm kê * **Tự động hóa sao lưu**: Lên lịch và quản lý snapshot cùng bản sao lưu đám mây * **Cấp phát đa thuê bao**: Tự động hóa việc tạo tenant và phân bổ tài nguyên * **Điều phối đa site**: Quản lý và truy vấn trên nhiều triển khai VergeOS ## Tài liệu và tài nguyên Để có tài liệu đầy đủ, bao gồm toàn bộ tham chiếu API và các ví dụ sử dụng chi tiết, hãy truy cập kho lưu trữ chính thức: * [Kho lưu trữ GitHub](https://github.com/verge-io/tsvergeos) * [Gói npm](https://www.npmjs.com/package/@vergeio/tsvergeos) ## Hỗ trợ Nếu bạn gặp sự cố hoặc có yêu cầu tính năng, vui lòng mở một issue trên kho lưu trữ GitHub: ## Tài nguyên bổ sung * [Tài liệu TypeScript](https://www.typescriptlang.org/docs/) * [Tài liệu API VergeOS](/knowledge-base/vi/automation-api/verge-api-guide.md) * [Python SDK](/automate-protect-and-extend/vi/tich-hop-va-api/python-sdk.md) - Phương án thay thế Python * [Go SDK](/automate-protect-and-extend/vi/tich-hop-va-api/go-sdk.md) - lựa chọn thay thế Go * [PowerShell Module](/automate-protect-and-extend/vi/tich-hop-va-api/powershell-module.md) - Giải pháp thay thế PowerShell * [Nhà cung cấp Terraform](/automate-protect-and-extend/vi/tich-hop-va-api/terraform-provider.md) - Hạ tầng dưới dạng mã --- # 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/typescript-sdk.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.