应使用 etcd/raft 库而非手写 Raft：仅导入 raftpb 和 raft/v3 包，自实现 Storage 与 Transport；node-id 需持久化且全局唯一；election timeout 需按网络调整；增删节点须经 leader 提交 ConfChange 并确认 apply。
用 raft 库而非自己实现共识逻辑
自己写 Raft 协议容易出错，且调试成本极高。Go 生态里 etcd/raft 是最稳定、被验证过的实现，它只负责核心状态机和日志复制，不绑定存储或网络——这正好适合你封装成可嵌入的选举模块。
常见错误是直接依赖 etcd/server/v3 整体包，结果引入大量非必要组件（如 gRPC server、鉴权、HTTP API），导致二进制体积膨胀、启动变慢、升级困难。
- 只导入
go.etcd.io/etcd/pkg/v3/raftpb和go.etcd.io/etcd/raft/v3两个包 - 自己实现
raft.Storage接口，底层用boltdb或badger存日志和快照，避免依赖 etcd 自带的wal和snap包 - 网络层用
net/http+json就够，不需要 gRPC；节点间通信只需实现raft.Transport的三个方法：Send、SendSnapshot、Receive
节点 ID 必须全局唯一且启动时不可变
raft 要求每个节点在集群生命周期内拥有固定 id，一旦变更（比如重启后随机生成），会导致旧日志被拒绝、投票失败、甚至脑裂。
典型误操作：用 hostname 或 IP 自动生成 ID，但在容器环境里 hostname 可能重复，IP 可能漂移。
立即学习“go语言免费学习笔记（深入）”；
- 把
node-id作为启动参数或配置项显式传入，例如--node-id=1001 - 在首次启动时生成并持久化到本地磁盘（如
./data/node-id），后续启动必须读取该文件，不允许覆盖 - 检查
raft.Config.ID是否为 0 或负数——etcd/raft会静默忽略非法值，但实际无法参与选举
心跳与超时参数必须按网络延迟调整
默认 election timeout 是 1000ms，适用于局域网；若节点跨公网部署，丢包率高、RTT 波动大，这个值会导致频繁重选举、集群震荡。
观察现象：日志里反复出现 "became candidate at term"、"lost leader lease"，但没真正选出 leader。
- 设置
raft.Config.ElectionTick = 10（即 10 个 heartbeat tick 后触发选举），再通过raft.Config.TickInterval控制基础 tick 间隔（建议 100–500ms） - 公式：实际 election timeout ≈
ElectionTick × TickInterval，公网环境建议 ≥ 3000ms - 务必同步调整所有节点的配置，哪怕只改一个节点也会破坏 quorum 判断
如何安全地增删节点
raft 不支持运行时直接修改成员列表。用 raft.ProposeConfChange 提交配置变更，但必须确保客户端只对 leader 发起请求，且 leader 自身要先 apply 成员变更再对外提供服务。
常见坑：客户端轮询多个节点发起 AddNode 请求，结果多个节点并发提交冲突的 ConfChange，导致集群卡在中间状态。
- 所有成员变更操作必须经由当前 leader 处理；可通过定期调用
raft.Status().Lead判断本地是否为 leader，不是则重定向 - 提交
raftpb.ConfChange后，需监听raft.Ready中的Ready.CommittedEntries，确认该 entry 已 apply 才返回成功 - 删除节点前，先用
raft.RemoveNode从 raft 状态中移除，再关闭其网络连接；否则残留节点可能持续发送心跳，干扰新配置收敛
真正的难点不在代码量，而在状态机与网络边界的耦合控制——比如 snapshot 传输期间能否响应读请求、follower 落后多少才触发追赶、confchange 提交后旧节点是否还接受写入。这些细节不写死在模块里，就只能靠使用者自己兜底。
