GitNexus 一直提示 Repository not indexed 的排查记录

最近我在一个 Java 多模块后端项目里使用 GitNexus 时，遇到了一个很容易误判的问题：项目目录下明明执行过 gitnexus analyze，但再运行 gitnexus status 时，仍然一直提示：

1 2	Repository not indexed. Run: gitnexus analyze

一开始看起来像是 GitNexus 没有识别当前仓库，或者 registry 没写进去。但继续追下去后发现，真正的问题不在 GitNexus 的仓库识别逻辑，而在底层 LadybugDB 扩展加载阶段。

这篇记录一下完整排查过程。

现象

当前项目路径是：

1	F:\WorkSpace\Project_server

项目根目录下已经存在 .gitnexus 目录，但 gitnexus status 始终返回未索引：

1	gitnexus status

输出：

1 2	Repository not indexed. Run: gitnexus analyze

继续看全局注册表：

1	gitnexus list

可以看到已有多个仓库，但没有 Project_server。也就是说，GitNexus 的全局 registry 里确实没有当前项目。

再检查本地 .gitnexus：

1	Get-ChildItem -Force .gitnexus

里面只有类似这样的文件：

1 2	lbug lbug.wal

但是没有关键的：

1	.gitnexus\meta.json

这说明 analyze 并没有真正完成。它只是创建了 LadybugDB 数据库文件，还没来得及写元数据和注册仓库。

先确认 status 有没有误判

我重新执行：

1	npx gitnexus analyze "F:\WorkSpace\Project_server" --name Project_server --verbose

输出只停在：

GitNexus Analyzer

Skipped 3 large files (>512KB, likely generated/vendored)
- portal-common/cloud-core/src/main/resources/ip2region/ip2region.db
- portal-aisecretary/portal-aisecretary-server/src/main/resources/font/SimSun.ttf
- portal-aisecretary/portal-aisecretary-server/src/main/resources/font/GB2312.ttf

然后进程退出，退出码是 1，但没有任何 JS 异常栈。

这一步基本确认了一个事实：status 的提示并不是误判。当前仓库确实没有完整索引，因为 analyze 在中途失败了。

把问题从项目代码里摘出来

为了判断是不是项目代码太大、某个源码文件解析失败，绕过 CLI，直接调用 GitNexus 的 pipeline API：

1	node --input-type=module --max-old-space-size=8192 --stack-size=4096 -e "..."

核心 pipeline 能正常完成，最终结果大致是：

1
2
3

7531 files
2241 communities
300 processes

这说明代码扫描、解析、调用关系分析、流程发现都不是根因。问题发生在 pipeline 之后，也就是把图写入 LadybugDB、写 meta.json、注册 registry 这一段。

继续往 LadybugDB 方向缩小范围

继续直接调用 GitNexus 的 runFullAnalysis，打印每个 phase。它最终停在：

1 2	PROGRESS complete 60 Pipeline complete PROGRESS lbug 60 Loading into LadybugDB...

随后进程直接退出 1。

这个位置对应 GitNexus 里的 LadybugDB 初始化和图写入逻辑。于是我进一步单独测试：

1	await initLbug('F:/WorkSpace/Project_server/.gitnexus/lbug-test')

结果也是进程直接退出，没有异常栈。

再拆开测试 LadybugDB 的最小创建流程：

1 2	const db = new lbug.Database('...'); const conn = new lbug.Connection(db);

这个是成功的。

然后逐条执行 GitNexus 的 schema 创建 SQL，也全部成功。

最后问题锁定到扩展加载：

1 2	LOAD fts LOAD vector

或者 GitNexus 代码里使用的：

1	LOAD EXTENSION VECTOR

在当前环境都会让 Node 进程直接退出。

根因：@ladybugdb/core 0.15.4 在当前 Windows 环境加载扩展会崩

当时环境是：

GitNexus 1.6.3
@ladybugdb/core 0.15.4
Node v22.18.0
Windows x64

我先确认 LadybugDB 版本：

1	node -e "..."

输出：

{
  "VERSION": "0.15.4",
  "STORAGE_VERSION": 40
}

然后测试：

1 2	await conn.query('LOAD fts') await conn.query('LOAD vector')

两者都会直接让 Node 退出。

进一步查看本地扩展缓存，发现扩展位于：

1	C:\Users\TheSL\.lbdb\extension\0.15.0\win_amd64\

里面有：

1 2	fts\libfts.lbug_extension vector\libvector.lbug_extension

虽然缓存目录名是 0.15.0，但这不一定单独说明问题。真正决定性证据来自对比测试：我从 npm cache 手动解包了 @ladybugdb/core@0.15.3 和 @ladybugdb/core-win32-x64@0.15.3，不执行 npm install，只直接 import 解包后的运行时。

使用 0.15.3 测试：

1 2	LOAD fts 成功 LOAD vector 成功

使用 0.15.4 测试：

1 2	LOAD fts 进程退出 LOAD vector 进程退出

所以结论很明确：这是 @ladybugdb/core 0.15.4 在当前 Windows 环境下加载动态扩展的问题，而不是 GitNexus 本身的索引逻辑问题。

修复方式：回退 LadybugDB 运行时，不禁用能力

一个简单但不合格的绕法是把 GitNexus 里的 loadVectorExtension() 注释掉。这样虽然能让普通索引跑完，但会牺牲 vector 能力，也掩盖了真实问题。

最终我采用的是保留功能的修复方式：把 GitNexus 全局安装目录里的 LadybugDB 运行时从 0.15.4 固定到已验证可用的 0.15.3。

先备份原始目录：

1	C:\Program Files\nodejs\node_modules\gitnexus\node_modules\@ladybugdb\backup-core-0154-20260507150648

然后替换：

1 2	C:\Program Files\nodejs\node_modules\gitnexus\node_modules\@ladybugdb\core C:\Program Files\nodejs\node_modules\gitnexus\node_modules\@ladybugdb\core-win32-x64

替换后验证：

GitNexus: 1.6.3
LadybugDB: 0.15.3
LOAD fts: success
LOAD vector: success

接着重新执行：

1	npx gitnexus analyze "F:\WorkSpace\Project_server" --name Project_server --force --verbose

这次成功完成：

Repository indexed successfully (63.8s)

120,294 nodes | 273,962 edges | 2206 clusters | 300 flows
F:\WorkSpace\Project_server

再执行：

1	gitnexus status

输出：

1 2	Repository: F:\WorkSpace\Project_server Status: up-to-date

gitnexus list 中也能看到：

Project_server
Path: F:\WorkSpace\Project_server
Stats: 7528 files, 120294 symbols, 273962 edges
Clusters: 2206
Processes: 300

顺手处理：预创建 FTS 索引

修复后我又测了一下：

1	gitnexus query "登录" -r Project_server

第一次查询时出现过一个额外问题：GitNexus 会懒创建 FTS index，但查询连接是 read-only，导致：

1	Cannot execute write operations in a read-only database

这个问题和前面的扩展崩溃不是同一个问题。解决方式是用写连接提前创建 FTS index：

await ensureFTSIndex('File', 'file_fts', ['name', 'content'])
await ensureFTSIndex('Function', 'function_fts', ['name', 'content'])
await ensureFTSIndex('Class', 'class_fts', ['name', 'content'])
await ensureFTSIndex('Method', 'method_fts', ['name', 'content'])
await ensureFTSIndex('Interface', 'interface_fts', ['name', 'content'])

之后再执行查询，BM25 检索可以正常工作。

复盘

这次问题最容易误导人的地方在于，表面现象是：

1	Repository not indexed

但真正原因不是 GitNexus 没识别仓库，也不是 registry 写入失败，而是 analyze 进程在写 registry 前被 LadybugDB 原生扩展加载问题中断了。

整个排查过程中，几个判断点比较关键：

.gitnexus 目录存在不代表索引完整，关键要看有没有 meta.json。
gitnexus list 只看全局 registry，项目目录残留半成品 .gitnexus 不会被认为已索引。
CLI 没有异常栈时，要考虑 native addon 或底层扩展直接终止进程。
拆分 pipeline、schema、extension 三层测试，能很快把问题从“项目代码”缩小到“数据库扩展运行时”。
修复时优先保留功能。这里正确方向不是禁用 vector，而是找到可工作的 LadybugDB 版本组合。

最终这次修复没有改 GitNexus 的业务逻辑，也没有牺牲 FTS/vector 能力，只是把底层 LadybugDB 运行时回退到了当前 Windows 环境下可稳定加载扩展的 0.15.3。

现象