VergeOS Python SDK（pyvergeos）

pyvergeos 是一个用于通过 REST API 管理 VergeOS 的 Python SDK，提供 Python 风格、带类型注释的接口，用于自动化 VM、网络、存储、租户和灾难恢复。

概述

pyvergeos 是一个 Python SDK，用于通过 REST API 管理 VergeOS 基础设施。它提供了一个符合 Python 风格、带类型注解的接口，可用于自动化虚拟机生命周期、网络、存储、多租户操作和灾难恢复工作流，非常适合自动化脚本、工具开发和集成。

主要功能

• 虚拟机管理：创建、配置、电源控制、克隆和快照
• 高级网络：虚拟网络、防火墙规则、DHCP、DNS、IPSec VPN 和 WireGuard
• NAS 与存储：卷管理、CIFS/NFS 共享和同步
• 多租户：带资源隔离的租户预配
• 灾难恢复：云快照、站点同步和恢复工作流
• 过滤：支持 OData 过滤，带流式过滤构建器 API
• 类型注解：为 IDE 自动补全和静态分析提供完整类型提示
• 跨平台：支持 Windows、macOS 和 Linux

要求

• Python 3.9 或更高版本
• VergeOS 26.0 或更高版本

安装

从 PyPI 安装（推荐）

pip install pyvergeos

使用 uv

uv add pyvergeos

从源码安装

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

身份验证

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

用户名/密码

from pyvergeos import VergeClient

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

SSL 证书验证

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

API 令牌

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

环境变量

export VERGE_HOST=192.168.1.100
export VERGE_USERNAME=admin
export VERGE_PASSWORD=secret

client = VergeClient.from_env()

生产环境推荐

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

上下文管理器

with VergeClient(host="192.168.1.100", token="api-token") as client:
    vms = client.vms.list()

自动清理

使用上下文管理器（with 语句）可确保连接被正确关闭，即使发生异常也是如此。

可用资源

该 SDK 可访问以下 VergeOS 资源：

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

使用示例

管理虚拟机

from pyvergeos import VergeClient

client = VergeClient(host="192.168.1.100", username="admin", password="secret")

# 列出所有虚拟机
for vm in client.vms.list():
    print(f"{vm.name}: {vm.ram}MB RAM, {vm.cpu_cores} cores")

# 获取特定虚拟机
vm = client.vms.get(name="web-server")

# 创建虚拟机
new_vm = client.vms.create(
    name="test-vm",
    ram=2048,
    cpu_cores=2,
    os_family="linux"
)

# 电源操作
vm.power_on()
vm.power_off()
vm.reset()

# 快照
vm.snapshot(retention=86400, quiesce=True)

# 克隆虚拟机
clone = vm.clone(name="test-clone")

# 添加磁盘和网卡
vm.drives.add(name="data", size=50*1024*1024*1024)
vm.nics.add(network=network.key)

client.disconnect()

创建和管理网络

# 创建虚拟网络
network = client.networks.create(
    name="app-network",
    network_address="10.10.1.0/24",
    ip_address="10.10.1.1",
    dhcp_enabled=True
)

network.power_on()
network.apply_rules()

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

过滤资源

该 SDK 支持多种过滤方式：

关键字参数

# 适用于基础过滤，简单易读
vms = client.vms.list(status="running", name="prod-*")

OData 过滤字符串

# 复杂查询使用完整的 OData 过滤语法
vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048")

过滤构建器

# 用于以编程方式构建过滤条件的流式 API
from pyvergeos import Filter

f = Filter().eq("os_family", "linux").and_().gt("ram", 2048)
vms = client.vms.list(filter=str(f))

等待任务

VergeOS 中的许多操作都是异步执行的。使用任务管理器等待完成：

result = vm.snapshot()
task = client.tasks.wait(result["task"], timeout=300)

异步操作

快照、克隆和迁移等操作会立即返回一个任务 ID。使用 client.tasks.wait() 来阻塞，直到操作完成。

错误处理

该 SDK 为不同错误条件提供了特定的异常类型：

from pyvergeos import NotFoundError, AuthenticationError, TaskTimeoutError

try:
    vm = client.vms.get(name="nonexistent")
except NotFoundError:
    print("未找到虚拟机")

try:
    task = client.tasks.wait(task_id, timeout=60)
except TaskTimeoutError as e:
    print(f"任务 {e.task_id} 超时")

可用异常类型

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

常见用例

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

文档与资源

完整文档（包括所有可用方法和详细使用示例）请访问官方仓库：

• GitHub 仓库
• PyPI 包

支持

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

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

其他资源

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