VergeOS Go SDK（govergeos）

govergeos 是一个用于通过 REST API 管理 VergeOS 基础设施的 Go 客户端库，为自动化 VM、网络、存储、租户和灾难恢复提供类型安全接口。

概述

govergeos 是一个用于通过 REST API 管理 VergeOS 基础设施的 Go 客户端库。它提供类型安全、符合 Go 习惯的接口，可用于自动化虚拟机生命周期、网络、存储、多租户操作和灾难恢复工作流，非常适合构建工具、控制器和基础设施自动化。

主要功能

• 虚拟机管理：创建、配置、电源控制、克隆和快照
• 高级网络：虚拟网络、防火墙规则、DHCP、DNS、IPSec VPN 和 WireGuard
• NAS 与存储: 卷管理、CIFS/NFS 共享、异步卷浏览和同步
• 多租户: 具有资源隔离和节点管理的租户部署
• 灾难恢复：云快照、站点同步和恢复工作流
• 类型安全 API: 用于模拟、上下文支持和线程安全并发操作的完整 Go 接口
• 零依赖: 仅使用标准库——无外部依赖
• 跨平台：支持 Windows、macOS 和 Linux

要求

• Go 1.21 或更高版本
• VergeOS 26.0 或更高版本

安装

使用 go get

go get github.com/verge-io/govergeos

在 go.mod 中

require github.com/verge-io/govergeos v0.1.2

身份验证

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

用户名/密码

import vergeos "github.com/verge-io/govergeos"

client, err := vergeos.NewClient(
    vergeos.WithBaseURL("https://192.168.1.100"),
    vergeos.WithCredentials("admin", "secret"),
    vergeos.WithInsecureTLS(true), // 适用于自签名证书
)
if err != nil {
    log.Fatal(err)
}

SSL 证书验证

设置 WithInsecureTLS(true) 仅适用于使用自签名证书的环境。对于具有有效证书的生产环境，请省略此选项。

API 密钥

client, err := vergeos.NewClient(
    vergeos.WithBaseURL("https://192.168.1.100"),
    vergeos.WithAPIKey("your-api-key-token"),
)

环境变量

export VERGEOS_HOST=https://192.168.1.100
export VERGEOS_USERNAME=admin
export VERGEOS_PASSWORD=secret
export VERGEOS_VERIFY_SSL=false

client, err := vergeos.NewClient(vergeos.WithEnvConfig())

变量	必需	默认值	描述
VERGEOS_HOST	是	—	基础 URL（例如， https://vergeos.example.com)
VERGEOS_USERNAME	否*	—	基础认证用户名
VERGEOS_PASSWORD	否*	—	基础认证密码
VERGEOS_API_KEY	否*	—	用于 Bearer 认证的 API 密钥
VERGEOS_VERIFY_SSL	否	true	验证 TLS 证书
VERGEOS_TIMEOUT	否	30	请求超时（秒）

*必须提供（USERNAME+PASSWORD）或 API_KEY 之一。

生产环境推荐

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

客户端选项

该客户端支持以下额外配置选项：

client, err := vergeos.NewClient(
    vergeos.WithBaseURL("https://192.168.1.100"),
    vergeos.WithCredentials("admin", "secret"),
    vergeos.WithTimeout(60 * time.Second),
    vergeos.WithUserAgent("my-automation/1.0"),
    vergeos.WithHTTPClient(customHTTPClient),
)

可用资源

该 SDK 可访问以下 VergeOS 资源：

类别	服务
虚拟机	VMs, VMDrives, VMNICs, VMSnapshots, VMDevices
网络	Networks, VNetRules, VNetAddresses, VNetHosts, VNetDNSViews/Zones/Records
VPN	VNetIPSecs, VNetIPSecPhase1s/Phase2s, VNetWireGuards, VNetWireGuardPeers
NAS/存储	NASServices, Volumes, VolumeSnapshots, VolumeCIFSShares, VolumeNFSShares, VolumeSyncs
租户	Tenants, TenantNodes, TenantStorage, TenantSnapshots, TenantLayer2Networks
用户和组	Users, Groups, Members, Permissions, UserAPIKeys
系统	Clusters, Nodes, Settings, System, Certificates
监控	Alarms, Logs, Tasks, StorageTiers, ClusterTiers
备份与灾难恢复	SnapshotProfiles, CloudSnapshots, Sites, SiteSyncs
自动化	Files, CloudInitFiles, WebhookURLs, Webhooks
Organization	Tags, TagCategories, TagMembers, ResourceGroups

使用示例

管理虚拟机

import (
    "context"
    "fmt"
    "log"

    vergeos "github.com/verge-io/govergeos"
)

func main() {
    client, err := vergeos.NewClient(
        vergeos.WithBaseURL("https://192.168.1.100"),
        vergeos.WithCredentials("admin", "secret"),
        vergeos.WithInsecureTLS(true),
    )
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // 列出所有虚拟机
    vms, err := client.VMs.List(ctx)
    if err != nil {
        log.Fatal(err)
    }
    for _, vm := range vms {
        fmt.Printf("%s: %dMB RAM, %d cores\n", vm.Name, vm.RAM, vm.CPUCores)
    }

    // 获取指定虚拟机
    vm, err := client.VMs.Get(ctx, 42)
    if err != nil {
        log.Fatal(err)
    }

    // 创建虚拟机
    newVM, err := client.VMs.Create(ctx, &vergeos.VMCreateRequest{
        Name:     "test-vm",
        RAM:      2048,
        CPUCores: 2,
        Cluster:  1,
    })
    if err != nil {
        log.Fatal(err)
    }

    // 电源操作（使用 ID.Int() 获取整数 ID）
    _ = client.VMs.PowerOn(ctx, newVM.ID.Int())
    _ = client.VMs.PowerOff(ctx, newVM.ID.Int())
    _ = client.VMs.Reset(ctx, newVM.ID.Int())

    // 创建快照
    _ = client.VMs.Snapshot(ctx, newVM.ID.Int(), &vergeos.VMSnapshotOptions{
        Name: "pre-upgrade",
    })

    // 克隆虚拟机
    clone, _ := client.VMs.Clone(ctx, vm.ID.Int(), &vergeos.VMCloneOptions{
        Name: "test-clone",
    })
    fmt.Printf("已克隆的虚拟机：%s\n", clone.Name)
}

创建和管理网络

ctx := context.Background()

// 创建虚拟网络
network, err := client.Networks.Create(ctx, &vergeos.NetworkCreateRequest{
    Name:        "app-network",
    Network:     "10.10.1.0/24",
    IPAddress:   "10.10.1.1",
    DHCPEnabled: vergeos.Ptr(true),
    DHCPStart:   "10.10.1.100",
    DHCPStop:    "10.10.1.200",
})
if err != nil {
    log.Fatal(err)
}

// 启动网络
_ = client.Networks.PowerOn(ctx, network.ID.Int())

// 添加防火墙规则
rule, err := client.VNetRules.Create(ctx, &vergeos.VNetRuleCreateRequest{
    VNet:             network.ID.Int(),
    Name:             "允许 SSH",
    Action:           vergeos.Ptr("accept"),
    Protocol:         vergeos.Ptr("tcp"),
    Direction:        vergeos.Ptr("incoming"),
    DestinationPorts: vergeos.Ptr("22"),
})
if err != nil {
    log.Fatal(err)
}

// 应用规则
_ = client.Networks.ApplyRules(ctx, network.ID.Int())

过滤资源

该 SDK 支持使用列表选项进行灵活筛选：

基本筛选

// 按电源状态筛选虚拟机（运行中）
vms, err := client.VMs.List(ctx,
    vergeos.WithFilter("powerstate eq true"),
)

多个选项

// 组合筛选、排序和分页
vms, err := client.VMs.List(ctx,
    vergeos.WithFilter("os_family eq 'linux' and ram gt 2048"),
    vergeos.WithSort("name"),
    vergeos.WithLimit(10),
    vergeos.WithOffset(0),
)

字段选择

// 仅返回特定字段（ID 字段使用 $key）
vms, err := client.VMs.List(ctx,
    vergeos.WithFields("$key,name,powerstate,ram"),
)

并发操作

该 SDK 线程安全，并支持使用 goroutine 进行并发操作：

import "sync"

var wg sync.WaitGroup
vmIDs := []int{1, 2, 3, 4, 5}

for _, id := range vmIDs {
    wg.Add(1)
    go func(vmID int) {
        defer wg.Done()
        vm, err := client.VMs.Get(ctx, vmID)
        if err != nil {
            log.Printf("获取虚拟机 %d 时出错：%v", vmID, err)
            return
        }
        status := "已停止"
        if vm.PowerState {
            status = "运行中"
        }
        fmt.Printf("虚拟机：%s，电源状态：%s\n", vm.Name, status)
    }(id)
}
wg.Wait()

上下文取消

所有方法都接受一个 context.Context，以便为长时间运行的操作设置超时并处理取消。

错误处理

该 SDK 为不同错误情况提供了特定错误类型：

import vergeos "github.com/verge-io/govergeos"

vm, err := client.VMs.Get(ctx, 999)
if err != nil {
    if vergeos.IsNotFoundError(err) {
        fmt.Println("未找到虚拟机")
    } else if vergeos.IsAuthError(err) {
        fmt.Println("认证失败")
    } else if vergeos.IsValidationError(err) {
        fmt.Println("无效的请求参数")
    } else {
        fmt.Printf("意外错误：%v\n", err)
    }
}

可用的错误类型

错误类型	辅助函数	描述
APIError	—	所有 API 错误的基础错误
AuthError	IsAuthError(err)	凭据无效或令牌已过期
NotFoundError	IsNotFoundError(err)	请求的资源不存在
ValidationError	IsValidationError(err)	参数值无效
UnsupportedVersionError	IsUnsupportedVersionError(err)	不支持的 VergeOS 版本

常见用例

• 基础设施自动化：以编程方式预配虚拟机、网络和存储
• Kubernetes 操作器: 为 VergeOS 资源构建自定义控制器
• CI/CD 集成：在流水线中创建和销毁测试环境
• 监控工具: 查询资源状态并构建自定义仪表板
• 备份自动化：安排并管理快照和云备份
• 多租户预配：自动化租户创建和资源分配

文档和资源

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

• GitHub 仓库
• Go 包文档

支持

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

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

其他资源

• Go 文档
• VergeOS API 文档
• Python SDK（pyvergeos） - Python 替代方案
• Terraform 提供程序 - 基础设施即代码