⚠️ 项目处于开发早期 · 当前版本 v0.0.0 · 敬请期待！

轻量化分布式 KV 存储系统 面向中小规模集群（3-100 节点）的去中心化分布式数据库，支持单机-分布式一体架构

• Go 1.21+
• 100MB+ 可用磁盘空间

# 克隆仓库
git clone https://github.com/jzhang405/NexKV.git
cd NexKV

# 构建二进制文件
go build -o bin/nexkv cmd/nexkv/main.go

# 运行节点
./bin/nexkv --config configs/config.yaml

# configs/config.yaml (三级配置结构 - PR-037)
cluster:
  name: "nexkv-cluster"
  base_dir: "~/.nexkv"  # 可被 NEXKV_BASE_DIR 环境变量覆盖

  hosts:
    - host_id: "host-1"
      seed_node: "/ip4/127.0.0.1/tcp/9211"

      nodes:
        - node_id: "node-1"
          role: "leaf"

# 注意：元数据目录现在由 {base_dir}/{host_id}/metadata 自动管理
# 数据目录现在由 {base_dir}/{host_id}/{shards|wal|snapshots} 自动管理

# 启动第二个节点
./bin/nexkv --config configs/node2.yaml

# 元数据自动同步，后台异步迁移数据
# 无需停机，平滑扩展为分布式集群

⭐ 最新架构：基于 DDD（Domain-Driven Design）的 5 层精简架构，47 个统一接口

flowchart TB
    subgraph L5["Layer 5: API 层"]
        API["KVClient<br/>TxClient"]
    end

    subgraph L4["Layer 4: 控制平面层"]
        Cluster["集群管理<br/>分片路由<br/>负载均衡<br/>选举"]
    end

    subgraph L3["Layer 3: 数据平面层"]
        Data["副本管理<br/>事务一致性<br/>Quorum/EC"]
    end

    subgraph L2["Layer 2: 存储引擎层"]
        Storage["双存储引擎<br/>Metadata KV + External KV"]
    end

    subgraph L1["Layer 1: 基础设施层"]
        Infra["网络通信<br/>GoroutineProvider<br/>AsyncOperation[T]<br/>可暂停调度器"]
    end

    API --> Cluster
    Cluster --> Data
    Data --> Storage
    Storage --> Infra

    style L5 fill:#e1f5ff,stroke:#333,stroke-width:2px
    style L4 fill:#fff4e6,stroke:#333,stroke-width:2px
    style L3 fill:#f3e5f5,stroke:#333,stroke-width:2px
    style L2 fill:#e8f5e9,stroke:#333,stroke-width:2px
    style L1 fill:#fff9c4,stroke:#333,stroke-width:2px

总计: 47 个统一接口 | 89 个实现文件

⭐ 核心能力：为 M2 存储引擎提供异步能力基础

核心实现：

• ✅ WALGroupCommit - 组提交机制，批量 fsync 优化吞吐量
• ✅ WALBatchReader - 批量 WAL 读取，优化恢复性能
• ✅ WALCodec - 统一的编解码接口，支持 JSON/MessagePack
• ✅ WALRotation - WAL 文件轮转，防止单文件过大
• ✅ 快照优化 - 快照命名优化为 .snap 扩展名

测试改进：

• 新增 12 个测试用例，覆盖批量操作场景
• 新增 20+ 编解码性能基准测试
• 测试覆盖率从 56% → 72%

性能对比（编解码 Benchmark）：

1. Fork 项目到你的 GitHub 账号
2. 创建功能分支：git checkout -b feature/your-feature
3. 遵循 PR 全流程（Pre 文档 → 开发 → 测试 → Post 文档）
4. 提交更改：git commit -m 'feat: add some feature'
5. 推送分支：git push origin feature/your-feature
6. 创建 Pull Request

遵循 Conventional Commits 规范：

<type>(<scope>): <subject>

type: feat | fix | docs | style | refactor | test | chore
scope: 模块名称
subject: 简短描述（不超过 50 字符）

• 遵循 docs/03_development/01_编码规范文档.md 定义的编码规范
• 所有公开接口必须有注释
• 复杂逻辑必须有解释说明
• 禁止使用魔法数字和魔法字符串
• 错误处理必须显式，禁止忽略
• CI/CD 通过：所有测试、lint、格式化检查

本项目基于 AGPL-3.0 许可证开源。详见 LICENSE 文件。

• Issues: GitHub Issues
• Discussions: GitHub Discussions

文档版本: v1.2 当前版本: v0.0.0（开发早期） 最后更新: 2026-01-22 维护者: NexKV 开发团队 测试覆盖率: 72.0%