用 GitNexus 索引代码库并提供交互式知识图谱 Web UI
概述
索引任意代码库为知识图谱，提供交互式 Web UI 探索符号、调用链、聚类和执行流。通过 Cloudflare 隧道远程访问。
使用场景
- 用户想可视化探索代码库架构
- 用户要求代码库的知识图谱/依赖图
- 用户想与他人分享交互式代码库浏览器
前置条件
- Node.js (v18+) — GitNexus 和代理所需
- git — 代码库必须有 .git 目录
- cloudflared — 用于隧道（如缺失自动安装到 ~/.local/bin）
大小警告
Web UI 在浏览器中渲染所有节点。约 5,000 文件以下的代码库工作良好。大型代码库（30k+ 节点）会卡顿或崩溃浏览器标签。
CLI/MCP 工具任意规模都可用——只有 Web 可视化有此限制。
步骤
1. 克隆并构建 GitNexus（一次性设置）
GITNEXUS_DIR="${GITNEXUS_DIR:-$HOME/.local/share/gitnexus}"
if [ ! -d "$GITNEXUS_DIR/gitnexus-web/dist" ]; then
git clone https://github.com/abhigyanpatwari/GitNexus.git "$GITNEXUS_DIR"
cd "$GITNEXUS_DIR/gitnexus-shared" && npm install && npm run build
cd "$GITNEXUS_DIR/gitnexus-web" && npm install
fi
2. 修补 Web UI 以支持远程访问
Web UI 默认用
localhost:4747 调用 API。修补为同源以便通过隧道/代理工作：
文件：
$GITNEXUS_DIR/gitnexus-web/src/config/ui-constants.ts
修改：
export const DEFAULT_BACKEND_URL = 'http://localhost:4747';
改为：
export const DEFAULT_BACKEND_URL = typeof window !== 'undefined' && window.location.hostname !== 'localhost'
? window.location.origin
: 'http://localhost:4747';
文件：
$GITNEXUS_DIR/gitnexus-web/vite.config.ts
在
server: { } 块内添加
allowedHosts: true（仅开发模式需要）：
server: {
allowedHosts: true,
// ... 现有配置
},
然后构建生产包：
cd "$GITNEXUS_DIR/gitnexus-web" && npx vite build
3. 索引目标代码库
cd /path/to/target-repo
npx gitnexus analyze --skip-agents-md
rm -rf .claude/ # 移除 Claude Code 特定产物
添加
--embeddings 启用语义搜索（更慢——分钟而非秒）。索引存在代码库内的
.gitnexus/（自动 gitignore）。
4. 创建代理脚本
写入文件（如
$GITNEXUS_DIR/proxy.mjs）。它提供生产 Web UI 并代理
/api/* 到 GitNexus 后端——同源、无 CORS 问题、无 sudo、无 nginx。
import http from 'node:http';
import fs from 'node:fs';
import path from 'node:path';
const API_PORT = parseInt(process.env.API_PORT || '4747');
const DIST_DIR = process.argv[2] || './dist';
const PORT = parseInt(process.argv[3] || '8888');
const MIME = {
'.html': 'text/html',
'.js': 'application/javascript',
'.css': 'text/css',
'.json': 'application/json',
'.png': 'image/png',
'.svg': 'image/svg+xml',
'.ico': 'image/x-icon',
'.woff2': 'font/woff2',
'.woff': 'font/woff',
'.wasm': 'application/wasm',
};
function proxyToApi(req, res) {
const opts = {
hostname: '127.0.0.1',
port: API_PORT,
path: req.url,
method: req.method,
headers: req.headers,
};
const proxy = http.request(opts, (upstream) => {
res.writeHead(upstream.statusCode, upstream.headers);
upstream.pipe(res, { end: true });
});
proxy.on('error', () => {
res.writeHead(502);
res.end('Backend unavailable');
});
req.pipe(proxy, { end: true });
}
function serveStatic(req, res) {
let filePath = path.join(DIST_DIR, req.url === '/' ? 'index.html' : req.url.split('?')[0]);
if (!fs.existsSync(filePath)) filePath = path.join(DIST_DIR, 'index.html');
const ext = path.extname(filePath);
const mime = MIME[ext] || 'application/octet-stream';
try {
const data = fs.readFileSync(filePath);
res.writeHead(200, { 'Content-Type': mime, 'Cache-Control': 'public, max-age=3600' });
res.end(data);
} catch {
res.writeHead(404);
res.end('Not found');
}
}
http.createServer((req, res) => {
if (req.url.startsWith('/api')) proxyToApi(req, res);
else serveStatic(req, res);
}).listen(PORT, () => console.log(GitNexus proxy on http://localhost:${PORT}));
5. 启动服务
# 终端 1：GitNexus 后端 API
npx gitnexus serve &
# 终端 2：代理（Web UI + API 同端口）
node "$GITNEXUS_DIR/proxy.mjs" "$GITNEXUS_DIR/gitnexus-web/dist" 8888 &
验证：
curl -s http://localhost:8888/api/repos 应返回已索引的代码库。
6. 用 Cloudflare 隧道（可选——用于远程访问）
# 如需安装 cloudflared（无需 sudo）
if ! command -v cloudflared &>/dev/null; then
mkdir -p ~/.local/bin
curl -sL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64
-o ~/.local/bin/cloudflared
chmod +x ~/.local/bin/cloudflared
export PATH="$HOME/.local/bin:$PATH"
fi
# 启动隧道（--config /dev/null 避免与现有命名隧道冲突）
cloudflared tunnel --config /dev/null --url http://localhost:8888 --no-autoupdate --protocol http2
隧道 URL（如
https://random-words.trycloudflare.com）打印到 stderr。分享它——任何有链接的人都能探索图谱。
7. 清理
# 停止服务
pkill -f "gitnexus serve"
pkill -f "proxy.mjs"
pkill -f cloudflared
# 从目标代码库移除索引
cd /path/to/target-repo
npx gitnexus clean
rm -rf .claude/
陷阱
--config /dev/null 对 cloudflared 必需，如果用户在 ~/.cloudflared/config.yml 有现有命名隧道配置。没有它，配置中的 catch-all 入口规则会对所有快速隧道请求返回 404。- 生产构建对隧道必需。Vite 开发服务器默认阻止非 localhost 主机（
allowedHosts）。生产构建 + Node 代理完全避免此问题。
- Web UI 不创建
.claude/ 或 CLAUDE.md。这些由 npx gitnexus analyze 创建。用 --skip-agents-md 抑制 markdown 文件，然后用 rm -rf .claude/ 清理其余。这些是 hermes-agent 用户不需要的 Claude Code 集成。
- 浏览器内存限制。Web UI 将整个图谱加载到浏览器内存。5k+ 文件的代码库可能卡顿。30k+ 文件可能崩溃标签。
- 嵌入可选。
--embeddings 启用语义搜索但大型代码库需要几分钟。快速探索跳过；如果想要 AI 聊天面板的自然语言查询则添加。
- 多代码库。
gitnexus serve 服务所有已索引代码库。索引多个代码库，启动一次 serve，Web UI 让你在其间切换。
评论区