seekdb 数据库架构图（源码导览）

一、seekdb 是什么

seekdb 是 OceanBase 团队推出的、面向 AI Agent 状态存储 (state store) 的多模态数据库：同时承载 向量 / 全文 / 关系 三类数据，对外完全兼容 MySQL 协议，可作为嵌入式库、单机 Server 或分布式集群运行。 它继承自 OceanBase 的 SQL 优化器与 LSM-Tree 存储引擎，并针对 Agent 的 「流式写 + 毫秒级检索 + 并发查询」工作负载，重写了索引构建路径，并提供 Kernel-level Copy-on-Write 沙箱。

• 三态部署一致性：嵌入式 / Server / 分布式共享同一份 oceanbase_static 内核库（见 src/observer/embed/CMakeLists.txt）。
• 多租户单进程：src/observer/omt 把同一个 observer 进程切分为多个独立租户。
• Paxos 复制日志：src/logservice/palf（Paxos-based Append-only Log File）。
• LSM-Tree + MVCC 存储：src/storage/memtable + src/storage/blocksstable。
• 异步索引流水线：src/share/change_stream/ 解耦 DML 与索引构建，消除 P99 抖动。
• 两级 HNSW 向量索引：src/share/vector_index/ + storage/ddl/ob_hnsw_embedmgr.*。
• COW Fork 沙箱：src/rootserver/fork_table/ + share/ob_fork_table_util.*。

二、整体分层架构

从客户端协议到底层物理存储，seekdb 由六个逻辑层组成。每一层既在嵌入模式下作为函数调用栈存在，也能在 Server 模式下被网络与 RPC 框架横向切分到多节点：

三、三种部署形态

3.1 嵌入模式（Embedded）

• 入口位于 src/observer/embed/{c,python,android}。
• C API（seekdb.h）：seekdb_open / seekdb_connect / seekdb_execute / seekdb_prepare / seekdb_step，仿 SQLite 风格 (SEEKDB_OK / SEEKDB_ROW / SEEKDB_DONE)。
• Python 绑定：ob_embed_impl.cpp，pybind11；亦可通过 SEEKDB_NO_PYTHON 编出纯 C 库供 Go/Android 复用。
• Android：android/seekdb_jni.cpp 通过 JNI 桥接 C 库；client/embedded_client.c 是 NDK 交叉编译的 CLI。
• 无网络栈、无 RPC，函数调用直达 SQL → Storage。

3.2 单机 Server 模式

• 启动入口：src/observer/main.cpp → ob_server.cpp::ObServer。
• 对外暴露 MySQL Wire Protocol（端口 2881）+ 内部 RPC（端口 2886）。
• 单 observer 进程内 多租户共存，sys/user 租户隔离 CPU、内存、IO。

3.3 OceanBase 分布式模式

• 多 observer 节点组成 Zone/Region。
• 每个 partition（即 LS / tablet）有三副本，使用 PALF 做 Paxos 复制。
• RootServer 服务在 sys 租户内运行，负责调度、Schema、负载均衡。

四、源码顶层目录

五、Observer 接入与调度层

Observer 是整个进程的大门。它负责接收客户端请求、按租户调度执行、并把请求转换成 SQL 引擎可识别的格式。代码位于 src/observer/。

5.1 关键文件

5.2 多租户 (OMT) 设计

• 每个租户拥有自有 worker pool + retry queue + 内存隔离上下文；越界请求被排队或拒绝。
• 用户租户之外存在 sys tenant（id=1），运行 RootServer、调度内部 SQL。
• 线程通过 MTL_SWITCH(tenant_id) 切换到目标租户上下文执行，所有模块对应的 MTL(Module*) 单例都按租户隔离。

六、SQL 引擎

SQL 引擎位于 src/sql/，是 OceanBase 历经多年沉淀的核心，seekdb 在其上扩展了向量、FTS、混合检索算子与 FORK/MERGE 语义。

6.1 子模块一览

6.2 SQL 执行链路

6.3 向量 / 全文相关的 DAS 算子

• das/ob_vector_index_lookup_op.cpp — 向量索引 ANN 查找（HNSW / IVF），结果按距离回表。
• das/ob_text_retrieval_op.cpp — 倒排表扫描，支持 MATCH AGAINST。
• das/ob_das_vec_define.cpp — 向量 DAS 任务结构。
• das/ob_das_domain_utils.cpp — 文本/向量等"领域索引"通用入口。

七、存储引擎

位于 src/storage/，是经典的 LSM-Tree + MVCC 架构。一个表被分成多个 tablet，多个 tablet 隶属于一个 LS (Log Stream)，LS 是复制和事务的最小单位。

7.1 关键概念

7.2 模块清单

八、事务子系统

位于 src/storage/tx/。seekdb 完整继承 OceanBase 的 MVCC + 2PC + Paxos 事务设计。

• GTS（Global Timestamp Service）：通过 ob_timestamp_service.cpp / ob_gts_source.cpp 提供全局单调递增时间戳作为 MVCC 版本。
• MVCC：行多版本由 memtable 链维护；读用 snapshot version 进行可见性判断。
• 分布式事务：跨 LS 写入走 2PC；ob_one_phase_committer 优化单 LS 提交。
• 多源数据 (MDS)：DDL、TableLock、auto-inc 元数据等附挂在事务里，与数据一起落 CLOG。

九、LogService（PALF 复制日志）

位于 src/logservice/，是分布式一致性、灾备、CDC 的统一底座。

9.1 子目录

十、RootServer（集群大脑）

仅 sys 租户启动，位于 src/rootserver/。负责 schema、调度、备份、DDL 串行化、Fork/Merge、合并冻结等。

• DDL service：CREATE/ALTER/DROP/INDEX 等全部串行化执行；产生 schema 版本，通过 schema service 广播。
• fork_table：核心实现 FORK DATABASE / FORK TABLE，下面专门展开。
• mview：物化视图刷新调度，对接 Change Stream。
• ai_model：注册外部 LLM/Embedding 模型；与 share/ai_service/ 协同。
• ccl（Concurrency Control）：限流规则 DDL。

十一、share 公共服务

src/share/ 是跨 SQL、Storage、RS 的横切层，集中存放公共服务、跨节点 RPC、缓存、AI 集成。

十二、Change Stream 异步索引流水线 ★ Agent 性能关键

位于 src/share/change_stream/。这是 seekdb 区别于 OceanBase 的核心新增模块， 也是「写路径不碰索引」、「查询永远只扫两层索引」得以成立的根因。

12.1 概念

普通 LSM 数据库写入时同步构建索引（向量/全文/物化视图），引起 P99 抖动；seekdb 让事务只写 redo， 索引由独立流水线从 PALF 异步消费 redo 构建。

12.2 关键组件

12.3 行可见性 / Rollback 支持

• 每条 redo 携带 stmt_seq_no，与 tx 的 rollback 区间集合 [to_seq, from_seq) 比较；命中区间的行直接丢弃，避免把已回滚的写入构建到索引。
• Fetcher 的 min_dep_lsn / refresh_scn 周期性写入全局表，使查询路径知道「索引追到了什么时间点」。

12.4 关键文件

十三、向量索引（两级 HNSW / IVF） ★

实现位于 src/share/vector_index/ + src/storage/ddl/ob_hnsw_embedmgr.* + sql/das/ob_vector_index_lookup_op.cpp。底层算法库通过 VSAG（OceanBase 开源的向量索引内核）实现。

13.1 两级索引架构

13.2 关键类

13.3 支持的索引参数

十四、全文检索（FTS）

分词器与查询入口分布在 src/storage/fts/ 与 share/ob_fts_index_builder_util.*。

14.1 内置分词器

14.2 关键文件

十五、Hybrid Search 混合检索

src/share/hybrid_search/ 提供了 Pinecone 风格的 JSON 查询入口，把 向量 + 全文 + 标量 翻译成一条 SQL Plan。

关键文件：ob_hybrid_search_executor.cpp、ob_query_translator.cpp、ob_query_parse.cpp、ob_query_request.cpp、ob_request_base.cpp。

十六、FORK / MERGE COW 沙箱 ★ Agent 探索安全网

实现位于 src/rootserver/fork_table/ + share/ob_fork_table_util.* + storage/ddl/ob_tablet_fork_task.*。这是 seekdb 区别于普通 DB 的另一个核心新特性。

16.1 概念

「FORK」并不真正复制数据；它在 schema 层为目标库/表创建新的 ID，并把所有 tablet 标记为 共享基线 + 写时复制 (Copy-on-Write) 模式。Agent 在沙箱里读写时：

• 读 = 旧 tablet 数据 + 沙箱自有增量；
• 写 = 只落到沙箱独有的 memtable / SSTable；
• 主库完全不受影响。

16.2 执行流程

16.3 关键文件

十七、Plugin 框架

src/plugin/ 提供动态加载机制（FT Parser、UDF、Storage engine 等）。

十八、PL 引擎 & ObJIT

十九、典型数据流

19.1 流式写 + 立即可查（Agent Memory）

19.2 混合检索一条 SQL 多模态下推

19.3 FORK / MERGE 沙箱生命周期

二十、组件能力总表

附 A · LSM-Tree 存储引擎深入

A.1 一行数据的一生

A.2 LSM 三层物理结构

A.3 与 RocksDB 的差异

A.4 Macro / Micro Block 物理布局

• Micro Block 16KB：解压/解码的最小单位，进 Block Cache。
• 列编码（blocksstable/encoding）：DICT、CONST、INTEGER、HEX_STRING、COLUMN_EQUAL、BIT_PACKING…每列独立选最优编码，含 AVX2/Neon 加速。
• 列存 Column Group：分析查询只读必要列，I/O 极省。
• Bloom Filter Cache：每个宏块独立训练，过滤负命中。
• 多级 Index Block：N 级 B+Tree-like 索引块，定位行只需 O(log N) 次 IO。

A.5 读路径的"行融合"

附 B · MVCC 实现深入

B.1 三个核心数据结构

B.2 写入：mvcc_write 的并发控制

B.3 提交：「延迟打版本号」

1. 事务 T 发起 commit；从 GTS 拿到全局严格单调的 commit_version (SCN)。
2. 写 redo 到 PALF；多数派落盘后认定 commit 成功。
3. 遍历 ObMemtableCtx.callback_list_：把所有该事务挂上去的 TransNode 的 trans_version_ 从 MAX 改写为 commit_version。
4. 从此该版本对所有 snapshot_version ≥ commit_version 的读可见。

B.4 回滚 / Rollback to Savepoint

• 整事务 rollback：遍历 callback_list_，把每个 TransNode 标记为 ABORTED 或直接从版本链摘除。
• Rollback to Savepoint：每条 DML 携带 seq_no_；rollback 给出区间 [to_seq, from_seq)，命中区间的节点不可见。Change Stream 也复用同一套区间判定。

B.5 读：可见性判定算法

B.6 并发原语

B.7 GTS：MVCC 的心脏

• GTS 服务（storage/tx/ob_timestamp_service.cpp）：sys 租户的 LS-1 是 GTS leader，提供单调递增的全局 SCN。
• 本地缓存：每个 observer 把最近拿到的 GTS 缓存几毫秒，批量分发，避免每事务一次 RPC。
• SCN ≈ HLC：物理时间戳 + 逻辑计数器混合，保证「外部一致性」（Lamport happens-before）。

B.8 Compact Node（链路压缩）

当一行的版本链超过 INDEX_TRIGGER_COUNT (=500) 个节点，会异步在链上插入一个 COMPACT 类型 TransNode，把若干历史版本压成一个完整的快照点，缩短后续读取路径。

B.9 ELR · Early Lock Release

OceanBase 的优化：commit 流程内一旦 redo 多数派落盘，立即释放行锁（甚至先于 callback 改写完所有 TransNode）。ObMvccRow 上的 max_elr_trans_version_ 记录了 ELR 后的最大版本，避免脏读。

附 C · 向量索引层架构深入

C.1 一个向量列在内核里到底有几张「表」？

看似一条 VECTOR INDEX idx_vec (emb) WITH (TYPE=hnsw)，seekdb 实际在内核创建 5 张辅助 tablet：

这 5 张表绑定在一起，由 ObPluginVectorIndexAdaptor 统一管理，对外只暴露「一个向量索引」概念。

C.2 Adaptor 把 5 张表黏成「两级 HNSW」

C.3 关键对象

C.4 写路径：从 INSERT 到 Delta HNSW 出现一个点

C.5 Delta → Snapshot 切换 (相当于向量索引的 minor freeze)

• 触发：delta 节点数超阈值 / 内存超阈值 / 主动调用 REFRESH INDEX。
• Scheduler 把当前 delta 「冻结」，新写入流向新的空 delta。
• 冻结 delta 与现有 snapshot 合并（直接增量插入或全量重建）→ 序列化 → 写 snapshot tablet 的 SSTable。
• 切换完成后，旧 delta 销毁，引用计数归零的 vsag 内存释放。

C.6 查询路径：Hybrid 过滤如何下推

关键：filter 是下推到 HNSW 图遍历内部的，而非 ANN 出 K 后再过滤——后者会因被过滤掉太多而出现「召回不足」需要放大 ef_search 的恶性循环。

C.7 支持的算法族

IVF 系列的桶（centroid）数据走 ObVectorIndexIvfCacheMgr + ObIvfAsyncTaskExecutor 异步训练与刷新。

附 D · HNSW 算法与工程实现

D.1 算法直觉：跳表 + 邻居图

HNSW (Hierarchical Navigable Small World) 把 ANN 看作「在一张图上做最短路径搜索」：

• 把每个向量当作图的一个节点，节点之间通过邻接边相连；
• 由于 small-world 特性，从任何点出发，沿"距离 query 最近的邻居"贪心走，期望 O(log N) 步可到 query 的近邻；
• 为了避免一开始就被困在局部最优，引入多层：高层稀疏（节点少、边长），用作"高速公路"；底层稠密（节点全、边短），用作"精修"。

D.2 图的层次结构

D.3 关键参数

D.4 插入算法（伪流程）

D.5 查询算法

1. 从 entry_point 出发，沿 layer L → 1 贪心下行：每层用 ef=1 的 best-first 搜索，找到该层离 query 最近的点。
2. 到达 layer 0，把上一层的最近点作为起点，做 ef_search 大小的 best-first 搜索（维护两个堆：candidates 最小堆 + W 最大堆）。
3. 循环：从 candidates 弹出最近点 c；若 dist(c, q) > W 堆顶 → 提前停止；否则展开 c 的邻居，未访问过的点计算距离，放入 candidates 和 W。
4. 最终返回 W 中的 top-K。

D.6 seekdb 的工程化要点

D.7 复杂度

附 E · Change Stream 正确性与背压

E.1 为什么 Fetcher 是单线程

PALF 是顺序日志。索引构建必须保证同一行的事件按顺序消费：先 INSERT 后 UPDATE 必须按这个顺序进入 HNSW，否则最终状态错。所以 Fetcher 单线程顺序拉日志，并按 tx_id 聚合，只在事务 commit 时整事务下推。

E.2 同事务多 DML 的顺序

• 每个 DML 携带 stmt_seq_no + row_seq_no。
• Dispatcher 切片到 worker 时，按 heap_pk 哈希选 worker —— 同一主键永远落到同一 worker，保证同行多事件顺序执行；不同行允许并行（吞吐源）。

E.3 Rollback to Savepoint 的正确性

这保证索引不会出现「曾发生又被回滚」的脏数据。

E.4 背压

E.5 refresh_scn 与可见性

• Fetcher 周期性把 refresh_scn 写入全局状态表。
• 查询路径调用 refresh_index() = 等待 refresh_scn ≥ 用户期望 snapshot。
• 嵌入式模式下 pyseekdb 的 refresh_index() 就是这个开关。

附 F · 写路径全链路时序

F.1 关键耗时分解

F.2 嵌入式模式下的差异

• 无网络栈，无 RPC：客户端 = 进程本身。
• PALF 仍在跑（写本地磁盘），但只单副本，"多数派" = 自己。append 耗时 ~ 几百 μs。
• Change Stream 同样运行，对应用透明。

附 G · 常见问题回答

Q1 · seekdb 怎么做到写入和查询并发还不抖动？

1. 写不碰索引：DML 只写 memtable + PALF redo；索引由 Change Stream 异步消费。
2. 索引层数恒为 2：Delta + Snapshot；查询永远只对两个 HNSW 做 ANN，不会随写入累积膨胀。
3. 读不加行锁：MVCC 用版本链 + SCN 比较解决可见性，避免读写竞争。
4. 资源隔离：OMT 给每个租户独立 worker pool + memstore 配额。

Q2 · 刚 INSERT 完为什么 APPROXIMATE 查询有可能查不到？

因为向量索引是异步构建的。解法：

• 显式 refresh_index()（pyseekdb 提供）；
• SQL 加 hint 等索引追平；
• 小表场景直接走精确扫描，不走 ANN。

Q3 · FORK DATABASE 怎么做到秒级、零拷贝？

1. RootServer 在 schema 层创建新 db + 新 table_id + 新 tablet_id（纯元数据，秒级）。
2. 每个新 tablet 标记 COW，引用原 tablet 的 SSTable 宏块，仅引用计数 +1，不复制数据。
3. 沙箱写入只写沙箱自己的 memtable / SSTable。读时融合「共享基线 + 沙箱增量」。
4. MERGE 按 STRATEGY 解冲突（FAIL/THEIRS/OURS）打回主库；DROP 直接释放引用，引用计数归零时回收宏块。

Q4 · DELETE 一个向量，HNSW 里这点为什么不能立刻拿掉？

HNSW 是双向邻居图，删点会让邻居出现悬挂边，破坏 small-world 性质。所以 seekdb 用 tombstone： DELETE 时写一个 DELETE TransNode + 把 vid 设入 vbitmap；查询时 FilterInterface 跳过； 只有 Snapshot 重建 / Major Merge 时才物理去除节点。

Q5 · HNSW 的 M 调大有什么后果？

• 召回↑（每点邻居更多，更难陷入局部最优）；
• 内存↑（线性增长）；
• 构图时间↑（每次插入更新更多邻居）；
• 查询延迟略↑（展开邻居更多次距离计算）。

经验：M=16 通用够用；高维稀疏数据可调到 32–48。

Q6 · Hybrid 查询里标量过滤掉 90%，ANN 还能召回吗？

因此即便选择率 ≤ 10%，召回率依然能保持。

Q7 · 事务 commit 之后，follower 还没重放完，从 follower 读会怎样？

• 读请求要求 snapshot_scn 已被本节点重放到（applyservice/replayservice 维护进度）。
• 若 follower 没追上：(a) 在 follower 上等到追平再读，(b) 路由器把请求重定向到 leader。具体由读策略与 ObProxy 决定。
• 强一致读总是从 leader / 多数派读。

Q8 · seekdb 比 Milvus / ES 在 Streaming 场景快的本质？

1. 索引段数不发散：Milvus 每次刷盘产生一个 segment，写久了几百段，并发查询时 N×M 段 × 线程争抢 CPU；seekdb 索引数永远是 2。
2. 写路径与索引解耦：seekdb 写 commit 不等索引；ES 的 refresh 是同步阻塞。
3. MVCC 不抢锁：高并发下读完全无锁；ES 的 segment 锁、Milvus 的 growing segment lock 都会成为瓶颈。
4. 同一存储 + 同一执行器：标量、向量、全文用同一套 SQL 计划下推到存储，比客户端 N+1 拼接快一个数量级。

Q9 · GTS 挂了集群还能写吗？

• GTS leader 故障 → 触发 LS-1 选主，新 leader 接管（PALF 保证）；典型 RTO < 8s。
• 切主期间事务拿不到 commit_version，会等待；不会读到旧版本（SCN 全局单调）。
• 容灾架构中可启用 standby_timestamp_service 减少 RTO。

Q10 · 一条 SQL 同时含 vector + fulltext + scalar 怎么执行？

Optimizer 生成一个 plan：

1. 标量索引/范围查询先产生候选行集合 → 转 bitmap；
2. 把 bitmap 注入 ANN 的 FilterInterface（前过滤），向量索引出 topK；
3. 同时倒排表按词命中产生 doc_id 集合；
4. 执行器内部按 SQL ORDER BY 合并打分（向量距离 + BM25 + 标量 score），最终 top-K 回主表取整行。

关键：所有过滤都在存储/索引层完成，结果集没有客户端拼接，这是性能/正确性优势的核心。