VergeOS Go SDK (govergeos)

govergeos là một thư viện client Go để quản lý hạ tầng VergeOS thông qua REST API, cung cấp các giao diện an toàn kiểu để tự động hóa VM, mạng, lưu trữ, tenant và khôi phục thảm họa.

Tổng quan

govergeos là một thư viện client Go để quản lý hạ tầng VergeOS thông qua REST API. Nó cung cấp một giao diện Go an toàn kiểu, đúng phong cách Go để tự động hóa vòng đời VM, mạng, lưu trữ, thao tác đa tenant và quy trình phục hồi sau thảm họa, rất phù hợp để xây dựng công cụ, operator và tự động hóa hạ tầng.

Tính năng chính

• Quản lý VM: Tạo, cấu hình, điều khiển nguồn, sao chép và snapshot
• Mạng nâng cao: Mạng ảo, quy tắc tường lửa, DHCP, DNS, VPN IPSec và WireGuard
• NAS & Lưu trữ: Quản lý volume, chia sẻ CIFS/NFS, duyệt volume không đồng bộ và đồng bộ hóa
• Đa thuê bao: Cấp phát tenant với cô lập tài nguyên và quản lý node
• Khôi phục sau thảm họa: Snapshot đám mây, đồng bộ hóa site và quy trình khôi phục
• API an toàn kiểu: Các interface Go đầy đủ để mock, hỗ trợ context và các thao tác đồng thời an toàn với luồng
• Không phụ thuộc: Chỉ dùng thư viện chuẩn—không có phụ thuộc bên ngoài
• Đa nền tảng: Hỗ trợ Windows, macOS và Linux

Yêu cầu

• Go 1.21 trở lên
• VergeOS 26.0 trở lên

Cài đặt

Dùng go get

go get github.com/verge-io/govergeos

Trong go.mod

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

Xác thực

SDK hỗ trợ nhiều phương thức xác thực:

Tên người dùng/Mật khẩu

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), // Dành cho chứng chỉ tự ký
)
if err != nil {
    log.Fatal(err)
}

Xác minh chứng chỉ SSL

Đặt WithInsecureTLS(true) chỉ dành cho môi trường có chứng chỉ tự ký. Với môi trường sản xuất có chứng chỉ hợp lệ, hãy bỏ qua tùy chọn này.

Khóa API

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

Biến môi trường

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())

Biến	Bắt buộc	Mặc định	Mô tả
VERGEOS_HOST	Có	—	URL cơ sở (ví dụ, https://vergeos.example.com)
VERGEOS_USERNAME	Không*	—	Tên người dùng cho xác thực cơ bản
VERGEOS_PASSWORD	Không*	—	Mật khẩu cho xác thực cơ bản
VERGEOS_API_KEY	Không*	—	Khóa API để xác thực bearer
VERGEOS_VERIFY_SSL	Không	true	Xác minh chứng chỉ TLS
VERGEOS_TIMEOUT	Không	30	Thời gian chờ yêu cầu tính bằng giây

*Cần một trong hai: (USERNAME+PASSWORD) hoặc API_KEY.

Khuyến nghị cho môi trường sản xuất

Sử dụng biến môi trường giúp giữ thông tin xác thực ra khỏi mã nguồn của bạn và dễ dàng dùng các thông tin xác thực khác nhau giữa các môi trường.

Tùy chọn client

Client hỗ trợ các tùy chọn cấu hình bổ sung:

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),
)

Tài nguyên có sẵn

SDK cung cấp quyền truy cập vào các tài nguyên VergeOS sau:

Danh mục	Dịch vụ
Máy ảo	VMs, VMDrives, VMNICs, VMSnapshots, VMDevices
Mạng	Networks, VNetRules, VNetAddresses, VNetHosts, VNetDNSViews/Zones/Records
VPN	VNetIPSecs, VNetIPSecPhase1s/Phase2s, VNetWireGuards, VNetWireGuardPeers
NAS/Lưu trữ	NASServices, Volumes, VolumeSnapshots, VolumeCIFSShares, VolumeNFSShares, VolumeSyncs
Tenant	Tenants, TenantNodes, TenantStorage, TenantSnapshots, TenantLayer2Networks
Người dùng & Nhóm	Users, Groups, Members, Permissions, UserAPIKeys
Hệ thống	Clusters, Nodes, Settings, System, Certificates
Giám sát	Alarms, Logs, Tasks, StorageTiers, ClusterTiers
Sao lưu & DR	SnapshotProfiles, CloudSnapshots, Sites, SiteSyncs
Tự động hóa	Files, CloudInitFiles, WebhookURLs, Webhooks
Organization	Tags, TagCategories, TagMembers, ResourceGroups

Ví dụ sử dụng

Quản lý máy ảo

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()

    // Liệt kê tất cả VM
    vms, err := client.VMs.List(ctx)
    if err != nil {
        log.Fatal(err)
    }
    for _, vm := range vms {
        fmt.Printf("%s: %dMB RAM, %d lõi\n", vm.Name, vm.RAM, vm.CPUCores)
    }

    // Lấy một VM cụ thể
    vm, err := client.VMs.Get(ctx, 42)
    if err != nil {
        log.Fatal(err)
    }

    // Tạo một VM
    newVM, err := client.VMs.Create(ctx, &vergeos.VMCreateRequest{
        Name:     "test-vm",
        RAM:      2048,
        CPUCores: 2,
        Cluster:  1,
    })
    if err != nil {
        log.Fatal(err)
    }

    // Các thao tác nguồn (dùng ID.Int() để lấy ID số nguyên)
    _ = client.VMs.PowerOn(ctx, newVM.ID.Int())
    _ = client.VMs.PowerOff(ctx, newVM.ID.Int())
    _ = client.VMs.Reset(ctx, newVM.ID.Int())

    // Tạo snapshot
    _ = client.VMs.Snapshot(ctx, newVM.ID.Int(), &vergeos.VMSnapshotOptions{
        Name: "pre-upgrade",
    })

    // Nhân bản một VM
    clone, _ := client.VMs.Clone(ctx, vm.ID.Int(), &vergeos.VMCloneOptions{
        Name: "test-clone",
    })
    fmt.Printf("VM đã nhân bản: %s\n", clone.Name)
}

Tạo và quản lý mạng

ctx := context.Background()

// Tạo mạng ảo
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)
}

// Bật nguồn cho mạng
_ = client.Networks.PowerOn(ctx, network.ID.Int())

// Thêm quy tắc tường lửa
rule, err := client.VNetRules.Create(ctx, &vergeos.VNetRuleCreateRequest{
    VNet:             network.ID.Int(),
    Name:             "Allow SSH",
    Action:           vergeos.Ptr("accept"),
    Protocol:         vergeos.Ptr("tcp"),
    Direction:        vergeos.Ptr("incoming"),
    DestinationPorts: vergeos.Ptr("22"),
})
if err != nil {
    log.Fatal(err)
}

// Áp dụng các quy tắc
_ = client.Networks.ApplyRules(ctx, network.ID.Int())

Lọc tài nguyên

SDK hỗ trợ lọc linh hoạt với các tùy chọn danh sách:

Lọc cơ bản

// Lọc VM theo trạng thái nguồn (đang chạy)
vms, err := client.VMs.List(ctx,
    vergeos.WithFilter("powerstate eq true"),
)

Nhiều tùy chọn

// Kết hợp lọc, sắp xếp và phân trang
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),
)

Chọn trường

// Chỉ trả về các trường cụ thể (dùng $key cho trường ID)
vms, err := client.VMs.List(ctx,
    vergeos.WithFields("$key,name,powerstate,ram"),
)

Thao tác đồng thời

SDK an toàn với luồng và hỗ trợ các thao tác đồng thời bằng 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("Lỗi khi lấy VM %d: %v", vmID, err)
            return
        }
        status := "stopped"
        if vm.PowerState {
            status = "running"
        }
        fmt.Printf("VM: %s, Trạng thái nguồn: %s\n", vm.Name, status)
    }(id)
}
wg.Wait()

Hủy context

Tất cả các phương thức chấp nhận một context.Context, cho phép bạn đặt thời gian chờ và xử lý việc hủy cho các thao tác chạy lâu.

Xử lý lỗi

SDK cung cấp các kiểu lỗi cụ thể cho các điều kiện lỗi khác nhau:

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

vm, err := client.VMs.Get(ctx, 999)
if err != nil {
    if vergeos.IsNotFoundError(err) {
        fmt.Println("Không tìm thấy VM")
    } else if vergeos.IsAuthError(err) {
        fmt.Println("Xác thực thất bại")
    } else if vergeos.IsValidationError(err) {
        fmt.Println("Tham số yêu cầu không hợp lệ")
    } else {
        fmt.Printf("Lỗi không mong đợi: %v\n", err)
    }
}

Các kiểu lỗi có sẵn

Kiểu lỗi	Hàm trợ giúp	Mô tả
APIError	—	Lỗi cơ sở cho mọi lỗi API
AuthError	IsAuthError(err)	Thông tin xác thực không hợp lệ hoặc token đã hết hạn
NotFoundError	IsNotFoundError(err)	Tài nguyên được yêu cầu không tồn tại
ValidationError	IsValidationError(err)	Giá trị tham số không hợp lệ
UnsupportedVersionError	IsUnsupportedVersionError(err)	Phiên bản VergeOS không được hỗ trợ

Các trường hợp sử dụng phổ biến

• Tự động hóa hạ tầng: Cấp phát VM, mạng và lưu trữ bằng chương trình
• Các operator Kubernetes: Xây dựng các controller tùy chỉnh cho tài nguyên VergeOS
• Tích hợp CI/CD: Tạo và hủy môi trường thử nghiệm trong pipeline
• Công cụ giám sát: Truy vấn trạng thái tài nguyên và xây dựng dashboard tùy chỉnh
• Tự động hóa sao lưu: Lên lịch và quản lý snapshot cùng bản sao lưu đám mây
• Cấp phát đa thuê bao: Tự động hóa việc tạo tenant và phân bổ tài nguyên

Tài liệu và tài nguyên

Để có tài liệu đầy đủ, bao gồm tất cả các phương thức có sẵn và ví dụ sử dụng chi tiết, hãy truy cập kho lưu trữ chính thức:

• Kho lưu trữ GitHub
• Tài liệu gói Go

Hỗ trợ

Nếu bạn gặp sự cố hoặc có yêu cầu tính năng, vui lòng mở một issue trên kho lưu trữ GitHub:

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

Tài nguyên bổ sung

• Tài liệu Go
• Tài liệu API VergeOS
• SDK Python (pyvergeos) - Phương án thay thế Python
• Nhà cung cấp Terraform - Hạ tầng dưới dạng mã