Omnigraph 图数据库质量保障体系深度解析:GQT 逻辑测试语料与 DST 确定性仿真框架

原创2026-10-12 17:33:541,670 阅读

Omnigraph 图数据库质量保障体系深度解析:GQT 逻辑测试语料与 DST 确定性仿真框架

Omnigraph 是一个面向对象存储的原生图数据库(graph database),支持分支工作流、类型化本体和多模态检索。正因为数据最终落在 S3/Azure 这类对象存储上,并发写入、崩溃恢复等场景才是它最容易出 Bug 的地方。Omnigraph 为此建了一套独特的质量保障体系:GQT 逻辑测试语料负责"每个行为都能被一个文本文件描述",DST 确定性仿真框架负责"任何故障都能被一键复现"。本文将带你完整看懂这套体系的设计思路与落地细节。

Omnigraph 图数据库基于对象存储的部署架构:集群数据根目录与写入准入租钥

上面这张来自 RFC 0029 的参考架构图,直观说明了为什么质量保障必须"重投入":所有图数据、清单(manifest)和 Ledger 都存放在 Azure Blob Storage 的 az:// 集群根目录下,每一次写入都要经过准入租钥。对象存储路径上的崩溃窗口与并发交错,正是 Omnigraph 最难复现、也最危险的 Bug 温床。

为什么图数据库需要"重武器"级测试?

传统关系型数据库的测试难点在 SQL 语义;而 Omnigraph 作为对象存储原生图数据库,最大的风险来自三类场景:

  • 崩溃恢复:一次写操作由多次持久化存储调用组成,中间任何一步断电/断网都会留下"半成品"状态;
  • 并发交错:多个写入者同时对 manifest 做 CAS 竞争,时序稍有不同结果就不同;
  • 隐性成本回归:RFC 0037 提到,曾经有一次"每个操作多出 55 次对象存储请求"的成本回归悄悄上线——因为墙钟基准测试把存储成本淹没在了方差里。

Omnigraph 的答案是两条腿走路:

层次 工具 回答的问题
行为正确性 GQT 逻辑测试语料(.gqt 文件) 查询、变更、分支合并的结果对不对?
状态机正确性 DST 确定性仿真(omnigraph-dst) 崩溃、故障、并发下,状态机是否守住了不变量?

两者的所有权划分写在 docs/dev/testing.md 中,核心原则是"在拥有该承诺的边界上测试"——查询行为归 GQT,机制断言、规模症状归 Rust 测试。

GQT 逻辑测试语料:一个文件 = 一个可执行的测试

📦 GQT(GQ Logic Test)语料位于 crates/omnigraph-gqt/,目前包含 330+ 个 .gqt 用例(cases/ 266 个、cases/v2/ 66 个,另有 2 个慢用例放在 cases_slow/ 由夜间工作流运行)。每个用例都是一个自包含的文本文件,格式规范定义在 RFC 0045 中。

一个 .gqt 文件长什么样?

以 branch_statement_lifecycle.gqt 为例,一个用例由若干节(section)组成:

# issue: none
# notes: Divergent writes merge; conflicting updates fail.

--- runner
timeout_ms: 10000
environments:
  - target: omnigraph-engine
    storage: local-filesystem

--- schema
node Person {
    name: String @key
    age: I32
}

--- seed
{"type":"Person","data":{"name":"alice","age":30}}

--- mutate
branch create b0
--- expect ok

结构一目了然:

  • --- runner:声明执行环境与超时(本地引擎、内存对象存储等);
  • --- schema + --- seed:声明 Schema 和种子数据;
  • --- query / --- mutate + --- expect:逐步操作并断言结果(行、受影响计数、错误信息);
  • 还支持 --- restart(重启后验证持久性)、循环、--- concurrent(并发块)、--- seam(故障注入点)。

回归测试的"文件锚点"约定

🧪 修复某个 issue 时,必须提交一个 issue_NNN_名称.gqt 用例,并在头部记录 red_on:(未修复构建上它必须是红的)。例如 issue_563_aggregate_uncapped.gqt 记录了"BM25 扫描窗口截断导致 count() 只数了 8 条而非 20 条"的回归。CI 会检查"关闭 issue 的 PR 必须携带同名回归用例",让回归测试从"靠自觉"变成"靠门禁"。

用例如何被发现与运行?

运行器 tests/gq_logic_tests.rs 用 datatest-stable 把 cases/ 下每一个 .gqt 递归注册成一个独立的 libtest 测试,因此:

  • 新增用例不需要写一行 Rust;
  • 可以用普通的名字过滤跑单个用例:
cargo test -p omnigraph-gqt --locked
cargo test -p omnigraph-gqt --test gq_logic_tests issue_563
  • 每次调用都会在 target/gqt-artifacts/ 生成 JSON 报告,并打印 --replay 复现命令,冻结输入、断言证据和存储请求账本,保证"失败的证据本身可重放"。

DST 确定性仿真框架:让不可复现的故障变得可复现

🎲 DST(Deterministic Simulation Testing,代码在 crates/omnigraph-dst/,设计见 RFC 0037)是这套体系里最有想象力的一环。核心概念只有三个:

Scenario(规则)+ Seed(一个种子数)= Universe(一个完整的模拟生命周期)

关键在于:调度器平局裁决、ULID 身份生成、墙钟时间、工作负载、存储故障、崩溃时机——一切都由同一个根种子派生。这意味着重跑同一个 (scenario, seed) 对,今天和一年后会生成完全一致的"宇宙":相同的操作流、相同的 ID 与时间戳、相同的存储调用顺序、相同的最终存储状态。

这正是确定性买到的东西:可重复性。最罕见的崩溃和竞态,从此变成一条可以用种子复现的永久测试用例。据 RFC 0037 统计,框架上线第一周就在 8000+ 个宇宙中发现了 12 个问题(含 3 个公开 issue)。

五类预言机(Oracle)持续审判

仿真不只是"重放",每个宇宙都被 5 组预言机(共 22 个检测器,见 detector_census.txt)连续检查:

  1. 差分模型:人与边被镜像到 BTreeMap/BTreeSet 中,每 3 步、最终重启后都必须与模型一致——同时兼任引用完整性预言机;
  2. 双向崩溃契约:崩溃的操作必须是原子的(状态恰好等于模型,或模型+该操作),恢复只能前滚、绝不能回滚已提交的写;
  3. OCC 不变量:任意两个提交不能共享同一个 graph_commit_id;
  4. 重放元测试:同一场景必须产生字节相等的 UniverseReport(含提交 ID 和完整查询的原始行序 JSON);
  5. 守恒律:批量两语句转账必须保持余额总和不变。

三种互补的故障模型

故障模型 比喻 机制
Fault plans "天气" 种子驱动的存储错误、延迟、丢失确认、文本损坏、有界陈旧
Crash-window hunt "狙击" 在引擎编目的 72 个命名 failpoint(catalog::CRASH_WINDOWS)中,于种子选定的操作序号触发崩溃
Crash-state enumeration "地毯式搜索"(ALICE 式) 对每个完成时刻 #k 都杀死一次进程,逐一对照精确世界模型

其中还有两条"送死通道":Lane A 是进程内模拟崩溃(存储包装器停止转发,同进程审判);Lane B 是真实死亡(父进程在 fsync 屏障行处等待到完成时刻 #k 后 SIGKILL 子进程,再从 oplog 恢复并审判)。

用确定性计数做性能回归

💡 由于一切可重放,"成本"也能被精确计数:仿真无法测墙钟,但可以精确数出每次操作的存储动作。cost_table.txt 就是一份提交进仓库的"金文件"(golden),例如:

AddFriend                    l.get        calls=110
AddFriend                    l.list       calls=16
AddFriend                    l.put        calls=24

"merge 的 PUT 次数从 12 变成 17"从此是一个有名字的回归测试,而不是没人复核的数字。

如何亲手跑起来

# 完整 GQT 语料 + 运行器自测
cargo test -p omnigraph-gqt --locked

# DST 仿真套件(其目录下的 .cargo/config.toml 会注入所需环境变量)
cd crates/omnigraph-dst
cargo test

# 用失败日志里的种子精确复现
OMNIGRAPH_DST_SEEDS=17689751483034105621 cargo test dst_v11_parallel_seed_fleet

⚠️ 注意:DST 与 GQT 不在默认工作区测试命令中(cargo test --workspace --exclude omnigraph-gqt --exclude omnigraph-dst),它们需要独立的构建配置;完整的命令与 CI 门禁见 docs/dev/testing.md。

关键资料导航

你想了解… 去看这里
测试所有权地图与规则 docs/dev/testing.md
GQT 语料与运行器 crates/omnigraph-gqt/
.gqt 格式合同 docs/rfcs/0045-gq-logic-tests.md
DST 仿真设计 docs/rfcs/0037-deterministic-simulation-harness.md
DST 运行与故障轴 crates/omnigraph-dst/README.md
存储成本金文件 / 预言机清单 cost_table.txt / detector_census.txt

一句话总结:GQT 让"行为"变成可版本化的文本资产,DST 让"故障"变成可复现的坐标。当图数据库跑在对象存储之上,这种"每个断言有文件、每次失败有种子"的质量保障体系,就是把分布式复杂度关进笼子的方式。

登录后查看全文
omnigraph