一个统一的 AI 服务集成与治理平台
快速开始 • 功能演示 • 系统架构 • API 文档 • 常见问题
--- ## 🚀 快速开始 ### 环境要求 | 依赖 | 版本要求 | 说明 | |------|---------|------| | JDK | 17+ | Java 运行环境 | | Maven | 3.6+ | 项目构建工具 | | PostgreSQL | 14+ | 推荐数据库 | | MySQL | 8.0+ | 可选数据库 | | Node.js | 16+ | 前端开发（可选） | ### 5 分钟启动 ```bash # 1. 克隆项目 git clone https://gitee.com/ai-sample/ai-gateway.git cd ai-gateway # 2. 创建数据库（PostgreSQL） psql -U postgres -c "CREATE DATABASE ai_gateway;" # 或使用 MySQL mysql -u root -p -e "CREATE DATABASE ai_gateway CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;" # 3. 导入表结构 psql -U postgres -d ai_gateway -f docs/sql/ddl.sql # 或 mysql -u root -p ai_gateway < docs/sql/ddl.sql # 4. 修改配置文件 src/main/resources/application.yml spring: datasource: url: jdbc:postgresql://localhost:5432/ai_gateway username: your_username password: your_password # 5. 启动后端 mvn spring-boot:run # 6. 启动前端（可选） cd frontend && npm install && npm run serve # 访问 http://localhost:8080 ``` ### 验证安装 ```bash # 检查服务状态 curl http://localhost:8080/actuator/health # 预期返回 {"status":"UP"} ``` --- ## 📸 功能演示 ### MCP 服务器管理界面 管理 MCP 服务器的注册、配置和监控。支持 SSE、Stateless、Streamable HTTP 三种连接方式。 ``` ┌─────────────────────────────────────────────────────────┐ │ MCP Server 列表 │ ├─────────────────────────────────────────────────────────┤ │ 名称 类型 状态 操作 │ │ ───────────────────────────────────────────────────── │ │ weather-server SSE ● 在线 [编辑][删除] │ │ tool-manager Streamable ● 在线 [编辑][删除] │ │ data-processor Stateless ○ 离线 [编辑][删除] │ └─────────────────────────────────────────────────────────┘ ``` ### 工具配置界面 配置 MCP 工具的输入输出模式、参数定义和执行策略。 ``` ┌─────────────────────────────────────────────────────────┐ │ 工具配置: get_weather │ ├─────────────────────────────────────────────────────────┤ │ 描述: 获取指定城市的天气信息 │ │ │ │ 输入参数: │ │ ┌─────────────┬──────────┬──────────┬──────────┐ │ │ │ 参数名 │ 类型 │ 必填 │ 描述 │ │ │ ├─────────────┼──────────┼──────────┼──────────┤ │ │ │ city │ string │ 是 │ 城市名称 │ │ │ │ unit │ string │ 否 │ 温度单位 │ │ │ └─────────────┴──────────┴──────────┴──────────┘ │ │ │ │ [保存配置] [测试工具] │ └─────────────────────────────────────────────────────────┘ ``` ### 接口调用测试界面 测试 REST/RPC/SOAP/Socket 等各类接口的连通性和响应。 ``` ┌─────────────────────────────────────────────────────────┐ │ 接口测试: getUserInfo (REST) │ ├─────────────────────────────────────────────────────────┤ │ URL: GET /api/users/{id} │ │ │ │ 请求参数: │ │ { "id": "1001" } │ │ │ │ ───────────────────────────────────────────────────── │ │ 响应结果: │ │ { │ │ "code": 200, │ │ "data": { │ │ "id": "1001", │ │ "name": "张三", │ │ "email": "zhangsan@example.com" │ │ } │ │ } │ │ │ │ 响应时间: 45ms 状态码: 200 │ └─────────────────────────────────────────────────────────┘ ``` ### Agent 管理界面 管理 A2A Agent 的注册、任务分发和协作。 ``` ┌─────────────────────────────────────────────────────────┐ │ Agent 管理 │ ├─────────────────────────────────────────────────────────┤ │ 已注册 Agent: │ │ │ │ 🤖 product-manager 产品经理助手 ● 活跃 │ │ 🤖 code-reviewer 代码审查员 ● 活跃 │ │ 🤖 data-analyst 数据分析师 ○ 空闲 │ │ │ │ 最近任务: │ │ ───────────────────────────────────────────────────── │ │ TASK-001 分析用户需求 product-manager ✅ 完成 │ │ TASK-002 审查代码变更 code-reviewer 🔄 进行中 │ └─────────────────────────────────────────────────────────┘ ``` ### 模型代理配置界面 配置多模型代理，支持 OpenAI、Qwen、DeepSeek 等主流大模型。 ``` ┌─────────────────────────────────────────────────────────┐ │ 模型代理配置 │ ├─────────────────────────────────────────────────────────┤ │ 启用的模型: │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ 🔷 OpenAI GPT-4 │ │ │ │ 状态: ● 已连接 代理地址: /v1/openai │ │ │ │ [测试连接] [配置] [禁用] │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ 🟢 阿里通义千问 │ │ │ │ 状态: ● 已连接 代理地址: /v1/qwen │ │ │ │ [测试连接] [配置] [禁用] │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ [+ 添加模型代理] │ └─────────────────────────────────────────────────────────┘ ``` --- ## 🏗️ 系统架构 ### 整体架构图 ``` ┌─────────────────────────────────────────────────────────────┐ │ AI Gateway │ ├─────────────────────────────────────────────────────────────┤ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ MCP │ │ Agent │ │ Model │ │ Skill │ │ │ │ 网关 │ │ 管理 │ │ 代理 │ │ 管理 │ │ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │ │ │ │ │ │ │ ┌────┴────────────┴────────────┴────────────┴────┐ │ │ │ 统一调度层 (SPI Plugin Registry) │ │ │ └────┬────────────┬────────────┬────────────┬────┘ │ │ │ │ │ │ │ │ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ │ │ │ REST │ │ RPC │ │ SOAP │ │ SOCKET │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ │ ┌───────┴───────┐ │ │ │ OpenAPI │ │ │ └───────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ### 核心模块说明 | 模块 | 状态 | 说明 | |------|------|------| | **MCP 网关** | ✅ 已实现 | MCP Server/Tool 的完整生命周期管理 | | **Agent 管理** | ✅ 已实现 | A2A 协议支持，Agent 注册与任务分发 | | **模型代理** | ✅ 已实现 | 统一的大模型调用接口，支持多厂商 | | **技能管理** | 🚧 规划中 | AI 技能的定义、组合与执行 | | **接口层** | ✅ 已实现 | REST/RPC/SOAP/Socket/OpenAPI 五种协议 | ### 技术栈 | 类别 | 技术 | |------|------| | 框架 | Spring Boot 3.4 | | 数据访问 | MyBatis-Plus | | 数据库 | PostgreSQL / MySQL | | JSON | Jackson | | 构建工具 | Maven | --- ## 📖 API 文档 ### MCP Server 接口 | 方法 | 端点 | 说明 | |------|------|------| | GET | `/mcpServer` | 获取所有 MCP 服务器 | | GET | `/mcpServer/{id}` | 获取指定服务器详情 | | POST | `/mcpServer` | 创建 MCP 服务器 | | DELETE | `/mcpServer/{id}` | 删除 MCP 服务器 | ### MCP Tool 接口 | 方法 | 端点 | 说明 | |------|------|------| | GET | `/mcpTool` | 获取所有 MCP 工具 | | GET | `/mcpTool/{id}` | 获取指定工具详情 | | GET | `/mcpTool/mcpServer/{mcpServerId}` | 获取服务器的工具列表 | | POST | `/mcpTool` | 创建 MCP 工具 | | PUT | `/mcpTool/{id}` | 更新 MCP 工具 | | DELETE | `/mcpTool/{id}` | 删除 MCP 工具 | ### REST Client 接口 | 方法 | 端点 | 说明 | |------|------|------| | GET | `/httpClient` | 获取所有 HTTP 客户端 | | GET | `/httpClient/{id}` | 获取指定客户端详情 | | POST | `/httpClient` | 创建 HTTP 客户端 | | PUT | `/httpClient/{id}` | 更新 HTTP 客户端 | | DELETE | `/httpClient/{id}` | 删除 HTTP 客户端 | ### RPC Client 接口 | 方法 | 端点 | 说明 | |------|------|------| | GET | `/rpcClient` | 获取所有 RPC 客户端 | | GET | `/rpcClient/{id}` | 获取指定客户端详情 | | POST | `/rpcClient` | 创建 RPC 客户端 | | PUT | `/rpcClient/{id}` | 更新 RPC 客户端 | | DELETE | `/rpcClient/{id}` | 删除 RPC 客户端 | | GET | `/rpcClient/{id}/methods` | 获取 RPC 方法列表 | ### SOAP Client 接口 | 方法 | 端点 | 说明 | |------|------|------| | GET | `/soapClient` | 获取所有 SOAP 客户端 | | GET | `/soapClient/{id}` | 获取指定客户端详情 | | POST | `/soapClient` | 创建 SOAP 客户端 | | PUT | `/soapClient/{id}` | 更新 SOAP 客户端 | | DELETE | `/soapClient/{id}` | 删除 SOAP 客户端 | | GET | `/soapClient/{id}/operations` | 获取 SOAP 操作列表 | ### Socket Client 接口 | 方法 | 端点 | 说明 | |------|------|------| | GET | `/socketClient` | 获取所有 Socket 客户端 | | GET | `/socketClient/{id}` | 获取指定客户端详情 | | POST | `/socketClient` | 创建 Socket 客户端 | | PUT | `/socketClient/{id}` | 更新 Socket 客户端 | | DELETE | `/socketClient/{id}` | 删除 Socket 客户端 | | GET | `/socketClient/{id}/commands` | 获取 Socket 命令列表 | > 📘 完整 API 文档请参阅 [API.md](./docs/API.md) --- ## ❓ 常见问题 ### Q1: 如何选择数据库？PostgreSQL 还是 MySQL？ **推荐 PostgreSQL**： - 更好的 JSON 支持（JSONB 类型） - 更完善的事务隔离 - 更优秀的并发性能 MySQL 适用于： - 已有 MySQL 基础设施 - 团队更熟悉 MySQL - 需要与现有 MySQL 系统集成 ### Q2: 如何添加新的大模型提供商？ 1. 在 `ModelConstant.java` 中添加提供商常量 2. 在 `ModelProxyServiceImpl.java` 中实现连接逻辑 3. 配置 API Key 和代理地址 ```java // ModelConstant.java public static final String NEW_MODEL = "new-model"; // ModelProxyServiceImpl.java case NEW_MODEL: // 实现新模型的连接逻辑 break; ``` ### Q3: MCP Server 连接失败怎么办？ 检查以下项目： 1. **网络连通性**：确认 MCP Server 地址可达 2. **端口开放**：确认防火墙已开放相应端口 3. **配置正确**：检查 SSE/HTTP 配置参数 4. **日志排查**：查看 `logs/ai-gateway.log` 错误信息 ### Q4: 如何配置 Dubbo RPC？ ```yaml # application.yml dubbo: registry: address: zookeeper://localhost:2181 protocol: name: dubbo port: 20880 ``` ### Q5: 支持哪些 RPC 协议？ | 协议 | 特点 | 适用场景 | |------|------|---------| | Dubbo | Java 原生，高性能 | Java 微服务 | | gRPC | 跨语言，HTTP/2 | 多语言微服务 | | Thrift | 跨语言，多协议 | 大数据、跨语言交互 | ### Q6: 如何实现 SOAP 安全认证？ 支持以下认证方式： - HTTP Basic / Digest 认证 - 客户端证书认证 - 自定义 SOAP Header ```java SoapClient client = new SoapClient(); client.setAuthType("BASIC"); client.setUsername("user"); client.setPassword("pass"); ``` ### Q7: 如何监控服务状态？ 1. **健康检查**：访问 `/actuator/health` 2. **指标监控**：访问 `/actuator/metrics` 3. **日志分析**：查看应用日志 ### Q8: 项目如何打包部署？ ```bash # 打包 mvn clean package -DskipTests # 运行 java -jar target/ai-gateway-2.0.0.jar # Docker 部署 docker build -t ai-gateway:latest . docker run -p 8080:8080 ai-gateway:latest ``` ### Q9: 如何扩展新的接口协议？ 1. 创建新的客户端实体类 2. 实现对应的 Mapper 和 Service 3. 创建 Controller 暴露 API 4. 添加对应的数据库表 ### Q10: 性能优化建议？ 1. **启用连接池**：配置 HikariCP 连接池 2. **开启缓存**：使用 Redis 缓存热点数据 3. **异步处理**：对耗时操作使用 @Async 4. **批量操作**：减少数据库交互次数 --- ## 📝 更新日志 ### [2.0.0-alpha] - 2026-03-17 **新增** - ✨ MCP 网关完整实现 - ✨ A2A Agent 协议支持 - ✨ 大模型统一代理（OpenAI/Qwen/DeepSeek 等） - ✨ 五种接口协议支持（REST/RPC/SOAP/Socket/OpenAPI） **优化** - ⚡ 重构 SPI 插件注册中心 - ⚡ 优化数据库表结构 ### [1.0.0] - 2025-01-15 **新增** - 🎉 项目初始版本 - ✨ MCP Server/Tool 基础功能 > 完整更新日志请参阅 [CHANGELOG.md](./CHANGELOG.md) --- ## 🤝 贡献指南 我们欢迎所有形式的贡献！ ### 如何贡献 1. **Fork 项目**：点击右上角 Fork 按钮 2. **创建分支**：`git checkout -b feature/your-feature` 3. **提交代码**：`git commit -m 'Add some feature'` 4. **推送分支**：`git push origin feature/your-feature` 5. **提交 PR**：创建 Pull Request ### 代码规范 - 遵循阿里巴巴 Java 开发手册 - 使用 4 空格缩进 - 类和方法必须有 Javadoc 注释 - 单元测试覆盖率 > 60% ### 提交规范 使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范： ``` feat: 新功能 fix: 修复 bug docs: 文档更新 style: 代码格式调整 refactor: 代码重构 test: 测试相关 chore: 构建/工具变更 ``` --- ## 📄 许可证 本项目采用 [MIT License](./LICENSE) 开源协议。 ``` MIT License Copyright (c) 2026 chenmin Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` --- ## 📞 联系方式 - **项目地址**：https://gitee.com/ai-sample/ai-gateway - **问题反馈**：提交 [Issue](https://gitee.com/ai-sample/ai-gateway/issues) - **作者**：chenmin ---如果这个项目对你有帮助，请给一个 ⭐ Star 支持一下！