XERJ autoindex 断点续跑指南:进程被杀后如何无痛恢复中断的索引任务
XERJ autoindex 断点续跑指南:进程被杀后如何无痛恢复中断的索引任务
一次 autoindex 任务可能运行几十分钟甚至几小时,中途被 Ctrl+C、断网或服务器宕机打断是常态。XERJ 通过写入 --state-dir 的恢复日志(resume journal)让「重新执行同一条命令」变成幂等操作:中断过的运行、恢复运行与全新对照运行最终收敛到完全相同的文档集合。本文从实战命令出发,结合 engine/crates/xerj-autoindex/src/state.rs 与 engine/crates/xerj-autoindex/src/ids.rs 的源码实现,讲清恢复日志的存储结构、内容派生的幂等 _id、中断与节点宕机两种场景的差异,以及如何在自己的语料上复现收敛验证。
结论先行:重跑同一条命令即可恢复
官方捕获实验在 8 MB 日志语料上分别执行了中断运行、恢复运行和干净对照运行三组实验,三者最终都落在 82,231 篇文档,且恢复运行与对照运行按 _id 升序排列的前 20 个文档 id 完全一致(以 000012965601f7179a683a4f8e346dc4 开头)。计数相同不足以证明内容一致,id 完全相同才是强证据——这正说明「恢复」不是「重新追加」,而是对同一文档集合的确定性重建。
核心命令:三条命令复现断点续跑
下面是捕获实验使用的完整命令序列,可直接照搬到自己的语料上。
命令 1:首次运行(显式指定状态目录)
恢复的前提是状态目录存在且位置固定,因此首次运行就要用 --state-dir 显式指定:
xerj autoindex ./logs --url http://127.0.0.1:9200 --prefix sig --state-dir ./state-sig --progress plain
命令 2:中断后重跑同一条命令
进程被中断后,什么参数都不用改,原样重跑:
xerj autoindex ./logs --url http://127.0.0.1:9200 --prefix sig --state-dir ./state-sig --progress plain
命令 3:核对最终文档数
curl -s 'http://127.0.0.1:9200/sig-*/_count'
恢复运行会在开头几行直接说明自己的状态。捕获实验中恢复运行的输出是:
resuming from journal ./state-sig/journal.ndjson (1 files already done)
estimate: no estimate — nothing to index
xerj-done ok=true exit=0 reason=completed wall=1.2s files=0 records=82231
注意 files=0:这次恢复运行实际提交了 0 条新记录,因为上一次中断前已完成的文件都记录在日志里了。xerj-done 这一终止行由 engine/crates/xerj-autoindex/src/progress.rs 统一输出,格式为 xerj-done ok=true exit=0 reason=completed wall=…s files=… records=…,任何一次跑完(无论成功或失败)都会打印,Agent 不必靠猜。
恢复日志(resume journal)是怎样工作的
autoindex 会把每一个处理完毕的文件追加写进 --state-dir 下的日志,下一次运行在规划任何工作之前先读这份日志。这正是断点续跑的全部秘密。
日志存放位置与默认值
状态目录的默认位置在 state.rs 中计算:
pub fn default_state_dir(root: &str, url: &str, prefix: &str) -> PathBuf {
let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".into());
Path::new(&home)
.join(".xerj")
.join("autoindex")
.join(crate::ids::state_key(root, url, prefix))
}
即默认落在 ~/.xerj/autoindex/<hash>/,其中 <hash> 由 (root, url, prefix) 三者经 xxh3_64 派生(见 ids.rs),保证不同来源、不同端点、不同前缀互不串扰。--state-dir 帮助文本(cli.rs)特别提醒:对 s3:// 来源,本地对象镜像也存放在状态目录下,务必指到有磁盘余量的路径。
日志是追加式 NDJSON,且放在扫描文件夹之外
state.rs 文件头注释写得很清楚:日志是追加式 NDJSON,位于被扫描文件夹之外。这意味着:
- 日志不会成为扫描对象的一部分,避免「索引自己的状态文件」;
- 一条被截断的尾部记录会被丢弃(torn last line 处理,见下文);
- 最坏情况下一个文件会被完整重处理,而幂等
_id会把它去重掉,不会产生重复文档。
日志里有哪些记录类型
从 state.rs 的 replay 逻辑(open_after_preflight,约 L1136-L1346)可以看到日志支持多种记录 kind:
run:新运行开始,记录root、url、prefix、run_id、bulk_timeout_secs与开始时间;resume:恢复运行的标记;plan:冻结的数据集规划(datasets、文件分配、junk 记录等);file_done:单个文件处理完成,含file_key、path、records、junk、bytes;file_replace_start:内容变更时先失效旧完成记录,再进入替换事务;finish:整个运行正常收尾的摘要;- 以及
sync_begin、sync_bootstrap、sync_commit等增量协调事务记录。
恢复运行(resumed=true)时,日志中每个 file_done 对应的 file_key 都会被记入内存中的 done 表,阶段 B 只处理不在 done 表里的文件。interrupted 标志则精确刻画「上次运行没有写 finish」这一事实(state.rs),后续的语料级收尾工作(如图谱扫描)会据此决定是否需要补做。
排他锁:同一状态目录不能被两个进程同时占用
preflight(state.rs)会先在状态目录下创建并独占锁定 .autoindex.lock 文件。如果另一个进程正占用同一 --state-dir,会得到明确报错「autoindex state … is already in use by another process」,并提示等待或改用别的 --state-dir。这也是为什么恢复时直接重跑同一条命令是安全的——不会有第二个进程跑来写同一份日志。
损坏尾部与写中断的自愈
日志追加是「写入 + fsync」的成对事务(append_transaction,state.rs):一旦追加或 fsync 失败,会把文件截断回事务起点回滚。打开日志时,若最后一条记录没有以换行结尾(典型的中断痕迹),会被判定为 torn tail 并截掉(state.rs),随后重跑补齐。真正的日志中部损坏则会拒绝恢复并给出明确建议:从备份恢复、截断到损坏点、或 --fresh 重建。
为什么重跑是安全的:内容派生的幂等 _id
恢复安全的根基不在日志,而在文档 id 的生成方式。看 ids.rs:
/// Content-based file identity: xxh3_64(first 64KB) ‖ file size.
pub fn file_key(path: &Path, size: u64) -> std::io::Result<String> {
// 读文件前 64KB,计算 xxh3_64 哈希并拼上文件大小
}
/// Deterministic document _id.
pub fn doc_id(dataset_slug: &str, file_key: &str, locator: &str) -> String {
// 输入 = "ax1\0" + dataset_slug + "\0" + file_key + "\0" + locator
// 输出 = xxh3_128 的 32 位十六进制串
}
要点:
file_key由内容哈希(前 64KB)+ 文件大小决定,与 mtime、扫描顺序无关,同一个文件任何一次遍历都得到同一个 key;doc_id由(dataset_slug, file_key, locator)三元组派生,因此对同一文件二次处理会产生完全相同的_id;- 相同的
_id走 bulk 的index动作是覆盖写而不是追加,这正是「重跑不会重复文档」的直接原因; - 单元测试
doc_id_stable(ids.rs)固化这一性质:相同输入得到相同 id,不同 locator 或不同 dataset 得到不同 id。
结论:丢了状态目录损失的只是时间,不是正确性——重跑会重读每个文件,但 id 稳定,索引收敛到同一文档集合而非翻倍。
中断(客户端被杀)与节点宕机是两回事
原文档特别强调了一个容易混淆的边界:本次捕获只证明了「重跑安全且幂等」,没有证明文件处理中途被硬杀也能保证一致。它观察到的现象是:在 8 MB 语料、总耗时 12.0 s 的运行进行到 6 s 时发送 SIGINT,客户端仍然打印 xerj-done ok=true exit=0 reason=completed wall=12.0s files=1 records=82231 并以退出码 0 收尾——信号落在两次提交之间,没有打断正在进行的文件提交。任何宣称「支持 mid-file abort」的表述都超出了本次捕获的证据范围。
节点宕机则是另一种终态。捕获保留过这样一条终止行:
xerj-done ok=false exit=1 reason=aborted wall=416.4s
伴随 /_bulk 的 Connection refused 错误——即 XERJ 节点已停止监听。XERJ 是单节点架构,没有故障转移,也没有第二个节点接管写入。处理方式:先把节点拉起来,再原样重跑同一条 autoindex 命令(保持同一个 --state-dir),日志会接管剩下的事。
源码测试:故障注入验证「恢复可修复」
仓库用故障注入测试固化了这些恢复语义,最直接的是 failure_resume_http_tests.rs:
resume_repairs_kills_after_plan_delete_and_final_bulk_before_file_done(L2385):在多个崩溃边界注入故障后重跑,断言最终文档数等于源记录数且全部为「新」内容;file_done_append_and_fsync_failures_are_fatal_and_resume_repairs(L2454):分别注入追加失败、fsync 失败、半截写入三种 IO 故障,验证重跑后文档集合完整且为最新内容;partial_file_done_is_rolled_back_before_another_worker_commits(L2831):双 worker 下其中一个半截写入被回滚、另一个正常提交,重放日志保持可解析,最终收敛;write_block_rejections_are_backend_fatal_and_the_file_stays_pending(L2898):服务端写阻塞时文件保持 pending 而不被标记完成,阻塞解除后同一条命令继续索引成功。
这些测试与文档结论互相印证:任何边界上的崩溃,重跑同一条命令都能修复到一致状态。
在自己语料上复现收敛证明
按文档给出的步骤,用两套前缀做对照实验:
- 中断运行写入
sig前缀; - 同
--state-dir重跑; - 另起一次全新运行到新前缀(如
sig-control,配独立状态目录)作为对照组。
先比总数:
curl -s 'http://127.0.0.1:9200/sig-*/_count'
curl -s 'http://127.0.0.1:9200/sig-control-*/_count'
再比内容——分别取两个索引按 _id 升序的前 20 篇文档 id 逐条对比:
curl -s -XPOST 'http://127.0.0.1:9200/sig-*/_search' -H 'content-type: application/json' -d '{"query":{"match_all":{}},"size":20,"sort":[{"_id":"asc"}],"_source":false}'
常见问题(FAQ)
索引进程半夜死了,必须从头再来吗?
不用。保持同一个 --state-dir 重跑同一条命令即可。XERJ 读取恢复日志,打印已经完成的文件数,只索引剩余部分。
文件夹索引进行到一半停了,能续上吗?
能。已完成的文件保持已索引状态,--state-dir 里的日志记录着它们。捕获实验中恢复运行提交了 0 条新记录,文档总数不变。
我杀掉了索引进程,之前的工作丢了吗?
日志已经记录的部分不会丢。同一语料上,中断运行、恢复运行、干净对照运行最终都收敛到 82,231 篇文档。
重启索引器会重复文档吗?
不会。文档 id 由内容派生,恢复运行与干净对照运行产出了完全一致的前 20 个 id 和相同的总数。
状态目录丢了怎么办?
重跑会从零开始重读每个文件。id 保持稳定,索引收敛到同一内容集合,不会翻倍;损失的只是时间。
SIGINT 会立即中止 autoindex 吗?
本次捕获没有证明这一点。信号在 12.0 s 运行的第 6 s 到达,客户端仍以 reason=completed 收尾,因此不能声称支持 mid-file abort。
如果停的是节点而不是客户端呢?
客户端会打印 xerj-done ok=false exit=1 reason=aborted 和连接错误。节点恢复后,用同一个 --state-dir 重跑即可。