# kv-cache

**Repository Path**: solidify-the-foundation/kv-cache

## Basic Information

- **Project Name**: kv-cache
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-07-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# kv-cache

> 一条主线项目，从「单机 KV」逐步演进到「Raft 分布式 KV」，把 Go 高阶能力（并发、运行时调优、网络编程、共识算法、工程化）一次性练透。
>
> 进度：**阶段 5 · Raft 分布式复制（已完成）** —— 主线五阶段收官

[English](./README.en.md) · 简体中文

---

## 路线（5 个阶段）

| 阶段 | 项目形态 | 核心练什么 | 状态 |
|------|----------|-----------|------|
| 0 | 工程骨架 | 项目布局、Makefile、CI、测试习惯 | ✅ |
| 1 | 单机 KV + RESP 协议 | TCP、协议解析、io 组合、基础并发 | ✅ |
| 2 | 并发优化与淘汰策略 | 分段锁、sync.Map、LRU/LFU、sync.Pool | ✅ |
| 3 | 运行时调优与可观测 | pprof、pipeline flush、Get 拷贝评估 | ✅ |
| 4 | 持久化与崩溃恢复 | WAL、快照、fsync、文件 IO | ✅ |
| 5 | 分布式：Raft 复制 | 共识、状态机、超时重试、网络分区 | ✅ |

---

## 当前能力

兼容 Redis RESP2 的最小 KV：`PING` / `ECHO` / `SET` / `GET` / `DEL` / `DBSIZE` / `QUIT` / `COMMAND`。

| 能力 | 开关 |
|------|------|
| 多种内存 Store | `-store=memstore\|sharded\|syncmap\|lru\|lfu` |
| WAL + 快照 | `-data-dir` / `-fsync` / `-snapshot-every` |
| pprof | `-pprof-addr` |
| Raft 三节点 | `-raft-id` / `-raft-addr` / `-raft-peers` |

文档：[stage-2](./docs/stage-2/sharded-store-benchmark.md) · [stage-3](./docs/stage-3/runtime-tuning.md) · [stage-4](./docs/stage-4/persistence.md) · [stage-5](./docs/stage-5/raft.md)

---

## 快速开始

```bash
make build
./bin/kvd                                    # 单机内存
./bin/kvd -data-dir ./data -store=sharded    # 持久化

# Raft 三节点
PEERS='1=127.0.0.1:7001,2=127.0.0.1:7002,3=127.0.0.1:7003'
./bin/kvd -addr 127.0.0.1:6381 -raft-id 1 -raft-addr 127.0.0.1:7001 -raft-peers "$PEERS" &
./bin/kvd -addr 127.0.0.1:6382 -raft-id 2 -raft-addr 127.0.0.1:7002 -raft-peers "$PEERS" &
./bin/kvd -addr 127.0.0.1:6383 -raft-id 3 -raft-addr 127.0.0.1:7003 -raft-peers "$PEERS" &
redis-cli -p 6382 SET foo bar   # 仅 leader 返回 OK
redis-cli -p 6381 GET foo       # 各节点本地读
```

---

## 目录结构

```
cmd/kvd/           # 入口：单机 / 持久化 / Raft
internal/
  resp/            # RESP2
  store/           # 内存 Store 实现
  persist/         # WAL + 快照
  raft/            # 最小 Raft + Memory/HTTP 传输
  server/          # TCP + Dispatcher（含 Raft 写路径）
docs/stage-{1..5}/
```

---

## 开发

```bash
make test && make race && make lint && make all
go test -count=1 ./internal/raft/
```

---

## 设计取舍一览

- 每连接一 goroutine + pipeline 攒批 flush
- Store 可插拔；`-data-dir` 装饰持久化
- 自研最小 Raft：写过 leader，读本地；分区用 MemoryTransport 测
- Raft 日志默认内存（状态机可叠 `-data-dir`）；无成员变更 / 无线性一致读