vredis

用 Rust 实现的、兼容 Redis RESP2 协议的迷你向量数据库。

Rust 1.98+ · 零第三方依赖 · MVP 采用暴力搜索保证正确性

5 分钟跑起来

cargo build
cargo run          # 监听 127.0.0.1:6379，等待 RESP2 客户端连接

• 默认监听 127.0.0.1:6379（仅本机回环）；端口被占用时打印明确提示并以退出码 1 退出，绝不自动更换端口。
• 跑测试（169 个，含真实 TCP 端到端）：cargo test

Docker 部署

docker build -t vredis .
docker run -d --name vredis -p 6379:6379 -v vredis-data:/app/data vredis

或使用 docker compose：

docker compose up -d
docker compose logs -f

数据持久化：vredis 的 WAL 与快照写在可执行文件所在目录下的 data/（design.md §3.1）， 镜像内二进制位于 /app/vredis，因此挂载点为 /app/data——compose 使用具名 volume vredis-data 挂载，容器重建/重启数据不丢；BGSAVE 快照与启动恢复机制在容器内照常工作。 容器以非 root 用户 vredis 运行（镜像内已预建 /app/data 并赋属主）。

支持的命令

KV 命令（兼容 Redis 语义与错误文案）

向量命令（本库扩展）

搜索引擎与 HNSW

VSEARCH 默认使用暴力搜索（O(N) 全量扫描，精确结果）。设置环境变量 VREDIS_HNSW=1 启用自研 HNSW 近似索引（O(log N) 图遍历）：

# docker-compose 示例
services:
  vredis:
    environment:
      - VREDIS_HNSW=1

• metric 一致性：查询 metric 与索引 metric（VADD 时锁定，缺省 cos）一致才走 HNSW； 不一致自动回落暴力搜索，保证正确性。
• 召回率实测（m=16, ef_construction=200, ef=100）：1k 点与 10k 点 recall@10 均为 1.0000。

真实会话记录 / 协议实测

本机无 redis-cli。以下为 PowerShell TCP 客户端驱动真实 vredis.exe（127.0.0.1:6379）的实测记录， | 是 RESP2 报文中 CRLF 的展示分隔符，内容逐字未改。RESP2 兼容性另由 36 个真实 TCP 集成测试保证（见 tests/integration.rs）。

=== PING
C> *1 | $4 | PING |
S> +PONG |

=== SET greet hello
C> *3 | $3 | SET | $5 | greet | $5 | hello |
S> +OK |

=== GET greet
C> *2 | $3 | GET | $5 | greet |
S> $5 | hello |

=== VADD faces 3 1.0 0.0 0.0
C> *6 | $4 | VADD | $5 | faces | $1 | 3 | $3 | 1.0 | $3 | 0.0 | $3 | 0.0 |
S> $1 | 0 |                                  ← 自动生成 id "0"

=== VADD faces 3 0.0 1.0 0.0
C> *6 | $4 | VADD | $5 | faces | $1 | 3 | $3 | 0.0 | $3 | 1.0 | $3 | 0.0 |
S> $1 | 1 |                                  ← 自动生成 id "1"

=== VSEARCH faces 1 1.0 0.0 0.0
C> *6 | $7 | VSEARCH | $5 | faces | $1 | 1 | $3 | 1.0 | $3 | 0.0 | $3 | 0.0 |
S> *2 | $1 | 0 | $1 | 0 |                    ← 扁平 [id="0", cos 距离="0"]

=== VDIM faces
C> *2 | $4 | VDIM | $5 | faces |
S> :3 |

=== GET faces（预期 WRONGTYPE）
C> *2 | $3 | GET | $5 | faces |
S> -WRONGTYPE Operation against a key holding the wrong kind of value |

架构

五层结构，依赖严格自上而下单向（详见 docs/design.md §1）：

客户端（redis-cli / 任意 RESP2 客户端）
  │ TCP，默认 127.0.0.1:6379
  ▼
① 网络层（src/net）
  TcpListener accept 循环；每个连接派生一个线程；阻塞式读写
  │
  ▼
② 协议解析层（src/protocol）
  请求方向：字节流 → RespValue        响应方向：RespValue → 字节流
  │
  ▼
③ 命令分发层（src/command）
  命令表（命令名 → 处理函数）；参数校验；Redis 风格错误文案
  │
  ├────────────────────────────┐
  ▼                            ▼
④ 存储层（src/storage）         ⑤ 向量索引层（src/vector）
  Db：key → Value 内存哈希表     距离度量：cos / l2 / dot
  Mutex<HashMap> 单把大锁        索引内暴力扫描 top-k（MVP 无 HNSW）

设计亮点

• 协议二进制安全：解析器绝不按行读取（bulk payload 可含 \r\n、\0），按声明长度切分； 含特殊字节的值从 SET 到 GET 端到端往返有专项测试。
• OOM 三重防护：bulk 长度上限 512MB（对齐 Redis proto-max-bulk-len）；数组元素上限 100 万 且绝不按声明数预分配；单连接输入缓冲 1GB 检查点（超限回错并断连）。
• 零第三方依赖：全部使用 Rust 标准库（std::net / thread / Mutex / BinaryHeap）， Cargo.toml 的 [dependencies] 为空。
• 锁纪律：VSEARCH 的距离计算与 top-k 收集在存储层单次持锁回调内完成， 绝不把整个索引克隆出锁外（对 10 万级向量索引是数量级差异）。
• 测试文化：169 个测试——协议层对 7 类消息做所有截断前缀的 Incomplete 断言、 恶意输入（$1000000000、*2000000000、65 层嵌套）防护测试、8 线程并发 KV 冒烟、 4 线程并发 VADD 的 id 唯一性验证。

运行环境

• Rust 1.98+（edition 2021；在 1.98.1 stable GNU 上开发验证）
• 无其他依赖，Windows / Linux / macOS 均可构建

持久化

• 数据目录：可执行文件所在目录下的 data/（Docker 镜像内为 /app/data），自动创建。
• 写路径先写 WAL 再改内存；BGSAVE 同步落快照（fsync + 原子替换）并截断 WAL。
• 启动时加载快照 + 重放 WAL；快照/WAL 损坏会明确报错退出，绝不静默丢数据。
• 破坏性变更（v0.4.0）：快照格式升级 v1→v2、WAL 记录带 metric—— v0.2.0 及更早的 data/ 目录不兼容，启动会明确报错，请删除后重新写入。

性能

实测数据（cargo run --release --bin bench，固定 seed 可复现；环境：Rust 1.98.1 GNU、 12th Gen Intel Core i5-12500H、Windows 11、32GB RAM；metric = l2，k = 10，100 查询； 不同批次运行存在正常计时抖动）：

规模趋势（ef_search = 100）：

ef_search 权衡（50k × 128 维）：

总结：HNSW 优势随规模扩大——1k 时常数开销主导反而慢于暴力，50k 时达 9.2×； 召回率可用 ef_search 换取（ef=800 时 0.93，仍比暴力快约 2×）。 诚实说明：128 维均匀随机是图索引的最坏情况（真实 embedding 有簇结构时召回 显著更高）；邻居裁剪为简单截断（论文启发式选择在 Roadmap）；小规模下 HNSW 常数开销主导、可能慢于暴力；ef_search 需按数据规模调节。

Roadmap / Known Limitations

以下为记录在案的未来方向，当前均未实现：

• HNSW 邻居选择启发式（论文 Algorithm 4，提升大规模图质量与召回率）
• 分片锁替代单把 Mutex
• VDEL（删除索引内单条向量）
• Graceful shutdown
• 流水线缓冲用 read_pos 指针替代 buf.drain（消除 O(n²)）

文档

• docs/design.md — 架构设计（v0.3）：分层、数据结构、命令语义、依赖选型
• docs/vredis-charter.md — 项目章程（最高规则）与 MVP 验收标准
• docs/acceptance.md — MVP 验收清单（8 条标准逐项复核）