VergeOS TypeScript SDK（tsvergeos）

tsvergeos 是一个用于通过 REST API 管理 VergeOS 的 TypeScript SDK，提供零依赖、可树摇优化、带类型的接口，用于自动化 VM、网络、存储、租户和多站点管理。

概述

tsvergeos 是一个用于通过 REST API 管理 VergeOS 基础设施的 TypeScript SDK。它提供零依赖、可按需打包、完全类型化的接口，用于自动化 VM 生命周期、网络、存储、多租户操作和多站点管理，非常适合自动化脚本、工具开发和集成。

主要功能

• 零依赖: 无需审计，无需破坏
• 支持 Tree Shaking: 只导入你使用的服务；未使用的服务会被死代码消除
• 完整类型覆盖: 每个资源、参数和响应都带有 TSDoc 文档的类型定义
• 93 个服务: 完整覆盖每一个 VergeOS API 端点
• 内置多站点: 从单一入口查询和管理多个 VergeOS 部署 SiteManager
• 跨平台: 可在 Node.js 20+、Deno、Bun 和现代浏览器中运行
• 过滤: 同时支持流式和 Filter 构建器以及函数式 buildFilter 简写

要求

• Node.js 20+（也支持 Deno 和 Bun）
• VergeOS 6.x（API v4）

安装

通过 npm 安装（推荐）

npm install @vergeio/tsvergeos

使用 pnpm / yarn / bun

pnpm add @vergeio/tsvergeos
# 或
yarn add @vergeio/tsvergeos
# 或
bun add @vergeio/tsvergeos

身份验证

该 SDK 支持多种身份验证方式：

API 密钥（推荐）

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

const client = await VergeClient.connect({
  host: "192.168.1.100",
  apiKey: "your-api-key",
  verifySsl: false, // 用于自签名证书
});

SSL 证书验证

设置 verifySsl: false 仅用于使用自签名证书的环境。对于具有有效证书的生产环境，请省略此参数或将其设置为 true.

用户名 / 密码

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

环境变量

export VERGEOS_HOST=192.168.1.100
export VERGEOS_API_KEY=your-api-key
# 可选：
export VERGEOS_VERIFY_SSL=false
export VERGEOS_TIMEOUT=60

const client = await VergeClient.connectFromEnv();

生产环境推荐

使用环境变量可避免在源代码中暴露凭据，并且便于在不同环境中使用不同凭据。

服务注册

该 SDK 使用可按需打包的导入——服务通过副作用导入进行注册，因此未使用的服务会从你的 bundle 中被死代码消除。

三种导入级别

// 1. 默认：约 48 个最常用服务（VM、网络、租户、存储等）
import { VergeClient } from "@vergeio/tsvergeos";

// 2. 完整：全部 93 个服务（告警、更新设置、存储层级等）
import { VergeClient } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/full";

// 3. 单独导入：精确选择你需要的内容
import { VergeClient } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/services/alarm";
import "@vergeio/tsvergeos/services/storage-tier";

未注册的服务

默认导入并不包含所有服务。如果你访问了一个未注册的服务（例如， client.alarms 却没有导入它），你会得到 undefined。对于仪表盘、管理工具或后端脚本这类不在乎 bundle 大小的场景，请使用 import '@vergeio/tsvergeos/full' 来注册全部内容。

仅类型导入

无论注册了哪些服务，类型导入对 bundle 都没有任何影响：

import type {
  VM,
  Alarm,
  Network,
  Tenant,
  Volume,
} from "@vergeio/tsvergeos/types";

可用资源

该 SDK 提供对 93 个服务的访问，覆盖完整的 VergeOS API：

类别	资源
计算	VM、磁盘、设备、NIC、机器快照、统计信息
网络	网络、规则、别名、地址、主机、DNS 区域/记录/视图
VPN	WireGuard 接口和对等节点、IPSec 连接和阶段
存储	卷、卷快照、CIFS/NFS 共享、同步、浏览器、存储层级
NAS	NAS 服务、用户、文件
租户	租户、节点、存储、快照、二层网络
配方	VM 和租户配方、实例、目录、仓库
快照	快照配置文件、周期、云快照
站点	API sites 服务——入站/出站同步、同步配置文件周期（与 SDK 的 SiteManager)
系统	系统、集群、节点、设置、日志、任务
监控	告警、告警类型、webhook、webhook URL
认证	用户、组、成员、权限、API 密钥
标签	标签、类别、成员
更新	更新设置、源、包、分支
其他	证书、cloud-init、资源组

使用示例

管理虚拟机

import { VergeClient } from "@vergeio/tsvergeos";
import "@vergeio/tsvergeos/services/vm";

const client = await VergeClient.connect({
  host: "192.168.1.100",
  apiKey: "your-api-key",
});

// 列出所有虚拟机
const vms = await client.vms.list();
for (const vm of vms) {
  console.log(`${vm.name}：${vm.ram}MB 内存，${vm.cpu_cores} 核心`);
}

// 获取指定虚拟机
const vm = await client.vms.get(42);
const vmByName = await client.vms.getByName("web-server");

// 创建虚拟机
const newVm = await client.vms.create({
  name: "test-vm",
  machine_type: "q35",
  ram: 2048,
  cpu_cores: 2,
  os_family: "linux",
});

// 电源操作
await client.vms.powerOn(newVm.$key);
await client.vms.powerOff(newVm.$key); // 优雅的 ACPI 关机

// 更新 VM
await client.vms.update(newVm.$key, { ram: 4096 });

// 删除 VM
await client.vms.delete(newVm.$key);

可靠的电源状态

该 powerstate VM 资源上的字段通常会被 API 省略。若要获取权威的实时电源状态，请查询机器状态服务：

import "@vergeio/tsvergeos/services/machine-status";

const status = await client.machineStatuses.getByMachine(newVm.$key);
console.log(status.running, status.status);

控制台访问

getConsoleInfo() 返回用于打开直连 VM 的 WebSocket 控制台的连接详情。支持三种认证方式——请根据控制台的渲染位置选择：

// 浏览器兼容：令牌嵌入在 WebSocket URL 中
const info = await client.vms.getConsoleInfo(42, {
  username: "admin",
  password: "secret",
});
if (info.isAvailable) {
  const rfb = new RFB(container, info.websocketUrl);
}

// Node / Deno / Bun：通过 Authorization 头使用 API 密钥
const info = await client.vms.getConsoleInfo(42, { apiKey: "..." });
const ws = new WebSocket(info.websocketUrl, {
  headers: { Authorization: `Bearer ${info.apiKey}` },
});

浏览器 WebSocket API 不支持自定义头——在浏览器中请使用用户名/密码或预先存在的令牌。若要直接打开 Web UI 控制台且无需 API 调用，请使用 client.vms.getConsoleURL(42).

过滤资源

该 SDK 支持多种过滤方式：

流式 Filter 构建器

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

函数式简写

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

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

分页和字段选择

const page = await client.vms.list({
  limit: 10,
  offset: 20,
  sort: "-created",
  fields: ["name", "status", "ram"],
});

// 或自动遍历所有页面（异步生成器）
for await (const vm of client.vms.listAll()) {
  console.log(vm.name);
}

多站点管理

从单一入口管理多个 VergeOS 部署：

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

// 查询特定站点
const eastVms = await manager.site("dc-east").vms.list();

// 将读取查询分发到所有站点
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}`);
}

// 仅分发到带有指定标签的站点
const prodVms = await manager.tagged("production").vms.list();

// 或同步注册一个预构建的 VergeClient（不进行版本检查）
const existing = new VergeClient({ host: "10.0.3.1", apiKey: "key-edge" });
manager.addSite("edge-01", existing, ["edge"]);

多站点查询

该 SiteManager 并行地将读取查询分发到所有已注册站点，并返回聚合结果以及每个站点的错误。使用 manager.tagged(tag) 将分发范围限定为站点子集。变更操作始终通过一个命名站点（manager.site("dc-east").vms.create(...)）；跨站点代理仅暴露 list().

错误处理

所有错误都继承 VergeError 并带有类型化子类和类型守卫函数：

import {
  isNotFoundError,
  isAuthError,
  isApiError,
  isValidationError,
} from "@vergeio/tsvergeos";

try {
  const vm = await client.vms.get(999);
} catch (err) {
  if (isNotFoundError(err)) {
    console.log("未找到 VM");
  } else if (isAuthError(err)) {
    console.log("认证失败");
  } else if (isApiError(err)) {
    console.log(`API 错误 ${err.statusCode}：${err.message}`);
  }
}

可用的错误类型

错误类	描述
VergeError	所有 SDK 错误的基础错误
ApiError	来自 API 的任何 HTTP 错误
NotFoundError	资源未找到（404）
AuthError	认证失败（401/403）
ConflictError	资源状态冲突（409）
ValidationError	无效的客户端输入
UnsupportedVersionError	服务器版本过旧
TaskError	异步任务失败
TaskTimeoutError	任务超出等待超时
SiteError	多站点操作失败

客户端配置

完整的配置选项集：

interface ClientConfig {
  host: string; // 服务器主机名或 URL
  apiKey?: string; // 用于 bearer 认证的 API 密钥
  username?: string; // basic 认证的用户名
  password?: string; // basic 认证的密码
  verifySsl?: boolean; // TLS 验证（默认：true）
  timeout?: number; // 请求超时，单位 ms（默认：30000）
  retries?: number; // 重试次数（默认：3）
  retryBackoff?: number; // 重试之间的退避时间，单位 ms（默认：1000）
  fetch?: typeof fetch; // 自定义 fetch 实现
  signal?: AbortSignal; // 取消信号
}

常见用例

• 基础设施自动化：以编程方式预配虚拟机、网络和存储
• CI/CD 集成：在流水线中创建和销毁测试环境
• 监控和报告：查询资源状态并生成清单报告
• 备份自动化：安排并管理快照和云备份
• 多租户预配：自动化租户创建和资源分配
• 多站点编排: 管理并跨多个 VergeOS 部署进行查询

文档和资源

有关完整文档、完整 API 参考和详细使用示例，请访问官方仓库：

• GitHub 仓库
• npm 包

支持

如果您遇到问题或有功能请求，请在 GitHub 仓库中提交 issue：

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

其他资源

• TypeScript 文档
• VergeOS API 文档
• Python SDK - Python 替代方案
• Go SDK - Go 替代方案
• PowerShell 模块 - PowerShell 替代方案
• Terraform 提供程序 - 基础设施即代码