GitNexus容器化索引本地仓库WORKSPACE_DIR用法与常见陷阱完整指南【免费下载链接】GitNexusGitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a git repository (Github, Gitlab, Azure, Local) or ZIP file, and get an interactive knowledge graph with a built in Graph RAG Agent. Perfect for code exploration项目地址: https://gitcode.com/GitHub_Trending/gi/GitNexusGitNexus是一个零服务器Zero-Server的代码智能引擎能把 Git 仓库变成可交互的知识图谱并内置 Graph RAG 智能体。除了浏览器端使用它还提供 Docker 容器化部署一行docker compose up -d即可启动 API 服务端口4747和 Web UI端口4173。而把宿主机上的本地仓库交给容器索引关键就在于环境变量WORKSPACE_DIR—— 用对了事半功倍用错了则索引不到任何仓库。WORKSPACE_DIR 是什么一条只读挂载在 docker-compose.yaml 中服务端容器有两类存储理解它们的分工是避免一切陷阱的前提挂载点来源作用/data/gitnexus命名卷gitnexus-data可读写持久化全局注册表、索引、克隆的仓库/workspace宿主机${WORKSPACE_DIR:-./workspace}只读:ro让你宿主机上已有的仓库可被索引核心配置就这一行# docker-compose.yaml 中的卷挂载 - ${WORKSPACE_DIR:-./workspace}:/workspace:ro也就是说WORKSPACE_DIR指向的宿主机目录会被只读挂进容器的/workspace。在宿主机上执行WORKSPACE_DIR$HOME/code docker compose up -d进入容器后$HOME/code/my-repo就变成了/workspace/my-repodocker compose exec gitnexus-server gitnexus index /workspace/my-repo容器内能直接用gitnexus命令是因为 Dockerfile.cli 把 CLI 入口软链到了/usr/local/bin/gitnexus省去手动调用node .../index.js的麻烦。 官方文档README.md 的 Docker 章节有完整说明。最快上手三步配置 WORKSPACE_DIR第 1 步准备.env文件cp .env.example .env.env.example 中已预置WORKSPACE_DIR、镜像名、容器名与端口等可覆盖项。⚠️ 注意其中默认值是WORKSPACE_DIR./——直接照抄会把当前项目根目录挂进容器见下文陷阱 2。第 2 步改为你的仓库目录# .env WORKSPACE_DIR/home/you/code强烈建议写绝对路径相对路径会以 compose 文件所在目录为基准解析换目录启动行为就变了。第 3 步带 env 文件启动并索引docker compose --env-file .env up -d docker compose exec gitnexus-server gitnexus index /workspace/my-repo启动后打开http://localhost:4173UI 会自动探测http://localhost:4747的服务器浏览器跑在宿主机上直接走映射端口即可。五大常见陷阱踩坑清单⚠️陷阱 1改完WORKSPACE_DIR忘记重启容器环境变量只在容器创建时被读取运行中的容器不会感知。修改后必须执行docker compose up -d # 或 docker compose down docker compose up -d否则你索引的永远是旧挂载点。陷阱 2默认./或./workspace的安全与空目录问题docker-compose.yaml 的注释特意说明默认指向一个空的./workspace/兄弟目录compose 首次启动时自动创建——这是刻意的安全设计避免把仓库根目录的.git、.env、CI 密钥暴露给容器但若你把 .env.example 里的WORKSPACE_DIR./原样保留并复制为.env效果就变成挂载项目根目录。虽然仍是:ro只读、无法被写入但仓库文件本身对容器可见。只挂你真正需要索引的目录是最稳妥的做法。陷阱 3相对路径基准错误WORKSPACE_DIRcode这类相对路径是相对于docker-compose.yaml所在目录解析的不是你的当前 shell 工作目录。在别的目录执行 compose 命令、或把 compose 文件挪进子目录挂载就会消失。最保险的做法依然是绝对路径或$HOME/code。陷阱 4只读挂载下的.gitnexus/缓存文件由于挂载是:roGitNexus 无法在你宿主机仓库里写.gitnexus/.gitignore来隐藏本地索引缓存。源码中 repo-manager.ts 专门处理了这种情况遇到EROFS/EACCES/EPERM时降级为警告而不是报错对应 issue #1549。代价是这些缓存文件可能在宿主机仓库的git status里显示为 untracked。这不是故障属于预期行为介意的话可在自己的.gitignore里加一行.gitnexus/。陷阱 5镜像名混淆image rename早期 Web UI 也发布在ghcr.io/abhigyanpatwari/gitnexus现在该 slug 专供CLI/服务端UI 迁移到了gitnexus-web镜像Docker Hub 镜像 为akonlabs/gitnexus与akonlabs/gitnexus-web。旧 tag 仍可拉取但新版本只发新 slug——建议直接采用官方捆绑的 compose 文件或核对镜像名。进阶把容器索引接进 AI 编码工具索引完成后价值不仅在于 Web 端浏览图谱。GitNexus 容器暴露的 MCP 端点可以让 Kilo Code 等 AI 编码助手直接查询你的代码知识图谱上图展示了在 Kilo Code 的Agent Behaviour → MCP Servers中gitnexus条目处于 connected 状态。配置细节参见 Documentation/kilo-code-mcp.md。速查表故障排查症状原因处理index报路径不存在用了宿主机路径/home/you/code/...容器内请改用/workspace/...挂载目录是空的WORKSPACE_DIR相对路径解析位置不对改为绝对路径并重启容器改 env 不生效容器未重建docker compose up -d重建警告 storage filesystem is not writable只读挂载下无法写.gitnexus/.gitignore可忽略在仓库.gitignore手动加.gitnexus/Web UI 连不上服务器端口被占用用SERVER_HOST_PORT/WEB_HOST_PORT换端口小结容器化索引本地仓库的心法一句话WORKSPACE_DIR挂宿主机目录 → 容器内路径前缀换成/workspace→ 索引数据落在gitnexus-data卷里持久保存。掌握启动时生效、只读挂载、绝对路径这三个要点就能避开绝大多数坑让 GitNexus 在 Docker 环境里稳定地为你的本地仓库构建知识图谱。相关资源路径编排文件docker-compose.yaml、.env.example构建文件Dockerfile.cli、Dockerfile.web存储与只读处理逻辑gitnexus/src/storage/repo-manager.ts主文档 Docker 章节README.md【免费下载链接】GitNexusGitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a git repository (Github, Gitlab, Azure, Local) or ZIP file, and get an interactive knowledge graph with a built in Graph RAG Agent. Perfect for code exploration项目地址: https://gitcode.com/GitHub_Trending/gi/GitNexus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
GitNexus容器化索引本地仓库：WORKSPACE_DIR用法与常见陷阱完整指南
GitNexus容器化索引本地仓库WORKSPACE_DIR用法与常见陷阱完整指南【免费下载链接】GitNexusGitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a git repository (Github, Gitlab, Azure, Local) or ZIP file, and get an interactive knowledge graph with a built in Graph RAG Agent. Perfect for code exploration项目地址: https://gitcode.com/GitHub_Trending/gi/GitNexusGitNexus是一个零服务器Zero-Server的代码智能引擎能把 Git 仓库变成可交互的知识图谱并内置 Graph RAG 智能体。除了浏览器端使用它还提供 Docker 容器化部署一行docker compose up -d即可启动 API 服务端口4747和 Web UI端口4173。而把宿主机上的本地仓库交给容器索引关键就在于环境变量WORKSPACE_DIR—— 用对了事半功倍用错了则索引不到任何仓库。WORKSPACE_DIR 是什么一条只读挂载在 docker-compose.yaml 中服务端容器有两类存储理解它们的分工是避免一切陷阱的前提挂载点来源作用/data/gitnexus命名卷gitnexus-data可读写持久化全局注册表、索引、克隆的仓库/workspace宿主机${WORKSPACE_DIR:-./workspace}只读:ro让你宿主机上已有的仓库可被索引核心配置就这一行# docker-compose.yaml 中的卷挂载 - ${WORKSPACE_DIR:-./workspace}:/workspace:ro也就是说WORKSPACE_DIR指向的宿主机目录会被只读挂进容器的/workspace。在宿主机上执行WORKSPACE_DIR$HOME/code docker compose up -d进入容器后$HOME/code/my-repo就变成了/workspace/my-repodocker compose exec gitnexus-server gitnexus index /workspace/my-repo容器内能直接用gitnexus命令是因为 Dockerfile.cli 把 CLI 入口软链到了/usr/local/bin/gitnexus省去手动调用node .../index.js的麻烦。 官方文档README.md 的 Docker 章节有完整说明。最快上手三步配置 WORKSPACE_DIR第 1 步准备.env文件cp .env.example .env.env.example 中已预置WORKSPACE_DIR、镜像名、容器名与端口等可覆盖项。⚠️ 注意其中默认值是WORKSPACE_DIR./——直接照抄会把当前项目根目录挂进容器见下文陷阱 2。第 2 步改为你的仓库目录# .env WORKSPACE_DIR/home/you/code强烈建议写绝对路径相对路径会以 compose 文件所在目录为基准解析换目录启动行为就变了。第 3 步带 env 文件启动并索引docker compose --env-file .env up -d docker compose exec gitnexus-server gitnexus index /workspace/my-repo启动后打开http://localhost:4173UI 会自动探测http://localhost:4747的服务器浏览器跑在宿主机上直接走映射端口即可。五大常见陷阱踩坑清单⚠️陷阱 1改完WORKSPACE_DIR忘记重启容器环境变量只在容器创建时被读取运行中的容器不会感知。修改后必须执行docker compose up -d # 或 docker compose down docker compose up -d否则你索引的永远是旧挂载点。陷阱 2默认./或./workspace的安全与空目录问题docker-compose.yaml 的注释特意说明默认指向一个空的./workspace/兄弟目录compose 首次启动时自动创建——这是刻意的安全设计避免把仓库根目录的.git、.env、CI 密钥暴露给容器但若你把 .env.example 里的WORKSPACE_DIR./原样保留并复制为.env效果就变成挂载项目根目录。虽然仍是:ro只读、无法被写入但仓库文件本身对容器可见。只挂你真正需要索引的目录是最稳妥的做法。陷阱 3相对路径基准错误WORKSPACE_DIRcode这类相对路径是相对于docker-compose.yaml所在目录解析的不是你的当前 shell 工作目录。在别的目录执行 compose 命令、或把 compose 文件挪进子目录挂载就会消失。最保险的做法依然是绝对路径或$HOME/code。陷阱 4只读挂载下的.gitnexus/缓存文件由于挂载是:roGitNexus 无法在你宿主机仓库里写.gitnexus/.gitignore来隐藏本地索引缓存。源码中 repo-manager.ts 专门处理了这种情况遇到EROFS/EACCES/EPERM时降级为警告而不是报错对应 issue #1549。代价是这些缓存文件可能在宿主机仓库的git status里显示为 untracked。这不是故障属于预期行为介意的话可在自己的.gitignore里加一行.gitnexus/。陷阱 5镜像名混淆image rename早期 Web UI 也发布在ghcr.io/abhigyanpatwari/gitnexus现在该 slug 专供CLI/服务端UI 迁移到了gitnexus-web镜像Docker Hub 镜像 为akonlabs/gitnexus与akonlabs/gitnexus-web。旧 tag 仍可拉取但新版本只发新 slug——建议直接采用官方捆绑的 compose 文件或核对镜像名。进阶把容器索引接进 AI 编码工具索引完成后价值不仅在于 Web 端浏览图谱。GitNexus 容器暴露的 MCP 端点可以让 Kilo Code 等 AI 编码助手直接查询你的代码知识图谱上图展示了在 Kilo Code 的Agent Behaviour → MCP Servers中gitnexus条目处于 connected 状态。配置细节参见 Documentation/kilo-code-mcp.md。速查表故障排查症状原因处理index报路径不存在用了宿主机路径/home/you/code/...容器内请改用/workspace/...挂载目录是空的WORKSPACE_DIR相对路径解析位置不对改为绝对路径并重启容器改 env 不生效容器未重建docker compose up -d重建警告 storage filesystem is not writable只读挂载下无法写.gitnexus/.gitignore可忽略在仓库.gitignore手动加.gitnexus/Web UI 连不上服务器端口被占用用SERVER_HOST_PORT/WEB_HOST_PORT换端口小结容器化索引本地仓库的心法一句话WORKSPACE_DIR挂宿主机目录 → 容器内路径前缀换成/workspace→ 索引数据落在gitnexus-data卷里持久保存。掌握启动时生效、只读挂载、绝对路径这三个要点就能避开绝大多数坑让 GitNexus 在 Docker 环境里稳定地为你的本地仓库构建知识图谱。相关资源路径编排文件docker-compose.yaml、.env.example构建文件Dockerfile.cli、Dockerfile.web存储与只读处理逻辑gitnexus/src/storage/repo-manager.ts主文档 Docker 章节README.md【免费下载链接】GitNexusGitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a git repository (Github, Gitlab, Azure, Local) or ZIP file, and get an interactive knowledge graph with a built in Graph RAG Agent. Perfect for code exploration项目地址: https://gitcode.com/GitHub_Trending/gi/GitNexus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考