Storage 存储引擎¶

本文件系统性阐述基于 BoltDB（bbolt）的嵌入式存储引擎实现，涵盖数据持久化机制、键值存储设计、事务处理、集合元数据存储、向量点数据序列化、批量操作优化、性能特征与磁盘使用模式、内存映射策略、配置选项、备份恢复、性能调优以及可靠性保证与扩展性。文档同时提供面向初学者的概念讲解与面向专家的底层实现细节，并通过具体代码示例路径帮助快速上手。

项目结构¶

该仓库采用按领域分层的组织方式：核心业务逻辑位于 core 包，命令行入口位于 cmd 目录，示例位于 example 目录，协议定义位于 core/proto。存储引擎位于 core/storage.go，配合 collection.go 提供集合级抽象，quantization.go 提供向量量化能力，models.go 定义数据模型与过滤器，proto 文件定义序列化结构。

graph TB
subgraph "核心包 core"
A["storage.go
存储引擎"]
B["collection.go
集合抽象"]
C["quantization.go
向量量化"]
D["models.go
数据模型/过滤器"]
E["proto/point.proto
PB 模型"]
end
subgraph "命令行"
F["cmd/govector/main.go
服务端入口"]
G["example/embedded/main.go
嵌入式示例"]
H["cmd/bench/main.go
基准测试"]
end
A --> E
B --> A
B --> D
C --> A
F --> A
F --> B
G --> A
G --> B
H --> B

核心组件¶

存储引擎 Storage：封装 bbolt 数据库，提供集合桶管理、点数据的增删改查、集合元数据的持久化与加载、批量写入与删除、关闭与状态检查。
集合 Collection：在存储之上提供线程安全的集合抽象，负责维度校验、版本号生成、持久化优先的一致性策略、索引更新与回滚尝试。
向量量化 Quantizer/SQ8Quantizer：提供 8 位标量量化接口与实现，用于压缩向量以降低磁盘占用。
数据模型与过滤器：定义点结构、评分结果、过滤条件、匹配类型与范围条件，支持多种匹配策略。
协议定义：通过 protobuf 定义点结构、评分点、过滤器等消息格式，确保跨语言/跨进程的稳定序列化。

架构总览¶

存储引擎采用“集合即桶”的键值存储设计，每个集合对应一个 bbolt 桶；点数据以 Protocol Buffers 序列化后作为值存入，ID 作为键；集合元数据单独保存在一个特殊桶中，使用 JSON 序列化。写入流程遵循“先持久化再索引”的一致性策略，读取时根据是否启用量化决定解压与内存清理。

graph TB
S["Storage
bbolt + PB"]
M["元数据桶
__collections_meta__"]
C1["集合桶 A"]
C2["集合桶 B"]
P["点数据
PB 序列化"]
Q["量化器
SQ8Quantizer"]
S --> M
S --> C1
S --> C2
C1 --> P
C2 --> P
S -.可选.-> Q

详细组件分析¶

存储引擎 Storage 组件¶

初始化与关闭
NewStorage/NewStorageWithQuantization：打开 bbolt 数据库文件，支持可选量化器与量化开关。
Close：优雅关闭数据库连接，幂等设计。
集合管理
EnsureCollection：为集合创建桶（若不存在），每个集合独立桶。
ListCollections：枚举所有集合桶（排除元数据桶）。
点数据操作
UpsertPoints：批量写入点，支持量化压缩；序列化为 PB；键为点 ID。
LoadCollection：批量读取集合点，反序列化 PB；若启用量化则解压并清理临时字段。
DeletePoints：批量删除点，忽略不存在的 ID。
元数据管理
SaveCollectionMeta：将集合元数据写入特殊桶，JSON 序列化。
LoadCollectionMeta/ListCollectionMetas：读取单个或全部元数据。
错误处理与状态
所有方法在存储关闭状态下返回明确错误。
写入失败时返回带上下文的错误信息，便于定位问题。

classDiagram
class Storage {

    -db : bbolt.DB
    -closed : bool
    -quantizer : Quantizer
    -useQuant : bool
    +NewStorage(dbPath) Storage
    +NewStorageWithQuantization(dbPath, useQuant, quantizer) Storage
    +Close() error
    +EnsureCollection(name) error
    +UpsertPoints(colName, points) error
    +LoadCollection(colName) map[string]*PointStruct, error
    +ListCollections() []string, error
    +SaveCollectionMeta(name, meta) error
    +LoadCollectionMeta(name) *CollectionMeta, error
    +ListCollectionMetas() []CollectionMeta, error
    +DeletePoints(colName, ids) error

}

集合 Collection 组件¶

生命周期与一致性
NewCollection/NewCollectionWithParams：创建集合，自动确保桶存在，保存元数据，从存储加载现有点到内存索引。
Upsert：先持久化，再更新内存索引；若索引更新失败，尝试回滚删除已持久化的点，保持一致性。
Delete：先删除存储，再删除索引；支持按 ID 或过滤器删除。
线程安全
使用读写锁保护集合内部状态与索引访问。
查询
Search：委托给底层索引（Flat/HNSW），支持过滤器与 TopK。

sequenceDiagram
participant U as "调用方"
participant Col as "Collection"
participant St as "Storage"
participant Idx as "VectorIndex"
U->>Col : Upsert(points)
Col->>Col : 校验维度/生成版本
Col->>St : UpsertPoints(name, points)
St-->>Col : 成功/失败
Col->>Idx : Upsert(points)
Idx-->>Col : 成功/失败
alt 索引失败
Col->>St : DeletePoints(name, ids)
St-->>Col : 回滚完成
end
Col-->>U : 返回结果

向量量化 Quantizer/SQ8Quantizer 组件¶

接口与实现
Quantizer：定义 Quantize/Dequantize/GetCompressedSize。
SQ8Quantizer：按向量最小/最大值归一化到 [0,255]，存储 min/max 与 8 位整数，解压时还原浮点向量。
存储集成
当启用量化时，UpsertPoints 将原始向量置空，将压缩后的字节串放入点的负载中，加载时解压并移除临时字段，节省内存。

flowchart TD
Start(["开始"]) --> CheckQuant{"启用量化?"}
CheckQuant --> |否| DirectStore["直接存储向量"]
CheckQuant --> |是| Compress["压缩向量为字节串"]
Compress --> StoreMeta["将压缩字节串写入负载
键名: __quantized_vector"]
DirectStore --> End(["结束"])
StoreMeta --> End

数据模型与过滤器¶

PointStruct/ScoredPoint：定义点 ID、版本、向量与负载。
Filter/Condition：支持 Must/MustNot 条件，支持精确匹配、范围、前缀、包含、正则。
匹配算法：MatchFilter/matchCondition/matchRange/matchPrefix/matchContains/matchRegex。

classDiagram
class PointStruct {

    +string ID
    +uint64 Version
    +[]float32 Vector
    +Payload Payload

}
class ScoredPoint {

    +string ID
    +uint64 Version
    +float32 Score
    +Payload Payload

}
class Filter {

    +[]Condition Must
    +[]Condition MustNot

}
class Condition {

    +string Key
    +ConditionType Type
    +MatchValue Match
    +RangeValue Range

}
class MatchValue {

    +interface{
} Value
}
class RangeValue {

    +interface{
} GT
+interface{} GTE
+interface{} LT
+interface{} LTE
}
Filter --> Condition
Condition --> MatchValue
Condition --> RangeValue

协议定义（Protocol Buffers）¶

PointStruct/Value/ScoredPoint/Filter/Condition/MatchValue：PB 消息定义，支持字符串、整数、双精度、布尔、字节等类型。
与存储的桥接：toProtoPoint/fromProtoPoint 在存储层负责与 PB 的转换。

classDiagram
class PointStruct {

    +string id
    +[]float vector
    +map~string,Value~ payload

}
class Value {

    +oneof value

}
class ScoredPoint {

    +string id
    +uint64 version
    +float score
    +map~string,Value~ payload

}
class Filter {

    +[]Condition must
    +[]Condition must_not

}
class Condition {

    +string key
    +MatchValue match

}
class MatchValue {

    +oneof value

}

依赖分析¶

外部依赖
bbolt：嵌入式键值数据库，提供 ACID 事务与只读视图。
protobuf：用于点结构与评分结果的高效序列化。
hnsw：可选的高性能近似最近邻索引（由集合层使用）。
内部耦合
Storage 依赖 bbolt 与 protobuf；Collection 依赖 Storage 与索引实现；Quantizer 与 Storage 解耦但被集成使用。
循环依赖
未发现循环依赖，模块边界清晰。

graph LR
BB["bbolt"] --> ST["Storage"]
PB["protobuf"] --> ST
ST --> CO["Collection"]
QU["Quantizer"] --> ST
CO --> IDX["VectorIndex(HNSW/Flat)"]

性能考虑¶

磁盘与内存映射
bbolt 基于 LSM-Tree 的变体，适合顺序写入与随机读取；通过批量写入减少事务开销。
量化可显著降低磁盘占用，但会引入解压成本；建议在高维向量场景开启。
事务与并发
写入使用 Update 事务，读取使用 View 事务；集合层使用读写锁隔离集合级并发。
批量操作
UpsertPoints/DeletePoints 支持批量，减少多次事务与系统调用开销。
查询路径
读取集合时可选择是否启用量化，避免不必要的解压；加载后清理临时字段释放内存。
基准测试
提供纯索引基准脚本，可用于评估 Flat/HNSW 在不同规模下的构建时间、延迟与吞吐。

故障排查指南¶

常见错误与处理
存储关闭：所有方法在存储关闭状态下返回错误，需确保在正确生命周期内使用。
集合不存在：Upsert/Load/Delete 对应桶不存在时的行为（Upsert 报错，Delete 忽略，Load 返回空）。
序列化失败：PB 序列化/反序列化错误会返回带上下文的错误，检查点结构与类型兼容性。
量化异常：解压失败或维度不一致会导致加载失败，检查量化器与存储数据一致性。
单元测试覆盖
测试包含基本 CRUD、量化、元数据、错误场景与关闭状态下的行为验证，可作为回归参考。

结论¶

该存储引擎以 bbolt 为基础，结合 PB 序列化与可选量化，在保证数据持久化与一致性的同时，提供了良好的性能与可扩展性。集合层通过“存储优先”的一致性策略与线程安全设计，使得嵌入式与微服务两种使用模式均具备工业级可靠性。对于大规模向量场景，建议结合量化与 HNSW 索引以获得更优的吞吐与延迟表现。

附录¶

使用示例（代码片段路径）¶

配置选项与最佳实践¶

存储配置
数据库路径：通过构造函数参数指定，建议使用绝对路径或稳定的相对路径。
量化开关：NewStorageWithQuantization 可启用 SQ8 量化，默认使用内置量化器。
性能调优
批量写入：合并小批次写入，减少事务次数。
量化策略：高维向量建议开启量化；注意查询时的解压成本。
索引选择：大规模数据优先 HNSW；小规模或低延迟要求可考虑 Flat。
备份与恢复
复制 bbolt 数据库文件即可完成物理备份；恢复时确保应用处于停止状态或使用只读模式。
元数据桶与集合桶均参与备份，确保重启后可自动发现集合。
可靠性与一致性
写入采用“存储优先”策略，失败时尝试回滚；集合层提供版本号与维度校验。
关闭存储前确保 Flush，避免数据丢失。
README.md:30-42