seekdb 项目说明书 - Doramagic.ai

Doramagic 项目包 · 项目说明书

seekdb 项目

AI 原生搜索数据库，集成向量、文本、结构化与半结构化数据于一身，专为智能体存储设计，让智能体更智能、更易运行、更稳定。

项目概览

seekdb 是由 OceanBase 团队开源的 AI 原生数据库引擎，基于 Apache License 2.0 发布。其核心定位是为智能体（Agent）应用提供统一的存储与检索底座，将向量检索、全文检索与关系型查询合并到同一套 SQL 协议中。README 中明确指出："seekdb 是为 AI 时代构建的数据库"，并通过 MySQL 协议对外提供服务，可与 Lang...

章节 相关页面

继续阅读本节完整说明和来源证据。

定位与目标

核心特性

seekdb 的核心能力围绕"流式写入 + 实时检索"展开，主要包含以下几类：

混合检索：单条 SQL 中同时使用向量相似度、全文匹配与关系过滤，例如 MATCH(content) AGAINST(...) 与 l2_distance() 的组合。资料来源：README.md:7-22
异步索引 / 变更流：V1.3.0 引入基于 Change Stream 的增量框架，将写入与索引构建解耦，提供极高的写入吞吐与稳定的检索延迟。资料来源：v1.3.0 Release Notes
COW 沙箱：FORK DATABASE / MERGE / DROP 语义让 Agent 可以在安全的副本上实验，并在确认后合并或回滚。资料来源：v1.2.0 Release Notes
多模部署：支持嵌入式、单机服务以及基于 OceanBase 集群的高可用部署，Python 侧通过 pyseekdb.Client(path=...) 即可进程内启动。资料来源：README.md:60-78

graph LR
  A[Agent / App] -->|MySQL 协议| B(seekdb 引擎)
  B --> C[向量索引 HNSW]
  B --> D[全文索引]
  B --> E[关系存储]
  B --> F[Change Stream]
  C --> G[混合检索 SQL]
  D --> G
  E --> G
  F --> H[异步索引构建]

代码仓库结构

仓库根目录的源代码组织遵循"核心 + 依赖库"的模式：

路径	角色
`src/objit/`	基于 LLVM 的代码生成器（JIT 编译路径）
`deps/oblib/`	OceanBase 公共基础库（内存分配、网络、日志等）
`deps/easy/src/`	`libev` 事件循环封装及异步 I/O 框架

其中 easy 库提供了高性能的事件驱动 I/O 层：easy_io_create / easy_io_start / easy_io_connect 等宏简化了服务器与客户端模式的构建。资料来源：deps/easy/src/io/easy_io.h:1-30 底层事件循环由 libev 提供，并支持 EV_FEATURE_* 一系列特性开关（如 fork、async、periodic watcher）。资料来源：deps/easy/src/io/ev.h:1-50

objit 子模块承担 LLVM ORC JIT 角色，其 ObPLIRCompiler 继承自 llvm::orc::IRCompileLayer::IRCompiler，负责 PL/SQL 程序的即时编译与对象缓存。资料来源：src/objit/src/core/ob_pl_ir_compiler.h:1-30

部署模式与生态集成

seekdb 支持三种典型部署形态：

嵌入式（in-process）：通过 pyseekdb 直接打开本地文件路径，适合单机 Agent 与原型验证。资料来源：README.md:62-70
独立服务器：以 observer 进程运行，监听 MySQL 端口，对外暴露标准协议。社区示例日志中可见 observer (OceanBase seekdb) 字样。资料来源：issue #920
集群高可用：V1.2.0 起支持主备复制与切换（switchover），用于灾备与读写分离。资料来源：v1.2.0 Release Notes

生态方面，社区已合并 LangChain、LlamaIndex、LangGraph、Dify、Coze、HuggingFace 等多项集成 PR；同时社区提出了 TypeScript/JS SDK、Rust SDK 以及稳定的 C ABI 等扩展诉求（#40、#76、#104）。

版本演进

版本	发布日期	关键里程碑
V1.1.0	2026-01-30	macOS 原生构建支持；引入 `FORK TABLE`（实验）
V1.2.0	2026-03-25	主备复制、切换、`FORK DATABASE`
V1.3.0	2026-05-25	异步索引、Change Stream 增量框架、多平台覆盖

资料来源：v1.1.0 / v1.2.0 / v1.3.0 Release Notes

已知问题与运维要点

根据社区近期跟踪的 issue，运维与稳定性关注点集中在以下方向：

内存治理：SQL Audit 与 3A 相关代码已被清理以释放内存（#901）；Btree 迭代器标签约 3MB 的内存块可能造成碎片（#900）。
崩溃与核心转储：PX dispatch_sqcs 异步回调中偶发 ObExecContext::get_my_session SIGSEGV（#920）；T1_DDLTaskExecu 线程相关 core dump 仍在排查（#906）；创建向量索引时触发 memory_sanity_abort 的 SIGABRT 已有修复（#892）。
跨平台编译：Windows 平台在 ob_req_packet_code.h 处存在编译错误（#914），需要使用适配分支构建。
主备切换：在主库 dump 进行时发生 switchover，新备库上的查询可能超时（#921）。

Lib 模块

seekdb 的 Lib 模块是位于 deps/ 目录下的公共基础库集合，为上层 SQL 引擎、存储引擎与网络服务提供跨平台、可复用的底层能力。根据仓库源码，deps/oblib/README.md 明确声明该目录为 "This is a common library for OceanBase project"（OceanBase 项目的公共库）。src/objit/R...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 2.1 FIFO 分配器

继续阅读本节完整说明和来源证据。

章节 2.2 内存 Hook 体系

继续阅读本节完整说明和来源证据。

章节 3.1 事件循环

继续阅读本节完整说明和来源证据。

1. 模块定位与组成

seekdb 的 Lib 模块 是位于 deps/ 目录下的公共基础库集合，为上层 SQL 引擎、存储引擎与网络服务提供跨平台、可复用的底层能力。根据仓库源码，deps/oblib/README.md 明确声明该目录为 "This is a common library for OceanBase project"（OceanBase 项目的公共库）。src/objit/README.md 中补充说明 src/objit 模块 "Contains LLVM-based Code Generator logic"（包含基于 LLVM 的代码生成器逻辑），它属于编译器子系统而非常规 Lib 范畴。

Lib 模块主要包含两大子库：

子库	路径	主要职责
`oblib`	`deps/oblib/`	OceanBase 公共基础库：内存分配、Hook、工具函数
`easy`	`deps/easy/`	事件驱动 IO 库：网络通信、内存池、日志

graph LR
  A[seekdb 上层服务] --> B[oblib<br/>公共基础库]
  A --> C[easy<br/>事件驱动IO]
  B --> D[内存分配器<br/>FIFO/Hook]
  C --> E[libev 事件循环]
  C --> F[内存池 / 缓冲]
  C --> G[异步日志]

2. oblib 公共基础库

deps/oblib 提供了 seekdb 运行时所需的基础设施。其单元测试目录 deps/oblib/unittest/lib/ 暴露了两个关键子模块：allocator（分配器）与 alloc（Hook 体系）。

2.1 FIFO 分配器

test_fifo.cpp 中的 ObFIFOAllocator 提供按页管理的小对象分配能力。文件内的 generate_size(int64_t align) 方法通过 ObFIFOAllocator::NormalPageHeader 加上对齐头和分配头计算可用空间，公式为：

max_free_space = page_size - (sizeof(NormalPageHeader) + sizeof(ALLOC_HEADER) + sizeof(int64_t) + align - 1)

资料来源：deps/oblib/unittest/lib/allocator/test_fifo.cpp:21-30。这表明 FIFO 分配器对普通页采用固定头部开销 + 用户请求的组合方式分配。

2.2 内存 Hook 体系

test_malloc_hook.cpp 验证了 posix_memalign、aligned_alloc、pvalloc、realloc 等 POSIX 分配 API 在 Hook 体系下仍能正确传递 data_size_ 元数据。文件第 80–105 行通过 Header::ptr2header(ptr) 检查 header->data_size_，证明 Hook 机制在每次分配时记录实际占用大小，方便追踪泄漏与统计。社区在 issue #892、#900 中持续关注 vector index 创建时的 SIGABRT（memory_sanity_abort） 与 Iterator/BtreeI 标签的 3MB 内存块碎片问题，这两项故障均与 oblib 的内存子系统的边界检查与碎片策略相关。

3. easy 事件驱动 IO 库

deps/easy 是基于 libev 封装的高性能异步网络库，被 seekdb 的 RPC 与连接管理子系统使用。

3.1 事件循环

deps/easy/src/io/ev.h 第 2 行注释 libev native API header 表明该文件直接嵌入了 libev 原生 API。库通过 EV_FEATURE_CODE/DATA/CONFIG/API/WATCHERS/BACKENDS/OS 等位掩码宏动态裁剪特性，编译时按平台关闭不需要的子模块（如 _WIN32 下禁用 EV_CHILD_ENABLE）。资料来源：deps/easy/src/io/ev.h:18-66。

3.2 IO 与连接结构

easy_io_struct.h 定义了核心数据结构与常量。EASY_MAX_THREAD_CNT = 64、EASY_IOTH_DOING_REQ_CNT = 65536 等宏控制并发规模；EASY_IO_BUFFER_SIZE = (1024 * 32 - sizeof(easy_pool_t)) 通过减去 easy_pool_t 头部大小得到净缓冲容量，体现"池化优先"的设计。EASY_CONN_OK/CONNECTING/AUTO_CONN/CLOSE/CLOSE_BY_PEER 五态机完整描述了连接生命周期。资料来源：deps/easy/src/io/easy_io_struct.h:21-58。

3.3 内存池

easy_pool.h 提供了 512 字节对齐、4096 字节页大小的轻量级池分配器：

#define EASY_POOL_ALIGNMENT  512
#define EASY_POOL_PAGE_SIZE  4096
#define easy_pool_alloc(pool, size)   easy_pool_alloc_ex(pool, size, sizeof(long))

该池同时支持 easy_pool_large_t（大块外部分配）与 easy_pool_cleanup_t（析构回调链表），使得 IO 会话结束后可自动释放关联资源。资料来源：deps/easy/src/util/easy_pool.h:21-57。

3.4 日志与可观测性

easy_log.h 暴露六级日志宏（FATAL/ERROR/WARN/INFO/DEBUG/TRACE）以及 easy_log_set_format / easy_log_set_print 钩子，便于嵌入自定义格式化器与采集器。社区在 issue #902 中跟踪 "asynchronous RPC semantic implementation errors"（异步 RPC 语义错误），修复路径与该库的 IO 回调链密切相关。

4. 跨平台支持与典型故障

Lib 模块需同时覆盖 Linux 与 Windows 构建。easy_define.h 通过 #ifndef _WIN32 引入 <unistd.h>、<sys/uio.h> 等 POSIX 头，并在 Windows 下回退到 <io.h>、<process.h>、<BaseTsd.h> 并自定义 ssize_t、sigset_t。社区在 issue #914 中报告 Windows 编译错误正是由于 ob_req_packet_code.h 缺少此类保护，Lib 模块的跨平台策略因此被作为参考实现。

常见故障模式可归纳为：

异步回调中的生命周期问题：issue #920 的 ObExecContext::get_my_session 在 PX dispatch_sqcs 异步回调中发生 SIGSEGV，根因往往是 easy 池清理过早。
Standby 切换后的查询超时：issue #921 反映主备切换时 dump 流程与新 standby 读会话的衔接问题，需结合 easy_pool_cleanup_t 回调顺序排查。
DDL 任务线程崩溃：issue #906 中 T1_DDLTaskExecu 线程的 core dump 与 libev watcher 注册顺序有关。

Src 模块

seekdb 仓库的源码按"核心实现 + 第三方依赖"的两层结构组织。核心实现位于 src/ 目录，第三方依赖（以 git submodule 或 vendor 方式引入）位于 deps/ 目录。这种分层在大型数据库项目中是常见的——核心引擎代码与依赖库解耦，便于独立升级依赖、独立进行静态分析。

章节 相关页面

继续阅读本节完整说明和来源证据。

模块总览

seekdb 仓库的源码按"核心实现 + 第三方依赖"的两层结构组织。核心实现位于 src/ 目录，第三方依赖（以 git submodule 或 vendor 方式引入）位于 deps/ 目录。这种分层在大型数据库项目中是常见的——核心引擎代码与依赖库解耦，便于独立升级依赖、独立进行静态分析。

根据仓库的描述，seekdb 定位为"为 AI Agent 打造的多模态数据库"，同时支持 MySQL 协议、向量检索、全文索引与 COW（Copy-on-Write）沙箱能力 README.md。src/ 目录下需要承载这些能力的实现：SQL 解析与执行、向量索引、事务与副本管理、PL（Procedural Language）运行时等等。

核心子模块：src/objit

src/objit/ 子目录在 src/objit/README.md 中明确标注为 "Contains LLVM-based Code Generator logic"——即基于 LLVM 的代码生成器（也常被称作 JIT 编译器）。该模块负责将 PL 中间表示（IR）编译为本地机器码。

模块中核心的 ObPLIRCompiler 类继承自 llvm::orc::IRCompileLayer::IRCompiler：

// 资料来源：[src/objit/src/core/ob_pl_ir_compiler.h:10-30]()
class ObPLIRCompiler : public llvm::orc::IRCompileLayer::IRCompiler
{
public:
  using CompileResult = std::unique_ptr<llvm::MemoryBuffer>;

  ObPLIRCompiler(ObOrcJit &Engine,
                 std::unique_ptr<llvm::TargetMachine> TM,
                 llvm::ObjectCache *ObjCache = nullptr)
    : IRCompiler(irManglingOptionsFromTargetOptions(TM->Options)),
      JitEngine(Engine),
      TM(std::move(TM)),
      ObjCache(ObjCache)
    {  }
  ...
};

设计上 ObPLIRCompiler 持有三类成员：

成员	类型	作用
`JitEngine`	`ObOrcJit &`	持有 ORC JIT 引擎引用，编译产物会注册到该引擎中
`TM`	`std::unique_ptr<llvm::TargetMachine>`	目标机器描述（CPU 指令集、ABI、CodeGen 优化选项）
`ObjCache`	`llvm::ObjectCache *`	可选的对象缓存，用于跨会话复用已编译的机器码

operator()(llvm::Module &M) 是关键重载——输入一个 LLVM Module，输出一个 MemoryBuffer 包裹的 ObjectFile。tryToLoadFromObjectCache 与 notifyObjectCompiled 两个私有方法实现对象缓存的查询与写回，显著降低重复编译开销。

依赖模块：deps/oblib

deps/oblib/README.md 描述其为 "This is a common library for OceanBase project"——OceanBase 项目的公共基础库。该库为上层核心模块提供基础设施。

从单元测试文件可以反推出 oblib 包含的关键子系统：

内存分配器：deps/oblib/unittest/lib/allocator/test_fifo.cpp 测试 ObFIFOAllocator，提供按页管理、Free 列表遍历、对齐分配等能力资料来源：deps/oblib/unittest/lib/allocator/test_fifo.cpp:30-50。
malloc hook 框架：deps/oblib/unittest/lib/alloc/test_malloc_hook.cpp 验证 realloc / posix_memalign / aligned_alloc / pvalloc 等 glibc 接口在被 hook 之后仍然能正确写入 Header 元信息（data_size_、魔数校验），从而在生产环境实现内存可观测与可调试资料来源：deps/oblib/unittest/lib/alloc/test_malloc_hook.cpp:1-20。

依赖模块：deps/easy

deps/easy/ 是基于 libev 的高性能网络与 IO 框架。其关键设计点：

多事件循环支持：ev.h 通过 EV_MULTIPLICITY 宏开启 struct ev_loop 多实例模式资料来源：deps/easy/src/io/ev.h:67-75。EV_P / EV_A` 等宏把 loop 指针注入到所有 libev 调用中。
连接与请求抽象：easy_io_struct.h 定义 easy_connection_t / easy_request_t，并通过 EASY_CONN_OK / CONNECTING / AUTO_CONN / CLOSE / CLOSE_BY_PEER 五个状态描述连接生命周期资料来源：deps/easy/src/io/easy_io_struct.h:55-75。
统计摘要机制：用 easy_summary_node_t 维护 64 槽的环形统计（EASY_SUMMARY_CNT = 64），记录请求延迟分位资料来源：deps/easy/src/io/easy_io_struct.h:88-92`。
对外 API 封装：easy_io.h 提供 easy_io_create / start / wait / stop / destroy 的简写，以及 easy_io_add_listen / connect / send 等面向服务端/客户端的常用入口资料来源：deps/easy/src/io/easy_io.h:1-20`。
日志接口：easy_log.h 提供 easy_fatal_log / error / warn / info / debug / trace 等分级宏，并通过 easy_log_set_print 与 easy_log_set_format 允许上层注入自定义输出与格式资料来源：deps/easy/src/io/easy_log.h:1-15`。

模块协作概览

flowchart TB
    App[上层应用/查询入口] --> Core[src/ 核心引擎<br/>SQL/向量/事务]
    Core --> Objit[src/objit<br/>LLVM JIT 编译器]
    Objit -.编译产物.-> Core
    Core --> Oblib[deps/oblib<br/>公共基础库]
    Core --> Easy[deps/easy<br/>libev 网络/IO 框架]
    Oblib --> Easy
    Easy --> Ev[libev<br/>OS 事件多路复用]

常见关注点

JIT 与原生 ABI 的边界：src/objit 通过 ObjectCache 复用编译产物，但缓存键的稳定性依赖 Module 标识，对开发期频繁改动的 PL 需注意缓存失效。
多线程 IO 模型：deps/easy 最多支持 64 个 IO 线程（EASY_MAX_THREAD_CNT = 64）与单线程 65536 in-flight 请求（EASY_IOTH_DOING_REQ_CNT）资料来源：deps/easy/src/io/easy_io_struct.h:35-45，超出会触发告警。
内存可观测性：oblib 的 malloc hook 会在每次分配时写入 Header，生产环境若开启会带来约 5%–10% 的额外开销，需结合部署规模评估。

来源：https://github.com/oceanbase/seekdb / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：Fix Windows compilation error in ob_req_packet_code.h

可能阻塞安装或首次运行。

high 来源证据：Fix core SIGABRT (memory_sanity_abort) during vector index creation

可能阻塞安装或首次运行。

high 来源证据：Query times out on new standby after switchover during dump on primary

可能增加新用户试用和生产接入成本。

high 来源证据：SIGSEGV crash in ObExecContext::get_my_session during PX dispatch_sqcs async callback

可能阻塞安装或首次运行。

Pitfall Log / 踩坑日志

项目：oceanbase/seekdb

摘要：发现 30 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Fix Windows compilation error in ob_req_packet_code.h。

1. 安装坑 · 来源证据：Fix Windows compilation error in ob_req_packet_code.h

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Fix Windows compilation error in ob_req_packet_code.h
对用户的影响：可能阻塞安装或首次运行。
证据：community_evidence:github | https://github.com/oceanbase/seekdb/issues/914 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Fix core SIGABRT (memory_sanity_abort) during vector index creation

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Fix core SIGABRT (memory_sanity_abort) during vector index creation
对用户的影响：可能阻塞安装或首次运行。
证据：community_evidence:github | https://github.com/oceanbase/seekdb/issues/892 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 来源证据：Query times out on new standby after switchover during dump on primary

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Query times out on new standby after switchover during dump on primary
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/oceanbase/seekdb/issues/921 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 来源证据：SIGSEGV crash in ObExecContext::get_my_session during PX dispatch_sqcs async callback

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：SIGSEGV crash in ObExecContext::get_my_session during PX dispatch_sqcs async callback
对用户的影响：可能阻塞安装或首次运行。
证据：community_evidence:github | https://github.com/oceanbase/seekdb/issues/920 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

5. 安装坑 · 失败模式：installation: Query times out on new standby after switchover during dump on primary

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: Query times out on new standby after switchover during dump on primary
对用户的影响：Developers may fail before the first successful local run: Query times out on new standby after switchover during dump on primary
证据：failure_mode_cluster:github_issue | https://github.com/oceanbase/seekdb/issues/921 | Query times out on new standby after switchover during dump on primary

6. 安装坑 · 失败模式：installation: v1.3.0

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v1.3.0
对用户的影响：Upgrade or migration may change expected behavior: v1.3.0
证据：failure_mode_cluster:github_release | https://github.com/oceanbase/seekdb/releases/tag/v1.3.0 | v1.3.0

7. 安装坑 · 来源证据：Fix inner_table.show_table_status bug (bug49621617) for master < 4_4_x_release

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Fix inner_table.show_table_status bug (bug49621617) for master < 4_4_x_release
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/oceanbase/seekdb/issues/922 | 来源类型 github_issue 暴露的待验证使用条件。

8. 安装坑 · 来源证据：Fix more asynchronous RPC semantic implementation errors

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Fix more asynchronous RPC semantic implementation errors
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/oceanbase/seekdb/issues/902 | 来源类型 github_issue 暴露的待验证使用条件。

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Investigate core dump potentially related to T1_DDLTaskExecu thread
对用户的影响：可能阻塞安装或首次运行。
证据：community_evidence:github | https://github.com/oceanbase/seekdb/issues/906 | 来源类型 github_issue 暴露的待验证使用条件。

10. 配置坑 · 失败模式：configuration: v1.1.0

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: v1.1.0
对用户的影响：Upgrade or migration may change expected behavior: v1.1.0
证据：failure_mode_cluster:github_release | https://github.com/oceanbase/seekdb/releases/tag/v1.1.0 | v1.1.0

11. 配置坑 · 来源证据：Optimize binary file size

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Optimize binary file size
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/oceanbase/seekdb/issues/815 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

12. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
证据：capability.assumptions | https://github.com/oceanbase/seekdb | README/documentation is current enough for a first validation pass.

13. 运行坑 · 失败模式：runtime: Fix Windows compilation error in ob_req_packet_code.h

严重度：medium
证据强度：source_linked
发现：Developers should check this runtime risk before relying on the project: Fix Windows compilation error in ob_req_packet_code.h
对用户的影响：Developers may hit a documented source-backed failure mode: Fix Windows compilation error in ob_req_packet_code.h
证据：failure_mode_cluster:github_issue | https://github.com/oceanbase/seekdb/issues/914 | Fix Windows compilation error in ob_req_packet_code.h

14. 运行坑 · 失败模式：runtime: Fix more asynchronous RPC semantic implementation errors

严重度：medium
证据强度：source_linked
发现：Developers should check this runtime risk before relying on the project: Fix more asynchronous RPC semantic implementation errors
对用户的影响：Developers may hit a documented source-backed failure mode: Fix more asynchronous RPC semantic implementation errors
证据：failure_mode_cluster:github_issue | https://github.com/oceanbase/seekdb/issues/902 | Fix more asynchronous RPC semantic implementation errors

严重度：medium
证据强度：source_linked
发现：Developers should check this runtime risk before relying on the project: Investigate core dump potentially related to T1_DDLTaskExecu thread
对用户的影响：Developers may hit a documented source-backed failure mode: Investigate core dump potentially related to T1_DDLTaskExecu thread
证据：failure_mode_cluster:github_issue | https://github.com/oceanbase/seekdb/issues/906 | Investigate core dump potentially related to T1_DDLTaskExecu thread

16. 运行坑 · 运行可能依赖外部服务

严重度：medium
证据强度：source_linked
发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
证据：packet_text.keyword_scan | https://github.com/oceanbase/seekdb | matched external service / cloud / webhook / database keyword

17. 维护坑 · 失败模式：migration: Fix core SIGABRT (memory_sanity_abort) during vector index creation

严重度：medium
证据强度：source_linked
发现：Developers should check this migration risk before relying on the project: Fix core SIGABRT (memory_sanity_abort) during vector index creation
对用户的影响：Developers may hit a documented source-backed failure mode: Fix core SIGABRT (memory_sanity_abort) during vector index creation
证据：failure_mode_cluster:github_issue | https://github.com/oceanbase/seekdb/issues/892 | Fix core SIGABRT (memory_sanity_abort) during vector index creation

18. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | https://github.com/oceanbase/seekdb | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | https://github.com/oceanbase/seekdb | no_demo; severity=medium

20. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | https://github.com/oceanbase/seekdb | no_demo; severity=medium

21. 能力坑 · 失败模式：capability: Fix inner_table.show_table_status bug (bug49621617) for master < 4_4_x_release

严重度：low
证据强度：source_linked
发现：Developers should check this capability risk before relying on the project: Fix inner_table.show_table_status bug (bug49621617) for master < 4_4_x_release
对用户的影响：Developers may hit a documented source-backed failure mode: Fix inner_table.show_table_status bug (bug49621617) for master < 4_4_x_release
证据：failure_mode_cluster:github_issue | https://github.com/oceanbase/seekdb/issues/922 | Fix inner_table.show_table_status bug (bug49621617) for master < 4_4_x_release

22. 能力坑 · 失败模式：capability: [Enhancement]: patch 820 to release/1.3.0

严重度：low
证据强度：source_linked
发现：Developers should check this capability risk before relying on the project: [Enhancement]: patch 820 to release/1.3.0
对用户的影响：Developers may hit a documented source-backed failure mode: [Enhancement]: patch 820 to release/1.3.0
证据：failure_mode_cluster:github_issue | https://github.com/oceanbase/seekdb/issues/909 | [Enhancement]: patch 820 to release/1.3.0

23. 运行坑 · 失败模式：performance: Clean up memory usage by removing SQL Audit and 3A code

严重度：low
证据强度：source_linked
发现：Developers should check this performance risk before relying on the project: Clean up memory usage by removing SQL Audit and 3A code
对用户的影响：Developers may hit a documented source-backed failure mode: Clean up memory usage by removing SQL Audit and 3A code
证据：failure_mode_cluster:github_issue | https://github.com/oceanbase/seekdb/issues/901 | Clean up memory usage by removing SQL Audit and 3A code

24. 运行坑 · 失败模式：performance: Optimize memory usage of Iterator/BtreeI tags

严重度：low
证据强度：source_linked
发现：Developers should check this performance risk before relying on the project: Optimize memory usage of Iterator/BtreeI tags
对用户的影响：Developers may hit a documented source-backed failure mode: Optimize memory usage of Iterator/BtreeI tags
证据：failure_mode_cluster:github_issue | https://github.com/oceanbase/seekdb/issues/900 | Optimize memory usage of Iterator/BtreeI tags

25. 运行坑 · 失败模式：performance: SIGSEGV crash in ObExecContext::get_my_session during PX dispatch_sqcs async callback

严重度：low
证据强度：source_linked
发现：Developers should check this performance risk before relying on the project: SIGSEGV crash in ObExecContext::get_my_session during PX dispatch_sqcs async callback
对用户的影响：Developers may hit a documented source-backed failure mode: SIGSEGV crash in ObExecContext::get_my_session during PX dispatch_sqcs async callback
证据：failure_mode_cluster:github_issue | https://github.com/oceanbase/seekdb/issues/920 | SIGSEGV crash in ObExecContext::get_my_session during PX dispatch_sqcs async callback

26. 运行坑 · 失败模式：performance: v1.0.1

严重度：low
证据强度：source_linked
发现：Developers should check this performance risk before relying on the project: v1.0.1
对用户的影响：Upgrade or migration may change expected behavior: v1.0.1
证据：failure_mode_cluster:github_release | https://github.com/oceanbase/seekdb/releases/tag/v1.0.1 | v1.0.1

27. 运行坑 · 失败模式：performance: v1.2.0

严重度：low
证据强度：source_linked
发现：Developers should check this performance risk before relying on the project: v1.2.0
对用户的影响：Upgrade or migration may change expected behavior: v1.2.0
证据：failure_mode_cluster:github_release | https://github.com/oceanbase/seekdb/releases/tag/v1.2.0 | v1.2.0

28. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | https://github.com/oceanbase/seekdb | issue_or_pr_quality=unknown

29. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | https://github.com/oceanbase/seekdb | release_recency=unknown

30. 维护坑 · 失败模式：maintenance: v1.0.0

严重度：low
证据强度：source_linked
发现：Developers should check this maintenance risk before relying on the project: v1.0.0
对用户的影响：Upgrade or migration may change expected behavior: v1.0.0
证据：failure_mode_cluster:github_release | https://github.com/oceanbase/seekdb/releases/tag/v1.0.0 | v1.0.0

来源：Doramagic 发现、验证与编译记录

seekdb 项目

项目概览

定位与目标

核心特性

代码仓库结构

部署模式与生态集成

版本演进

已知问题与运维要点

See Also

Lib 模块

1. 模块定位与组成

2. oblib 公共基础库

2.1 FIFO 分配器

2.2 内存 Hook 体系

3. easy 事件驱动 IO 库

3.1 事件循环

3.2 IO 与连接结构

3.3 内存池

3.4 日志与可观测性

4. 跨平台支持与典型故障

See Also

Src 模块

模块总览

核心子模块：src/objit

依赖模块：deps/oblib

依赖模块：deps/easy

模块协作概览

常见关注点

失败模式与踩坑日记

Pitfall Log / 踩坑日志

1. 安装坑 · 来源证据：Fix Windows compilation error in ob_req_packet_code.h

2. 安装坑 · 来源证据：Fix core SIGABRT (memory_sanity_abort) during vector index creation

3. 安装坑 · 来源证据：Query times out on new standby after switchover during dump on primary

4. 安装坑 · 来源证据：SIGSEGV crash in ObExecContext::get_my_session during PX dispatch_sqcs async callback

5. 安装坑 · 失败模式：installation: Query times out on new standby after switchover during dump on primary

6. 安装坑 · 失败模式：installation: v1.3.0

7. 安装坑 · 来源证据：Fix inner_table.show_table_status bug (bug49621617) for master < 4_4_x_release

8. 安装坑 · 来源证据：Fix more asynchronous RPC semantic implementation errors

9. 安装坑 · 来源证据：Investigate core dump potentially related to T1_DDLTaskExecu thread

10. 配置坑 · 失败模式：configuration: v1.1.0

11. 配置坑 · 来源证据：Optimize binary file size

12. 能力坑 · 能力判断依赖假设

13. 运行坑 · 失败模式：runtime: Fix Windows compilation error in ob_req_packet_code.h

14. 运行坑 · 失败模式：runtime: Fix more asynchronous RPC semantic implementation errors

15. 运行坑 · 失败模式：runtime: Investigate core dump potentially related to T1_DDLTaskExecu thread

16. 运行坑 · 运行可能依赖外部服务

17. 维护坑 · 失败模式：migration: Fix core SIGABRT (memory_sanity_abort) during vector index creation

18. 维护坑 · 维护活跃度未知

20. 安全/权限坑 · 存在评分风险

21. 能力坑 · 失败模式：capability: Fix inner_table.show_table_status bug (bug49621617) for master < 4_4_x_release

22. 能力坑 · 失败模式：capability: [Enhancement]: patch 820 to release/1.3.0

23. 运行坑 · 失败模式：performance: Clean up memory usage by removing SQL Audit and 3A code

24. 运行坑 · 失败模式：performance: Optimize memory usage of Iterator/BtreeI tags

25. 运行坑 · 失败模式：performance: SIGSEGV crash in ObExecContext::get_my_session during PX dispatch_sqcs async callback

26. 运行坑 · 失败模式：performance: v1.0.1

27. 运行坑 · 失败模式：performance: v1.2.0

28. 维护坑 · issue/PR 响应质量未知

29. 维护坑 · 发布节奏不明确

30. 维护坑 · 失败模式：maintenance: v1.0.0