WuKongIM channellog 本地存储设计:基于 Pebble 的 channel 消息日志落盘方案解析
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的展示层语义与 checkpointHW联动,以及 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
对应的三条规则:
- 持久化的消息日志按 ISR 日志偏移(offset)排序;
messageSeq一律被解释为offset + 1;- 提交可见性由 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 包,靠文件和对象边界约束职责"。包内规划为三类代码:
- channel 面向的语义门面代码;
- 本地 Pebble 存储代码;
- 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的消息,删除所有后续消息。
其内部等价操作是三段式的:
- 把 offset 日志截断到
to = seq; - 把 checkpoint
HW钳制到<= seq; - 裁剪任何起始点越过新本地末尾的 epoch-history 尾部记录。
这意味着 TruncateLogTo 不只是删日志,它必须同步修正 checkpoint 与 epoch history,保证截断后本地存储内部仍然自洽——这一点在实现计划的 TestTruncateLogToRemovesTailAndClampsCheckpoint 用例中被显式锁定(append 三条消息、HW=3、TruncateLogTo(2) 后仅剩 seq 1 和 2)。
ISR 集成:同一份 Store 双面复用
设计的精妙之处在于:同一个 channel 作用域的 Store 实例,既服务 channellog 的本地读路径,也服务 ISR replica 的构造。推荐的接线顺序(设计文档 ISR Integration 一节):
Open(path)打开DB;- 调用
db.ForChannel(key)拿到Store; - 从该
Store派生 ISR 适配器; - 把适配器传入 replica 构造(
isr.ReplicaConfig的LogStore、CheckpointStore、EpochHistoryStore、SnapshotApplier); - 继续用同一个
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 语义":
- 添加
DB、Store、键空间定义与编解码; - 添加本地 offset 日志持久化;
- 添加 checkpoint、history、snapshot 持久化;
- 添加 ISR 桥接适配器;
- 添加 seq 读取与截断辅助;
- 接入真实存储的集成测试。
实现计划把这一顺序拆为 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 缺少真实持久化路径的缺口,又为后续按需扩展(幂等状态、搜索、二级索引)保留了清晰边界。