outbox

package
v0.1.15 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: 7 Imported by: 0

Documentation

Overview

Package outbox 实现节点流量上报的本地持久化发件箱(审计 F1)。

解决什么问题:原实现把待上报流量放在内存 map 里,reportPending 发送前先清空、仅当 WebSocket 写失败才放回,且主控收到报文后不回复执。于是「主控写库失败 / 主控在提交前退出 / 回执丢失」这三种情况都会让这批消费永久消失(xray 采集基线已推进,下一轮增量不会重报)。

本包提供的是**至少一次投递**的持久化侧:

  • 采集到的增量先落盘成不可变批次(每个批次一个 UUID,重发复用同一 ID);
  • 只有收到主控 traffic_ack(ok=true) 才删批;
  • 进程重启后从磁盘恢复未确认批次,重连继续发。

幂等由主控侧承担:同一 BatchID 重复投递会被去重(见主控 traffic_batches 表)。 因此本包只保证「不丢」,不保证「不重」——重复是正常恢复路径,不是错误。

文件格式与 accounts.Store 同风格:JSON + 临时文件 rename 原子替换 + 权限 600。 损坏文件不静默覆盖:改名隔离为 .corrupt-<ts> 后以空发件箱继续(保留现场供排查), 因为「拒绝启动」会让节点彻底停止上报,比丢一批更糟。

Index

Constants

View Source
const (
	DefaultMaxAge     = 7 * 24 * time.Hour
	DefaultMaxBatches = 20000
)

默认阈值(构造时可覆盖,见 SetLimits)。

Variables

This section is empty.

Functions

This section is empty.

Types

type Batch

type Batch struct {
	ID        string    `json:"id"`
	Seq       uint64    `json:"seq"`
	BootID    string    `json:"boot_id"`
	CreatedAt time.Time `json:"created_at"`
	Entries   []Entry   `json:"entries"`
}

Batch 一个不可变批次。创建后 Entries 不再变动(新数据进新批次)——这是去重成立的前提: 同一 BatchID 在两次投递之间内容必须一致,否则主控按 ID 去重会丢掉后加的部分。

func (Batch) Down

func (b Batch) Down() int64

func (Batch) Up

func (b Batch) Up() int64

Up/Down 批次字节合计(用于日志与主控侧去重记录)。

type Entry

type Entry struct {
	Email   string `json:"email,omitempty"`
	Inbound string `json:"inbound,omitempty"`
	Up      int64  `json:"up"`
	Down    int64  `json:"down"`
	// CycleID 采集时刻的账期 ID(0 = 未知)。随批次一起持久化:重发时仍是原账期,
	// 不会因为重发时刻用户的账期已切换而被算到新账期头上。
	CycleID uint64 `json:"cycle_id,omitempty"`
}

Entry 批次内的一条流量增量(与 protocol.TrafficEntry 同构,刻意不依赖 protocol 包: 落盘格式独立于协议演进,协议加字段不会让旧文件读不出来)。

type Outbox

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

Outbox 持久化发件箱(并发安全)。

func New

func New(path string) *Outbox

New 创建发件箱(path 由 agent 配置注入,默认 /etc/xray-agent/traffic_outbox.json)。 path 为空 = 纯内存模式(不落盘):仅供测试与「未配置路径」的降级运行,生产必须给路径。

func (*Outbox) Ack

func (o *Outbox) Ack(batchID string) (bool, error)

Ack 确认并删除某批次(主控回执 ok=true 时调用)。返回是否命中。 落盘失败时不从内存删除(宁可下次重发被主控去重,也不丢数据)。

func (*Outbox) Append

func (o *Outbox) Append(entries []Entry) (Batch, bool, error)

Append 把一批新采集到的增量落盘为不可变批次,返回该批次。 entries 为空返回零值批次与 false(不建空批次)。 落盘失败时**不改变内存状态**(调用方据此保留原始 pending 下轮重试),返回错误。

func (*Outbox) BootID

func (o *Outbox) BootID() string

BootID 本次进程启动标识(批次随附,供主控判 Seq 缺口)。

func (*Outbox) DropExpired

func (o *Outbox) DropExpired(now time.Time) int

DropExpired 丢弃超龄与超量批次,返回本次丢弃数(累计值见 Dropped)。 由上报循环周期调用。丢弃即数据丢失,故返回的数目必须被调用方以告警级别记录。

func (*Outbox) Dropped

func (o *Outbox) Dropped() int

Dropped 累计丢弃批次数(进程内)。

func (*Outbox) Load

func (o *Outbox) Load() error

Load 启动时加载磁盘上的未确认批次。文件不存在视为空;损坏时隔离现场并继续(返回 error 供调用方告警,但内部状态已可用)。幂等:可重复调用。

func (*Outbox) Oldest

func (o *Outbox) Oldest() (Batch, bool)

Oldest 返回最旧的未确认批次(无则 false)。调用方拿到的是副本(Entries 已复制), 可安全在锁外发送。

func (*Outbox) OldestExcept

func (o *Outbox) OldestExcept(skip func(batchID string) bool) (Batch, bool)

OldestExcept 按 FIFO 返回第一个 skip 判定为「不跳过」的批次(全被跳过或无批次则 false)。 供上报侧跳过本连接已发出、正在等主控回执的批次,避免无谓重发。 谓词在持有内部锁时调用:实现方只能读自己的状态,不得回调 Outbox 方法(会死锁)。

func (*Outbox) Pending

func (o *Outbox) Pending() (batches, entries int)

Pending 返回未确认批次数与总条目数。

func (*Outbox) Persistent

func (o *Outbox) Persistent() bool

Persistent 是否落盘(path 非空)。

func (*Outbox) SetLimits

func (o *Outbox) SetLimits(maxAge time.Duration, maxBatches int)

SetLimits 覆盖超龄/超量阈值(测试用;生产走默认值)。

Jump to

Keyboard shortcuts

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