VergeOS TypeScript SDK (tsvergeos)

tsvergeos là một TypeScript SDK để quản lý VergeOS thông qua REST API, cung cấp giao diện có kiểu, không phụ thuộc, có thể tree-shake để tự động hóa VM, mạng, lưu trữ, tenant và đa site.

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ị)

npm install @vergeio/tsvergeos

Dùng pnpm / yarn / bun

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ị)

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ý
});

Xác minh chứng chỉ SSL

Đặ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

const client = await VergeClient.connect({
  host: "192.168.1.100",
  username: "admin",
  password: "secret",
});

Biến môi trường

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

const client = await VergeClient.connectFromEnv();

Khuyến nghị cho môi trường sản xuất

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

// 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";

Dịch vụ chưa đăng ký

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ý:

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

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);

Trạng thái nguồn đáng tin cậy

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:

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ị:

// 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:

Trình tạo bộ lọc fluent

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 });

Viết tắt hàm

import { buildFilter } from "@vergeio/tsvergeos";

const vms = await client.vms.list({
  filter: buildFilter({
    status: "running",
    name: "web*",
    cpu_cores: { gt: 2 },
  }),
});

Phân trang và chọn trường

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);
}

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:

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<VM>[], 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"]);

Truy vấn đa site

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:

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}`);
  }
}

Các kiểu lỗi có sẵn

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:

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
• Gói npm

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:

https://github.com/verge-io/tsvergeos/issues

Tài nguyên bổ sung

• Tài liệu TypeScript
• Tài liệu API VergeOS
• Python SDK - Phương án thay thế Python
• Go SDK - lựa chọn thay thế Go
• PowerShell Module - Giải pháp thay thế PowerShell
• Nhà cung cấp Terraform - Hạ tầng dưới dạng mã