> 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/learn-the-platform/zh/mo-kuai-8-kai-fa-yu-devops/02-python-sdk.md).

# Python SDK（pyvergeos）

该 **pyvergeos** SDK 为整个 VergeOS REST API 提供了一个 Python 风格、带类型注解的接口。你无需手写原始 HTTP 请求，而是使用 **资源管理器** — `client.vms`, `client.networks`, `client.tenants` —— 它们可直接映射到 VergeOS 对象。SDK 负责认证、分页、重试和异步任务轮询，让你的自动化脚本保持简洁并专注于业务逻辑。

## 需求与安装

**前提条件：**

* **Python 3.9** 或更高版本
* **VergeOS 26.0** 或更高版本
* 可运行于 **Windows、macOS 和 Linux**

**从 PyPI 安装（推荐）：**

```bash
pip install pyvergeos
```

**或者使用 uv（更快的替代方案）：**

```bash
uv add pyvergeos
```

**从源码（开发）：**

```bash
git clone https://github.com/verge-io/pyvergeos.git
cd pyvergeos
pip install .
```

## 身份验证

SDK 支持三种认证方式，分别适用于不同的环境。

### 用户名和密码

最简单的方法，适用于交互式脚本和开发：

```python
from pyvergeos import VergeClient

client = VergeClient(
    host="192.168.1.100",
    username="admin",
    password="secret",
    verify_ssl=False  # 仅用于自签名证书
)
```

### API 令牌

用于生产环境自动化，且你已预先生成 API 密钥：

```python
client = VergeClient(
    host="192.168.1.100",
    token="your-api-token"
)
```

### 环境变量

推荐的生产环境方式——将凭据保留在源代码之外：

```bash
export VERGE_HOST=192.168.1.100
export VERGE_USERNAME=admin
export VERGE_PASSWORD=secret
export VERGE_VERIFY_SSL=false      # 可选
export VERGE_TIMEOUT=30            # 可选
export VERGE_RETRY_TOTAL=3         # 可选
export VERGE_RETRY_BACKOFF=1       # 可选
```

```python
client = VergeClient.from_env()
```

### 上下文管理器

在生产代码中始终使用上下文管理器，以确保连接被正确关闭，即使发生异常也是如此：

```python
with VergeClient(host="192.168.1.100", token="api-token") as client:
    vms = client.vms.list()
    for vm in vms:
        print(f"{vm.name}: {vm.ram}MB RAM")
# 连接会在此处自动关闭
```

## 资源管理器

每一种 VergeOS 资源类型都通过客户端对象上的一个 **资源管理器** 暴露出来。每个管理器都提供一致的 `list()`, `get()`, `create()`、以及操作方法。

### 虚拟机

`client.vms` —— 创建、配置、通电控制、克隆、快照，并管理 VM 的驱动器/NIC。

### 网络

`client.networks` —— 虚拟网络、防火墙规则、DHCP、DNS 和网络电源管理。

### 租户

`client.tenants` —— 多租户配置、资源隔离、快照、存储和网络块。

### NAS 与存储

`client.nas` —— NAS 服务、卷、CIFS/NFS 共享和卷同步。

### 灾难恢复

`client.dr` —— 云快照、站点同步和恢复工作流。

### 用户与组

`client.users` —— 用户账户、组、权限和 API 密钥管理。

### 任务与监控

`client.tasks` —— 异步任务跟踪、等待、超时。另有：告警和日志。

### 系统与 GPU

`client.clusters`, `client.nodes`, `client.gpu` —— 集群/节点信息、存储层和 GPU 设备管理。

### 完整资源表

| 类别          | 可用资源                     |
| ----------- | ------------------------ |
| **虚拟机**     | VM、驱动器、NIC、快照            |
| **网络**      | 网络、防火墙规则、DNS、DHCP、别名、主机  |
| **VPN**     | IPSec 连接、WireGuard 接口和对端 |
| **NAS/存储**  | NAS 服务、卷、CIFS/NFS 共享、卷同步 |
| **租户**      | 租户管理、快照、存储块、网络块          |
| **用户与组**    | 用户、组、权限、API 密钥           |
| **系统**      | 集群、节点、存储层、证书             |
| **监控**      | 告警、日志、任务                 |
| **备份与灾难恢复** | 快照配置文件、云快照、站点、站点同步       |

## 资源过滤

SDK 提供三种过滤资源的方法，从简单的关键字参数到完整的 OData 过滤器构建器。

### 关键字参数

用于基本过滤的最简单方法——直接传入字段名：

```python
# 查找所有正在运行的 Linux 虚拟机
vms = client.vms.list(status="running", os_family="linux")

# 通配符匹配
vms = client.vms.list(name="prod-*")
```

### OData 过滤字符串

对于复杂查询，传入原始 OData 过滤表达式：

```python
# 使用运算符组合条件
vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048")
```

### 过滤器构建器（流式 API）

以类型安全和自动补全的方式通过程序构建过滤器：

```python
from pyvergeos import Filter

# 使用运算符方法进行流式链式调用
f = Filter().eq("os_family", "linux").and_().gt("ram", 2048)
vms = client.vms.list(filter=str(f))
```

**可用的过滤运算符：**

| 方法        | OData 运算符 | 示例                                    |
| --------- | --------- | ------------------------------------- |
| `.eq()`   | `eq`      | `Filter().eq("status", "running")`    |
| `.ne()`   | `ne`      | `Filter().ne("os_family", "windows")` |
| `.gt()`   | `gt`      | `Filter().gt("ram", 4096)`            |
| `.lt()`   | `lt`      | `Filter().lt("cpu_cores", 8)`         |
| `.ge()`   | `ge`      | `Filter().ge("ram", 2048)`            |
| `.le()`   | `le`      | `Filter().le("ram", 8192)`            |
| `.and_()` | `以及`      | 链式连接多个条件                              |
| `.or_()`  | `或`       | 组合可选条件                                |

## 异步任务处理

许多 VergeOS 操作——快照、克隆、迁移——会 **以异步方式** 运行，并立即返回任务 ID。SDK 提供任务管理器用于轮询完成情况：

```python
# 快照会返回一个任务引用
result = vm.snapshot(retention=86400, quiesce=True)

# 等待快照完成（最多阻塞 300 秒）
task = client.tasks.wait(result["task"], timeout=300)
print(f"快照已完成：{task}")
```

如果任务未能在超时时间内完成，则会 `TaskTimeoutError` 抛出，并带有 `task_id` 属性，因此你可以稍后检查状态：

```python
from pyvergeos import TaskTimeoutError

try:
    task = client.tasks.wait(task_id, timeout=60)
except TaskTimeoutError as e:
    print(f"任务 {e.task_id} 仍在运行——稍后再查看")
```

## 错误处理

SDK 提供了结构化的异常层次结构，因此你可以捕获特定的失败模式：

| 异常                    | 说明                 |
| --------------------- | ------------------ |
| `VergeError`          | 所有 SDK 错误的基类异常     |
| `AuthenticationError` | 凭据无效或令牌已过期         |
| `NotFoundError`       | 请求的资源不存在           |
| `ConflictError`       | 资源状态冲突（例如：虚拟机已在运行） |
| `ValidationError`     | 无效的参数值             |
| `TaskTimeoutError`    | 任务未能在超时时间内完成       |
| `TaskError`           | 任务在执行过程中失败         |

```python
from pyvergeos import NotFoundError, AuthenticationError

try:
    vm = client.vms.get(name="nonexistent-vm")
except NotFoundError:
    print("未找到 VM——请检查名称")
except AuthenticationError:
    print("认证失败——请验证凭据")
```

## 重试配置

SDK 会自动重试瞬时错误（HTTP 429、500、502、503、504），并采用指数退避：

```python
client = VergeClient(
    host="192.168.1.100",
    token="api-token",
    retry_total=5,            # 最大重试次数（默认：3）
    retry_backoff_factor=2,   # 退避倍数（默认：1）
)
```

设置 `retry_total=0` 可完全禁用重试，适用于对时间敏感的操作。

## 租户上下文切换

pyvergeos 可以 **从主系统连接到租户上下文** ，从而启用集中式自动化脚本，用于管理多个租户中的资源：

```python
# 从主系统获取一个租户
tenant = client.tenants.get(name="customer-a")

# 连接到该租户的上下文
tenant_client = tenant.connect()

# 现在在租户内部管理资源
tenant_vms = tenant_client.vms.list()
for vm in tenant_vms:
    print(f"租户 VM：{vm.name}")

# 在租户内创建网络
tenant_client.networks.create(
    name="tenant-app-net",
    network_address="10.50.1.0/24",
    ip_address="10.50.1.1",
    dhcp_enabled=True
)
```

这对 **MSP 和服务提供商** 他们需要通过一个脚本在数十个或数百个租户环境中自动化配置。

## 实际示例

### VM 生命周期管理

```python
with VergeClient.from_env() as client:
    # 创建一个新虚拟机
    vm = client.vms.create(
        name="web-server-01",
        ram=4096,
        cpu_cores=2,
        os_family="linux"
    )

    # 添加一个 50 GB 数据盘
    vm.drives.add(name="data", size=50 * 1024 * 1024 * 1024)

    # 连接到网络
    network = client.networks.get(name="app-network")
    vm.nics.add(network=network.key)

    # 开机
    vm.power_on()
    print(f"VM {vm.name} 正在运行")
```

### 带防火墙规则的网络

```python
with VergeClient.from_env() as client:
    # 创建网络
    network = client.networks.create(
        name="web-tier",
        network_address="10.20.1.0/24",
        ip_address="10.20.1.1",
        dhcp_enabled=True
    )
    network.power_on()

    # 添加防火墙规则
    network.rules.create(
        name="Allow HTTPS",
        action="accept",
        protocol="tcp",
        dest_port=443
    )
    network.rules.create(
        name="Allow SSH",
        action="accept",
        protocol="tcp",
        dest_port=22
    )
    network.apply_rules()
```

### 结合过滤的批量操作

```python
with VergeClient.from_env() as client:
    # 对所有正在运行的生产虚拟机执行快照
    prod_vms = client.vms.list(name="prod-*", status="running")

    for vm in prod_vms:
        result = vm.snapshot(retention=86400, quiesce=True)
        task = client.tasks.wait(result["task"], timeout=300)
        print(f"已对 {vm.name} 创建快照")
```

### 多租户清单报告

```python
with VergeClient.from_env() as client:
    for tenant in client.tenants.list():
        tenant_client = tenant.connect()
        vms = tenant_client.vms.list()
        print(f"\n--- {tenant.name} ---")
        for vm in vms:
            print(f"  {vm.name}: {vm.ram}MB RAM, {vm.cpu_cores} cores")
```

## 重要说明

{% hint style="warning" %}
**线程安全**

pyvergeos 客户端 **不是线程安全的**. 如果你需要并发操作，请为每个线程创建独立的 `VergeClient` 实例。对于真正并行的工作负载，可以考虑 **govergeos** Go SDK，它专为使用 goroutine 进行并发而设计。
{% endhint %}

{% hint style="info" %}
**来自 VMware 或 Nutanix？**

pyvergeos 提前值得了解的三种模式：

* **过滤** —— 一个流式的 `Filter()` 构建器会生成 OData 风格的表达式（`.eq()`, `.gt()`, `.and_()`, `.or_()`），或者你也可以将原始 OData 字符串传给 `list(filter=...)`.
* **任务轮询** —— 异步操作会返回一个任务引用； `client.tasks.wait(task_id, timeout=...)` 会阻塞直到完成，并在 `TaskTimeoutError` 超时时时抛出。
* **租户上下文** — `tenant.connect()` 返回一个作用域限定在租户内部的客户端，因此同一个脚本无需重新连接到不同的端点，就能驱动主系统和任何子租户。
  {% endhint %}

## 其他资源

* [GitHub 仓库](https://github.com/verge-io/pyvergeos) —— 源代码、问题反馈和贡献
* [PyPI 包](https://pypi.org/project/pyvergeos/) —— 最新发布版本和版本历史
* [VergeOS API 文档](/knowledge-base/zh/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/learn-the-platform/zh/mo-kuai-8-kai-fa-yu-devops/02-python-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.