如何解决XTDB中的“missing docs”问题并恢复服务？

诊断步骤 #

• 提取完整错误日志：重点找报错关联的事务ID、时间戳，以及存储层（RocksDB）的异常记录，比如磁盘满、权限变更、崩溃日志——这类问题常导致索引与文档数据脱节。
• 检查底层存储键值对：用XTDB内置调试工具或直接遍历RocksDB键，查找前缀为idx-的索引条目，确认是否存在指向陌生ID的残留记录（XTDB的文档键前缀为doc-，若只有索引无对应文档，就会触发该错误）。
• 排查近期操作：确认是否执行过批量删除、绕过XTDB API直接操作RocksDB的行为，或是刚完成XTDB版本升级——这类操作容易破坏数据一致性。
• 校验节点状态：调用xt/status API查看节点健康度，重点关注RocksDB是否有 corruption 标记，以及磁盘空间、文件权限是否正常。

恢复方案（无需重建数据库） #

方案1：清理孤立索引条目 #

适用于确认陌生ID无业务关联、仅为残留索引的场景：

1. 暂停XTDB节点，完整备份RocksDB数据目录（必做，避免不可逆损失）。
2. 用XTDB存储API或RocksDB CLI，删除所有包含该陌生ID的索引键（比如idx-ea、idx-ae类型的索引条目）。
3. 重启XTDB节点，尝试写入数据验证恢复效果。

方案2：回放事务日志 #

适用于事务中途失败导致的索引-文档不一致场景：

1. 暂停写入操作，备份RocksDB数据目录。
2. 调用xt/replay-tx-log API全量回放事务日志，XTDB会基于日志重新构建文档与索引，自动修复不一致：

   (xt/replay-tx-log node {:replay-type :full})
   

3. 回放完成后重启节点，验证写入功能是否恢复。

生产环境预防措施 #

• 定期全量备份RocksDB数据目录，单独备份事务日志（tx-log前缀的存储区域）。
• 所有数据变更仅通过XTDB官方事务API执行，禁止直接操作底层RocksDB存储。
• 监控存储层日志与节点状态，及时预警磁盘空间不足、权限异常等问题。
• 版本升级前先在测试环境验证兼容性，升级前必须备份数据。

内容的提问来源于stack exchange，提问作者Kaz Librowski