企业官网建设流程全解析

TigerBeetle 如何用 VOPR 确定性模拟器按固定 seed 复现集群故障场景

【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetle

在 TigerBeetle 的模拟测试中，如果某次 VOPR 运行暴露出集群故障（断言崩溃、状态不收敛等），下一步就是把这个故障在本地精确复现出来调试。TigerBeetle 的确定性模拟器 VOPR（Viewstamped Operation Replicator）基于一个 seed 号和 Git commit 完全确定运行过程：只要 seed 和代码版本相同，任何一次发现的 bug 都可以原样重放。本文的任务就是：在本地构建 TigerBeetle 源码树后，用一个固定的 seed 运行 VOPR，复现并观察一次带故障注入的集群模拟，并看懂它的输出。

适用前提来自 docs/internals/HACKING.md：TigerBeetle 使用了 io_uring 等较新的内核特性和高级 CPU 指令，需要较新的内核（≥ 5.6）和 CPU；生产部署目前仅支持 Linux，开发调试同样可在 Windows 和 MacOS 上进行。以下操作假设你已经处于 tigerbeetle 仓库目录内。

准备环境并构建

按 HACKING.md 中的步骤，先用仓库自带的脚本下载与构建匹配的 Zig 工具链，再构建数据库本身：

./zig/download.ps1 # Yes, .ps1 even on Linux. ./zig/zig build -Drelease ./tigerbeetle version

其中./zig/download.ps1在 Linux 上也是用这个.ps1脚本（文档原样如此）；./tigerbeetle version用于确认新构建的 TigerBeetle 可用。这一步同时把 VOPR 依赖的构建体系准备好，后续的zig build vopr会在需要时自动编译模拟器。

用固定 seed 运行 VOPR

VOPR 的构建入口在 build.zig 中注册：vopr步骤是 "Run the VOPR"，vopr:build只构建不运行。运行全部模拟测试：

./zig/zig build vopr

不带 seed 时，VOPR 每轮使用随机 seed，结果不可精确重放。要按固定 seed 复现，把 seed 放在--之后（HACKING.md 原文示例为123，build 脚本注释中的示例为42）：

./zig/zig build vopr -- 123

文档说明：使用特定 seed 运行 VOPR 会得到"fully deterministic, reproducible outcome"。seed 的作用体现在 docs/internals/vopr.md 中：VOPR 用随机 seed 调参，向模拟中注入不同种类的故障——丢弃和乱序网络包、切分网络分区、破坏"磁盘"的读写；模拟器提交数百批操作并检查它们被按预期应用，同时验证共识与集群恢复机制（safety 与 liveness）。

一个关键限制：复现必须与产生故障的 Git commit 一致。vopr.md 明确指出模拟器是"based on aseednumber and the Git commit"确定性的，所以"seed + commit"两者相同才谈得上重放同一次模拟。

判断这次复现是失败还是通过

VOPR 的退出信息直接给出判定（以下两行均来自 src/vopr.zig 中的实际日志语句）：

• 模拟通过时，最后一行输出（示例格式，ticks 数量随运行不同而变化）：

  PASSED (N ticks)

• 模拟出现无法恢复的 liveness 故障时，先打印最终集群状态，然后输出：

  you can reproduce this failure with seed=<seed>

  之后进程以 fatal 失败退出（"no state convergence"）。这正是"复现集群故障场景"的预期结果：拿到这行日志，就说明同 seed 重放确实还原出了原始故障。

另外注意一个模式限制：不带 seed 的运行必须以 ReleaseSafe 模式执行（源码中会 fatal："no seed provided: the simulator must be run with -OReleaseSafe"），而ReleaseFast与ReleaseSmall因会关闭断言而不被支持。带固定 seed 的调试重放使用默认构建模式即可。

读懂 VOPR 的集群状态输出

失败重放时会打印逐 replica 的状态行，各列含义在 docs/internals/testing.md 中有完整定义，常用的几列：

1. Replica 索引；
2. 事件：!crash、^recover、空格 commit、$sync、Xreformat、[/]checkpoint 开始/完成；
3. 该 replica 自认的角色：/primary、\backup、|standby、~syncing、#（已 crash）、F（reformatting 中）；
4. 状态符号：.normal、vview_change、rrecovering、hrecovering_head、ssync；
5. View，例如74V表示replica.view=74；
6. Checkpoint/Commit，例如83/_90/_98C分别表示最高已 checkpoint 的 op、在该 checkpoint 之上已应用到的 op、集群已知提交到的 op；
7. Journal op 区间，例如87:150Jo表示 journal 中最小/最大 op。

testing.md 给出的示例输出（文档示例，数值不要当作固定预期）：

3 [ / . 3V 71/_99/_99C 68:_99Jo 0/_0J! 68:_99Wo <__0:__0> v1:2 183Ga 0G! 0G? 0/4Pp 0/3Rq 4 ^ \ . 2V 23/_23/_46C 19:_50Jo 0/_0J! 19:_50Wo <__0:__0> v1:2 nullGa 0G! 0G? 3 ] / . 3V 95/_99/_99C 68:_99Jo 0/_0J! 68:_99Wo <__0:__0> v1:2 167Ga 0G! 0G? 0/4Pp 0/3Rq

调试某次故障时，对照上面的列定义逐行读这些状态，就能看出 crash/恢复事件发生在哪个 replica、当时的 view 与 commit 进度。

可选：调整日志与构建开关

build 系统提供两个与 VOPR 相关的-D选项（见 build.zig）：

• -Dvopr-log=short|full：short（默认）只打印状态转换，full按日志级别打印全部调试信息；
• -Dvopr-state-machine：选择状态机，默认accounting。

例如想要更详细的日志来观察复现过程：

./zig/zig build -Dvopr-log=full vopr -- 123

如果只想把模拟器编译出来、稍后再手动运行，用./zig/zig build vopr:build。

边界与限制

• 确定性 = seed + commit：换 commit 后同一个 seed 跑出的不再是原来那次模拟，复现前必须先确认代码版本。
• 断言常开：TigerBeetle 即使在生产中也保留断言，模拟中任何断言被打破都会让模拟崩溃，这类失败同样可以用"seed + commit"重放调试（见 vopr.md）。
• 随机模拟之外的定向用例：对于随机模拟难以或过于缓慢覆盖的场景，项目用同一套确定性模拟基础设施测试特定用例，实现在 src/vsr/replica_test.zig，可作为复现失败后的进一步对照阅读。
• CFO：仓库还有一台持续模糊测试集群（Continuous Fuzzing Orchestrator，src/scripts/cfo.zig），用于在 PR 上做大面积随机 seed 扫描，与本地固定 seed 重放是互补的两条路径，不属于本地复现的必要步骤。

复现是否成功，看两点即可：退出前是否打出了与原始故障一致的you can reproduce this failure with seed=...与 fatal 信息；或者在同 seed 下PASSED说明该版本上故障已被修掉。之后即可在这个确定性重放上继续断点调试。

【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetle