protocol

package
v0.1.17 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 21, 2026 License: AGPL-3.0 Imports: 3 Imported by: 0

Documentation

Overview

Package protocol 定义主控-节点通信协议(主控与 Agent 共用)。

传输:WebSocket(生产 wss 由用户自备反代终止 TLS 后以明文 ws 转发给主控,主控恒监听 ws)。 消息:JSON 文本帧,{type, id, payload},请求-响应用 id 配对。

Index

Constants

View Source
const (
	// 节点 → 主控
	MsgAuth          = "auth"
	MsgHeartbeat     = "heartbeat"
	MsgTrafficReport = "traffic_report"
	MsgResult        = "result"

	// 主控 → 节点
	MsgPushConfig  = "push_config"
	MsgSyncUsers   = "sync_users"
	MsgRestartXray = "restart_xray"
	MsgGetStatus   = "get_status"
	MsgGetLogs     = "get_logs"
	// MsgTrafficAck 主控→节点:流量批次落库回执(审计 F1)。节点收到 ok=true 才删本地批次;
	// 未收到(写库失败/主控崩溃/回执丢失)则保留重发,由主控侧 BatchID 去重兜住重复投递。
	MsgTrafficAck = "traffic_ack"

	// Phase T:内部账户与证书
	MsgSetupInternalAccount  = "setup_internal_account"  // 主控→节点:为 relay 入站生成内部 UUID
	MsgRotateInternalAccount = "rotate_internal_account" // 主控→节点:重新生成内部 UUID
	MsgPushCert              = "push_cert"               // 主控→节点:TLS 证书下发落盘
	MsgInternalUUIDReport    = "internal_uuid_report"    // 节点→主控:内部 UUID 变更主动上报(主控侧已实现接收;agent 当前不发,保留备用)

	// 运维指令
	MsgUpgradeAgent    = "upgrade_agent"    // 主控→节点:升级 agent 二进制(自升级,见 internal/agent/upgrade)
	MsgUpgradeProgress = "upgrade_progress" // 节点→主控:agent 升级进度状态上报
	MsgAgentSettings   = "agent_settings"   // 主控→节点:下发上报/心跳等运行时设置(0=保持不变)

	// 认证握手结果(主控→节点,首条 auth 消息的应答帧类型)
	MsgAuthOK  = "auth_ok"
	MsgAuthBad = "bad_auth"
)

消息类型常量(与《系统设计方案》§4.3 对齐)。

View Source
const CapTrafficAck = "traffic_ack"

CapTrafficAck 主控能力:流量批次落库回执 + BatchID 去重(见 AuthOKPayload.Caps)。

Variables

This section is empty.

Functions

func Encode

func Encode(typ, id string, payload any) ([]byte, error)

Encode 编码消息帧。

Types

type AgentSettingsPayload

type AgentSettingsPayload struct {
	ReportIntervalSec    int `json:"report_interval_sec,omitempty"`    // 流量上报周期(秒)
	HeartbeatIntervalSec int `json:"heartbeat_interval_sec,omitempty"` // 状态心跳周期(秒)
}

AgentSettingsPayload 主控→节点:运行时设置(连接建立与设置保存时下发,仅当前会话生效, 不写回 agent.yaml;字段为 0 表示保持现状)。agent.yaml 仍是主控未下发时的兜底。

type AuthOKPayload

type AuthOKPayload struct {
	OK   bool     `json:"ok"`
	Caps []string `json:"caps,omitempty"`
}

AuthOKPayload 主控→节点:认证成功回执。

Caps 声明主控支持的可选能力,是**双向兼容的关键**:节点只有在 Caps 里看到 CapTrafficAck 时才进入「等回执才删批」模式。旧主控(回执只有 ok,无 caps)下节点 降级为发完即删——否则未确认批次会每轮重发,而旧主控小时桶 upsert 是加法且无批次去重, 同一批流量会被反复累加到用户账上。

func (AuthOKPayload) HasCap

func (p AuthOKPayload) HasCap(cap string) bool

HasCap 主控是否声明支持某能力(nil Caps = 旧主控)。

type AuthPayload

type AuthPayload struct {
	NodeID string `json:"node_id"`
	Secret string `json:"secret"`
}

AuthPayload 节点认证(node_secret 不放入 URL,避免日志泄露)。

type GetLogsPayload

type GetLogsPayload struct {
	Lines int `json:"lines"`
}

GetLogsPayload 请求最近日志。

type GetStatusPayload

type GetStatusPayload struct{}

GetStatusPayload 查询完整状态。

type HeartbeatPayload

type HeartbeatPayload struct {
	CPU         float64         `json:"cpu"`                  // 百分比
	Mem         float64         `json:"mem"`                  // 已用内存(字节)
	MemTotal    float64         `json:"mem_total"`            // 总内存(字节)
	Disk        float64         `json:"disk"`                 // 已用磁盘(字节)
	DiskTotal   float64         `json:"disk_total"`           // 总磁盘(字节)
	XrayRunning bool            `json:"xray_running"`         // xray 是否在运行
	OnlineUsers int             `json:"online_users"`         // 在线用户数(当前活跃连接的去重用户)
	OnlineIPs   []OnlineUserIPs `json:"online_ips,omitempty"` // 每用户在线连接源 IP 快照(xray OnlineMap)
	RxRate      float64         `json:"rx_rate"`              // 实时速率(字节/秒)
	TxRate      float64         `json:"tx_rate"`
	RxBytes     uint64          `json:"rx_bytes"`          // 累计物理网卡接收字节
	TxBytes     uint64          `json:"tx_bytes"`          // 累计物理网卡发送字节
	Version     string          `json:"version,omitempty"` // agent 版本(旧 agent 不上报)
	TS          int64           `json:"ts"`                // unix 秒
	// 启动失败可观测性(2026-09-21):xray 起不来时把状态与原因带回主控,
	// 面板不再只看到"未运行"却不知道为什么。旧主控忽略未知字段、旧 agent 不发(字段为空)。
	XrayState     string `json:"xray_state,omitempty"`            // running / restarting / failed / stopped
	XrayLastError string `json:"xray_last_error,omitempty"`       // 最近一次启动失败原因(已截断)
	XrayErrorAt   int64  `json:"xray_error_at,omitempty"`         // 该原因的观测时刻(unix 秒)
	XrayFailures  int    `json:"xray_restart_failures,omitempty"` // 连续启动失败次数
	// 配置对账(2026-09-21,旧主控忽略未知字段):DiskHash = 磁盘配置内容哈希;
	// RunningHash = 本进程最后一次成功启动时那份配置的哈希(xray 只在启动时读一次配置,
	// 热更落盘只改磁盘、不改这个值)。主控拿 RunningHash 判断节点跑的是不是它以为的配置,
	// 拿 DiskHash 判断磁盘是否与它记录的一致。
	DiskHash    string `json:"disk_hash,omitempty"`
	RunningHash string `json:"running_hash,omitempty"`
}

HeartbeatPayload 心跳与节点状态。

type InternalUUIDReportPayload

type InternalUUIDReportPayload struct {
	Tag  string `json:"tag"`
	UUID string `json:"uuid"`
}

InternalUUIDReportPayload 节点→主控:内部 UUID 变更主动上报(如 CLI 轮换)。 主控侧已实现接收;agent 当前不发(内部 UUID 经 SetupInternalResult 回执承载),保留备用。

type Message

type Message struct {
	Type    string          `json:"type"`
	ID      string          `json:"id,omitempty"` // 请求 ID,result 回执时回填
	Payload json.RawMessage `json:"payload,omitempty"`
}

Message 为统一消息帧。

func Decode

func Decode(data []byte) (*Message, error)

Decode 解码消息帧。

func (*Message) PayloadTo

func (m *Message) PayloadTo(v any) error

Payload 解析消息负载到 v。

type OnlineUserIPs

type OnlineUserIPs struct {
	Email string   `json:"email"`
	IPs   []string `json:"ips,omitempty"`
}

OnlineUserIPs 单个用户当前活跃连接的去重源 IP(refcount 快照,连接断开即移除; 127.0.0.1/::1 不计入)。

type PushCertPayload

type PushCertPayload struct {
	Domain  string `json:"domain"`
	CertPEM string `json:"cert_pem"`
	KeyPEM  string `json:"key_pem"`
}

PushCertPayload 主控→节点:TLS 证书下发(agent 校验 PEM 匹配后落盘)。

type PushConfigPayload

type PushConfigPayload struct {
	ConfigJSON string `json:"config_json"`
}

PushConfigPayload 下发 Xray 配置(P1 为完整 config JSON 透传, 模板生成器放 P3/P5)。

type ResultPayload

type ResultPayload struct {
	OK    bool   `json:"ok"`
	Error string `json:"error,omitempty"`
	Data  any    `json:"data,omitempty"`
}

ResultPayload 指令回执(id 回填请求 ID)。

type SetupInternalAccountPayload

type SetupInternalAccountPayload struct {
	Tag string `json:"tag"`
}

SetupInternalAccountPayload 主控→节点:为 relay 入站生成(或轮换)内部 UUID。

type SetupInternalResult

type SetupInternalResult struct {
	Tag  string `json:"tag"`
	UUID string `json:"uuid"`
}

SetupInternalResult setup/rotate 回执 data(uuid 由节点生成,主控以此覆盖 DB)。

type StatusData

type StatusData struct {
	XrayRunning bool       `json:"xray_running"`
	Pid         int        `json:"pid,omitempty"`
	UptimeSec   int64      `json:"uptime_sec,omitempty"`
	ConfigPath  string     `json:"config_path,omitempty"`
	StartedAt   *time.Time `json:"started_at,omitempty"` // 未托管实例(上一轮 agent 遗留)无此值
	// 启动失败可观测性(2026-09-21,旧主控忽略未知字段)
	XrayState     string `json:"xray_state,omitempty"`
	XrayLastError string `json:"xray_last_error,omitempty"`
	XrayFailures  int    `json:"xray_restart_failures,omitempty"`
	// 配置对账(2026-09-21,旧主控忽略未知字段):DiskHash = 磁盘上配置内容的 SHA-256;
	// RunningHash = 本进程最后一次成功启动时那份配置的 SHA-256。两者不一致 = 磁盘被改过
	// 但没重启(xray 只在启动时读一次配置,运行中改盘上文件对它零影响);主控再拿
	// RunningHash 与它记录的已生效内容比对,即可判断节点跑的是不是它以为的那份配置。
	DiskHash    string `json:"disk_hash,omitempty"`
	RunningHash string `json:"running_hash,omitempty"`
}

StatusData Agent 返回的完整状态。

type SyncUsersPayload

type SyncUsersPayload struct {
	Users map[string][]User `json:"users"`
	// ConfigJSON 可选:主控在节点处于「无待生效结构」时附带一份完整配置(= 运行中结构的
	// 快照 + 本帧用户集),节点在 gRPC 热更成功后把它落盘,让磁盘与运行中的用户集保持一致
	// (不变量 I2),节点重启不会把用户集回退到上一次冷更。
	//
	// 老 agent 忽略未知字段 ⇒ 自动退化成「只热更不落盘」,与旧行为一致,无需能力协商。
	// 顺序约定:节点必须先热更后落盘——-test 比 gRPC 严格,先落盘会把「热更得过、-test
	// 不过」的内容留在磁盘上,节点一重启就起不来。
	ConfigJSON string `json:"config_json,omitempty"`
}

SyncUsersPayload 全量用户同步负载(InboundTag -> []User)。

type TrafficAckPayload

type TrafficAckPayload struct {
	BatchID string `json:"batch_id"`
	OK      bool   `json:"ok"`
	Error   string `json:"error,omitempty"`
}

TrafficAckPayload 主控→节点:流量批次落库回执(审计 F1)。 节点只在收到 ok=true 后删除本地 outbox 中的该批次;未收到回执(主控写库失败、 主控崩溃、回执丢失、连接断开)时保留并重发,由主控侧 BatchID 去重兜住重复投递。

type TrafficEntry

type TrafficEntry struct {
	UserID    uint64 `json:"user_id"`
	Email     string `json:"email,omitempty"`
	Inbound   string `json:"inbound,omitempty"`
	UpBytes   int64  `json:"up_bytes"`
	DownBytes int64  `json:"down_bytes"`
	// CycleID 账期 ID:本条增量所属的用户计费周期(主控经 sync_users 下发,节点在
	// **采集时刻**打标)。切换周期(购买/续费/重置)时主控递增该用户的 cycle_id 并立即
	// 推送新名单,节点据此把切换前已采集的增量按旧账期结算、切换后的按新账期——
	// 消费归属因此不再依赖上报时刻(Period),旧套餐消费不会落到新套餐头上(审计 F3)。
	// 0 = 未知(旧 agent 未打标 / 入站维度条目无用户账期):主控回退按 period_start 归属。
	CycleID uint64 `json:"cycle_id,omitempty"`
}

TrafficEntry 单条流量记录。两个维度互斥: 用户维度——Email 填邮箱(UserID=0 时主控按 Email 匹配用户),落 traffic_logs; 入站维度——Inbound 填入站 tag 且 Email 留空,主控仅累计 inbounds.up/down 冗余计数器 (dashboard 节点流量占比/入站限额消费),不落用户流水防 KPI 双计(2026-09-01 接通)。

type TrafficReportPayload

type TrafficReportPayload struct {
	Entries []TrafficEntry `json:"entries"`
	Period  string         `json:"period"` // 上报周期起始,RFC3339
	// BatchID 批次唯一标识(UUID):同一批数据重发必须复用同一 ID,主控据此去重
	// (审计 F2:小时桶 upsert 是加法,无批次去重时重发会翻倍计量)。
	// 空 = 旧 agent:主控不做去重、不回 ACK(维持旧行为)。
	BatchID string `json:"batch_id,omitempty"`
	// Seq 批次序号(跨重启单调递增):与 BootID 合用于运维判缺口——同一 BootID 内 Seq
	// 跳号即节点侧丢了批次。不参与去重(去重键只有 BatchID)。
	Seq uint64 `json:"seq,omitempty"`
	// BootID 本次 agent 进程启动的随机标识:Seq 只在同一 BootID 内有缺口语义。
	BootID string `json:"boot_id,omitempty"`
}

TrafficReportPayload 流量批量上报(P2 使用)。

type UpgradeAgentPayload

type UpgradeAgentPayload struct {
	Target string `json:"target,omitempty"`
	Force  bool   `json:"force,omitempty"`
}

UpgradeAgentPayload 主控→节点:升级/回滚 agent 二进制。Target 为空 = 拉取最新 release;Force 为 true = 忽略版本高低强制覆盖(回滚)。

type UpgradeProgressPayload

type UpgradeProgressPayload struct {
	Phase   string `json:"phase"` // starting | checking | downloading | verifying | replacing | restarting | failed | success
	Target  string `json:"target,omitempty"`
	Message string `json:"message"`
	Error   string `json:"error,omitempty"`
	TS      int64  `json:"ts"`
}

UpgradeProgressPayload 节点→主控:升级进度上报。

type User

type User struct {
	UUID  string `json:"uuid"`
	Email string `json:"email"`
	Flow  string `json:"flow,omitempty"`
	Level uint32 `json:"level,omitempty"`
	Limit int    `json:"limit,omitempty"` // 最大在线设备数限制
	// CycleID 该用户当前账期 ID(≥1):节点收到与本地记录不同的值即视为发生周期切换,
	// 立刻做一次采集把切换前的增量按旧账期封账(见 TrafficEntry.CycleID)。
	// 0 = 旧主控未下发(节点不做切换处理,按未知账期上报)。
	CycleID uint64 `json:"cycle_id,omitempty"`
}

User 节点同步的用户信息。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL