protocol

package
v0.3.3 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 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"
	// MsgMetrics 快车道实时指标(2026-11-01):CPU / 网速 / 连接数 / 每用户速率,默认 3s 一帧。
	// 主控只有在 auth_ok 里声明 CapMetricsSplit 时节点才发;旧主控收不到也不影响旧路径
	// (节点仍把所有字段塞回 heartbeat,字节级行为不变)。
	MsgMetrics = "metrics"

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

	// 证书下发(内部账户 setup/rotate 已随 relay 模型一并退役,见 PROTOCOL.md)
	MsgPushCert  = "push_cert"  // 主控→节点:TLS 证书下发落盘
	MsgPushCA    = "push_ca"    // 主控→节点:CA 根证书下发落盘(出站 TLS 验签用,不含私钥)
	MsgSyncCerts = "sync_certs" // 主控→节点:证书目录 GC(只保留当前引用的托管证书)

	// 运维指令
	MsgUpgradeAgent    = "upgrade_agent"    // 主控→节点:升级 agent 二进制(自升级,见 internal/agent/upgrade)
	MsgUpgradeXray     = "upgrade_xray"     // 主控→节点:替换 node 上的 xray 内核二进制(停 xray → 校验 → 替换 → 拉起)
	MsgUpgradeProgress = "upgrade_progress" // 节点→主控:agent 升级进度状态上报
	MsgAgentSettings   = "agent_settings"   // 主控→节点:下发上报/心跳等运行时设置(0=保持不变)

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

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

View Source
const CapMetricsSplit = "metrics_split"

CapMetricsSplit 主控能力:支持 metrics 快车道(2026-11-01)。 节点只在 auth_ok 里看到该能力时才把实时字段从心跳里摘出去单独发送;否则维持 「所有字段 30s 心跳」的旧行为——这是本次拆分唯一的回滚开关。

View Source
const CapPushCA = "push_ca"

CapPushCA 节点能力:支持 push_ca 把 CA 根证书落盘。 主控只有在节点心跳声明该能力后,才会把出站 TLS 验签写成 certificates[].certificateFile(否则退回内联 PEM,保证旧 agent 可用)。

View Source
const CapSyncCerts = "sync_certs"

CapSyncCerts 节点能力:支持 sync_certs 清理不再被引用的托管证书目录。 主控只在节点声明该能力后下发 GC;旧 agent 忽略未知消息(不回帧),主控不会等它。

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"` // 状态心跳周期(秒)
	// MetricsIntervalSec 快车道实时指标周期(秒,2026-11-01)。旧 agent 忽略未知字段,
	// 继续按 yaml 的 metrics_interval(默认 3s)跑;0 = 保持现状。
	MetricsIntervalSec int `json:"metrics_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 ConnStatsPayload added in v0.3.0

type ConnStatsPayload struct {
	TCPEstablished int `json:"tcp_established"`
	TCPTotal       int `json:"tcp_total"`
	UDP            int `json:"udp"`
}

ConnStatsPayload 节点内核连接表快照。

TCPTotal 不含 LISTEN;UDP 是绑定 socket 数而不是会话数(一条 QUIC socket 承载多会话)。

type GetLogsPayload

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

GetLogsPayload 请求最近日志。

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 不上报)
	// Caps 节点能力声明(agent→主控):主控据此决定能否使用只在新 agent 上可行的配置形态。
	// 旧 agent 不发(nil);旧主控忽略未知字段。当前声明 CapPushCA 与 CapSyncCerts。
	Caps []string `json:"caps,omitempty"`
	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"`
	// XrayVersion 当前 xray 内核版本(如 "26.10.21")。旧 agent 不填、旧主控忽略未知字段。
	// 节点在启动与内核替换后探测并缓存,心跳只读缓存,不额外起进程。
	XrayVersion string `json:"xray_version,omitempty"`
	// XrayUnmanaged 使用本节点配置路径、但不是 agent 拉起的 xray 进程 PID。
	// 这类进程的 stdout/stderr 不经过 agent 管道,日志不会出现在 get_logs 里
	// (面板上表现为"节点没日志")。旧 agent 不填(nil)、旧主控忽略未知字段。
	XrayUnmanaged []int `json:"xray_unmanaged,omitempty"`
	// Conns 连接数快照(2026-11-01 新增,整机口径)。用指针区分「平台不支持/旧 agent 不上报」
	// 与「节点确实 0 连接」——旧 agent 不发该字段(nil),旧主控忽略未知字段。
	Conns *ConnStatsPayload `json:"conns,omitempty"`
}

HeartbeatPayload 心跳与节点状态(慢车道,默认 30s)。

2026-11-01 起按车道拆分:主控声明 CapMetricsSplit 时,CPU / RxRate / TxRate / RxBytes / TxBytes / Conns 改由 MetricsPayload 承载,本结构里这些字段不再填(旧主控 不会声明该能力,因此收到的仍是全集)。XrayRunning 是例外——两车道都填:主控靠它 判断「进程不在就清空在线名单」,缺字段会被反序列化成 false 而误清。

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 MetricsPayload added in v0.3.0

type MetricsPayload struct {
	CPU         float64 `json:"cpu"`
	RxRate      float64 `json:"rx_rate"`
	TxRate      float64 `json:"tx_rate"`
	RxBytes     uint64  `json:"rx_bytes"`
	TxBytes     uint64  `json:"tx_bytes"`
	XrayRunning bool    `json:"xray_running"`
	// Conns 整机连接数(同 HeartbeatPayload.Conns)。nil = 平台不支持(非 Linux)。
	Conns *ConnStatsPayload `json:"conns,omitempty"`
	// UserRates 每(用户, 入站)的瞬时速率:统计键 u<uid>.i<iid>@panel.local 携带两维,
	// 主控据此反解归属。只含在线用户(离线用户速率为 0、没有传输价值)。
	UserRates []UserRatePayload `json:"user_rates,omitempty"`
	TS        int64             `json:"ts"` // unix 秒
}

MetricsPayload 快车道实时指标(2026-11-01,节点→主控,默认 3s 一帧)。

只有主控在 auth_ok 里声明 CapMetricsSplit 时才会收到本帧;同一批字段届时不再在 HeartbeatPayload 里重复发送(`xray_running` 例外:慢车道保留,见 HeartbeatPayload)。 本帧可丢:每一帧都是全量快照,主控就地覆盖,丢一帧只损失一个采样点。

type OnlineUserIPs

type OnlineUserIPs struct {
	Email string   `json:"email"`
	IPs   []string `json:"ips,omitempty"`
	// IPLastSeen 每个 IP 最近一次建连/增连时刻(unix 秒,xray OnlineMap 的 lastSeen)。
	// 主控可用于展示「空闲多久」;旧主控忽略未知字段,旧 agent 不发。
	IPLastSeen map[string]int64 `json:"ip_last_seen,omitempty"`
}

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

type PushCAPayload added in v0.2.0

type PushCAPayload struct {
	ID      uint64 `json:"id"`
	Name    string `json:"name,omitempty"` // 仅用于日志/回执
	CertPEM string `json:"cert_pem"`
}

PushCAPayload 主控→节点:CA 根证书下发(只下发公钥,CA 私钥永不离开面板)。 节点落盘到 <certs_dir>/ca/<id>.crt;出站配置以 certificateFile 引用它做验签。

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 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 遗留)无此值
	// XrayVersion 当前 xray 内核版本(旧 agent 不填,旧主控忽略未知字段)
	XrayVersion string `json:"xray_version,omitempty"`
	// XrayBin 当前 xray 可执行文件路径
	XrayBin string `json:"xray_bin,omitempty"`
	// 启动失败可观测性(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 SyncCertsPayload added in v0.2.0

type SyncCertsPayload struct {
	Domains []string `json:"domains"`
}

SyncCertsPayload 主控→节点:证书目录 GC。Domains 是当前仍被引用的托管证书域名全集; 节点删除 <certs_dir> 下不在该集合中的托管证书目录(只删 push_cert 写出的布局,不碰其它文件)。

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"`
	// Kind 升级对象:空/agent(旧节点默认)| xray。旧主控忽略该字段,
	// 因此 agent 升级行为与既有语义完全一致。
	Kind string `json:"kind,omitempty"`
}

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

type UpgradeXrayPayload added in v0.2.0

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

UpgradeXrayPayload 主控→节点:替换 xray 内核二进制。 Target 为空 = 由节点查询 XTLS/Xray-core 最新 release;Force 为 true 时允许降级/同版本强制重装。

type User

type User struct {
	UUID  string `json:"uuid"`
	Email string `json:"email"`
	Flow  string `json:"flow,omitempty"`
	Level uint32 `json:"level,omitempty"`
	// 设备数限制字段已于 2026-10-27 下线(Xray 无按 IP/连接掐断能力,字段从未生效);
	// 旧主控若仍下发 limit,新节点按未知字段忽略。
	// CycleID 该用户当前账期 ID(≥1):节点收到与本地记录不同的值即视为发生周期切换,
	// 立刻做一次采集把切换前的增量按旧账期封账(见 TrafficEntry.CycleID)。
	// 0 = 旧主控未下发(节点不做切换处理,按未知账期上报)。
	CycleID uint64 `json:"cycle_id,omitempty"`
}

User 节点同步的用户信息。

type UserRatePayload added in v0.3.0

type UserRatePayload struct {
	Email string  `json:"email"` // u<uid>.i<iid>@panel.local
	Up    float64 `json:"up"`
	Down  float64 `json:"down"`
}

UserRatePayload 单个统计键的瞬时速率(字节/秒,两帧累计计数器之差 ÷ 真实帧间隔)。

Jump to

Keyboard shortcuts

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