# 5dRaft

**Repository Path**: galaxy_0/5d-raft

## Basic Information

- **Project Name**: 5dRaft
- **Description**: 5Draft（五帝） 在标准 Raft 基础上，引入预测性健康感知与主动领导权移交机制，让集群从“被动等待故障”进化到“主动择优而居”。
1. Follower 上报健康：每次心跳响应中携带自身健康快照2. Leader 全局择优：Leader 维护所有 Follower 的健康视图，持续比较3. 预测让贤：当某 Follower 的健康分显著优于Leader且持续稳定时Leader 主动禅让
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-05
- **Last Updated**: 2026-09-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 5Draft（五帝）

**5Draft: A Predictive Health-Aware Raft with Proactive Leadership Transfer**

![Language](https://img.shields.io/badge/language-C%2B%2B17-blue)
![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20Windows%20%7C%20WSL-success)
![Build](https://img.shields.io/badge/build-CMake-orange)
![NuRaft](https://img.shields.io/badge/Raft-NuRaft-informational)
![License](https://img.shields.io/badge/license-MIT-green)

在标准 Raft 基础上引入**预测性健康感知**与**主动领导权移交（禅让）**，让集群从
“被动等待故障超时”进化为“主动择优而居”。

> *“不待其崩，择贤而让；观势推演，永续安康。”*

核心闭环：

1. **Follower 上报健康**：每次心跳响应（AppendEntries meta）携带自身健康快照
   （静态分 H + 一阶导 H' + 二阶导 H''）；
2. **Leader 全局择优**：Leader 维护所有 Follower 的健康视图，持续比较预测分；
3. **预测让贤**：当某 Follower 的预测性健康分显著优于 Leader 且持续稳定时，
   Leader 主动调用 NuRaft 原生 `yield_leadership(false, successor)` 优雅禅让。

## 设计原则

| 原则 | 说明 |
|------|------|
| 安全第一 | 日志完整性作为硬性门禁，完全继承 Raft Safety（由 NuRaft 原生保证） |
| 预测优先 | 一阶/二阶导数区分“瞬态抖动”与“持续劣化” |
| 主动交接 | Leader 通过心跳响应感知全局健康，主动让贤 |
| 改造最小 | 基于 NuRaft 扩展，不新增 RPC，仅复用 asio meta 通道 |
| 优雅降级 | 健康采集故障、meta 缺失或分数相近时，自动回退标准 Raft |

## 平台支持

| 平台 | 支持情况 | 说明 |
|------|----------|------|
| **Linux** | ✅ 已验证 | 健康采集读取 `/proc/stat`、`/proc/meminfo`；验证环境 Debian 13 + g++ 14.2 + CMake 3.31 |
| **WSL**（推荐开发环境） | ✅ 已验证 | WSL2 Debian，真实三节点 NuRaft 集群演示与全部测试均在此环境通过 |
| **Windows** | ✅ 支持 | 健康采集使用 `GetSystemTimes` / `GlobalMemoryStatusEx`；NuRaft/asio 官方支持 Windows 构建（心跳参数会自动切换为 1s/2–4s） |
| **macOS** | ⚙️ 理论支持 | NuRaft 与 asio 均支持 macOS；健康采集暂未实现（未提供平台接口时返回中性默认值并降级），欢迎贡献 |

编译器要求：支持 **C++17** 的编译器（GCC ≥ 7 / Clang ≥ 6 / MSVC ≥ 2019 16.x）。
核心库 `libdraft5` 仅依赖 C++17 标准库与 pthread；NuRaft 集成库额外依赖
asio 与 zlib（Debian/Ubuntu：`apt-get install -y libasio-dev zlib1g-dev`）。

## 目录结构

```
5dRaft/
├── CMakeLists.txt
├── include/draft5/
│   ├── health_types.hpp        # 健康快照/网络传输结构 + 预测分公式
│   ├── trend_analyzer.hpp      # 滑动窗口 + 最小二乘法求 H'/H''
│   ├── health_monitor.hpp      # CPU/内存/RTT 采集（Linux + Windows）
│   ├── message_extension.hpp   # 健康快照 <-> 心跳 meta 编解码
│   ├── active_scheduler.hpp    # 主动调度器（择优 + 连续计数防抖 + 禅让）
│   ├── vote_extension.hpp      # 健康感知投票决策（Lease 失效回退标准 Raft）
│   ├── five_draft_node.hpp     # 节点集成层（统一入口 + 混沌演练注入）
│   ├── raft_interface.hpp      # Raft 抽象接口（与具体实现解耦）
│   ├── logger.hpp              # 轻量日志宏
│   ├── nuraft_adapter.hpp      # NuRaft 适配（IRaftServer + 4 个 meta 回调）
│   ├── nuraft/                 # 真实 NuRaft 节点组件
│   │   ├── nuraft_node.hpp           # raft_launcher + tick 线程 + 5Draft
│   │   ├── nuraft_state_machine.hpp  # 最小内存态状态机
│   │   └── nuraft_logger.hpp         # NuRaft 日志桥接
│   └── sim/sim_cluster.hpp     # 仿真集群（无网络依赖的闭环演示/测试）
├── src/                        # 上述模块实现
├── demo/
│   ├── main.cpp                # 仿真演示（劣化禅让/抖动抑制/投票决策）
│   ├── nuraft_demo.cpp         # 真实 NuRaft 三节点集群禅让演示（混沌注入）
│   └── nuraft_real_test.cpp    # 全链路真实验证（真实 CPU 压力，无 Mock）
├── tests/test_main.cpp         # 31 项单元测试
├── third_party/NuRaft/         # NuRaft 源码（git 子模块，gitee 镜像，Apache-2.0）
├── doc/方案.md                  # 完整设计方案
├── doc/blog-5draft.md          # 项目宣传博客（含 mermaid 架构/时序图）
├── doc/使用说明书.md            # 用户使用说明书（API/配置/集成/运维）
├── doc/测试报告.md              # 测试报告（单元/仿真/真实集群/全链路验证）
├── LICENSE                     # MIT 开源协议
└── README.md
```

## 依赖

- C++17 编译器（验证环境：WSL Debian，g++ 14.2）
- CMake ≥ 3.26（NuRaft 要求）
- [NuRaft](https://gitee.com/mirrors/NuRaft.git)（以 git 子模块提供）
- asio（Debian/Ubuntu：`apt-get install -y libasio-dev`）
- zlib（`apt-get install -y zlib1g-dev`）；OpenSSL 可选

### 获取源码（含子模块）

```bash
git clone --recursive https://gitee.com/galaxy_0/5d-raft.git
# 若已克隆但缺子模块：
git submodule update --init --recursive
```

## 构建（WSL / Linux）

```bash
cd /mnt/e/work/development/5dRaft/5dRaft   # 你的项目路径
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
ctest --test-dir build --output-on-failure
```

产物：

| 目标 | 说明 |
|------|------|
| `libdraft5.a` | 5Draft 核心库（健康采集、趋势分析、主动调度、投票决策、消息扩展） |
| `libdraft5_nuraft.a` | 真实 NuRaft 集成库（链接 `libnuraft.a`） |
| `5draft_demo` | 仿真集群演示（无需 NuRaft 网络） |
| `nuraft_demo` | **真实 NuRaft 三节点集群**上的主动禅让演示（混沌注入触发） |
| `nuraft_real_test` | **全链路真实验证**：真实集群 + 真实 CPU 压力（内核记账）触发禅让 |
| `unit_tests` | 单元测试（31 项） |

## 运行演示

### 1. 仿真闭环演示

```bash
./build/5draft_demo
```

- 场景 1：Leader 健康缓慢劣化 → 连续 3 个周期预测分显著落后 → **主动禅让**；
- 场景 2：Leader 单周期瞬态抖动后恢复 → 二阶导识别恢复 + 连续计数防抖 → **不切换**；
- 场景 3：Lease 有效时健康择优投票 / Lease 失效回退标准 Raft。

### 2. 真实 NuRaft 集群演示

```bash
./build/nuraft_demo
```

在本机启动 3 个真实 NuRaft 节点（`127.0.0.1:25011~25013`），完成组阁与
初始选举后，对 Leader 注入“持续劣化”混沌健康（`BeginDrill`），Follower 保持
真实健康。心跳 meta 中健康数据持续交换，ActiveScheduler 连续 3 次判定 Follower
预测分显著更优后，调用 **NuRaft 原生 `yield_leadership(false, successor)`**
优雅禅让，程序观测到 Leader 切换后输出 `[PASS]`。

### 3. 全链路真实验证（无 Mock）

```bash
./build/nuraft_real_test
```

与 `nuraft_demo` 的区别：**不注入任何健康数据**。3 个真实 NuRaft 节点组阁后，
对当前 Leader 启动 `nproc` 个占空自旋业务线程（约 85% 占空比），这些线程
注册到 Leader 的健康监控器，其 CPU 消耗由内核真实记账（Linux 读
`/proc/self/task/<tid>/stat` 的 utime/stime）。程序逐项打印真实采集数据
（CPU 可用率、内存、健康分、预测分）并自动检查：

1. 集群组阁成功；
2. 基线期 Leader 真实 CPU 可用率 > 0.9、健康分 > 0.75；
3. 施压后 Leader 真实 CPU 可用率降至 < 0.5（实测约 0.18）；
4. Leader 预测健康分真实下滑（实测 0.93 → 0.14）；
5. ActiveScheduler 主动禅让（`yield_leadership`），term 递增且全员一致；
6. 卸载压力后旧 Leader CPU 可用率真实恢复 > 0.9。

实测输出见 [doc/blog-5draft.md](doc/blog-5draft.md)。

### 4. 单元测试

```bash
./build/unit_tests
```

覆盖：趋势分析（劣化检测/毛刺过滤/钳制）、消息编解码（含脏数据降级）、
主动调度（连续计数触发/分差不足不触发/乒乓抑制）、投票决策、仿真端到端禅让。

## 在 NuRaft 工程中集成 5Draft

```cpp
#include "draft5/nuraft/nuraft_node.hpp"

draft5::nuraft_support::NuraftNode::Options opts;
opts.id = 1;
opts.host = "127.0.0.1";
opts.port = 25000;
opts.weights = draft5::HealthWeights::LatencySensitive();  // 权重模板
opts.sched.threshold = 0.08;            // 预测分差值阈值
opts.sched.consecutive_required = 3;    // 连续优于次数（防抖）

draft5::nuraft_support::NuraftNode node(opts);
node.Init();              // 内部完成：健康采集线程、meta 回调安装、Leader tick 线程
// Leader 侧加入成员：
node.AddPeer(2, "127.0.0.1:25001");
```

关键映射：

- 5Draft `IRaftServer::transfer_leadership(id)` → NuRaft
  `raft_server::yield_leadership(false, successor_id)`（暂停写入 → 继任者追平日志
  → 优雅退位）；
- 健康快照通过 `asio_service::options` 的 `write/read_req/resp_meta_` 四个回调
  随心跳与投票消息携带，**不新增 RPC**；
- 日志完整性投票门禁由 NuRaft 原生保证；Lease 失效时 `VoteDecider` 回退标准 Raft。

## 配置参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `threshold` | 0.08 | 预测分差值阈值（建议 0.05~0.1） |
| `consecutive_required` | 3 | 连续优于 Leader 的次数（防抖） |
| `check_interval_ms` | 50 | Leader 检查间隔 |
| `window_size` | 6 | 趋势分析滑动窗口（采样点） |
| `alpha` | 4.0 | 预测外推心跳周期数 |
| `beta` | 0.5 | 二阶修正系数 |
| 权重模板 | CPU/Mem/Net | 计算密集 0.5/0.2/0.3；内存密集 0.2/0.5/0.3；延迟敏感 0.2/0.2/0.6 |

调优建议：先以干跑模式（只打日志不切换）观察健康分波动，取 3σ 作为阈值。

## 开源协议

本项目原创代码（`include/draft5/`、`src/`、`demo/`、`tests/`）采用
**[MIT License](LICENSE)** 开源，Copyright © 2026 宋炜。

项目中包含的第三方组件保持其原有协议，不受 MIT 协议影响：

| 组件 | 协议 | 说明 |
|------|------|------|
| [NuRaft](https://gitee.com/mirrors/NuRaft.git) | Apache-2.0 | 以 git 子模块位于 `third_party/NuRaft`；本项目链接其静态库，并复用 `examples/` 下的内存态 state manager / log store（Apache-2.0） |
| [Asio](https://think-async.com/Asio/) | Boost Software License 1.0（standalone 模式） | NuRaft 的网络层依赖，系统包 `libasio-dev` 提供 |
| zlib | zlib License | NuRaft 可选压缩依赖，系统包 `zlib1g-dev` 提供 |

MIT 协议允许自由使用、修改、分发与商用，唯一要求是在副本中保留版权声明与
许可声明。