WuKongIM channellog 本地存储设计:基于 Pebble 的 channel 消息日志落盘方案解析

原创2026-10-16 12:29:371,886 阅读
文章标签:即时通讯后端

WuKongIM channellog 本地存储设计:基于 Pebble 的 channel 消息日志落盘方案解析

导读:本文围绕 WuKongIM 仓库中的《Channellog Local Storage Design》(docs/superpowers/specs/2026-04-03-channellog-local-storage-design.md)展开,讲解如何在 pkg/storage/channellog 包内为 channel 增加一套真实的本地持久化消息日志存储。读完本文,你将掌握:为什么存储真相必须是 groupKey + offset 而非 channel + messageSeq、如何以单一 Go 包 + 文件级职责边界组织 Pebble 存储、messageSeq 如何作为 offset + 1 的展示层语义与 checkpoint HW 联动,以及 V1 四个 seq 读取 API(单条加载、正向区间、反向区间、截断)的完整语义约定。

背景:channellog 的定位与"缺一块真存储"的问题

在 WuKongIM 的演进中,pkg/storage/channellog 是一个面向 channel 的语义门面(facade)包,它已经承担了以下 channel 侧语义职责(见设计文档 Problem 一节):

  • ChannelKey -> GroupKey 的翻译;
  • 元数据兼容性检查(metadata compatibility checks);
  • 删除围栏(delete fencing);
  • messageSeq = committed offset + 1 这一核心换算;
  • 面向 channel 的 send / fetch / status 接口。

但设计文档明确指出:该包此前并未拥有一个具体的本地持久化存储实现,现有测试依赖的是一组 fake:

  • MessageLog(消息日志接口)
  • ChannelStateStore(channel 状态存储接口)
  • 运行时 group 句柄(runtime group handles)

这就形成了一个缺口:架构意图上存储应收归 channellog,但实际可部署的持久化路径并不存在。与此同时,设计者拒绝了另起一个 pkg/storage/msgdb 包的方案——那会新增一个公共边界和一层命名,而当前决策是"存储留在 channellog 内"。

从当前仓库演进看,这一设计意图最终以更细化的形态落地:channel 的持久化存储已迁移为 pkg/channel/store 下的真实实现(如 pkg/channel/store/memory.go 中的 ChannelStore、Checkpoint、LEO/HW 边界、AppendLeader/ApplyFollower/ReadCommitted 等能力),而通用 Pebble 存储底座由 pkg/raftlog/pebble_db.go 提供。本文按设计文档原意讲述 V1 方案本身,并附注仓库现状以对照。

V1 范围:窄而清晰的四个能力

设计文档把 V1 范围刻意收窄,避免重蹈旧 wkdb/message.go 那种"消息表 + 二级索引"混合设计的覆辙。V1 只做四件事:

能力 说明
单条消息加载 按 messageSeq 加载单条消息(LoadMsg)
正向区间加载 按 messageSeq 区间正向加载(LoadNextRangeMsgs)
反向区间加载 按 messageSeq 区间反向加载(LoadPrevRangeMsgs)
截断到 seq 保留 messageSeq <= seq 的消息并丢弃后续(TruncateLogTo)

同时明确不做的事(Non-Goals):

  • 不新建 pkg/storage/msgdb 顶层包;
  • 不在 pkg/storage/channellog 下引入子包;
  • 不让 messageSeq 成为存储层的事实真相(source of truth);
  • 不复刻旧 wkdb/message.go 风格的"消息表 + 二级索引"混合设计;
  • 不实现 payload 搜索、发送者索引、时间戳索引、channel 级 last-seq 缓存。

存储真相:groupKey + offset,而非 channel + messageSeq

这是整份设计最核心的决策,值得单独展开。设计文档的 Source Of Truth 一节写得很明确:

存储层真相(source of truth):
    groupKey + offset

而不是:
    channel + messageSeq

对应的三条规则:

  1. 持久化的消息日志按 ISR 日志偏移(offset)排序;
  2. messageSeq 一律被解释为 offset + 1;
  3. 提交可见性由 checkpoint 的 HW(high-water mark)推导,V1 不额外存储独立的 lastMessageSeq 键。

为什么这样设计?因为 ISR(in-sync replica)复制层已经以 offset 为序维护日志,如果存储层再单独持久化一份 messageSeq 序列,就会产生"双份真相":一旦两者漂移,channel 的读路径和 ISR 的恢复路径就会互相矛盾。让 messageSeq 始终从 offset + 1 派生、让 HW 唯一决定提交边界,本地存储就能与 ISR 恢复行为天然保持一致。

这一"单一真相"原则在当前仓库中仍有清晰体现:pkg/channel/store 的内存实现同样以连续的 Index(offset 语义)为日志主序,MessageSeq 由 messageFromRecord 直接取 record.Index 派生(见 pkg/channel/store/memory.go),checkpoint 也只保留 HW 一个提交水位,读取时以 leo/HW 钳制可见范围。

检查点与可见性模型

V1 不存 lastMessageSeq,取而代之的统一模型是:

  • 最后一条已提交可见消息的 seq 就是 checkpoint.HW;
  • 已提交区间之后下一条可读的 messageSeq 是 checkpoint.HW + 1;
  • 空 channel 意味着 HW == 0。

这样既消除了重复状态,又让本地存储与 ISR 恢复行为保持一致——replica 重开后只需要读回 checkpoint,就能复原"哪些消息可见"。

包形态:一个包、三种代码、按文件分责

设计明确否决了子包化(local、bridge、msgdb 子包都不要),主张"保持单一 Go 包,靠文件和对象边界约束职责"。包内规划为三类代码:

  1. channel 面向的语义门面代码;
  2. 本地 Pebble 存储代码;
  3. ISR 存储桥接代码。

对应的文件规划(代码组织规则,不是新的包边界):

  • 语义门面文件:meta.go、send.go、fetch.go、apply.go
  • 本地存储文件:db.go、store.go、log_store.go、seq_read.go、checkpoint_store.go、history_store.go、snapshot_store.go
  • 键空间与编解码文件:store_keys.go、store_codec.go(原有的 codec.go 继续专职消息记录编码与 payload 哈希)
  • ISR 桥接文件:isr_bridge.go

配套的实施计划文档 docs/superpowers/plans/2026-04-03-channellog-local-storage-implementation.md 进一步明确了这份文件划分,并补充了包级哨兵错误(ErrInvalidArgument、ErrMessageNotFound、ErrCorruptValue)与 doc.go 的职责更新。

各文件职责速览

文件 职责
db.go DB、Open、Close、ForChannel
store.go Store、通用构造与校验辅助、channel key 与派生 group key 的共享访问
store_keys.go 定义 V1 全部 Pebble 键空间:消息日志条目、checkpoint 状态、epoch 历史、snapshot payload;不含任何语义逻辑
store_codec.go 非消息记录的 value 编解码:checkpoint payload、epoch history payload、snapshot 元数据/包装值
log_store.go 基于 offset 的本地日志:Append、Read、LEO、Truncate、Sync——存储真相层
seq_read.go messageSeq 读表面:LoadMsg、LoadNextRangeMsgs、LoadPrevRangeMsgs、seq↔offset 换算、基于 checkpoint HW 的提交区间围栏
checkpoint_store.go checkpoint 持久化:Load、Store;字段至少含 Epoch、LogStartOffset、HW
history_store.go epoch 历史持久化:Load、Append
snapshot_store.go snapshot payload 持久化与替换;V1 把 payload 视为不透明字节
isr_bridge.go 从 Store 构建 ISR 适配器,让同一份存储同时满足 log store / checkpoint store / epoch history / snapshot applier 四类行为;可 import pkg/replication/isr,Pebble 文件保持聚焦本地存储语义

对象模型:DB 与 channel 作用域的 Store

本地存储入口沿用了与 pkg/storage/metadb 相同的通用形态(设计文档 Object Model 一节):

type DB struct { ... }

func Open(path string) (*DB, error)
func (db *DB) Close() error
func (db *DB) ForChannel(key ChannelKey) *Store
type Store struct { ... }

Store 是 channel 作用域的句柄,它一次性绑定三样东西:

  • ChannelKey(channel 业务标识)
  • 派生出的 GroupKey(复制组标识)
  • 底层的 *pebble.DB

这样设计的好处是:上层无需为每次操作反复推导存储前缀或运行时键,Store 建好后所有读写都直接复用已绑定的上下文。当前仓库的 pkg/raftlog Pebble 底座也采用了同构的"DB 持有引擎、按 scope 派生句柄"模式——DB 持有一个 *pebble.DB 与 write/GC 生命周期,并通过 For(scope)/ForSlot/ForController 派生不同作用域的存储句柄(见 pkg/raftlog/pebble_db.go 与 For 系列方法)。

Store 推荐的 V1 本地 API 如下(设计文档原文):

func (s *Store) LoadMsg(seq uint64) (ChannelMessage, error)
func (s *Store) LoadNextRangeMsgs(startSeq, endSeq uint64, limit int) ([]ChannelMessage, error)
func (s *Store) LoadPrevRangeMsgs(startSeq, endSeq uint64, limit int) ([]ChannelMessage, error)
func (s *Store) TruncateLogTo(seq uint64) error

这些方法故意放在 Store 上而不是 Cluster 上——避免 channel 门面变成一个"存储 + 复制"混合对象。

责任划分

  • DB 拥有:Pebble 生命周期、Open/Close 与基础 batch 辅助、创建 channel 作用域的 Store 句柄;不做 channel 语义检查。
  • Store 拥有:channel 本地持久化数据操作,分两类——本地读与维护 API、ISR 桥接适配器。

读语义详解:四个 API 的精确约定

单条加载:LoadMsg(seq)

规则(设计文档原文):

  • seq 必须大于 0;
  • offset = seq - 1;
  • 消息仅当 offset < checkpoint.HW 时可见。

也就是说:即使日志里物理存在该条记录,只要它尚未越过 HW(未提交),读 API 就不得返回——"已提交才可见"是 V1 读路径的铁律。

正向区间加载:LoadNextRangeMsgs(startSeq, endSeq, limit)

规则:

  • startSeq 闭区间(inclusive);
  • endSeq == 0 表示上界开放(open-ended),即"读到可读上限为止";
  • 实际可读上界仍然被已提交的 HW 钳制。

反向区间加载:LoadPrevRangeMsgs(startSeq, endSeq, limit)

规则:

  • 保留上层期望的旧语义形状(backward window);
  • 先在 seq 空间计算反向窗口;
  • 再翻译到 offset 空间;
  • 可见性同样以已提交 HW 为上限。

截断:TruncateLogTo(seq)

保持旧有的 channel 面向含义:

保留 messageSeq <= seq 的消息,删除所有后续消息。

其内部等价操作是三段式的:

  1. 把 offset 日志截断到 to = seq;
  2. 把 checkpoint HW 钳制到 <= seq;
  3. 裁剪任何起始点越过新本地末尾的 epoch-history 尾部记录。

这意味着 TruncateLogTo 不只是删日志,它必须同步修正 checkpoint 与 epoch history,保证截断后本地存储内部仍然自洽——这一点在实现计划的 TestTruncateLogToRemovesTailAndClampsCheckpoint 用例中被显式锁定(append 三条消息、HW=3、TruncateLogTo(2) 后仅剩 seq 1 和 2)。

ISR 集成:同一份 Store 双面复用

设计的精妙之处在于:同一个 channel 作用域的 Store 实例,既服务 channellog 的本地读路径,也服务 ISR replica 的构造。推荐的接线顺序(设计文档 ISR Integration 一节):

  1. Open(path) 打开 DB;
  2. 调用 db.ForChannel(key) 拿到 Store;
  3. 从该 Store 派生 ISR 适配器;
  4. 把适配器传入 replica 构造(isr.ReplicaConfig 的 LogStore、CheckpointStore、EpochHistoryStore、SnapshotApplier);
  5. 继续用同一个 Store 提供 channel 本地读与截断辅助。

Cluster 本身不应构造 Pebble 键、不应持有裸 Pebble 依赖——它只依赖 MessageLog 这类窄接口。实现计划还特别要求 DB 满足 MessageLog 接口,使既有 Cluster.Config.Log 装配保持狭窄。

从仓库现状看,这一"同一存储双面复用"的形态已具雏形:pkg/channel/store 的 ChannelStore 同时暴露复制面(AppendLeader、ApplyFollower、ReadLog、StoreCheckpoint)与读面(ReadCommitted、LookupMessageByID、GetLastSenderMessageSeq),而复制层在 pkg/channel/replication 目录实现,ISR 语义(CommitModeQuorum/CommitModeLocal、leader/follower 角色)定义在 pkg/channel/types.go。

键空间与编解码约定

store_keys.go 规划 V1 的四个 Pebble 键空间,实现计划给出了具体的前缀常量(0x10 起跳,为后续扩展留出空间):

const (
	keyspaceLog        byte = 0x10 // 消息日志条目
	keyspaceCheckpoint byte = 0x11 // checkpoint 状态
	keyspaceHistory    byte = 0x12 // epoch 历史
	keyspaceSnapshot   byte = 0x13 // snapshot payload
)

实施要点(来自实现计划 Implementation Notes):

  • groupKey 在键中使用长度定界(length-delimited)或明确无歧义的编码,不能只依赖字符串分隔符——避免不同 channel 的键互相碰撞;
  • 从 Pebble 读出的字节在返回给上层前必须拷贝(copy bytes out),防止调用方持有 Pebble 内部缓冲造成数据被复用/篡改;
  • 消息记录编码继续留在 codec.go(记录编码 + payload 哈希),非消息的 checkpoint/history/snapshot 值编解码放在 store_codec.go。

被否决的替代方案:为什么这些路不走

设计文档 Rejected Alternatives 一节给出了四组被否决的方案及理由,理解这些理由有助于把握设计的边界意图:

被否决方案 否决理由
新建 pkg/storage/msgdb 顶层包 当前决策是让本地消息存储留在 pkg/storage/channellog 内,避免再开一个公共存储包边界
在 pkg/storage/channellog 下加子包 选定方向是"单包 + 文件/对象职责约束",而不是再加一层包可见性规则
让 messageSeq 成为持久化主排序键 会重复 ISR 日志真相,削弱"messageSeq 由已提交 offset 派生"这一不变式
整体复刻旧 wkdb/message.go 语义 V1 只需要本地日志存储 + seq 读取 + 截断;把搜索和索引行为拉进来会无谓扩大范围,且当下没有真实调用方

测试策略:三层测试锁定语义

设计要求 V1 配齐三层测试(Testing Requirements 一节),实现计划进一步细化了用例清单:

1. 本地 Pebble 存储测试(db_test.go、log_store_test.go、checkpoint_store_test.go、history_store_test.go、snapshot_store_test.go、seq_read_test.go),锁定:

  • Open/Close/ForChannel 行为,以及 ForChannel 正确绑定派生 groupKey(用例 TestOpenCreatesDBAndForChannelBindsDerivedGroupKey);
  • append 后按 seq 单条加载、正向区间加载、反向区间加载;
  • 截断到 seq(TestTruncateLogToRemovesTailAndClampsCheckpoint);
  • checkpoint load/store 往返、epoch history load/append 往返与顺序、snapshot payload 替换/读取;
  • 提交围栏:TestLoadMsgReturnsCommittedMessageOnly 验证 HW=2 时 LoadMsg(3) 返回 ErrMessageNotFound;
  • DB.Read 按 groupKey 隔离且遵守 limit/maxBytes 预算(TestDBReadScopesByGroupKeyAndBudget)。

2. ISR 桥接集成测试(isr_bridge_test.go),锁定:

  • 一个 Store 实例能同时支撑 replica 的 log/checkpoint/history/snapshot 四类接口(TestStoreAdaptersBackReplicaRecovery);
  • append 后推进 checkpoint,重开(reopen)后状态仍在(TestStoreAdaptersRecoverCheckpointAndLogAfterReopen:同一临时目录写 → 关闭 → 重开 DB → 重建 Store → 重建 isr.Replica → 断言恢复出的 HW 与本地可见范围等于存储的 checkpoint);
  • follower apply 与 recovery 保持本地日志与 checkpoint 一致;
  • snapshot 安装正确更新可见范围与 payload(TestStoreSnapshotAdapterPersistsOpaquePayload)。

3. channellog 语义回归测试(storage_integration_test.go + 既有 fetch/send 测试),锁定:

  • 只返回已提交消息(TestFetchWithRealStoreReturnsCommittedMessagesOnly);
  • messageSeq == offset + 1(TestRealStoreSeqLoadsUseOffsetPlusOneSemantics);
  • seq 加载与 checkpoint HW 对齐。

实现计划还给出了一个关键约束:保留既有 fake 测试不动,新增真实存储的独立测试环境(storage_testenv_test.go 提供临时目录 Pebble 辅助、编码消息夹具、checkpoint/history 辅助),语义断言聚焦"提交可见性"与"messageSeq = offset + 1",且不扩大 Cluster 的公共 API——send.go、fetch.go 应在 MessageLog 抽象不变的前提下原样工作。

实施顺序:先稳存储真相,再加 seq 门面

设计文档的 Migration Strategy 给出的推荐顺序,本质是"先让存储真相层稳定,再在其上铺 seq 语义":

  1. 添加 DB、Store、键空间定义与编解码;
  2. 添加本地 offset 日志持久化;
  3. 添加 checkpoint、history、snapshot 持久化;
  4. 添加 ISR 桥接适配器;
  5. 添加 seq 读取与截断辅助;
  6. 接入真实存储的集成测试。

实现计划把这一顺序拆为 6 个 TDD 任务(存储外壳 → offset 日志 → checkpoint/epoch/snapshot → seq 读与截断 → ISR 桥接 → 语义集成覆盖),每步先写失败测试、再实现、再跑 go test ./pkg/storage/channellog -count=1 与 go test ./pkg/replication/isr -count=1 收尾。

与当前仓库的对应关系

需要特别说明的是:本文所述设计文档标注日期为 2026-04-03、状态为 Proposed,它规划的目标包 pkg/storage/channellog 在当前仓库快照中已不存在——channel 存储职能已演进为 pkg/channel/store(含内存实现 memory.go、适配器 adapter.go、channel_adapter.go 等),通用 Pebble 持久化底座由 pkg/raftlog(核心为 pebble_db.go)提供,仓库 go.mod 同时引入 github.com/cockroachdb/pebble v1.0.0 与 github.com/cockroachdb/pebble/v2 v2.1.4(见 go.mod)。阅读本文时,请把设计文档当作"V1 边界与语义契约"的权威定义来理解,其核心决策——offset 为存储真相、messageSeq = offset + 1、HW 决定提交可见性、单一包按文件分责——正是理解当前 channel 存储架构的关键线索。

总结

这份设计文档给出了一套克制而清晰的本地存储方案:不新开包、不建子包、不让 messageSeq 成为第二份真相,而是以"groupKey + offset 为存储真相、checkpoint.HW 为提交水位、messageSeq = offset + 1 为读面解释"三原则构建 V1 的 Pebble 本地日志。配合 Store 的 channel 作用域绑定、四类 seq 读 API、ISR 桥接复用与三层测试锁定,它既填补了 channellog 缺少真实持久化路径的缺口,又为后续按需扩展(幂等状态、搜索、二级索引)保留了清晰边界。

登录后查看全文
WuKongIM