第一次看到caveman这个名字，是在技术社区的项目推荐里。我第一反应是：这是个讲原始人生活的趣味项目？还是某个游戏模组？点进去才发现，它是一个用 Go 写的极简分布式键值存储系统。说真的，在 etcd、Consul 这种巨头统治的领域里，有人愿意花时间写一个"穴居人"级别的存储，反而勾起了我的兴趣。
分布式存储向来以"重"著称，Raft、Paxos、复杂的运维体系，劝退过不少人。caveman恰恰相反，它追求的是一种原生态的朴素——代码量不大，概念直白，就像穴居人用石头和木棍解决问题一样，不加多余的装饰。这篇文章我想从设计理念、核心机制、部署实操到二次扩展，完整拆解一下这类"返璞归真"的存储系统到底值不值得用、能怎么用，以及我们能从里面学到什么。
不管你是准备自研一个内部工具，还是单纯想搞懂 Raft 在实际项目中怎么落地，这篇文章都值得你花几分钟看完。我会把关键原理揉碎了讲，也附上我在实测中踩过的坑和整理好的操作步骤。
1. 为什么一个分布式系统会叫"caveman"
1.1 名字背后的设计哲学
命名这件事，往往最能暴露作者的真实意图。就像 Redis 名字里有"Remote Dictionary Server"一样，caveman这个名字透露出的信号很直接：我要做的东西，和那些满是抽象、微服务、治理框架的现代系统划清界限。它代表的是一种"少即是多"的存储理念——还原到分布式存储最核心、最基础的需求：把数据安全地复制到多台机器上，能在节点挂掉后继续对外服务。
和市面上常见的分布式存储做对比，能更清楚地看出它的定位：
| 系统 | 定位 | 复杂度 | 适用场景 |
|---|---|---|---|
| etcd | 配置中心 + 服务发现 | 中高，协议细节多 | 云原生基础设施 |
| Consul | 服务网格 + 注册中心 | 中高，功能全面 | 微服务架构 |
| Redis Cluster | 分布式缓存 | 中，依赖客户端支持 | 高速缓存 |
caveman | 极简 KV 存储 | 低，源码可快速读完 | 学习、内部工具、原型验证 |
它不是为了在生产环境替代 etcd 而生的，更像是给那些被复杂分布式系统搞得头大的人，提供一个可以完全掌握的参照物。它存在的意义是：当一个分布式系统把功能裁剪到只剩"读、写、复制、容灾"，整个架构会变成什么样。
1.2 它要解决的根本问题
数据写入一台机器后，机器突然断电、硬盘损坏，数据就丢了。分布式存储要解决的问题，就是把数据冗余到多台机器上，并且保证这么多机器看到的数据是一致的。caveman核心就是靠复制日志来实现这一目标：客户端只和"领导者"节点交互，领导者把写操作追加到本次 Raft 日志里，其他节点同步这份日志，过半节点确认后，这次写入就算成功了。
听起来简单，但落到工程实现上，有一连串问题要处理：某个节点落后了怎么追？领导者挂了谁来接班？网络抖动导致选举频繁怎么抑制？这些就是 Raft 协议要管的家务事。caveman的价值在于，它把这些头绪理顺后，用最直接的方式塞进了不到几千行的代码里。
2. 一致性内核：Raft 在 caveman 里怎么落地
2.1 从"领导者的权威"开始理解 Raft
Raft 不是发明了什么高深理论，它只是把分布式一致性问题拆成了几个能看懂的子问题：领导者选举、日志复制、安全性。在学习caveman的过程中，我发现只要抓住"领导者"这个角色，整个协议就通了一半。
系统里每个节点有状态：领导者（Leader）、跟随者（Follower）、候选人（Candidate）。正常情况下只有领导者在做事：接收客户端请求、把请求生成日志条目、复制到跟随者。跟随者只需要被动响应领导者的心跳。如果跟随者一段时间没收到心跳，它会认为领导者可能挂了，于是发起选举，把自己变成候选人，拉取其他节点的选票。
初学的时候，我一直纠结一个细节：为什么必须过半数？举个例子，三个节点的集群中，同一个任期里最多只能有一个节点获得两票，不可能同时出现两个获得过半票数的候选人。这就是多数派投票从数学上杜绝了"双领导者"的可能，也是 Raft 安全性的基石。caveman的选举代码里能看到这个判断逻辑：票数大于节点数除以二以后，节点才会切换角色。
2.2 日志复制与提交的完整链路
这里演示一个 PUT 请求从客户端下发到数据落盘的全过程：
- 客户端把
PUT /key/value请求发给领导者。 - 领导者检查自己任期，把这条写操作包装成一个日志条目，追加到本地日志。
- 领导者向所有跟随者并行发送
AppendEntries请求，消息里带着日志条目内容和领导者的最新提交索引。 - 跟随者收到请求后，会先做一致性检查：本地日志中前一条日志的索引和任期，必须和请求里携带的前一条日志信息匹配，才允许追加新条目。
- 领导者收到超过半数的成功确认后，把这条日志标记为已提交，然后真正把数据应用到状态机（也就是内存中的哈希表）。
- 领导者把提交结果返回给客户端，同时在下一个心跳中把提交索引同步给跟随者。
纸上谈兵到这里，很多人会以为"提交"是瞬间完成的。实际操作中，有一个容易忽略的细节：领导者不能提交旧任期的日志条目。一个常见的实现陷阱是，如果新领导者上任后直接提交前任留下的未提交日志，在特定网络分区场景下，会出现日志被覆盖后丢失的问题。
caveman这类极简实现通常的处理方式是：领导者先追加一条自己任期内的新日志（哪怕是个空操作），把提交索引推进到自己任期内的这条日志上，强制在上任后先确立权威，再处理历史日志。这个细节如果不注意，测试时偶尔能通过，但一旦遇到节点故障恢复，就容易出现数据不一致。
2.3 选举超时的工程调优
Raft 协议里有两个关键时间参数：心跳间隔和选举超时。caveman默认可能给的是常见的 1 秒心跳、5 秒选举超时，但工程上必须根据自己的网络环境调整。
我在搭建实验集群时，有过一次惨痛教训：三台机器在同一机房，网络延迟很低，但因为没有调整参数，集群每十几秒就会出现一次重新选举，整个分布式锁服务跟着反复抖动。后来排查发现，是因为我的服务器负载高，Go 运行时 GC 导致领导者心跳响应偶尔超过选举超时阈值，跟随者误判领导者下线。
解决方案是拉大两个参数之间的差距：心跳间隔设 500 毫秒，选举超时设在 1500 到 3000 毫秒之间的随机值。注意，Raft 规范要求选举超时必须是随机的，防止多个跟随者同时超时、同时发起选举造成选票分裂。源码里通常会有一个随机数生成的逻辑，但很多二次开发者在改参数时会不小心把随机性去掉，这种错误在单节点测试时完全发现不了，集群一上线就露馅。
3. 存储引擎与 API 设计：一个 KV 系统的主干
3.1 存储层为什么不直接用数据库
caveman的存储层设计得相当克制。它没有把数据直接落到某个复杂的 SQL 引擎上，而是采用"内存哈希表 + 日志回放"的经典模型。写入时先写日志文件，日志同步并提交后，再更新内存哈希表。重启时，通过重放日志文件恢复内存状态。
这个模型的好处立竿见影：内存操作快，吞吐高；日志文件是顺序追加写，磁盘性能也友好。它牺牲的是数据的即时持久性——如果日志文件还没来得及 fsync 就把进程杀了，最后几条日志还是会丢。caveman把 fsync 的开关暴露给调用方，默认可能关闭以保证性能，追求极致性能时确实可以这么调，但一旦机器突然断电，很容易丢失最近几秒的写入。
Redis 也采用类似的 AOF 机制，所以很多从 Redis 转过来的人会很快适应。如果你需要更强的可靠性，可以自己在日志写入逻辑中加上 fsync 调用，代价是每次写入都等待磁盘强制落盘，吞吐量可能掉一半以上。这正是"极简"哲学的体现：不替用户拍板，把选择权留给使用者。
3.2 暴露的 API 表面与协议选择
接口走的是 HTTP，因为通用性和调试便利性无人能比。核心接口基本围绕三个动作展开：
# 写入或更新 curl -X PUT http://127.0.0.1:8080/key/value # 读取 curl http://127.0.0.1:8080/key # 删除 curl -X DELETE http://127.0.0.1:8080/key没有实现复杂的事务，也没有范围查询、TTL、Watch 机制，就是一个干干净净的键值存储。这会让一些人觉得功能太少，但这恰恰是极简设计的精妙之处——每条代码都经过审视，不存在"好像可能有用的功能"。
3.3 一次读请求的降级策略
写入必须经过领导者，但读请求呢？caveman这类系统通常支持两种模式：从领导者读，或者从跟随者读。
从领导者读，能保证读到的一定是已经提交的最新数据，但领导者的负载会很高。从跟随者读，能分摊读压力，但可能出现数据滞后——跟随者刚从领导者那拿到日志同步，还没来得及应用，就有读请求打进来。系统里可以加一个名为LinearizableRead的开关决定是否使用更严格的读一致性方案，比如让领导者确认自己还是领导者（发出心跳并等待多数派回应）后才处理读请求，这样能彻底解决读到过期数据的问题，但每次读都要多一次 RTT。
我在实测中遇到过一个很实际的场景：做读写混合测试时，从跟随者读到的数据时新时旧，某次 GET 请求竟然返回了已删除的 key。后来通过领导者确认机制解决了。如果你的业务允许少量读延迟，从跟随者读是个性价比很高的选择。
4. 从单机到集群：部署与容灾实测
4.1 单机模式的快速上手
与其看一堆架构图，不如先把它跑起来。假设你已经拿到编译好的二进制或者克隆了源码，单机模式本质上就是让一个节点自身组成集群：
# 启动第一个节点，监听 8080 端口 ./caveman -id node1 -addr 127.0.0.1:8080 -dir /tmp/caveman-data-dir参数会创建数据目录，日志文件会写在那里。启动后马上用 curl 写入一条数据：
curl -X PUT http://127.0.0.1:8080/test/hello curl http://127.0.0.1:8080/test如果一切正常，GET 请求会返回hello。这一步验证了基本读写通路。
4.2 搭建三节点集群：我在初始化时踩过的坑
三节点集群才能体现容灾能力。第一次搭集群时，我以为像 Redis 那样启动三个实例就能自动发现彼此，结果怎么试都只有单节点状态。后来才意识到，这种去中心化的系统，节点之间不会自动互相感知，必须通过 API 显式把节点列表告诉其中一个节点。
# 三个终端，分别启动三个节点 ./caveman -id node1 -addr 127.0.0.1:8080 -dir /tmp/caveman-data/node1 ./caveman -id node2 -addr 127.0.0.1:8081 -dir /tmp/caveman-data/node2 ./caveman -id node3 -addr 127.0.0.1:8082 -dir /tmp/caveman-data/node3然后向第一个节点提交集群变更：
curl -X POST http://127.0.0.1:8080/cluster/add -d '{"id":"node2","addr":"127.0.0.1:8081"}' curl -X POST http://127.0.0.1:8080/cluster/add -d '{"id":"node3","addr":"127.0.0.1:8082"}'这里有一个新手很容易踩的坑：节点加入集群后，如果新节点没有初始数据，需要从领导者同步快照。caveman这类系统为了简化，可能只会同步日志中尚未被压缩的部分，不会自动迁移全量数据。我就在测试中遇到过节点加入集群成功，但一直查不到旧数据的情况——后来发现，必须在业务数据写入之前就完成集群组建，否则老数据无法回放给新节点。
正确的启动顺序是：先把三个节点组成集群，再开始写数据。如果已经有存量数据，只能选择停掉所有节点，清空新节点的数据目录，再重新加入。
4.3 宕机演练：杀领导者与杀跟随者的差异
集群就绪后，我做了一次故障演练。目标是观察节点故障场景下的表现。
先杀掉领导者节点，客户端写入暂时会失败。等待选举超时窗口过去后，剩余节点会选出新的领导者，之后写入恢复。整个过程里未提交的写入可能会返回错误，但已提交的写入不会丢。把原领导者重新拉起，它会作为跟随者自动加入，从新领导者那里同步丢失的日志。
如果杀掉的是跟随者，整个过程完全无感，因为多数派仍然在线，读写不受影响。
观察发现，caveman这类 Raft 实现在节点恢复时，会做一次全量日志同步，如果日志很长，恢复过程会慢，期间该节点处于不可用状态。生产环境中应该开启"快照压缩"功能，定期把状态机做成快照文件，日志就可以截断到快照点之后，恢复时先加载快照再追日志，速度能快好几个数量级。
4.4 集群节点配置的注意事项
关于节点地址，有一点必须强调：-addr参数写的是这个节点对外提供服务的地址，而集群内部节点之间通信时用的也是这个地址。因此，地址必须写成其他节点能访问到的地址，不能用localhost或者127.0.0.1以外的回环别名。如果节点分布在多台机器，务必写内网 IP 而非公网 IP，公网延迟高，心跳更容易超时。
另外，节点 ID 不要乱起，最好用有语义的名字，比如node1、node1-backup，否则日志里全是节点 ID，排障的时候很痛苦。
5. 在 caveman 之上做扩展：实际项目中的二次开发
5.1 快照与日志压缩实现思路
日志无限增长是 Raft 系统的通病。每写一条数据，日志就追加一条；即使后来把 key 删了，日志里删除记录还在。久而久之，磁盘占用、节点恢复时间都会暴涨。
实现快照的思路是：每隔 N 条日志或每隔一定时间，将当前内存哈希表完整序列化到磁盘，记录此刻的日志索引。然后，就可以安全地删除这个索引之前的日志文件。节点重启时，先加载最新快照，再重放快照后的日志。
用 Go 来实现的话，核心逻辑框架大致是这样：
type SnapshotManager struct { store *Store lastIndex uint64 } func (sm *SnapshotManager) TakeSnapshot(targetIndex uint64) error { data, err := sm.store.Marshal() if err != nil { return err } snapshot := &Snapshot{ Index: targetIndex, Data: data, } // 原子写临时文件后重命名，避免崩溃导致快照损坏 tmpPath := filepath.Join(snapshotDir, "snapshot.tmp") finalPath := filepath.Join(snapshotDir, "snapshot.dat") if err := os.WriteFile(tmpPath, snapshot.encode(), 0644); err != nil { return err } return os.Rename(tmpPath, finalPath) } func (sm *SnapshotManager) Restore() (*Snapshot, error) { // 读取快照文件，解码后回填内存状态 }快照文件与日志文件不要放在同一个目录，否则清理日志的时候容易误删快照，这个坑我在某次内部工具的开发中踩过。
5.2 增加简单的认证与权限控制
caveman默认没有一个认证机制，这在隔离的内网里还好，但一旦端口暴露出去，任何人都能读写数据，风险极高。做二次开发时，最轻量级的做法是加一个静态 Token 校验：
func authMiddleware(next http.Handler, token string) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { if r.Header.Get("Authorization") != "Bearer "+token { http.Error(w, "unauthorized", http.StatusUnauthorized) return } next.ServeHTTP(w, r) }) }在 HTTP 服务层包一层中间件即可，不需要侵入 Raft 核心逻辑。进阶一点可以做基于角色的权限控制，但那就违背了"穴居人"的初衷了。
5.3 从 caveman 反推 Redis Cluster 的设计
研究caveman的另一个收获，是能拿它当"分布式系统的解剖标本"，用最简单的方式理解那些大厂的复杂系统。Redis Cluster 里很多核心概念在 Raft 里都有对应物：主节点对应领导者，故障切换对应选举，从节点对应跟随者。一旦理解了caveman，再去看 etcd 和 Consul 的源码就轻松很多了。
6. 适合自己的才是最好的：一些终极建议
手上已经试用过caveman一段时间，说说我对它的整体感受，以及一套清晰的选型思路。
第一，如果只是想快速掌握 Raft 的整体流程，只读源码是不够的，必须亲手搭一个三节点集群，杀掉一个节点，再拉起来。整个过程走一遍，比刷十篇协议分析文章都管用。
第二，如果要在生产环境里使用它，前提条件非常苛刻：业务模型简单、数据量可控、允许短时间的写入中断、有监控告警机制、团队具备读完源码的能力。随便缺一条，都建议谨慎评估，因为出了问题，文档和社区支持都很有限。
第三，caveman最大的价值在于"完整"——它是一个麻雀虽小五脏俱全的分布式存储系统，从选举、复制、持久化到一致性都覆盖到了。哪怕完全不用它，把它当作读懂 Raft、读懂 etcd/Consul 的阶梯，也非常值得。
最后，我在二次开发的实践中还有一个体会，就是这类极简系统的代码有一个好习惯：它把失败的路径全部都画在我脑子里。比如写入未提交直接崩溃、领导者被分区后继续接收写入、跟随者带着过期日志请求加入集群……每一个边缘情况，都能在真实的分布式故障里找到对应。这样的代码读完后，你会对"分布式系统为什么这么容易出问题"有切肤的理解，而这种经验，是背多少面试题都换不来的。
