跳转到内容
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Python SDK(pyvergeos)

使用 pyvergeos Python SDK 自动化 VergeOS 基础设施——可通过 Python 脚本管理虚拟机生命周期、网络、多租户、存储和灾难恢复。

该 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 安装(推荐):

pip install pyvergeos

或者使用 uv(更快的替代方案):

uv add pyvergeos

从源码(开发):

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

身份验证

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

用户名和密码

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

API 令牌

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

环境变量

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

上下文管理器

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

资源管理器

每一种 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 过滤器构建器。

关键字参数

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

OData 过滤字符串

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

过滤器构建器(流式 API)

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

可用的过滤运算符:

方法
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 提供任务管理器用于轮询完成情况:

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

错误处理

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

异常
说明

VergeError

所有 SDK 错误的基类异常

AuthenticationError

凭据无效或令牌已过期

NotFoundError

请求的资源不存在

ConflictError

资源状态冲突(例如:虚拟机已在运行)

ValidationError

无效的参数值

TaskTimeoutError

任务未能在超时时间内完成

TaskError

任务在执行过程中失败

重试配置

SDK 会自动重试瞬时错误(HTTP 429、500、502、503、504),并采用指数退避:

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

租户上下文切换

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

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

实际示例

VM 生命周期管理

带防火墙规则的网络

结合过滤的批量操作

多租户清单报告

重要说明

来自 VMware 或 Nutanix?

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

  • 过滤 —— 一个流式的 Filter() 构建器会生成 OData 风格的表达式(.eq(), .gt(), .and_(), .or_()),或者你也可以将原始 OData 字符串传给 list(filter=...).

  • 任务轮询 —— 异步操作会返回一个任务引用; client.tasks.wait(task_id, timeout=...) 会阻塞直到完成,并在 TaskTimeoutError 超时时时抛出。

  • 租户上下文 — tenant.connect() 返回一个作用域限定在租户内部的客户端,因此同一个脚本无需重新连接到不同的端点,就能驱动主系统和任何子租户。

其他资源

最后更新于

这有帮助吗?