central

README

Central - 云端 Central API

管理 ZeroTier Central 云端控制面板（api.zerotier.com）。

安装

import "github.com/topic-kit/sko-toolkit/zerotier/central"

获取 Token

1. 登录 my.zerotier.com
2. Account → 创建 API Token

快速开始

ctx := context.Background()
c := central.New("your_api_token")

networks, _ := c.Networks().List(ctx)
for _, n := range networks {
    fmt.Println(n.ID, n.Config.Name)
}

⚠️ v1.0.0 起所有方法都接受 context.Context 作为首参。

配置选项

c := central.New("token",
    central.WithBaseURL("https://api.zerotier.com/api/v1"),
    central.WithTimeout(30 * time.Second),
)

API

状态

status, _ := c.Status(ctx)
// status.APIVersion, status.User.DisplayName

网络

// 列表
networks, _ := c.Networks().List(ctx)

// 详情
network, _ := c.Networks().Get(ctx, "network_id")

// 创建
config := central.NewNetworkConfig().
    Name("My Network").
    Private(true).
    AddRoute("10.0.0.0/24", nil).
    AddIPPool("10.0.0.1", "10.0.0.254").
    V4AssignMode(true).
    Build()
c.Networks().Create(ctx, config)

// 更新
c.Networks().Update(ctx, "network_id", config)

// 删除
c.Networks().Delete(ctx, "network_id")

成员

// 列表
members, _ := c.Networks().Members("network_id").List(ctx)

// 授权
c.Networks().Members("network_id").Authorize(ctx, "member_id")

// 取消授权
c.Networks().Members("network_id").Deauthorize(ctx, "member_id")

// 更新
config := central.NewMemberConfig().
    Name("my-device").
    Authorized(true).
    IPAssignments("10.0.0.100").
    Build()
c.Networks().Members("network_id").Update(ctx, "member_id", config)

// 删除
c.Networks().Members("network_id").Delete(ctx, "member_id")

速率限制

• 付费用户：100 请求/秒
• 免费用户：20 请求/秒

Documentation

Overview

Package central 提供 ZeroTier Central API 的 Go 客户端

Index

• type AssignMode
• type CentralStatus
• type Client
  • func New(token string, opts ...Option) Client
• type CreateNetworkConfig
• type CreateNetworkRequest
• type DNS
• type IPAssignmentPool
• type Member
• type MemberConfig
• type MemberConfigBuilder
  • func NewMemberConfig() *MemberConfigBuilder
  • func (b *MemberConfigBuilder) ActiveBridge(v bool) *MemberConfigBuilder
  • func (b *MemberConfigBuilder) Authorized(v bool) *MemberConfigBuilder
  • func (b *MemberConfigBuilder) Build() *UpdateMemberRequest
  • func (b *MemberConfigBuilder) Description(desc string) *MemberConfigBuilder
  • func (b *MemberConfigBuilder) IPAssignments(ips ...string) *MemberConfigBuilder
  • func (b *MemberConfigBuilder) Name(name string) *MemberConfigBuilder
  • func (b *MemberConfigBuilder) NoAutoAssignIPs(v bool) *MemberConfigBuilder
• type MemberService
• type Network
• type NetworkConfig
• type NetworkConfigBuilder
  • func NewNetworkConfig() *NetworkConfigBuilder
  • func (b *NetworkConfigBuilder) AddIPPool(start, end string) *NetworkConfigBuilder
  • func (b *NetworkConfigBuilder) AddRoute(target string, via *string) *NetworkConfigBuilder
  • func (b *NetworkConfigBuilder) Build() *CreateNetworkConfig
  • func (b *NetworkConfigBuilder) DNS(domain string, servers ...string) *NetworkConfigBuilder
  • func (b *NetworkConfigBuilder) EnableBroadcast(v bool) *NetworkConfigBuilder
  • func (b *NetworkConfigBuilder) MTU(mtu int) *NetworkConfigBuilder
  • func (b *NetworkConfigBuilder) MulticastLimit(limit int) *NetworkConfigBuilder
  • func (b *NetworkConfigBuilder) Name(name string) *NetworkConfigBuilder
  • func (b *NetworkConfigBuilder) Private(v bool) *NetworkConfigBuilder
  • func (b *NetworkConfigBuilder) V4AssignMode(zt bool) *NetworkConfigBuilder
  • func (b *NetworkConfigBuilder) V6AssignMode(zt, rfc4193, n6plane bool) *NetworkConfigBuilder
• type NetworkService
• type Option
  • func WithBaseURL(url string) Option
  • func WithHTTPClient(hc *http.Client) Option
  • func WithTimeout(timeout time.Duration) Option
  • func WithToken(token string) Option
• type Route
• type StatusUser
• type UpdateMemberConfig
• type UpdateMemberRequest
• type User

Types

type AssignMode

type AssignMode struct {
	ZT      bool `json:"zt"`
	RFC4193 bool `json:"rfc4193,omitempty"`
	N6Plane bool `json:"6plane,omitempty"`
}

AssignMode IP 分配模式

type CentralStatus

type CentralStatus struct {
	ID           string          `json:"id"`
	Type         string          `json:"type"`
	Clock        int64           `json:"clock"`
	Version      string          `json:"version"`
	APIVersion   string          `json:"apiVersion"`
	Uptime       int64           `json:"uptime"`
	User         *StatusUser     `json:"user,omitempty"`
	ReadOnlyMode bool            `json:"readOnlyMode"`
	LoginMethods map[string]bool `json:"loginMethods"`
}

CentralStatus Central API 状态（包含当前用户信息）

type Client

type Client interface {
	// Status 获取 Central 状态（包含当前用户信息）
	Status(ctx context.Context) (*CentralStatus, error)
	// Networks 网络管理
	Networks() NetworkService
}

Client ZeroTier Central API 客户端接口

func New

func New(token string, opts ...Option) Client

New 创建新的 Central API 客户端

type CreateNetworkConfig

type CreateNetworkConfig struct {
	Name              string             `json:"name,omitempty"`
	Private           *bool              `json:"private,omitempty"`
	EnableBroadcast   *bool              `json:"enableBroadcast,omitempty"`
	MTU               *int               `json:"mtu,omitempty"`
	MulticastLimit    *int               `json:"multicastLimit,omitempty"`
	Routes            []Route            `json:"routes,omitempty"`
	IPAssignmentPools []IPAssignmentPool `json:"ipAssignmentPools,omitempty"`
	V4AssignMode      *AssignMode        `json:"v4AssignMode,omitempty"`
	V6AssignMode      *AssignMode        `json:"v6AssignMode,omitempty"`
	DNS               *DNS               `json:"dns,omitempty"`
}

CreateNetworkConfig 创建网络配置

type CreateNetworkRequest

type CreateNetworkRequest struct {
	Config *CreateNetworkConfig `json:"config"`
}

CreateNetworkRequest 创建网络请求

type DNS

type DNS struct {
	Domain  string   `json:"domain"`
	Servers []string `json:"servers"`
}

DNS 配置

type IPAssignmentPool

type IPAssignmentPool struct {
	IPRangeStart string `json:"ipRangeStart"`
	IPRangeEnd   string `json:"ipRangeEnd"`
}

IPAssignmentPool IP 分配池

type Member

type Member struct {
	ID                  string        `json:"id"`
	NetworkID           string        `json:"networkId"`
	NodeID              string        `json:"nodeId"`
	Name                string        `json:"name"`
	Description         string        `json:"description"`
	Config              *MemberConfig `json:"config"`
	LastOnline          int64         `json:"lastOnline"`
	LastSeen            int64         `json:"lastSeen"`
	PhysicalAddress     string        `json:"physicalAddress"`
	ClientVersion       string        `json:"clientVersion"`
	ProtocolVersion     int           `json:"protocolVersion"`
	SupportsRulesEngine bool          `json:"supportsRulesEngine"`
}

Member 网络成员

type MemberConfig

type MemberConfig struct {
	Authorized      bool     `json:"authorized"`
	ActiveBridge    bool     `json:"activeBridge"`
	NoAutoAssignIPs bool     `json:"noAutoAssignIps"`
	CreationTime    int64    `json:"creationTime"`
	IPAssignments   []string `json:"ipAssignments"`
	SSOExempt       bool     `json:"ssoExempt"`
}

MemberConfig 成员配置

type MemberConfigBuilder

type MemberConfigBuilder struct {
	// contains filtered or unexported fields
}

MemberConfigBuilder 成员配置构建器

func NewMemberConfig

func NewMemberConfig() *MemberConfigBuilder

NewMemberConfig 创建成员配置构建器

func (*MemberConfigBuilder) ActiveBridge

func (b *MemberConfigBuilder) ActiveBridge(v bool) *MemberConfigBuilder

ActiveBridge 设置是否为活动桥接

func (*MemberConfigBuilder) Authorized

func (b *MemberConfigBuilder) Authorized(v bool) *MemberConfigBuilder

Authorized 设置是否授权

func (*MemberConfigBuilder) Build

func (b *MemberConfigBuilder) Build() *UpdateMemberRequest

Build 构建配置

func (*MemberConfigBuilder) Description

func (b *MemberConfigBuilder) Description(desc string) *MemberConfigBuilder

Description 设置成员描述

func (*MemberConfigBuilder) IPAssignments

func (b *MemberConfigBuilder) IPAssignments(ips ...string) *MemberConfigBuilder

IPAssignments 设置 IP 分配

func (*MemberConfigBuilder) Name

func (b *MemberConfigBuilder) Name(name string) *MemberConfigBuilder

Name 设置成员名称

func (*MemberConfigBuilder) NoAutoAssignIPs

func (b *MemberConfigBuilder) NoAutoAssignIPs(v bool) *MemberConfigBuilder

NoAutoAssignIPs 设置是否禁用自动 IP 分配

type MemberService

type MemberService interface {
	// List 列出网络所有成员
	List(ctx context.Context) ([]Member, error)
	// Get 获取成员详情
	Get(ctx context.Context, memberID string) (*Member, error)
	// Update 更新成员配置
	Update(ctx context.Context, memberID string, req *UpdateMemberRequest) (*Member, error)
	// Authorize 授权成员
	Authorize(ctx context.Context, memberID string) (*Member, error)
	// Deauthorize 取消授权
	Deauthorize(ctx context.Context, memberID string) (*Member, error)
	// Delete 删除成员
	Delete(ctx context.Context, memberID string) error
	// SetName 设置成员昵称
	SetName(ctx context.Context, memberID string, name string) (*Member, error)
	// SetDescription 设置成员描述
	SetDescription(ctx context.Context, memberID string, description string) (*Member, error)
	// SetIPAssignments 设置成员 IP 地址
	SetIPAssignments(ctx context.Context, memberID string, ips []string) (*Member, error)
}

MemberService 成员管理服务接口

type Network

type Network struct {
	ID                    string         `json:"id"`
	Clock                 int64          `json:"clock"`
	Config                *NetworkConfig `json:"config"`
	Description           string         `json:"description"`
	RulesSource           string         `json:"rulesSource"`
	OwnerID               string         `json:"ownerId"`
	OnlineMemberCount     int            `json:"onlineMemberCount"`
	AuthorizedMemberCount int            `json:"authorizedMemberCount"`
	TotalMemberCount      int            `json:"totalMemberCount"`
	CapabilitiesByName    map[string]int `json:"capabilitiesByName"`
	TagsByName            map[string]int `json:"tagsByName"`
}

Network 网络信息

type NetworkConfig

type NetworkConfig struct {
	ID                string             `json:"id"`
	Name              string             `json:"name"`
	Private           bool               `json:"private"`
	CreationTime      int64              `json:"creationTime"`
	LastModified      int64              `json:"lastModified"`
	EnableBroadcast   bool               `json:"enableBroadcast"`
	MTU               int                `json:"mtu"`
	MulticastLimit    int                `json:"multicastLimit"`
	Routes            []Route            `json:"routes"`
	IPAssignmentPools []IPAssignmentPool `json:"ipAssignmentPools"`
	V4AssignMode      *AssignMode        `json:"v4AssignMode"`
	V6AssignMode      *AssignMode        `json:"v6AssignMode"`
	DNS               *DNS               `json:"dns,omitempty"`
}

NetworkConfig 网络配置

type NetworkConfigBuilder

type NetworkConfigBuilder struct {
	// contains filtered or unexported fields
}

NetworkConfigBuilder 网络配置构建器

func NewNetworkConfig

func NewNetworkConfig() *NetworkConfigBuilder

NewNetworkConfig 创建网络配置构建器

func (*NetworkConfigBuilder) AddIPPool

func (b *NetworkConfigBuilder) AddIPPool(start, end string) *NetworkConfigBuilder

AddIPPool 添加 IP 分配池

func (*NetworkConfigBuilder) AddRoute

func (b *NetworkConfigBuilder) AddRoute(target string, via *string) *NetworkConfigBuilder

AddRoute 添加路由

func (*NetworkConfigBuilder) Build

func (b *NetworkConfigBuilder) Build() *CreateNetworkConfig

Build 构建配置

func (*NetworkConfigBuilder) DNS

func (b *NetworkConfigBuilder) DNS(domain string, servers ...string) *NetworkConfigBuilder

DNS 设置 DNS

func (*NetworkConfigBuilder) EnableBroadcast

func (b *NetworkConfigBuilder) EnableBroadcast(v bool) *NetworkConfigBuilder

EnableBroadcast 设置是否启用广播

func (*NetworkConfigBuilder) MTU

func (b *NetworkConfigBuilder) MTU(mtu int) *NetworkConfigBuilder

MTU 设置 MTU

func (*NetworkConfigBuilder) MulticastLimit

func (b *NetworkConfigBuilder) MulticastLimit(limit int) *NetworkConfigBuilder

MulticastLimit 设置多播限制

func (*NetworkConfigBuilder) Name

func (b *NetworkConfigBuilder) Name(name string) *NetworkConfigBuilder

Name 设置网络名称

func (*NetworkConfigBuilder) Private

func (b *NetworkConfigBuilder) Private(v bool) *NetworkConfigBuilder

Private 设置是否私有网络

func (*NetworkConfigBuilder) V4AssignMode

func (b *NetworkConfigBuilder) V4AssignMode(zt bool) *NetworkConfigBuilder

V4AssignMode 设置 IPv4 分配模式

func (*NetworkConfigBuilder) V6AssignMode

func (b *NetworkConfigBuilder) V6AssignMode(zt, rfc4193, n6plane bool) *NetworkConfigBuilder

V6AssignMode 设置 IPv6 分配模式

type NetworkService

type NetworkService interface {
	// List 列出所有网络
	List(ctx context.Context) ([]Network, error)
	// Get 获取网络详情
	Get(ctx context.Context, networkID string) (*Network, error)
	// Create 创建新网络
	Create(ctx context.Context, config *CreateNetworkConfig) (*Network, error)
	// Update 更新网络配置
	Update(ctx context.Context, networkID string, config *CreateNetworkConfig) (*Network, error)
	// Delete 删除网络
	Delete(ctx context.Context, networkID string) error
	// Members 获取成员服务
	Members(networkID string) MemberService
}

NetworkService 网络管理服务接口

type Option

type Option func(*client)

Option 客户端配置选项

func WithBaseURL

func WithBaseURL(url string) Option

WithBaseURL 设置 API 地址

func WithHTTPClient

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient 自定义 HTTP 客户端

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout 设置请求超时

func WithToken

func WithToken(token string) Option

WithToken 设置 API Token

type Route

type Route struct {
	Target string  `json:"target"`
	Via    *string `json:"via,omitempty"`
}

Route 路由配置

type StatusUser

type StatusUser struct {
	ID          string `json:"id"`
	OrgID       string `json:"orgId"`
	DisplayName string `json:"displayName"`
	SMSNumber   string `json:"smsNumber,omitempty"`
}

StatusUser 状态中的用户信息

type UpdateMemberConfig

type UpdateMemberConfig struct {
	Authorized      *bool    `json:"authorized,omitempty"`
	ActiveBridge    *bool    `json:"activeBridge,omitempty"`
	NoAutoAssignIPs *bool    `json:"noAutoAssignIps,omitempty"`
	IPAssignments   []string `json:"ipAssignments,omitempty"`
}

UpdateMemberConfig 更新成员配置

type UpdateMemberRequest

type UpdateMemberRequest struct {
	Name        string              `json:"name,omitempty"`
	Description string              `json:"description,omitempty"`
	Config      *UpdateMemberConfig `json:"config,omitempty"`
}

UpdateMemberRequest 更新成员请求

type User

type User struct {
	ID                string            `json:"id"`
	OrgID             string            `json:"orgId"`
	GlobalPermissions map[string]bool   `json:"globalPermissions"`
	DisplayName       string            `json:"displayName"`
	Email             string            `json:"email"`
	Auth              map[string]string `json:"auth,omitempty"`
	SMSNumber         string            `json:"smsNumber,omitempty"`
	Tokens            []string          `json:"tokens,omitempty"`
}

User 用户信息（完整）