> 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/zh/ji-cheng-yu-api/typescript-sdk.md).

# VergeOS TypeScript SDK（tsvergeos）

## 概述

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 安装（推荐）

```bash
npm install @vergeio/tsvergeos
```

### 使用 pnpm / yarn / bun

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

## 身份验证

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

### API 密钥（推荐）

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

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

{% hint style="info" %}
**SSL 证书验证**
{% endhint %}

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

### 用户名 / 密码

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

### 环境变量

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

```typescript
const client = await VergeClient.connectFromEnv();
```

{% hint style="success" %}
**生产环境推荐**
{% endhint %}

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

## 服务注册

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

### 三种导入级别

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

{% hint style="warning" %}
**未注册的服务**
{% endhint %}

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

### 仅类型导入

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

```typescript
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、资源组                                       |

## 使用示例

### 管理虚拟机

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

// 列出所有虚拟机
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);
```

{% hint style="info" %}
**可靠的电源状态**
{% endhint %}

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

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

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

### 控制台访问

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

```typescript
// 浏览器兼容：令牌嵌入在 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 支持多种过滤方式：

{% tabs %}
{% tab title="流式 Filter 构建器" %}

```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="函数式简写" %}

```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="分页和字段选择" %}

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

{% endtab %}
{% endtabs %}

### 多站点管理

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

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

// 查询特定站点
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"]);
```

{% hint style="success" %}
**多站点查询**
{% endhint %}

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

## 错误处理

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

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

{% hint style="info" %}
**可用的错误类型**
{% endhint %}

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

## 客户端配置

完整的配置选项集：

```typescript
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 仓库](https://github.com/verge-io/tsvergeos)
* [npm 包](https://www.npmjs.com/package/@vergeio/tsvergeos)

## 支持

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

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

## 其他资源

* [TypeScript 文档](https://www.typescriptlang.org/docs/)
* [VergeOS API 文档](/knowledge-base/zh/automation-api/verge-api-guide.md)
* [Python SDK](/automate-protect-and-extend/zh/ji-cheng-yu-api/python-sdk.md) - Python 替代方案
* [Go SDK](/automate-protect-and-extend/zh/ji-cheng-yu-api/go-sdk.md) - Go 替代方案
* [PowerShell 模块](/automate-protect-and-extend/zh/ji-cheng-yu-api/powershell-module.md) - PowerShell 替代方案
* [Terraform 提供程序](/automate-protect-and-extend/zh/ji-cheng-yu-api/terraform-provider.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/zh/ji-cheng-yu-api/typescript-sdk.md?ask=<question>&goal=<endgoal>
```

`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.