GitNexus_Ubuntu2204_最佳实践

GitNexus on Ubuntu 22.04 最佳实践

本文档记录如何在 Ubuntu 22.04 LTS 上部署和使用 GitNexus 最新版本（1.4.10+）。 由于 @ladybugdb/core 的 native binary 需要 GLIBC 2.38+，而 Ubuntu 22.04 仅提供 GLIBC 2.35， 因此需要通过 Docker（基于 Ubuntu 24.04）来运行 GitNexus。

---

目录

1. 环境要求
2. 安装 Docker
3. 配置 Docker 镜像加速
4. 构建 GitNexus Docker 镜像
5. 索引项目代码
6. 配置 MCP Server
7. 日常使用
8. 升级 GitNexus
9. 问题排查

---

1. 环境要求

组件	要求
操作系统	Ubuntu 22.04 LTS
Docker	20.10+
Node.js（宿主机）	不需要（运行在容器内）
磁盘空间	Docker 镜像约 1.5GB + 每个项目索引空间
网络	首次构建需要访问 Docker Hub 和 npm registry

为什么需要 Docker

GitNexus 1.4.x 依赖 @ladybugdb/core，其 native binary (lbugjs.node) 编译目标为 GLIBC 2.38+。 Ubuntu 22.04 的系统 GLIBC 版本为 2.35，无法加载该 binary，表现为：

Error: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found

通过 Docker 容器（Ubuntu 24.04, GLIBC 2.39）运行 GitNexus 可以完美解决此问题，且：

• 代码文件保留在宿主机，通过 volume 挂载，无需同步
• MCP Server 通过 stdio 通信，延迟可忽略
• 升级只需重新构建镜像

---

2. 安装 Docker

# 安装 Docker Engine
curl -fsSL https://get.docker.com | sudo sh
 
# 将当前用户加入 docker 组（免 sudo）
sudo usermod -aG docker $USER
 
# 立即生效（不用重新登录）
newgrp docker
 
# 验证安装
docker --version
docker run --rm hello-world

如果 Claude Code 等进程在 newgrp 之前启动，可以临时放开 socket 权限：

sudo chmod 666 /var/run/docker.sock

注意：重启后 socket 权限会恢复，建议通过 newgrp docker 或重新登录来永久解决。

---

3. 配置 Docker 镜像加速

国内网络环境下直接访问 Docker Hub 可能不通，需要配置镜像加速器。

sudo tee /etc/docker/daemon.json <<'EOF'
{
  "registry-mirrors": [
    "https://docker.1panel.live",
    "https://docker.m.daocloud.io"
  ]
}
EOF
 
sudo systemctl restart docker

验证加速器是否生效：

docker info | grep -A5 "Registry Mirrors"

---

4. 构建 GitNexus Docker 镜像

4.1 创建 Dockerfile

在项目中创建 Dockerfile.mcp（已存在于 gitnexus/Dockerfile.mcp）：

FROM ubuntu:24.04
 
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl ca-certificates git && \
    curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && \
    apt-get install -y --no-install-recommends nodejs && \
    rm -rf /var/lib/apt/lists/*
 
ENV ONNXRUNTIME_NODE_INSTALL=skip
 
RUN npm install -g gitnexus@1.4.10
 
ENTRYPOINT ["gitnexus"]

关键点说明：

• 基础镜像 ubuntu:24.04：提供 GLIBC 2.39，满足 @ladybugdb/core 的要求
• 安装 git：GitNexus 需要 git 来检测仓库状态和 commit 信息
• ONNXRUNTIME_NODE_INSTALL=skip：跳过 onnxruntime 的 CUDA binary 下载（NuGet 源在国内不稳定），不影响索引和查询功能，仅影响 GPU 加速的嵌入向量生成

4.2 构建镜像

cd /home/zbc/pangu/GitNexus/gitnexus
docker build -f Dockerfile.mcp -t gitnexus:1.4.10 .

4.3 验证镜像

docker run --rm gitnexus:1.4.10 --version
# 输出: 1.4.10

---

5. 索引项目代码

5.1 Docker 运行参数说明

所有 Docker 命令都需要以下参数：

docker run --rm \
  -v /home/zbc:/home/zbc \    # 挂载宿主机 home 目录
  --user 1000:1000 \           # 以宿主机用户身份运行（避免 git safe.directory 问题）
  -e HOME=/home/zbc \          # 设置 HOME（容器默认 HOME 不对）
  -w /path/to/repo \           # 设置工作目录为目标仓库
  gitnexus:1.4.10 \
  <command>

参数必要性：

参数	原因	不加的后果
-v /home/zbc:/home/zbc	让容器访问宿主机代码和索引文件	找不到任何文件
--user 1000:1000	匹配宿主机文件所有者 UID/GID	git 报 “dubious ownership” 拒绝操作
-e HOME=/home/zbc	让 GitNexus 找到 ~/.gitnexus/registry.json	MCP Server 报 “No indexed repos”
-w /path/to/repo	设置工作目录	GitNexus 不知道要操作哪个仓库

提示：--user 的值可通过 id -u 和 id -g 获取。大多数单用户系统是 1000:1000。

5.2 索引单个项目

docker run --rm \
  -v /home/zbc:/home/zbc --user 1000:1000 \
  -w /home/zbc/micode/MiuiSystemUI \
  gitnexus:1.4.10 analyze

带嵌入向量（语义搜索）：

docker run --rm \
  -v /home/zbc:/home/zbc --user 1000:1000 \
  -w /home/zbc/micode/MiuiSystemUI \
  gitnexus:1.4.10 analyze --embeddings

5.3 批量索引多个项目

DOCKER_OPTS="--rm -v /home/zbc:/home/zbc --user 1000:1000"
 
for repo in \
  /home/zbc/micode/MiuiSystemUI \
  /home/zbc/micode/MiuiSystemUIPlugin \
  /home/zbc/micode/framework/base \
  /home/zbc/micode/frameworksNative/native \
  /home/zbc/pangu/MiuiAod \
  /home/zbc/micode/aospframeworks/base \
  /home/zbc/pangu/perfetto; do
  echo "=== Indexing $repo ==="
  docker run $DOCKER_OPTS -w "$repo" gitnexus:1.4.10 analyze
done

并行索引（加速，适合多核机器）：

DOCKER_OPTS="--rm -v /home/zbc:/home/zbc --user 1000:1000"
 
docker run $DOCKER_OPTS -w /home/zbc/micode/MiuiSystemUI gitnexus:1.4.10 analyze &
docker run $DOCKER_OPTS -w /home/zbc/micode/framework/base gitnexus:1.4.10 analyze &
docker run $DOCKER_OPTS -w /home/zbc/pangu/MiuiAod gitnexus:1.4.10 analyze &
docker run $DOCKER_OPTS -w /home/zbc/micode/aospframeworks/base gitnexus:1.4.10 analyze &
wait
echo "All done!"

5.4 查看索引状态

# 查看单个仓库状态
docker run --rm -v /home/zbc:/home/zbc --user 1000:1000 \
  -w /home/zbc/micode/MiuiSystemUI gitnexus:1.4.10 status
 
# 查看所有已索引仓库
docker run --rm -v /home/zbc:/home/zbc --user 1000:1000 \
  -e HOME=/home/zbc gitnexus:1.4.10 list

---

6. 配置 MCP Server

GitNexus 通过 MCP（Model Context Protocol）与 Claude Code 通信。需要将 .mcp.json 中的 MCP Server 配置改为 Docker 启动方式。

6.1 配置格式

在项目根目录的 .mcp.json 或全局 ~/.mcp.json 中：

{
  "mcpServers": {
    "gitnexus": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/home/zbc:/home/zbc",
        "--user", "1000:1000",
        "-e", "HOME=/home/zbc",
        "gitnexus:1.4.10",
        "mcp"
      ]
    }
  }
}

关键参数：

• -i：交互模式，MCP 通过 stdin/stdout 通信，必须开启
• --rm：容器退出后自动清理
• 不需要 -t：MCP 不需要 TTY

6.2 需要更新的配置文件

检查所有包含 gitnexus MCP 配置的文件并统一更新：

# 查找所有 .mcp.json
find /home/zbc -maxdepth 3 -name ".mcp.json" -exec grep -l "gitnexus" {} \;

通常需要更新：

• ~/.mcp.json — 全局配置（所有项目生效）
• <project>/.mcp.json — 项目级配置（优先级高于全局）

6.3 验证 MCP Server

docker run --rm -i \
  -v /home/zbc:/home/zbc --user 1000:1000 -e HOME=/home/zbc \
  gitnexus:1.4.10 mcp <<< \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}'

成功输出应包含：

GitNexus: MCP server starting with N repo(s): ...
{"result":{"protocolVersion":"2024-11-05",...,"serverInfo":{"name":"gitnexus","version":"1.4.10"}},...}

---

7. 日常使用

7.1 Shell 别名（推荐）

在 ~/.bashrc 或 ~/.zshrc 中添加：

alias gitnexus='docker run --rm -v /home/zbc:/home/zbc --user 1000:1000 -e HOME=/home/zbc -w "$(pwd)" gitnexus:1.4.10'

之后可以直接使用：

cd /home/zbc/micode/MiuiSystemUI
gitnexus status
gitnexus analyze
gitnexus list

7.2 代码变更后更新索引

在提交代码后重新索引：

cd /path/to/repo
gitnexus analyze    # 使用上面的别名

GitNexus 是增量索引，如果代码没变会输出 “Already up to date”。

7.3 新项目索引

cd /path/to/new/git/repo
gitnexus analyze

索引完成后 MCP Server 会自动发现新仓库（通过 ~/.gitnexus/registry.json）。

7.4 清理索引

cd /path/to/repo
gitnexus clean

---

8. 升级 GitNexus

8.1 升级步骤

cd /home/zbc/pangu/GitNexus/gitnexus
 
# 1. 修改 Dockerfile.mcp 中的版本号
sed -i 's/gitnexus@1.4.10/gitnexus@NEW_VERSION/' Dockerfile.mcp
 
# 2. 重新构建镜像
docker build -f Dockerfile.mcp -t gitnexus:NEW_VERSION .
 
# 3. 更新所有 .mcp.json 中的镜像 tag
find /home/zbc -maxdepth 3 -name ".mcp.json" -exec \
  sed -i 's/gitnexus:1.4.10/gitnexus:NEW_VERSION/g' {} \;
 
# 4. 更新 shell 别名（如果设置了）
# 编辑 ~/.bashrc 中 gitnexus 别名的版本号
 
# 5. 重新索引所有项目（如有 schema 变化）
gitnexus analyze

8.2 保留旧镜像

建议保留上一个版本的镜像作为回退：

# 查看已有镜像
docker images gitnexus
 
# 需要回退时修改 .mcp.json 中的 tag 即可

8.3 清理旧镜像

docker rmi gitnexus:OLD_VERSION

---

9. 问题排查

9.1 GLIBC 版本不匹配

现象：

Error: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found

原因： 直接在宿主机运行了 gitnexus（未通过 Docker）。

解决： 所有 gitnexus 命令必须通过 Docker 运行，不要使用 npx gitnexus 或 node dist/cli/index.js。

---

9.2 git “dubious ownership” 错误

现象： Not a git repository 或 detected dubious ownership。

原因： Docker 容器默认以 root 运行，与宿主机文件 owner 不匹配。

解决： 确保使用了 --user $(id -u):$(id -g) 参数。

---

9.3 MCP Server 找不到仓库

现象： No indexed repos yet。

原因： 容器内 HOME 默认不是 /home/zbc，找不到 registry.json。

解决： 确保 MCP 配置中包含 -e HOME=/home/zbc。

---

9.4 onnxruntime 安装失败

现象： 构建镜像时报 Failed to download build list. HTTP status code = 302。

原因： onnxruntime-node 的 postinstall 脚本从 NuGet 下载 CUDA binary 失败。

解决： Dockerfile 中设置 ENV ONNXRUNTIME_NODE_INSTALL=skip。该环境变量跳过 CUDA binary 下载，不影响核心功能。

---

9.5 Docker 权限问题

现象： permission denied while trying to connect to the docker API

解决：

# 方案 1：临时（重启后失效）
sudo chmod 666 /var/run/docker.sock
 
# 方案 2：永久
sudo usermod -aG docker $USER
# 然后重新登录或执行 newgrp docker

---

9.6 Docker Hub 无法访问

现象： connection reset by peer 或超时。

解决： 配置镜像加速器（见第 3 节）。

---

9.7 索引过时 (stale)

现象： GitNexus MCP 工具提示 index is stale。

解决：

docker run --rm -v /home/zbc:/home/zbc --user 1000:1000 \
  -w /path/to/repo gitnexus:1.4.10 analyze

---

9.8 KuzuDB 旧格式索引

现象： has a stale KuzuDB index. Run: gitnexus analyze。

原因： 索引是用旧版 GitNexus（1.3.x，使用 KuzuDB）创建的，需要迁移到 LadybugDB 格式。

解决： 重新运行 analyze，会自动迁移：

docker run --rm -v /home/zbc:/home/zbc --user 1000:1000 \
  -w /path/to/repo gitnexus:1.4.10 analyze

---

附录

A. 关键文件路径

文件	用途
~/.gitnexus/registry.json	全局仓库注册表（记录所有已索引仓库）
<repo>/.gitnexus/	仓库索引数据目录
<repo>/.gitnexus/meta.json	索引元数据（commit hash、索引时间、统计）
~/pangu/GitNexus/gitnexus/Dockerfile.mcp	GitNexus Docker 镜像定义文件
~/.mcp.json	全局 MCP Server 配置
<project>/.mcp.json	项目级 MCP Server 配置
/etc/docker/daemon.json	Docker 守护进程配置（镜像加速器）

B. Docker 命令速查

# 查看 gitnexus 镜像
docker images gitnexus
 
# 查看运行中的 gitnexus 容器
docker ps | grep gitnexus
 
# 进入容器调试
docker run --rm -it \
  -v /home/zbc:/home/zbc --user 1000:1000 -e HOME=/home/zbc \
  --entrypoint bash gitnexus:1.4.10
 
# 查看容器内 GLIBC 版本
docker run --rm gitnexus:1.4.10 bash -c "ldd --version" 2>/dev/null || \
docker run --rm --entrypoint ldd gitnexus:1.4.10 --version

C. 当前已索引仓库

项目	路径	符号数	关系数
MiuiSystemUI	/home/zbc/micode/MiuiSystemUI	72,521	184,658
MiuiSystemUIPlugin	/home/zbc/micode/MiuiSystemUIPlugin	5,704	11,156
base (miui)	/home/zbc/micode/framework/base	88,465	271,166
native	/home/zbc/micode/frameworksNative/native	39,150	70,782
MiuiAod	/home/zbc/pangu/MiuiAod	8,959	21,511
base (aosp)	/home/zbc/micode/aospframeworks/base	578,843	1,684,890
perfetto	/home/zbc/pangu/perfetto	42,579	98,479