一个统一的 AI 服务集成与治理平台
快速开始 • 系统架构 • 核心功能 • 开发指南 • API 文档
--- ## 项目简介 AI Gateway 是一个基于 Spring Boot 构建的统一 AI 服务集成与治理平台，采用**单体架构 + 多租户复合架构**设计，提供统一的 AI 服务集成、治理与技能市场能力。 **架构特点**： - **单体架构**：单一可部署应用，遵循 Controller → Service → Mapper 标准分层，模块边界清晰，启动即用、易于维护与扩展。 - **多租户复合架构**：支持**单租户 / 多租户双模式**运行，基于动态数据源实现租户数据源自动路由，租户间数据隔离（独立库），并具备租户能力订阅与数据归属管控——兼顾本地开发的轻量便捷与生产环境的多租户 SaaS 隔离。 ### 技术栈 | 类别 | 技术 | 版本 | |------|------|------| | 框架 | Spring Boot | 3.5.13 | | 数据访问 | MyBatis-Plus | 3.5.15 | | 认证 | Sa-Token | 1.45.0 | | AI | Spring AI | 1.1.4 | | MCP SDK | io.modelcontextprotocol.sdk | 1.1.2 | | 数据库 | PostgreSQL / MySQL / H2 | 14+ / 8.0+ | | 对象存储 | MinIO | 8.3.5 | | 工具库 | Hutool | 5.8.41 | | API 文档 | Knife4j (SpringDoc) | 4.5.0 | | Java | JDK | 17+ | | 构建工具 | Maven | 3.6+ | | 管理前端 | Vue 2 + Element UI | 2.x | | Hub 前端 | Next.js 14 + React 18 + Tailwind CSS | 14.x | | CLI 工具 | Node.js | 18+ | ### 核心特性 - **多租户架构** — 单租户 / 多租户双模式，动态数据源路由，租户级数据隔离与能力订阅 - **MCP 网关** — 完整的 MCP Server/Tool 生命周期管理，支持 SSE/Stateless/Streamable HTTP 三种传输 - **Agent 管理** — A2A / ACP 协议支持，Agent 注册、任务分发、交互（收藏/点赞/评价/举报） - **AgentSpec** — DSL 规则引擎，Agent 行为安全执行 - **多模型代理** — 适配器模式对接 OpenAI、Qwen、DeepSeek、Claude 等多厂商 LLM - **多协议接口** — REST / RPC(Dubbo/gRPC/Thrift) / SOAP / Socket / OpenAPI 五种协议 - **技能管理** — 技能注册、包上传/下载、安全扫描、运行时执行 - **技能市场** — 多平台技能浏览与导入（ClawHub、SkillHub.cn、NPM、GitHub 等） - **提示词管理** — 模板化提示词与变量渲染 - **聊天会话** — 多轮对话会话管理 --- ## 快速开始 ### 环境要求 | 依赖 | 版本要求 | 说明 | |------|---------|------| | JDK | 17+ | Java 运行环境 | | Maven | 3.6+ | 项目构建工具 | | PostgreSQL | 14+ | 推荐数据库 | | MySQL | 8.0+ | 可选数据库 | | Node.js | 18+ | 前端开发（可选） | ### 5 分钟启动 #### 1. 克隆项目 ```bash git clone https://gitee.com/artislong/ai-gateway.git cd ai-gateway ``` #### 2. 创建数据库 **PostgreSQL:** ```bash psql -U postgres -c "CREATE DATABASE ai_gateway;" ``` **MySQL:** ```bash mysql -u root -p -e "CREATE DATABASE ai_gateway CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;" ``` #### 3. 导入表结构 ```bash # PostgreSQL psql -U postgres -d ai_gateway -f docs/sql/all_in_one.sql # MySQL mysql -u root -p ai_gateway < docs/sql/all_in_one.sql ``` #### 4. 修改配置文件 编辑 `src/main/resources/application.yml`: ```yaml spring: datasource: url: jdbc:postgresql://localhost:5432/ai_gateway username: your_username password: your_password ``` #### 5. 启动后端 ```bash mvn spring-boot:run ``` #### 6. 启动前端 ```bash # 管理端界面（Vue 2，端口 :8081） cd frontend && npm install && npm run serve # Skill Hub 用户界面（Next.js，端口 :3000） cd frontend-hub && npm install && npm run dev ``` #### 7. 访问应用 | 服务 | 地址 | |------|------| | 后端 API | http://localhost:8080/ai-gateway | | 管理后台 | http://localhost:8081 | | Skill Hub | http://localhost:3000 | | Swagger UI | http://localhost:8080/ai-gateway/swagger-ui.html | | 健康检查 | http://localhost:8080/ai-gateway/actuator/health | | Prometheus | http://localhost:8080/ai-gateway/actuator/prometheus | #### 8. 前端界面预览 ##### Dashboard 首页  ##### MCP 管理界面  ##### 接口管理界面  ##### Agent 管理界面  ##### 模型代理界面  ##### 技能管理界面  ##### 提示词管理界面  ##### 聊天对话界面  ### 验证安装 ```bash curl http://localhost:8080/ai-gateway/actuator/health # 预期返回 {"status":"UP"} ``` --- ## 系统架构 ### 整体架构图 ``` ┌──────────────────────────────────────────────────────────────┐ │ AI Gateway │ ├──────────────────────────────────────────────────────────────┤ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ MCP │ │ Agent │ │ Model │ │ Skill │ │ │ │ 网关 │ │ 管理 │ │ 代理 │ │ 管理 │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ │ ┌────┴─────────────┴─────────────┴─────────────┴────┐ │ │ │ Controller 层 │ │ │ └────┬─────────────┬─────────────┬─────────────┬────┘ │ │ │ │ │ │ │ │ ┌────┴─────┐ ┌─────┴────┐ ┌─────┴────┐ ┌──────┴──────┐ │ │ │ REST │ │ RPC │ │ SOAP │ │ Socket │ │ │ └──────────┘ │Dubbo/gRPC│ └──────────┘ └─────────────┘ │ │ │ /Thrift │ │ │ │ └──────────┘ ┌─────────┴─────────┐ │ │ │ OpenAPI │ │ │ └───────────────────┘ │ │ ┌──────────────────────────────────────────────────────────┐│ │ │ 技能市场（多平台适配） ││ │ │ ClawHub │ SkillHub.cn │ NPM │ GitHub │ Generic ││ │ └──────────────────────────────────────────────────────────┘│ └──────────────────────────────────────────────────────────────┘ ``` ### 后端模块划分（`src/main/java/com/artislong/`） | 包名 | 用途 | |---------|---------| | `mcp/` | MCP 网关 — 服务端/工具生命周期管理，协议适配器，客户端代理 | | `agent/` | A2A 与 ACP 代理注册、任务提交、交互（点赞/收藏/评价/举报） | | `agentspec/` | AgentSpec DSL — 规则定义、执行日志、LLM 代理安全执行 | | `model/` | 多供应商 LLM 代理 — 适配器模式对接 OpenAI、Qwen、DeepSeek、Claude | | `skills/` | Skill Hub — 技能增删改查、包上传/下载、运行时执行、安全扫描、市场平台 | | `prompt/` | 提示词模板及变量渲染 | | `chat/` | 聊天会话处理 | | `oauth/` | 认证 — Sa-Token 双用户体系，登录/注册，安全配置 | | `dashboard/` | 首页统计 | | `monitoring/` | Prometheus 指标配置 | | `rule/` | 规则引擎 | | `config/` | MyBatis-Plus 配置，OpenAPI (SpringDoc) 配置 | | `common/` | 共享服务 | | `exception/` | 异常处理器 | | `utils/` | 工具类 | ### 项目结构 ``` ai-gateway/ ├── src/ │ ├── main/ │ │ ├── java/com/artislong/ │ │ │ ├── mcp/ # MCP 网关 │ │ │ │ ├── core/ # server/client/tool/call 核心抽象 │ │ │ │ ├── entity/ │ │ │ │ ├── controller/ │ │ │ │ └── service/ │ │ │ ├── agent/ # Agent 系统 (A2A/ACP) │ │ │ ├── agentspec/ # AgentSpec DSL 规则引擎 │ │ │ ├── model/ # Model 代理系统 │ │ │ ├── skills/ # 技能管理与市场平台 │ │ │ │ ├── market/ # 多平台适配器 │ │ │ │ ├── runtime/ # 技能运行时执行器 │ │ │ │ └── controller/ │ │ │ ├── prompt/ # 提示词管理 │ │ │ ├── chat/ # 聊天会话 │ │ │ ├── oauth/ # 认证授权 │ │ │ ├── dashboard/ # 首页统计 │ │ │ ├── monitoring/ # Prometheus 监控 │ │ │ ├── config/ # 配置类 │ │ │ ├── common/ # 共享服务 │ │ │ └── utils/ # 工具类 │ │ └── resources/ │ │ ├── application.yml │ │ ├── application-test.yml │ │ ├── application-local.yml │ │ └── schema.sql │ └── test/ ├── frontend/ # 管理后台 (Vue 2 + Element UI) ├── frontend-hub/ # Skill Hub (Next.js 14 + React 18) ├── skill-cli/ # CLI 工具 (Node.js) ├── docs/ │ ├── sql/ # 数据库脚本 │ ├── api/ # API 文档与测试 │ ├── images/ # 界面截图 │ ├── deploy/ # 部署配置 │ ├── DEVELOPMENT.md # 开发手册 │ └── SKILL_SPEC.md # 技能规范 ├── infra/ # 基础设施配置 ├── pom.xml └── README.md ``` --- ## 核心功能 ### 1. MCP 网关 **支持的传输方式:** - SSE — Server-Sent Events - Stateless HTTP — 无状态 HTTP - Streamable HTTP — 流式 HTTP **核心功能:** - MCP Server 注册、启停与管理 - MCP Client 连接管理（SSE/Stdio/Streamable HTTP） - MCP Tool 发现与执行（5 种协议适配） - 工具注册与参数校验 ### 2. Agent 管理 (A2A / ACP 协议) **协议支持:** - A2A — Agent-to-Agent 协议 - ACP — Agent Communication Protocol **交互功能:** - 收藏 / 点赞 / 评价 / 举报 - 任务提交与状态查询 - Hub 页面浏览（匿名可访问） ### 3. AgentSpec DSL - 规则定义（Guardrail / Enforcement / Monitoring） - 触发事件匹配（on_message / on_action / on_tool_call / on_response） - 谓词条件与执行动作 - LLM Agent 安全执行 ### 4. 模型代理 **支持的 LLM 厂商:** - OpenAI (GPT-4, GPT-3.5) - Anthropic (Claude 3 系列) - 阿里通义 (Qwen 系列) - DeepSeek (DeepSeek-V2/V3) - 智谱 (GLM 系列) - 本地模型 (Ollama) **适配器模式:** - 统一 `ModelAdapter` 接口 - 易于扩展新厂商 - 支持多模型并行 ### 5. 技能管理与市场 **技能类型:** - TOOL — 工具型技能 - PROMPT — 提示词型技能 - WORKFLOW — 工作流型技能 - KNOWLEDGE — 知识型技能 **运行时执行器:** - PromptExecutor — 提示词执行 - SkillToolExecutor — 工具执行 - WorkflowExecutor — 工作流执行 - KnowledgeExecutor — 知识执行 **安全扫描:** - 敏感词检测 - 文件扩展名黑名单 - 文件大小上限 **技能市场平台:** | 平台 | 编码 | 说明 | |------|------|------| | ClawHub | `clawhub` | 官方 Clawd 技能市场 | | SkillHub.cn | `skillhub` | 国内技能市场（无需魔法） | | NPM Registry | `npm` | NPM 包搜索 | | GitHub | `github` | GitHub Topics 搜索 | | OpenClaw | `openclaw` | OpenClaw 社区仓库 | 支持的功能：浏览技能、查看详情、版本管理、文件预览、一键导入、批量导出（Excel/ZIP）。 ### 6. 接口协议 | 协议 | 实现 | |------|------| | REST | HTTP RESTful API 客户端 | | RPC | Dubbo / gRPC / Thrift | | SOAP | SOAP 1.1 / 1.2 | | Socket | TCP / UDP / WebSocket | | OpenAPI | OpenAPI 3.0 / Swagger 2.0 | --- ## 开发指南 ### 构建与运行 ```bash # 启动后端（本地开发使用 H2 内存数据库） mvn spring-boot:run # 使用指定 profile mvn spring-boot:run -Dspring-boot.run.profiles=dev # 运行全部测试 mvn test # 运行指定测试 mvn test -Dtest=AiGatewayIntegrationTest # 打包 mvn clean package -DskipTests # Docker docker build -t ai-gateway:latest . docker run -p 8080:8080 ai-gateway:latest ``` ### 接口测试 ```bash # 无需认证的接口 curl -X POST http://localhost:8080/ai-gateway/api/public/endpoint \ -H "Content-Type: application/json" -d '{}' # 需要认证的接口 TOKEN=$(curl -s -X POST http://localhost:8080/ai-gateway/api/oauth/login \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":"admin123"}' | jq -r '.data.token') curl -X GET http://localhost:8080/ai-gateway/api/skills/list \ -H "Authorization: Bearer $TOKEN" ``` ### 添加新的技能市场平台 1. 实现 `PlatformAdapter` 接口 2. 在 `MarketPlatformInitializer` 注册预设平台 3. 前后端自动适配 ### 代码规范 - 遵循阿里巴巴 Java 开发手册 - 使用 Tab 缩进 - 提交遵循 Conventional Commits: `feat:` / `fix:` / `docs:` / `style:` / `refactor:` / `test:` / `chore:` --- ## API 文档 完整 API 文档请参考 Swagger UI: `http://localhost:8080/ai-gateway/swagger-ui.html` ### 技能市场 API | 方法 | 端点 | 说明 | |------|------|------| | GET | `/api/skill-hub/market/platforms` | 获取平台列表 | | POST | `/api/skill-hub/market/platforms` | 添加自定义平台 | | PUT | `/api/skill-hub/market/platforms/{code}` | 更新平台配置 | | DELETE | `/api/skill-hub/market/platforms/{code}` | 删除平台 | | GET | `/api/skill-hub/market/platforms/{code}/skills` | 搜索平台技能 | | GET | `/api/skill-hub/market/platforms/{code}/skills/{slug}` | 获取技能详情 | | GET | `/api/skill-hub/market/platforms/{code}/skills/{slug}/versions` | 获取版本列表 | | GET | `/api/skill-hub/market/platforms/{code}/skills/{slug}/versions/{version}` | 获取版本详情 | | GET | `/api/skill-hub/market/platforms/{code}/skills/{slug}/file` | 获取文件内容 | | GET | `/api/skill-hub/market/platforms/{code}/skills/{slug}/download` | 下载技能包 | | POST | `/api/skill-hub/market/import` | 批量导入技能 | | POST | `/api/skill-hub/market/export/excel` | 导出 Excel | | POST | `/api/skill-hub/market/export/zip` | 导出 ZIP | ### 技能 Hub API | 方法 | 端点 | 说明 | |------|------|------| | GET | `/api/skill-hub/skills` | 获取技能列表 | | POST | `/api/skill-hub/skills/upload` | 上传技能包 | | GET | `/api/skill-hub/skills/name/{name}` | 按名称获取技能 | | GET | `/api/skill-hub/skills/{name}/versions` | 获取技能版本 | | GET | `/api/skill-hub/skills/{name}/files` | 获取文件树 | | GET | `/api/skill-hub/skills/{name}/files/content` | 获取文件内容 | | GET | `/api/skill-hub/skills/search` | 搜索技能 | | GET | `/api/skill-hub/categories` | 获取分类列表 | | GET | `/api/skill-hub/whoami` | 获取当前用户 | ### 用户认证 API | 方法 | 端点 | 说明 | |------|------|------| | POST | `/api/oauth/login` | 登录 | | POST | `/api/oauth/register` | 注册 | | POST | `/api/oauth/logout` | 登出 | | GET | `/api/oauth/current` | 获取当前用户 | | POST | `/api/oauth/send-code` | 发送验证码 | --- ## 常见问题 ### Q1: 如何选择数据库？ **推荐 PostgreSQL:** - 更好的 JSON 支持（JSONB 类型） - 更完善的事务隔离 - 更优秀的并发性能 **开发环境:** 可使用 H2 内存数据库（配置 `application-local.yml`）。 ### Q2: 如何添加新的大模型提供商？ 1. 在 `model/adapter/` 包下创建新的适配器 2. 实现模型调用接口 3. 在配置文件中添加 API Key ### Q3: MCP Server 连接失败怎么办？ 1. 检查网络连通性 2. 确认端口开放 3. 检查配置参数 4. 查看应用日志 ### Q4: 如何打包部署？ ```bash # 打包 mvn clean package -DskipTests # 运行 java -jar target/ai-gateway-1.0.jar # Docker 部署 docker build -t ai-gateway:latest . docker run -p 8080:8080 ai-gateway:latest ``` ### Q5: 如何配置环境变量？ 关键环境变量： - `env.ip` — 数据库/Redis 服务器 IP - `SKILL_RUNTIME_PATH` — 技能包解压目录 - `MINIO_*` — MinIO 对象存储配置 --- ## 许可证 本项目采用 [MIT License](./LICENSE) 开源协议。 --- ## 联系方式 - **作者**: artislong - **项目地址**: https://gitee.com/artislong/ai-gateway ---如果这个项目对你有帮助，请给一个 ⭐ Star 支持一下！