Kiwi Floyd Storage 生产化改进：Redis Hashtag、多实例原子性、Compaction、Block Cache 与安全重分片

[AlexStocks]

背景

Kiwi 的 storage 层参考 Floyd，在一个逻辑 DB 下使用多个独立 RocksDB instance，并在每个 instance 内使用多个 Column Family 保存 String、复杂类型 Meta 和 Data。

该结构可以分散 RocksDB 压力并为 slot 迁移提供物理边界，但也引入了跨 RocksDB 原子性、路由稳定性、Compaction、缓存预算和存储格式升级等生产化问题。本 Discussion 作为总设计入口；达成共识后继续拆分或关联独立 Issue。

Floyd 设计参考：OpenAtomFoundation/pikiwidb#2052

已确认的工作流

1. 多 RocksDB 与 Multi-Key 语义

当前多实例 MSET/MSETNX 按 instance 分组后逐个提交。单个 RocksDB 内的 WriteBatch 是原子的，但多个独立 RocksDB 之间没有统一提交点；后续 instance 写失败或进程崩溃时，已经提交的 instance 无法回滚。

MGET 与写命令需要分开定义：

• MSET/MSETNX：涉及写原子性；跨 instance 时必须在任何写入前拒绝，不能部分提交；
• MGET：可以跨 instance fan-out，但需要明确它是否只提供逐实例读取，还是要求同 slot/同 instance 获得更强的一致视图；
• RENAME/RPOPLPUSH/SMOVE/*STORE：需要按 standalone 与 cluster 模式分别定义行为。

关联已有 Issue：#196

Redis Hashtag 前置条件

当前 Kiwi 实际使用：

CRC16-ARC(full_key) % db_instance_num

它没有实现 Redis Hashtag，也不是 Redis Cluster 使用的 CRC16-XMODEM。代码中的“compatible with Redis Cluster hash slot”注释与实际算法不一致。

标准 Redis 路由应为：

slot = CRC16-XMODEM(hashtag_or_full_key) mod 16384
instance = persisted_slot_map[slot]

其中第一个有效 {...} 内的非空内容作为 hashtag。

建议模式：

• Cluster：multi-key 命令必须同 Redis slot，不同 slot 在任何写入前返回 CROSSSLOT；
• Standalone 单实例：保留完整 Redis multi-key 语义；
• Standalone 多实例：短期定义为 slot-aware 模式，写命令必须同 slot/同 instance；MGET 的 fan-out 一致性单独确定；
• 不引入跨多个 RocksDB 的通用 2PC，除非未来有明确需求与恢复协议。

算法切换会重新映射已有数据，必须受格式/路由版本门禁保护，不能直接替换。

2. Compaction 完整闭环

当前 Storage::do_compact_range() 和 do_compact_specific_key() 只打印日志并返回成功，尚未调用已经存在的 Redis::compact_range()。这会让管理命令和慢 key 后台任务看起来成功，实际没有执行压缩。

需要完成：

• key → instance 路由；
• DataType → Meta/Data CF 选择；
• 编码后的 begin/end/prefix 边界；
• 慢 key CompactSpecificKey；
• old-SST/periodic compaction；
• ProgressiveCompact；
• 队列去重、任务合并、限流、取消和真实错误返回；
• compaction bytes、duration、queue latency、pending bytes、stall、过滤删除数等指标。

详细设计放在 Issue #88。

3. Reserve 字段与 Block Cache

Floyd/Kiwi 的 persisted key/value 为未来扩展保留了较大的固定 reserve 字段。压缩后的 SST 可能降低部分磁盘成本，但 memtable、WAL、未压缩主 block cache 和编解码仍承担开销。

优化顺序建议：

1. 先修复真正的跨 CF、跨 RocksDB 共享 block cache；
2. 应用并验证配置的 block_cache_size 与 table_options；
3. 建立 cache usage/hit/miss/pinned/entry-role 指标；
4. 对 LRU 与 HyperClockCache 做同预算 A/B；
5. 再评估 Compressed Secondary Cache；
6. 长期通过 format v2 减少固定 reserve，而不是只依赖 cache 压缩。

详细设计放在 Issue #143。

4. 实例元数据与安全启动

当前 instance = hash(key) % db_instance_num，但实例数和路由算法没有持久化。修改实例数会让已有 key 路由到新的目录，表现为数据丢失；reshard_slots() 仍未实现。

第一阶段先持久化拓扑并建立启动门禁：

• db_instance_num；
• slot count；
• hash/hashtag 算法与版本；
• slot map 与 checksum；
• instance 目录完整性。

配置或算法与落盘值不一致时拒绝打开。长期使用显式 slot_to_instance[16384] 和可恢复的 reshard 状态机。

跟踪 Issue：#343

5. 存储格式版本化

Key/Value 编码、CF schema、Comparator 和路由算法均属于持久化契约。PR #262 已经发生过 MemberDataKey endian 变化，说明 reserve 字段不能替代版本机制。

需要统一 StorageManifest：

• key/value format version；
• CF schema version；
• comparator versions；
• slot hash 与 slot map version；
• 当前 Kiwi 版本；
• 明确的打开、迁移、降级拒绝和回滚策略。

跟踪 Issue：#342

推荐执行顺序

Phase 0：安全门禁

1. 完成存储格式版本与 Manifest；
2. 持久化 instance topology、slot/hash 版本；
3. 对配置不一致和旧格式明确拒绝启动。

Phase 1：路由与命令语义

1. 实现标准 Redis CRC16-XMODEM + Hashtag；
2. 引入稳定的 16384 slot 和显式 slot map；
3. MSET/MSETNX 在写前完成 same-slot/same-instance 校验；
4. 定义 MGET、RENAME、RPOPLPUSH、SMOVE、集合/ZSet store 命令语义；
5. 增加 Redis 官方 slot 测试向量和故障注入测试。

Phase 2：Compaction

1. 接通实际 CompactRange；
2. 完成慢 key compact；
3. 完成 periodic/old-SST/progressive 策略；
4. 增加限流、队列与可观测性。

Phase 3：缓存与格式效率

1. 修复共享 Block Cache；
2. 建立同预算 benchmark；
3. 评估 HyperClock/Compressed Secondary Cache；
4. 设计更紧凑、可迁移的 format v2。

统一验收原则

• 不允许跨 instance 写命令部分成功后返回错误；
• 不允许配置变化导致已有数据静默不可见；
• 不允许未执行的 compact 返回成功；
• 不允许 persisted format 变化后无版本门禁地打开旧库；
• 所有路由算法使用 Redis 官方测试向量；
• 所有性能优化在相同总内存和相同数据集下比较；
• 所有迁移和 reshard 路径必须覆盖中断、重启和回滚。

已有关联项

• Cross-slot atomicity：Improve the atomicity of cross slots commands #196
• Compaction worker：Redis结构体compaction线程管理优化 #88
• Shared Block Cache：[ENHANCE] Incomplete block cache sharing implementation #143
• Storage format/version：feat(storage): 建立存储格式版本与迁移门禁 #342
• Instance topology/safe startup：feat(storage): 持久化实例拓扑并拒绝不安全启动配置 #343
• Raft slot/instance validation：fix(raft): validate mutation slots and RocksDB instance routing during apply #337
• Multi-instance snapshot frontier：fix(raft): build multi-instance snapshots at one applied frontier #339

Raft apply 与 multi-instance snapshot 已在 Discussion #330 及 #332～#340 跟进，本 Discussion 不重复定义其 crash-safe apply 协议。

[AlexStocks]

Multi-Key 的当前优先级和支持边界已单独形成决策记录：

#346

最新结论：

• Multi-Key 按 P2 跟踪；
• Kiwi 当前阶段暂不支持涉及两个或以上逻辑 Redis Key 的命令；
• 即使 Key 使用同 Hashtag，也暂不作为当前已支持能力对外承诺；
• 现阶段不建设跨 RocksDB 事务或跨实例一致性读；
• 后续重新开启支持前，必须先完成标准 Redis slot/Hashtag、持久化 slot map、统一路由校验、稳定锁顺序、单 RocksDB WriteBatch 和 Raft 语义闭环。

本总 Discussion 中 Compaction、Block Cache、StorageManifest 和实例拓扑等其他工作不因该 P2 决策降级。