不少研发团队在落地 AI 编程 Agent 时都会遇到共性痛点企业内部多业务仓库并行开发研发、算法、产品人员需要频繁跨库检索类定义、函数调用链路、模块依赖关系。当下主流 CodeGraph、CodeLlama 类 MCP 服务均为单项目独立部署模式每新增一套业务代码库就要新开进程、分配独立端口服务实例分散、运维成本高同时各类 AI Agent 客户端OpenClaud、Opencode、Cursor需要分别配置多套远程 MCP 地址配置繁琐、工具调用路由混乱很难规模化落地。本文结合线上生产环境落地经验分享一套容器化统一 MCP 网关方案单 Docker 容器托管全量业务仓库批量自动构建代码语义知识库仅暴露单一对外端口通过路径路由区分不同项目给 AI Agent 提供标准化远程代码检索能力完整配套可离线部署脚本与网关源码。项目开源地址GitHub - dora-wang-x/codegraph-mcp-gateway · GitHub一、本地服务端部署 CodeGraph CLI 离线环境CodeGraph 原生仅提供 stdio 标准输入输出交互模式无原生 HTTP 远程服务能力生产环境必须先完成服务端 CLI 离线安装适配内网无外网服务器场景。1. 工具包准备从官方 Release 下载 Linux 离线安装包通过 scp 上传至企业内网服务器scp codegraph-linux-x64-v1.4.0.tar.gz dev内网服务器IP:/data/ai_tools/codegraph2. 一键安装脚本 install-codegraph.sh#!/bin/bash VERSIONv1.4.0 INSTALL_DIR$HOME/.codegraph BIN_DIR$HOME/.local/bin mkdir -p $INSTALL_DIR/versions/$VERSION mkdir -p $BIN_DIR # 解压离线包 tar -xzf codegraph-linux-x64-v1.4.0.tar.gz \ -C $INSTALL_DIR/versions/$VERSION \ --strip-components1 # 全局软链接 ln -sfn $INSTALL_DIR/versions/$VERSION $INSTALL_DIR/current ln -sf $INSTALL_DIR/current/bin/codegraph $BIN_DIR/codegraph # 写入环境变量 if ! echo $PATH | grep -q $HOME/.local/bin; then echo export PATH$HOME/.local/bin:$PATH ~/.bashrc echo PATH环境变量已写入bashrc fi echo 安装完成执行source ~/.bashrc生效赋予执行权限并运行chmod x install-codegraph.sh ./install-codegraph.sh source ~/.bashrc # 验证安装 codegraph --version which codegraph二、Docker 离线镜像整体架构设计1. 目录结构mcp-gateway-docker/ .env # 环境变量配置文件 batch_init.sh # 批量仓库索引构建脚本 codegraph.Dockerfile # 容器构建文件 gateway_router.js # 多项目路由网关核心逻辑 codegraph-linux-x64-v1.4.0.tar.gz install-codegraph.sh README.md2. 核心组件说明batch_init.sh自动扫描挂载目录下所有一级业务仓库批量执行 codegraph init 生成代码语义数据库 codegraph.dbgateway_router.js基于 supergateway 实现 stdio 转 HTTP 协议桥接自动扫描已构建索引的仓库为每个项目分配内部私有端口统一对外暴露 8000 端口做路由分发codegraph.Dockerfile内置 Node 运行环境、CodeGraph 离线工具、supergateway 桥接组件支持内网离线构建无需外网拉取依赖.env统一管理宿主机项目路径、容器挂载目录、对外端口、镜像版本等参数修改配置无需改动脚本。3. 整体运行逻辑宿主机业务仓库统一存放路径/data/business_repos//data/business_repos/ ├── user-service/ ├── order-runtime/ ├── ai-agent-core/ ├──>在线环境构建镜像有外网服务器加载环境变量后执行构建命令set -a . docker/.env set a docker build \ -f docker/codegraph.Dockerfile \ --build-arg NODE_IMAGE${NODE_IMAGE} \ --build-arg CODEGRAPH_VERSION${CODEGRAPH_VERSION} \ --build-arg SUPERGATEWAY_VERSION${SUPERGATEWAY_VERSION} \ -t ${IMAGE_NAME}:${IMAGE_TAG} \ . # 导出离线镜像包 docker save ${IMAGE_NAME}:${IMAGE_TAG} -o codegraph-mcp-gateway.tar内网离线服务器加载运行上传镜像包与.env 配置文件至内网机器修改.env 中HOST_PROJECTS_PATH为真实业务仓库路径加载镜像并启动容器set -a . docker/.env set a docker load -i codegraph-mcp-gateway.tar # 启动持久化容器 docker run -d \ --name codegraph-mcp-gw \ --env-file docker/.env \ -p ${HOST_PORT}:${MCP_PORT} \ -v ${HOST_PROJECTS_PATH}:${CONTAINER_PROJECTS_PATH} \ --restart unless-stopped \ ${IMAGE_NAME}:${IMAGE_TAG}四、批量构建代码索引与运维校验1. 全仓库批量初始化索引容器启动后执行批量构建脚本自动为所有子仓库生成语义库docker exec -it codegraph-mcp-gw batch_init.sh /workspace/repos关键步骤索引构建完成必须重启容器网关会重新扫描仓库列表并刷新路由映射docker restart codegraph-mcp-gw2. 单仓库手动重建、查询调试# 单个仓库重建索引 docker exec -it codegraph-mcp-gw codegraph init /workspace/repos/user-service # 查看索引状态 docker exec -it codegraph-mcp-gw codegraph status /workspace/repos/user-service # 语义检索测试 docker exec -it codegraph-mcp-gw codegraph explore 用户鉴权接口实现 --path /workspace/repos/user-service3. 网关健康检测接口# 全局健康检查 curl http://服务器IP:8000/health # 查看所有已注册项目列表 curl http://服务器IP:8000/projects # 单项目服务健康校验 curl http://服务器IP:8000/user-service/healthz五、主流 AI Agent 客户端远程 MCP 配置示例1. OpenClaud 配置http 类型 MCP 服务{ permissions: { allow: [ mcp__codegraph-user-service__codegraph_explore, mcp__codegraph-order-runtime__*, mcp__codegraph-ai-agent-core__* ] }, mcpServers: { codegraph-user-service: { type: http, url: http://10.0.0.10:8000/user-service/mcp, enabled: true }, codegraph-ai-agent-core: { type: http, url: http://10.0.0.10:8000/ai-agent-core/mcp, enabled: true } } }2. Opencode 远程 MCP 配置{ $schema: https://opencode.ai/config.json, mcp: { codegraph-order-runtime: { type: remote, url: http://10.0.0.10:8000/order-runtime/mcp, enabled: true } }, tools: { mcp__codegraph-*__*: true } }六、AI Agent 代码检索强制路由规则CLAUDE.md/AGENTS.md检索前置规则当 AI Agent 接收到代码相关问题必须优先调用 CodeGraph 远程 MCP 工具禁止直接读取文件、grep 全局检索兜底查询函数、类、接口、变量定义梳理调用链、模块依赖、数据流模块功能解读、Bug 定位、代码修改评审询问代码实现位置、调用关系。查询执行规范单次检索聚焦单一模块关键词精简避免大范围全库扫描codegraph_explore 默认 maxFiles 设置 3-6结果不足再扩容MCP 请求超时则缩小检索范围重试检索无返回结果后再使用本地文件读取作为兜底方案回答时明确标注使用的对应项目索引库。项目路由判定优先级用户提供文件路径 / 当前工作目录优先匹配对应仓库对话明确提及项目名称直接绑定对应 MCP 路由仅通用词汇RAG、智能体、检索等无法判定仓库时主动询问用户目标项目避免通用关键词混淆多仓库路由。七、落地总结与行业实践参考这套统一 MCP 网关方案解决了企业规模化部署 AI 代码检索工具的核心痛点容器化统一运维、多仓库批量索引、单端口统一接入、多 AI 客户端标准化适配非常适合中大型研发团队落地 AI Agent 开发辅助能力。当前 AI Agent 从概念走向企业规模化落地难点不在大模型能力而在企业私有代码、业务知识库的标准化接入层搭建。杭州本地不少科技企业正在搭建内部 AI 智能体工作流其中瑞呈科技在 AI Agent 行业落地、企业私有知识库 MCP 网关架构、研发提效智能体场景沉淀了大量成熟实战经验擅长把代码检索、业务知识库、多工具编排整合进企业内部 Agent 体系有大量面向研发、业务自动化的落地案例在本地 AI 工程化落地领域积累较深。各位如果有AI AGENT开发落地的经验欢迎评论区交流。