决策记录：Kiwi 当前暂不支持 Multi-Key 命令（P2）

[AlexStocks]

结论

当前阶段，Kiwi 暂不支持涉及两个或以上逻辑 Redis Key 的 Multi-Key 命令。

该能力按 P2 跟踪：保留设计和后续演进方向，但不进入当前优先开发范围，也不在现阶段引入跨 RocksDB 事务、跨实例一致性读或通用 2PC。

这里的“不支持”是当前产品和架构决策，不代表现有代码已经完成统一禁用。仓库中已经存在的 Multi-Key 命令和分片执行路径仍需盘点，确保它们不会在不具备完整语义保证的情况下被误认为已经支持。

范围定义

Multi-Key 指一个 Redis 命令同时访问两个或以上的逻辑 Redis Key，例如：

• MGET key1 key2
• MSET key1 value1 key2 value2
• MSETNX
• RENAME / RENAMENX
• COPY
• SMOVE
• RPOPLPUSH / BRPOPLPUSH
• LMOVE / BLMOVE
• SDIFF / SINTER / SUNION
• SDIFFSTORE / SINTERSTORE / SUNIONSTORE
• ZINTER / ZUNION / ZDIFF
• ZINTERSTORE / ZUNIONSTORE
• Lua、事务或未来命令中一次涉及多个 Redis Key 的操作

以下命令虽然参数很多，但只操作一个逻辑 Redis Key，因此不属于本决策限制范围：

• HSET key field1 value1 field2 value2
• SADD key member1 member2
• ZADD key score1 member1 score2 member2
• LPUSH key value1 value2
• DEL key 等单 Key 操作

判断依据是“涉及多少个逻辑 Redis Key”，不是参数数量，也不是内部产生多少条 RocksDB KV。

为什么当前不支持

1. 多 RocksDB 实例没有统一原子提交点

Kiwi/Floyd 将数据分散到多个独立 RocksDB instance。单个 RocksDB 内的 WriteBatch 可以提供原子提交，但多个 RocksDB 之间没有统一提交点。

如果一个命令按 instance 分组后依次提交：

instance 0 提交成功
instance 1 提交失败或进程崩溃

则命令会留下部分成功状态，无法满足 MSET、MSETNX、RENAME、SMOVE、*STORE 等命令要求的原子语义。

2. 当前路由与标准 Redis Cluster slot 尚未完全对齐

当前 Kiwi 路由仍需要完成标准 Redis Hashtag、CRC16-XMODEM、固定 16384 slot 和持久化 slot map 等工作。

在这些基础能力完成前，不能把“当前碰巧落在同一个 RocksDB instance”视为稳定的同 slot 语义。实例数或路由算法变化后，同一组 Key 可能被重新映射。

3. Multi-Key 只读同样需要定义一致性

MGET、SINTER、SUNION 等只读命令虽然没有写原子性问题，但跨多个 RocksDB instance 时没有天然的统一 Snapshot。

如果直接 fan-out，返回结果可能来自不同 RocksDB 的不同时间点。当前阶段不为这类命令承诺跨实例一致性读视图。

4. Cluster/Raft 路径还需要一致的前置验证

未来支持 Multi-Key 时，至少需要保证：

• 命令入口正确提取全部 Key；
• propose 前完成 same-slot 校验；
• State Machine apply 进行防御性校验；
• 锁顺序稳定；
• 同一原子操作使用一个 RocksDB WriteBatch；
• 路由版本、slot map 和 Raft 日志语义一致。

在这些条件未闭环前，继续扩展 Multi-Key 命令会扩大后续兼容和数据正确性风险。

当前阶段的行为原则

1. 不实现跨 RocksDB 通用事务

当前不引入：

• 跨 RocksDB 2PC；
• 跨实例 WAL 协调；
• 跨实例回滚日志；
• 跨实例一致性 Snapshot；
• 以 Raft 日志代替本地多实例原子提交的临时方案。

未来只有在存在明确业务需求、故障恢复协议和可验证收益时，才重新评估这些方案。

2. 不以同 Hashtag 作为当前可用承诺

标准 Redis Hashtag 是未来 Multi-Key same-slot 支持的必要条件，但当前决策是“暂不支持 Multi-Key”，因此即使多个 Key 使用同一个 Hashtag，也不表示 Kiwi 当前已经承诺支持该命令。

例如：

MSET {user1}:name "A" {user1}:age "18"

该写法是未来 same-slot 路由的正确方向，但在 Multi-Key 能力正式完成并通过验收前，不能作为当前绕过方式对外承诺。

3. 不允许静默拆分后部分执行

现有或未来命令不得：

1. 把 Multi-Key 请求按 RocksDB instance 分组；
2. 依次执行每组操作；
3. 在部分实例已经成功后才返回错误。

当前不支持的命令应在任何存储读取、写入或 Raft propose 前，以统一、明确、可测试的方式拒绝。

具体采用“不注册命令”还是返回统一 ERR ... not supported，由后续命令兼容性盘点决定；但不能继续保留看似成功、实际缺少原子性或一致性的行为。

当前 P2 工作内容

P2 不等于立即实现全部 Multi-Key 命令，而是保留以下工作入口：

1. 盘点当前命令表中所有 Multi-Key 命令；
2. 为每个命令声明准确的 Key 提取规则；
3. 建立命令矩阵，区分：
   • 多 Key 只读；
   • 多 Key 无条件写；
   • 多 Key 条件写；
   • source/destination 搬移；
   • 多读一写的 *STORE；
4. 检查现有命令是否存在按 instance 拆分并部分提交的路径；
5. 在正式支持前建立统一的不支持行为；
6. 为未来 same-slot 支持保留集中式路由校验边界。

建议矩阵格式：

命令	类型	Key 提取规则	当前状态	未来同 slot 语义	原子边界
MGET	多 Key 读	argv[1..]	暂不支持	可评估单实例 Snapshot	只读一致性待定义
MSET	多 Key 写	奇数位置参数	暂不支持	一个 RocksDB WriteBatch	全有或全无
MSETNX	条件写	奇数位置参数	暂不支持	检查和写入同一临界区	条件检查与提交原子
RENAME	source/destination	两个 Key	暂不支持	同 slot、同 Batch	删除源与写目标原子
SMOVE	source/destination	两个 Key	暂不支持	同 slot、同 Batch	两个集合同时修改
SINTERSTORE	多读一写	sources + destination	暂不支持	同 slot、锁内读取和覆盖	目标替换原子

未来重新开启支持的前置门槛

只有以下基础条件完成后，才重新评估将 Multi-Key 从 P2 提升：

• 实现标准 Redis Hashtag 提取规则；
• 使用 CRC16-XMODEM 和固定 16384 slot；
• 持久化 slot 到 instance 的映射及算法版本；
• 启动时验证路由配置与落盘 Manifest 一致；
• 提供集中式 Multi-Key Key 提取和 same-slot 校验；
• 不使用“同 RocksDB instance”替代“同 Redis slot”；
• 多 Key 锁使用稳定顺序，避免死锁；
• 同 slot 写操作通过一个 RocksDB WriteBatch 提交；
• MSETNX 等条件命令在同一临界区内完成检查和写入；
• Raft propose 与 State Machine apply 使用一致的路由语义；
• 覆盖 Redis 官方 slot/Hashtag 测试向量；
• 覆盖失败、并发、崩溃、重启和部分提交防护测试；
• 明确 Multi-Key 只读命令的一致性承诺。

满足前置门槛后，优先考虑“只支持同 slot Multi-Key”，不默认建设跨 slot 或跨 RocksDB 的分布式事务。

当前阶段的验收标准

本决策完成落地时，应满足：

• 已列出当前注册的全部 Multi-Key 命令；
• 已区分单 Key 多参数命令与真正的 Multi-Key 命令；
• 所有暂不支持的 Multi-Key 命令在接触存储前统一拒绝；
• 不存在按 RocksDB instance 分组后逐组提交的公开执行路径；
• 不存在部分执行后再返回错误的路径；
• Standalone、Cluster 和 Raft 模式对“不支持”的行为一致；
• 文档和测试不再把同 Hashtag 描述为当前已支持能力；
• 后续新增命令必须声明其 Key 数量和路由约束。

与其他存储工作的关系

本 Discussion 只记录 Multi-Key 的当前优先级和支持边界。

以下两项仍按原 Issue 推进，不因 Multi-Key 被定为 P2 而降级：

1. StorageManifest 随 Checkpoint、Raft Snapshot、备份和恢复传播

   • 存储格式跟踪：feat(storage): 建立存储格式版本与迁移门禁 #342
   • 实例拓扑与安全启动：feat(storage): 持久化实例拓扑并拒绝不安全启动配置 #343
   • Multi-instance Snapshot：fix(raft): build multi-instance snapshots at one applied frontier #339

2. Compaction Filter 使用生产编码器和真实 CompactRange 验证

   • Compaction 闭环：Redis结构体compaction线程管理优化 #88

关联项

• Floyd Storage 生产化总讨论：Kiwi Floyd Storage 生产化改进：Redis Hashtag、多实例原子性、Compaction、Block Cache 与安全重分片 #344
• Cross-slot atomicity：Improve the atomicity of cross slots commands #196
• Compaction worker：Redis结构体compaction线程管理优化 #88
• Storage format/version：feat(storage): 建立存储格式版本与迁移门禁 #342
• Instance topology/safe startup：feat(storage): 持久化实例拓扑并拒绝不安全启动配置 #343
• Multi-instance snapshot frontier：fix(raft): build multi-instance snapshots at one applied frontier #339