基于 SOFAJRaft + Spring Boot 构建高可用 KV 存储集群（完整源码）

基于 SOFAJRaft + Spring Boot 构建高可用 KV 存储集群（完整源码）引言在分布式系统中，一致性是核心难题。Raft 是比 Paxos 更易于理解的共识算法，而 SOFAJRaft 是蚂蚁集团开源的 Java 高性能 Raft 实现。本文带你从零构建一个3 节点高可用 KV 存储集群，包含完整源码、Raft 选举与日志复制、Leader 自动故障转移，以及一个实时 Dashboard 用于可视化验证集群行为。**适用读者**：有 Java/Spring Boot 基础的开发者，对分布式共识感兴趣的同学**学到什么**：Raft 核心概念、SOFAJRaft 集成方式、状态机设计、Leader 重定向、故障转移实战1. 系统架构1.1 角色分配组件技术选型Raft 引擎SOFAJRaft 1.4.0应用框架Spring Boot 2.7.18KV 存储ConcurrentHashMap（状态机）节点 RPCBolt（JRaft 内置）客户端 APIREST (HTTP/JSON)1.2 端口分配节点HTTP (REST API)Raft RPCNode 180808081Node 280828083Node 3808480851.3 架构图┌──────────────────────────────────────────────────────────┐ │ Raft Cluster │ │ │ │ Node1(:8080) ──Raft RPC── Node2(:8082) ──Raft RPC── Node3(:8084) │ RPC:8081 RPC:8083 RPC:8085 │ (Follower) (Leader) (Follower) │ │ ▲ │ ▲ │ │ │ 307 Redirect │ Log Replication │ │ │ └────────────────────────┴────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────┘ ▲ │ HTTP REST ▼ Client (curl / Dashboard)所有写请求必须提交给 Leader。如果请求落在 Follower 上，返回307 Temporary Redirect自动转发到 Leader。2. 项目结构src/main/java/com/raftha/ ├── RaftHaApplication.java # Spring Boot 入口 ├── config/ │ ├── AppConfig.java # CORS + RestTemplate │ └── RaftProperties.java # 配置映射 + 校验 ├── raft/ │ ├── RaftServerBootstrap.java # JRaft 节点启动/停止 │ ├── KvStateMachine.java # KV 状态机（StateMachine） │ ├── SimpleLogStorage.java # 自定义日志存储 │ └── CustomJRaftServiceFactory.java # 服务工厂 └── controller/ └── KvController.java # REST API + Leader 重定向3. 完整代码实现3.1 pom.xml?xml version="1.0" encoding="UTF-8"? project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent groupIdcom.raftha/groupId artifactIdraft-ha-app/artifactId version1.0.0/version nameraft-ha-app/name properties java.version1.8/java.version jraft.version1.4.0/jraft.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.alipay.sofa/groupId artifactIdjraft-core/artifactId version${jraft.version}/version exclusions exclusion groupIdorg.apache.logging.log4j/groupId artifactIdlog4j-api/artifactId /exclusion exclusion groupIdorg.apache.logging.log4j/groupId artifactIdlog4j-core/artifactId /exclusion /exclusions /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build /project3.2 启动入口package com.raftha; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class RaftHaApplication { public static void main(String[] args) { SpringApplication.run(RaftHaApplication.class, args); } }3.3 配置映射与校验package com.raftha.config; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.stereotype.Component; import javax.annotation.PostConstruct; import java.util.List; @Component @ConfigurationProperties(prefix = "raft") public class RaftProperties { private int serverId; private String serverAddr; private ListString peers; private ListString httpAddrs; private String dataPath; private int electionTimeoutMs = 300; private int heartbeatIntervalMs = 100; // JRaft 1.4.0 内部推导 private int snapshotIntervalSecs = 3600; @PostConstruct public void validate() { if (serverAddr == null || serverAddr.trim().isEmpty()) throw new IllegalStateException("raft.server-addr must not be empty"); if (peers == null || peers.isEmpty()) throw new IllegalStateException("raft.peers must not be empty"); if (httpAddrs == null || httpAddrs.isEmpty()) throw new IllegalStateException("raft.http-addrs must not be empty"); } // getters setters... }3.4 节点配置文件application-node1.yml（节点 1，HTTP 8080 / RPC 8081）：server: port: 8080 raft: server-id: 1 server-addr: 127.0.0.1:8081 peers: - 127.0.0.1:8081 - 127.0.0.1:8083 - 127.0.0.1:8085 http-addrs: - http://127.0.0.1