Raft的“复制状态机”是指所有节点按完全相同的日志顺序逐条执行相同命令，最终达到一致状态，而非同步数据快照；其核心是日志复制、任期校验、多数派提交与串行Apply。
状态机同步不是“复制数据”，而是“复现执行序列”
直接把结构体 json.Marshal 后塞进 Redis，或用 sync.Map 存个 map[string]interface{}，根本不算状态机同步。Raft 所谓的“复制状态机”，是指所有节点按**完全相同的日志顺序、逐条执行相同命令**，最终达到一致状态。这意味着你必须把业务逻辑抽象成可序列化、可重放的命令（比如 {"op":"set","key":"user:123","value":"{...}","version":42}），而不是同步结果快照。
常见错误是：客户端写一次 HTTP 接口，服务端存 DB + 更新本地 cache，再发个 Pub/Sub 消息通知其他节点 reload —— 这本质是缓存失效，不是状态机同步。一旦网络分区或消息丢失，各节点状态立即分叉。
- 每条日志必须带唯一递增索引（
LogIndex）和当前任期（Term），用于检测日志冲突 - 命令必须幂等且无副作用：不能含
time.Now()、rand.Intn()或直接调用外部 API - 状态机 Apply 阶段必须串行执行，哪怕日志已持久化，也得用 channel 或 mutex 控制顺序
用 Raft 实现同步，关键在日志提交判定逻辑
很多人卡在“为什么 Leader 写了日志，Follower 却没应用？”，问题不在网络或编码，而在提交（commit）条件没满足。Raft 要求：只有当某条日志被**当前 Term 的 Leader 复制到多数节点**后，才能推进 CommitIndex 并触发 Apply。它不看时间、不看心跳次数，只认落盘成功的节点数。
示例判断逻辑（简化）：
立即学习“go语言免费学习笔记（深入）”；
if len(successPeers) >= len(peers)/2+1 && entry.Term == currentTerm {
commitIndex = max(commitIndex, entry.Index)
}
容易踩的坑：
- 误把“收到 AppendEntries 响应”当作“日志已落盘”——实际需检查响应中的
Success字段和Term是否匹配 - 未校验
PrevLogIndex和PrevLogTerm就接受日志，导致日志链断裂（此时 Follower 应返回Success=false，Leader 需回退重试） - CommitIndex 推进后，没触发本地状态机 Apply，或 Apply 时 panic 导致后续日志阻塞
Go 客户端与 Redis 协作时，租约和版本向量不能省
如果你用 Redis 做日志存储或状态快照（比如 SET state:user:123 "{...}" EX 30 NX），别指望单靠 NX 保证一致性。分布式环境下，必须引入租约（lease）和版本向量（version vector）双保险。
具体落地要点：
- 每次写前先
GET state:user:123:lease，检查expire_at是否未过期；过期则需重新争抢租约（SET state:user:123:lease "node-a" EX 30 NX） - 读取当前版本向量：
GET state:user:123:vv→ 解析为map[string]uint64，合并本节点增量后 CAS 写回 - 所有 Redis 操作必须用
go-redis/v9，传入带超时的context.WithTimeout(ctx, 500*time.Millisecond)，避免 goroutine 泄漏 - 禁止用
DEL state:user:123清理状态——应设短 TTL，靠 Redis 自动过期，否则删除期间出现写请求会丢失
文件类状态同步，必须用内容寻址 + 变更广播双机制
同步文件元数据或二进制内容时，“路径一致”不等于“内容一致”。os.SameFile 在跨节点场景下毫无意义，filepath.WalkDir 只能扫本机快照，无法感知远端变更。
可靠做法是：
- 所有文件入库前计算
sha256.Sum，路径按哈希分片存储，如/data/ab/cd/abcdef123... - 每次变更生成一条日志：
{op:"put", hash:"abc...", size:1024, mtime:1720949520}，走 Raft 日志复制 - 节点收到日志后，先
HEAD远端 URL 校验Content-Length和X-Content-SHA256header，匹配才GET - 删除操作绝不走
os.Remove，统一转为写日志：{op:"delete", hash:"abc..."}，由各节点自行清理本地副本
真正的难点从来不是怎么把字节从 A 传到 B，而是怎么让所有节点对“此刻该呈现什么状态”达成共识——这需要你在命令设计、日志校验、租约管理、内容哈希四个层面同时设防，漏掉任何一环，一致性就会在某个凌晨三点悄然崩塌。
