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
- type Batch
- type Entry
- type Outbox
- func (o *Outbox) Ack(batchID string) (bool, error)
- func (o *Outbox) Append(entries []Entry) (Batch, bool, error)
- func (o *Outbox) DropExpired(now time.Time) int
- func (o *Outbox) Load() error
- func (o *Outbox) OldestExcept(skip func(batchID string) bool) (Batch, bool)
- func (o *Outbox) Pending() (batches, entries int)
- func (o *Outbox) Persistent() bool
- func (o *Outbox) SetLimits(maxAge time.Duration, maxBatches int)
- func (o *Outbox) SetMaxBytes(maxBytes int)
Constants ¶
const ( DefaultMaxAge = 7 * 24 * time.Hour DefaultMaxBatches = 20000 DefaultMaxBytes = 10 * 1024 * 1024 // 10MB )
默认阈值(构造时可覆盖,见 SetLimits / SetMaxBytes)。
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 去重会丢掉后加的部分。
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 ¶
New 创建发件箱(path 由 agent 配置注入,默认 /etc/xray-agent/traffic_outbox.json)。 path 为空 = 纯内存模式(不落盘):仅供测试与「未配置路径」的降级运行,生产必须给路径。
func (*Outbox) Append ¶
Append 把一批新采集到的增量落盘为不可变批次,返回该批次。 entries 为空返回零值批次与 false(不建空批次)。 落盘失败时**不改变内存状态**(调用方据此保留原始 pending 下轮重试),返回错误。
func (*Outbox) DropExpired ¶
DropExpired 丢弃超龄与超量批次,返回本次丢弃数。 由上报循环周期调用。丢弃即数据丢失,故返回的数目必须被调用方以告警级别记录。
func (*Outbox) OldestExcept ¶
OldestExcept 按 FIFO 返回第一个 skip 判定为「不跳过」的批次(全被跳过或无批次则 false)。 供上报侧跳过本连接已发出、正在等主控回执的批次,避免无谓重发。 谓词在持有内部锁时调用:实现方只能读自己的状态,不得回调 Outbox 方法(会死锁)。
func (*Outbox) SetMaxBytes ¶ added in v0.1.17
SetMaxBytes 覆盖发件箱文件字节上限(测试用;生产走默认 10MB)。