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)
以类型安全和自动补全的方式通过程序构建过滤器:
可用的过滤运算符:
.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 生命周期管理
带防火墙规则的网络
结合过滤的批量操作
多租户清单报告
重要说明
其他资源
最后更新于
这有帮助吗?