JanusGraph 故障与恢复实战指南:事务预写日志、恢复进程与实例故障处理

原创2026-10-11 22:24:201,459 阅读
文章标签:图数据库分布式数据库后端

JanusGraph 故障与恢复实战指南:事务预写日志、恢复进程与实例故障处理

JanusGraph 被设计为高可用、健壮的分布式图数据库,但在大规模部署中故障不可避免。本文以官方运维文档 docs/operations/recovery.md 为主体,系统讲解事务失败的处理机制、基于事务预写日志(Write-Ahead Log)的自动修复流程、事务恢复进程的启动与统计,以及 JanusGraph 实例故障后如何安全地从集群中移除失效实例记录。读完本文,你将掌握 tx.log-tx、tx.max-commit-time 等关键配置的取值规则,能够独立部署与运维事务恢复进程,并正确处理单实例故障对集群级操作的影响。

事务失败的处理模型

事务可能因多种原因失败,JanusGraph 对失败的处理取决于失败发生在其生命周期的哪个阶段。

提交前的失败:可安全重试

如果事务在提交之前失败,所有变更都会被丢弃,应用程序可以依据业务逻辑重试该事务。同样,锁冲突或其他一致性失败会在数据持久化之前抛出异常,因而同样可以安全重试。持久化阶段是事务开始向各后端系统写入数据的时刻,也是事务失败处理的转折点。

持久化阶段:先主后端、后次级后端

JanusGraph 的提交流程(见 StandardJanusGraph.java)遵循严格的顺序:

  1. 写入事务预写日志(PRECOMMIT 记录)——如果启用了 tx.log-tx;
  2. 提交存储后端(主持久化)——所有图变更以一次批量变更(batch mutation)的形式写入存储后端,以保证在支持原子性的后端上原子提交。若此次批量变更因存储后端异常而失败,整个事务即告失败;
  3. 提交索引后端与用户日志(次级持久化)——若主持久化成功,但索引后端或日志系统写入失败,事务仍被视为成功,因为存储后端是图的权威数据源(authoritative source)。

源码提交逻辑清晰地体现了这一原则:mutator.commitStorage() 失败会直接抛出异常中止事务(代码注释 [FAILURE] If primary storage persistence fails abort directly),而 mutator.commitIndexes() 的失败只会被收集、记录日志,不会导致事务回滚;最终写入日志的状态被标记为 SECONDARY_FAILURE 而不是失败。

不过,这种「存储成功、索引失败」的情况会在索引与日志中造成不一致。为了自动修复此类不一致,JanusGraph 可以维护一个事务预写日志,通过配置启用:

tx.log-tx = true
tx.max-commit-time = 300 s

tx.log-tx 对应源码中的 SYSTEM_LOG_TRANSACTIONS 配置项(见 GraphDatabaseConfiguration.java),类型为 GLOBAL,默认 false。启用后,每次变更事务都会额外多一次日志写入,因此会略微增加延迟并占用额外的存储空间。

正确理解与配置 tx.max-commit-time

tx.max-commit-time(对应源码 MAX_COMMIT_TIME,默认 300 s,见 GraphDatabaseConfiguration.java)用于判定一个事务何时可以被认为「已失败」。恢复进程在读取事务日志、越过某个事务第一条日志条目之后 tx.max-commit-time 的时间跨度时,就对该事务给出结论。因此,这个超时应当被配置为持久化阶段最大时长的宽松上界。注意:它不包含提交之前所花费的时间。

最小值:storage.write-time 的倍数

持久化阶段先写入存储后端,然后依次写入每个索引后端,每次写入在临时失败时都会按 storage.write-time 重试。因此 tx.max-commit-time 必须超过 storage.write-time 乘以「1 + 索引后端数量」;当配置不满足该条件时,JanusGraph 会在图打开时记录一条警告。

为什么 300 秒只是一个起点

从源码 MAX_COMMIT_TIME 的注释 可以归纳出,tx.max-commit-time 的实际需要量远比上述最小值大:

  • 时钟在写入被「准备」之前就已开始计时;
  • 变更数超过 storage.buffer-size 的事务,会分多个块写入存储后端,每个块各自重试;
  • 在无事务隔离的存储后端(Cassandra、HBase,或设置了 storage.transactions=false 的 BerkeleyDB)上,事务创建的 schema 元素会先以一次独立的存储写入提交;
  • 每次写入的最后一次尝试可能超出 storage.write-time。

默认值 300 秒能够覆盖「存储后端 + 一个索引后端」在默认写入时间下的场景,并额外留出一个写入时间。因此大事务需要留出更多余量。

用户日志与 read-lag-time 的影响

写用户日志(TransactionBuilder.logIdentifier)的事务暴露时间更长:如果其用户日志事件在恢复进程读到最终状态之前过期,恢复进程会再次发送该用户日志事件,因此用户日志的写入时间(log.user.send-delay 为 0 时最长可达 log.user.max-write-time)也必须被容纳在内。最终状态自身的写入不在此列:其日志条目从写入之前开始计时,与所有条目一样,必须在 log.tx.read-lag-time 内变得可见。

一个提交时长超过 tx.max-commit-time、或其实例在「用户日志写入」与「最终状态写入」之间失败的事务,其用户日志事件仍会被再次发送。只希望每个事件恰好看到一次的消费者,可以像识别原始事件那样,通过事务 ID 识别这种重复事件。

恢复进程的「放弃」语义与内存代价

恢复进程在日志读取进度越过「某事务第一条被读到条目之后 tx.max-commit-time」时放弃该事务,无论各条日志条目相隔多远、无论日志读取多慢——到那时,它已经读到了提交在 tx.max-commit-time 内写入、并在 log.tx.read-lag-time 内可见的全部内容。恢复进程会一直保留它读到的每个事务,直到读取进度越过上述界限,因此其内存占用随该值增长。

日志分区读取失败会阻塞进度直至成功;某分区永久性读取失败且不再被读取时,一旦其消息处理完毕,该分区会被排除在进度之外并记录错误日志。当所有分区都不再被读取时,将不再读取任何内容,进度按停止读取时的时钟继续推进,恢复进程仍会像按时钟等待时那样给出已掌握的事务,而不是无限期地保留它们。

启动事务恢复进程

仅仅开启 tx.log-tx 还不够:必须有一个独立的进程持续读取日志,识别部分失败的事务并修复由此产生的不一致。官方建议在与集群相连的独立机器上运行事务修复进程,以隔离故障。

使用 JanusGraphFactory 启动

通过 JanusGraphFactory.startTransactionRecovery(graph, startTime) 启动恢复进程(见 JanusGraphFactory.java),其中 startTime 是一个 Java Instant,指定恢复进程应从预写日志的哪个时间点开始读取(即自 epoch 以来的时间):

recovery = JanusGraphFactory.startTransactionRecovery(graph, startTime);

从源码可以看到,该方法实际构造了 StandardTransactionLogProcessor((StandardJanusGraph) graph, start)。构造函数会做三项前置校验(见 StandardTransactionLogProcessor.java):

  • 图实例必须非空且处于打开状态;
  • startTime 非空;
  • 图的配置必须启用了事务日志(Transaction logging must be enabled for recovery to work)——若未开启 tx.log-tx,恢复进程无法启动。

恢复进程的生命周期

恢复进程一旦启动便永不结束,仅会在以下三种情况下停止:

  1. 手动调用 recovery.shutdown();
  2. 进程遇到错误并因异常而失败;
  3. 图被关闭(graph.close())。

从源码看,shutdown()(StandardTransactionLogProcessor.java#L258-L289)会先等待后台清理线程停止,然后关闭修复线程池并等待其中的修复任务完成;在循环恢复模式下,还会注销日志读取器并停止读取进程,以释放资源。

读取进度统计:getStatistics()

恢复进程运行期间,调用 recovery.getStatistics() 可以获得恢复进度信息,它返回三个数字(对应源码 getStatistics() 中的三个计数器):

  1. 第一个数字:次级持久化成功的事务数量(successTxCounter);
  2. 第二个数字:次级持久化失败并被尝试恢复的事务数量,每个事务在尝试结束后计数一次(failureTxCounter);
  3. 第三个数字:无法恢复的次级持久化失败事务数量(failureTxRepairExceptionCounter)。

需要注意:已经停止的恢复进程不再修复事务;进程停止后才被放弃的事务(非循环恢复进程在仍读取日志时可能发生),或其修复在图关闭之后才开始的事务,会计入第二和第三个数字且不会发起修复尝试。源码中 notRepaired() 方法(StandardTransactionLogProcessor.java#L293-L297)正是此语义的实现:它同时递增失败计数与无法修复计数,并记录警告日志。

处理时间估算

根据 startTime 的取值和 log.tx.read-interval 配置,恢复进程可能需要运行数小时才能处理完预写日志中的全部相关条目:

  • startTime 定义了预写日志从哪个时间点开始读取;
  • 日志每隔 log.tx.read-interval 毫秒读取一次,每次迭代处理一个约 100 秒长的日志分片(该常量在源码 KCVSLog.java 中定义为 TIMESLICE_INTERVAL = 100 * 1000 * 1000 微秒,即 100 秒);
  • log.tx.read-interval 对应源码 LOG_READ_INTERVAL,默认值为 5000 ms(见 GraphDatabaseConfiguration.java#L1316-L1318)。

例如:startTime 配置为读取最近二十小时(72 000 秒)的日志条目、log.tx.read-interval 设为 5 000 ms(5 秒),则处理完所有日志条目大约至少需要一小时(72 000 / 100 × 5 = 3 600 秒 = 1 小时)。注意:如果存在大量次级持久化失败的事务,修复这些事务本身需要时间,恢复进程可能耗时更长。

修复日志与重启注意事项

当找到需要修复的预写日志条目时,JanusGraph 的日志系统中会出现如下 INFO 级日志消息,事务 ID 位于方括号内(源码见 StandardTransactionLogProcessor.java#L329):

Attempting to repair partially failed transaction [...]

即使通过 recovery.shutdown() 停止了恢复进程,只要没有关闭图,再次对同一图启动恢复进程就会报错:

Provided read marker is not compatible with existing read marker for previously registered readers

要避免该错误,必须在重新启动恢复进程之前先执行 graph.close()。

此外,StandardTransactionLogProcessor 还支持两个与修复并发相关的配置(见 GraphDatabaseConfiguration.java#L273-L290):

  • tx.recovery.verbose:是否将恢复的事务与活动打印到标准输出,默认 false;
  • tx.recovery.repair-pool-size:修复不完整事务的线程数,默认不设置时使用 JVM 公共池的线程数(默认等于处理器数减一、至少为一)。由于修复操作大多在等待 I/O,更多线程能更快地追上大量不完整事务;
  • tx.recovery.repair-keep-alive-time:修复线程等待下一个修复任务的空闲时间,默认 1 分钟。

循环事务恢复(Recurring Transaction Recovery)

在每日数据摄入的场景下,需要循环运行事务恢复,以确保数据每天的「主持久化」和「次级持久化」(例如由混合索引后端完成的索引写入)都成功。

由于 JanusGraphFactory.startTransactionRecovery() 并不适合循环执行,JanusGraph 提供了专门的方法,可在同一图上多次运行事务恢复(见 JanusGraphFactory.java#L307-L317):

recovery = JanusGraphFactory.startRecurringTransactionRecovery(graph, startTime);

与普通事务恢复进程一样,循环事务恢复进程使用相同的 graph 与 startTime 参数,并提供相同的 getStatistics() 和 shutdown() 方法。区别在于:循环模式在停止时会注销日志读取器并停止读取进程(源码 shutdown()),并且使用 ReadMarker.fromTimeRecurring(startTime) 创建读取标记(StandardTransactionLogProcessor.java#L208-L213),从而允许读取标记被多次注册。

进程停止后,可以再次调用 startRecurringTransactionRecovery(),从相同或另一个开始时间重新启动。

JanusGraph 实例失败处理

JanusGraph 对单个实例的失败具有鲁棒性:集群中其他实例不受影响,在失效实例重启期间可以继续处理事务且性能不降。

然而,某些 schema 相关操作(例如安装索引)需要所有 JanusGraph 实例协同。为此,JanusGraph 维护着所有运行中实例的记录。如果一个实例失败(即没有正常关闭),JanusGraph 仍会认为它处于活跃状态,并期望它参与集群级操作;该实例未参与或未确认操作,会导致这些操作失败。

手动移除失效实例

此时,用户必须手动从集群中移除失效实例的记录,然后重试该操作。具体步骤是:对任意一个运行中的 JanusGraph 实例打开管理事务,检查运行中实例列表以定位失效实例,最后将其移除:

mgmt = graph.openManagement()
mgmt.getOpenInstances() //all open instances
==>7f0001016161-dunwich1(current)
==>7f0001016161-atlantis1
mgmt.forceCloseInstance('7f0001016161-atlantis1') //remove an instance
mgmt.commit()

当前 JanusGraph 实例的唯一标识符带有后缀 (current),便于识别。从源码看,getOpenInstances() 会把当前实例的 UID 移出集合后重新加上 (current) 后缀返回;而 forceCloseInstance(instanceId) 做了严格校验:

  • 不能关闭当前实例——会抛出「Cannot force close this current instance」异常;
  • 目标实例必须是当前打开的实例;
  • 目标实例的注册时间必须早于当前管理事务的开始时间(防止误关刚成功重启的实例)。

当前实例无法通过 forceCloseInstance 关闭,而应使用 g.close() 正常关闭。

高风险场景与安全边界

必须确保被手动移除的实例确实已经不再活跃。从集群中移除一个仍然活跃的 JanusGraph 实例可能导致数据不一致。因此,在实例会被自动重启的环境中操作时尤其要谨慎——被自动重启的实例可能很快再次出现在运行实例列表中,此时移除操作将难以判断其真实状态。

值得注意的是,JanusGraph 也提供了自动化的替代方案:graph.management-auto-close-stale-instances 配置(见 GraphDatabaseConfiguration.java#L1262-L1267,默认 false)可以在启用后,自动强制关闭未在 graph.management-ack-timeout(默认 120 秒)内确认 schema 变更的实例,将其从注册存储中移除,从而不再阻塞 schema 状态转换。

日志相关配置速查

事务预写日志的完整配置项可在 Configuration Reference 中查阅。以下是本文涉及的核心日志配置及其在源码中的默认值:

配置项 默认值 说明(对应源码)
tx.log-tx false 是否将事务变更写入预写日志用于恢复(GraphDatabaseConfiguration.java#L246)
tx.max-commit-time 300 s 判定事务失败的时间上界(GraphDatabaseConfiguration.java#L250)
log.read-interval 5000 ms 从后端批量读取日志消息的间隔(GraphDatabaseConfiguration.java#L1316)
log.read-lag-time 500 ms 读出现在后端所允许的最大时间(KCVSLog.java#L137)
log.max-write-time 10000 ms 将日志消息持久化到后端前尝试的最长时间(KCVSLog.java#L127)
log.send-delay 1000 ms 批量发送前消息在本地缓冲的最长时间(GraphDatabaseConfiguration.java#L1312)
log.ttl 事务日志默认 7 天 所有日志条目的 TTL(GraphDatabaseConfiguration.java#L1324)
tx.recovery.verbose false 是否将恢复活动打印到标准输出(GraphDatabaseConfiguration.java#L276)
tx.recovery.repair-pool-size 未设置(用公共池) 修复线程数(GraphDatabaseConfiguration.java#L280)
tx.recovery.repair-keep-alive-time 1 min 修复线程空闲存活时间(GraphDatabaseConfiguration.java#L287)

关于 TTL 的说明:运维文档原文提到事务预写日志的 TTL 为 2 天,而当前仓库源码中 TRANSACTION_LOG_DEFAULT_TTL = Duration.ofDays(7)(GraphDatabaseConfiguration.java#L1290),即当前仓库默认 TTL 为 7 天。日志条目会在 TTL 到期后过期,以控制存储开销;可通过 log.ttl 配置项调整。

源码级流程回顾:一次提交如何被记录与修复

结合 StandardJanusGraph.java 的提交实现 与 StandardTransactionLogProcessor.java,一次完整的「记录 → 检测 → 修复」闭环如下:

  1. 提交开始时,若启用 tx.log-tx,先写入 PRECOMMIT 状态条目到事务日志;
  2. 存储后端提交成功后,写入 PRIMARY_SUCCESS(若还有次级持久化)或 COMPLETE_SUCCESS(无次级持久化);
  3. 依次提交各索引后端与用户日志;任何失败都被收集但不中止事务,最终写入 SECONDARY_SUCCESS 或 SECONDARY_FAILURE(后者附带失败索引与用户日志失败信息);
  4. 恢复进程从 startTime 起按 log.read-interval 周期读取日志,跟踪每个事务的状态演化(源码 TxEntry.update() 中的状态机:StandardTransactionLogProcessor.java#L524-L545);
  5. 对停留在 SECONDARY_FAILURE / PRIMARY_SUCCESS 状态、且已越过 tx.max-commit-time 界限的事务,fixSecondaryFailure() 会先通过 restoreExternalIndexes() 重放混合索引文档(StandardTransactionLogProcessor.java#L328-L367),再重新发送用户日志事件。

该机制在仓库测试中得到验证,例如 InMemoryTransactionRecoveryTest.java 演示了「开启 tx.log-tx 后启动恢复进程、断言 tx.max-commit-time 生效、最后 shutdown 并关闭图」的完整用法;InMemoryTransactionRecoveryThreadsTest.java 则覆盖了多线程场景下的恢复行为。

运维要点总结

  • 恢复能力依赖 tx.log-tx = true,开启后每个变更事务多一次日志写入,延迟与存储开销随之增加;
  • tx.max-commit-time 必须显著大于 storage.write-time × (1 + 索引后端数),大事务、用户日志与 schema 提交场景需额外留出余量;配置过短时图打开会给出警告;
  • 恢复进程应运行在与集群相连的独立机器上,以隔离故障域;
  • 非循环恢复进程一旦停止便无法对同一图直接重启,需先 graph.close();每日数据摄入场景应改用 startRecurringTransactionRecovery();
  • 通过 getStatistics() 的三个计数监控修复进度,用日志关键字 Attempting to repair partially failed transaction 定位具体被修复的事务;
  • 移除失效实例务必先确认其已真正停止运行,在自动重启环境中尤其谨慎,也可考虑启用 graph.management-auto-close-stale-instances 自动清理。
登录后查看全文
janusgraph