不建议裸机硬啃Raft，需先验证Go模块、网络绑定、存储初始化及客户端重定向等基础配置；否则易卡在节点不可见、端口冲突、panic或请求静默丢弃等问题。
直接上手测试 Raft 或 Paxos 前，先确认你不是在裸机上硬啃——go 环境本身没问题，但分布式一致性算法的验证依赖网络通信、状态持久化和多节点协同，跳过基础校验会卡在「节点互相看不见」这种低级问题上。
检查 go version 和 GOPATH 是否实际生效
很多人执行 go version 看到 1.21+ 就以为万事大吉，但 go build 报 cannot find module providing package github.com/hashicorp/raft，往往是因为没开模块模式或 GO111MODULE=on 没生效。
- 运行
go env GOPATH和go env GOMOD，确认输出路径合理且GOMOD不是空字符串 - 新建测试目录，执行
go mod init testraft，再go get github.com/hashicorp/raft@v1.7.0（注意用稳定 tag，别用main分支） - 如果
go list -m all里没出现github.com/hashicorp/raft，说明模块未真正拉取，常见原因是 proxy 设置失效或公司内网拦截
用 hashicorp/raft 启动最小三节点集群时端口冲突最常见
官方示例常写 raft.NewRaft(config, fsm) 就完事，但真实测试必须显式绑定网络地址。否则三个进程默认都监听 :8080 或 localhost:0（随机端口），导致第二个节点启动就报 listen tcp :8080: bind: address already in use。
- 每个节点的
transport必须指定唯一监听地址，例如：raft.NewTCPTransport("127.0.0.1:9001", nil, 3, 10*time.Second, os.Stderr) - 节点间通信地址（即其他节点要 dial 的地址）要填对，比如节点 B 的地址是
127.0.0.1:9002，那节点 A 的 peer 列表里就得写"B": "127.0.0.1:9002"，不能只写端口号 - Windows 下若用 WSL2，
127.0.0.1在不同子系统间不通，得换成host.docker.internal或宿主机真实 IP
raft.LogStore 和 raft.StableStore 不初始化就会 panic
hashicorp/raft 要求传入的 LogStore 和 StableStore 非 nil，哪怕你只想内存跑通流程。直接传 nil 会触发 panic: log store is nil，错误信息不提示该填啥，新手容易懵。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
- 快速验证可用
raft.NewInmemStore()，它返回一对内存版LogStore和StableStore - 但注意：内存存储重启即丢，测试选举或日志复制可以，测故障恢复（如 kill leader 后重启）必须换
boltDB或badger - 若用
raft.NewLogCache(raft.NewInmemStore(), 32)，缓存大小单位是「条目数」不是字节，设太小（如 1）会导致日志截断，后续Apply失败
客户端请求发给 follower 时没有自动重定向
hashicorp/raft 默认不处理 HTTP 层转发。你用 curl 发 POST http://localhost:9002/apply 到 follower，它不会像 etcd 那样返回 307 Temporary Redirect 到 leader，而是直接返回 400 Bad Request 或静默丢弃。
- 必须自己实现「是否 leader」判断：调用
raft.State() == raft.Leader，否则直接拒绝请求 - 或者加一层代理逻辑：follower 收到请求后，用
raft.Leader()获取当前 leader 地址，再用http.Client转发过去 - 别依赖
raft.AddPeer返回值判断 leader —— 它只表示配置变更提交成功，不保证当前节点已是 leader
最容易被忽略的是：Raft 的「已提交日志」不等于「已应用」。你看到 raft.Apply() 返回了 future.Error() 为 nil，只代表日志已写入本地 log store；真正执行业务逻辑（比如更新 map）是在 FSM 的 Apply 方法里，这里出 panic 才会导致整个节点 crash，且无日志提示——得开 raft.Logger 并设为 debug 级才能捕获。
