stats

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: AGPL-3.0 Imports: 20 Imported by: 0

Documentation

Overview

Package stats 通过 Xray gRPC StatsService 采集用户流量,并支持 HandlerService 动态更新用户。 实现模型对照《xray-api-探索.md》§4(3x-ui GetTraffic 轮询模式): QueryStats 全量拉取 → 维护 last 基线 → 差值 = 本周期增量(xray 重启归零视为 0)。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Collector

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

Collector 采集 Xray stats 并通过 HandlerService 动态同步用户。

func New

func New(apiAddr string) *Collector

New 构造采集器(apiAddr 如 127.0.0.1:10085)。

func (*Collector) Close

func (c *Collector) Close()

Close 关闭连接。

func (*Collector) CloseOnline added in v0.1.19

func (c *Collector) CloseOnline()

CloseOnline 关闭在线拉取专用连接(拉取循环退出时调用)。

func (*Collector) Collect

func (c *Collector) Collect(ctx context.Context) ([]Entry, error)

Collect 拉取全量计数器并返回自上次以来的流量增量(用户维度 + 入站维度两个计数器族)。 若 xray 未运行/连接失败返回 error,由调用方决定重连。

func (*Collector) OnlineForHeartbeat added in v0.1.19

func (c *Collector) OnlineForHeartbeat(xrayRunning bool) (int, []OnlineUser)

OnlineForHeartbeat 心跳帧的在线快照读取:只读内存,不做任何 gRPC。 快照由后台拉取循环(RefreshOnlineOnce,随心跳周期节拍)持续刷新并原子发布; 心跳读内存 = 零 RPC、零阻塞,xray API 慢不再拖住心跳发送,也不会与计费采集/ 用户同步抢 Collector.mu(锁内 gRPC 曾把消息循环最长卡住 8–13s)。

容错链:xray 未运行 → OnlineMap 随进程消失必为空,发布空快照并直接返回; 无任何成功快照 → 返回空;快照距上次成功刷新超过 maxOnlineStale(xray 卡死、 拉取持续失败)→ 返回空,防止心跳无限携带冻结的旧名单。 返回的切片是已发布不可变快照的一部分,调用方只读、不得修改。

func (*Collector) RefreshOnlineOnce added in v0.1.19

func (c *Collector) RefreshOnlineOnce()

RefreshOnlineOnce 拉取一次 GetUsersStats 并原子发布新快照(由后台拉取循环按心跳周期调用)。 成功 → 发布新快照;失败 → 沿用旧快照(瞬时抖动不让在线数闪跳为 0),限频记日志。 只允许单个后台 goroutine 串行调用(专用连接无并发保护)。

func (*Collector) SampleRates added in v0.3.0

func (c *Collector) SampleRates(ctx context.Context) []RateSample

SampleRates 采样每个在线用户的瞬时上下行速率(2026-11-01,快车道专用)。

与 Collect 的三条硬边界:

  • **不复用 Collect 的基线与锁**:那边每消费一次就推进 c.last,被第二方读一次就吃掉 计费增量(漏账)。这里自带 rateLast/rateAt 与专用 gRPC 连接,计费链路零影响。
  • **只读**:QueryStats 固定 Reset_=false,绝不清零 xray 计数器。
  • **采集范围 = 在线用户 ∪ 本帧有增量的用户**:在线名单来自后台在线快照(零额外 RPC), 让空闲但仍在线的用户保留一行 0 速率、面板不闪烁;同时并入本帧计数器有增量的用户, 因为 xray 的 OnlineMap 明确忽略回环地址(app/stats/online_map.go 的 AddIP 对 127.0.0.1/[::1] 直接 return),纯本机联调/回环转发的场景在线名单恒为空——只看在线 名单会让「明明在跑流量却一条速率都没有」。快照超龄(xray 卡死)时按空集处理, 仍由增量提供数据,宁可少一行也不给冻结读数。

速率 = (本次累计值 − 上次累计值) ÷ 两次采样的真实间隔。首帧只建基线;计数器新出现或 xray 重启归零(值变小)时本帧记 0 并重建基线,避免把历史总量当成一秒的流量。 调用方必须串行(metricsLoop 单 goroutine)。

func (*Collector) SeedUsers added in v0.1.17

func (c *Collector) SeedUsers(configJSON []byte) error

SeedUsers 按一份 xray 配置重建内存用户缓存(不变量 I5:缓存恒等于运行中 xray 的用户集)。

为什么是「重建」而不是「清空」:缓存是移除操作的唯一依据(SyncUsers 的移除分支只遍历它), 而 xray 每次从磁盘配置启动(冷更 / 回滚 / 崩溃自愈 / 慢探底 / 开机 / 手动重启)都会换掉 自己的用户集。旧实现只清空缓存,于是紧随其后的第一次同步一个都摘不掉;更糟的是添加分支 会把 payload 回填进缓存,分歧从此对后续每一次同步都不可见(被删 / 被封 / 超量 / 过期的 用户能一直用到下一次冷更,最长 1h)。见 docs/architecture/配置下发-热更冷更与状态机.md §1.2。

解析失败时保留原缓存并返回错误:清空正是要修的那个 bug,宁可沿用旧视图也不能留空。

func (*Collector) SeedUsersFromFile added in v0.1.17

func (c *Collector) SeedUsersFromFile(path string) error

SeedUsersFromFile 读取配置并重建缓存(xray 已按该文件启动时使用)。

func (*Collector) SyncUsers

func (c *Collector) SyncUsers(ctx context.Context, targetUsers map[string][]protocol.User) error

SyncUsers 通过 gRPC HandlerService 增量调整 Xray 中的用户。

type Entry

type Entry struct {
	Email   string
	Inbound string
	Up      int64
	Down    int64
}

Entry 单条流量增量(用户维度 Email / 入站维度 Inbound 二选一)。

type OnlineUser

type OnlineUser struct {
	Email string
	IPs   []string
	// LastSeen 每个 IP 最近一次建连时刻(unix 秒,透传 xray OnlineMap 的 lastSeen)。
	LastSeen map[string]int64
}

OnlineUser 单个用户的在线快照:当前活跃连接的去重源 IP 列表。

type RateSample added in v0.3.0

type RateSample struct {
	Email string
	Up    float64
	Down  float64
}

RateSample 单个统计键的瞬时速率(字节/秒)。

Jump to

Keyboard shortcuts

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