qyyfw/ai-paas-comparison
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 补全基础设施文档 (DB设计/API规范/MiMoCode配置)

Browse Source 
- 03-数据库设计.md: ER图 + 12张表定义 + Redis数据结构 + Migration策略
- 04-API接口规范.md: OpenAPI 3.0 约定 + 全部接口定义 (Auth/APIKey/LLM/Billing/Registry/Skills/IM/Admin)
- 05-AGENTS-MiMoCode配置.md: MiMo Code 核心配置文件，包含项目结构/技术栈/开发规范/模块说明

至此 docs/ 目录包含完整的6份基础设计文档，可作为 MiMo Code 的上下文输入
This commit is contained in:
qyyfw committed 2026-06-27 10:51:13 +00:00
1 parent 67c3270aad
commit d9a8a0e93c
5 files changed
+2099
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/02-系统架构设计.md
+453
View File
@@ -0,0 +1,453 @@
# AI PaaS 商业平台 — 系统架构设计
> 版本: 1.0 | 日期: 2026-06-27
> 基于: 5 平台交叉验证共识 + 方案二（稳扎稳打）
---
## 1. 架构总览
### 1.1 分层架构图
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 用户入口层 (Access) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐│
│ │ Web UI │ │ REST API │ │ WebSocket│ │ CLI │ │ IM Bot ││
│ │ (React) │ │ │ │ (SSE) │ │ (Phase5) │ │ (Phase4) ││
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘│
└───────┼──────────────┼──────────────┼──────────────┼──────────────┼──────┘
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ API Gateway (Apache APISIX 3.15+) │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐ │
│ │jwt-auth │ │key-auth │ │limit- │ │api- │ │ proxy-rewrite │ │
│ │JWT验证 │ │Key验证 │ │count │ │breaker │ │ + CORS │ │
│ │ │ │ │ │限流 │ │熔断 │ │ │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────────────┘ │
│ │
│ 路由表: │
│ /api/v1/auth/* → auth-service:8081 │
│ /api/v1/capabilities/* → registry-service:8082 │
│ /v1/chat/completions → openapi-gateway:8083 │
│ /api/v1/billing/* → billing-service:8084 │
│ /api/v1/skills/* → skills-service:8085 │
│ /api/v1/admin/* → admin-service:8086 │
│ /api/v1/im/* → im-gateway:8087 │
│ /api/v1/mcp/* → mcp-proxy:8088 │
│ /api/v1/agent/* → agent-proxy:8089 │
└─────────────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 核心业务层 (Core Services) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────────┐ │
│ │ auth-service │ │ billing-svc │ │ registry-service │ │
│ │ Go :8081 │ │ Go :8084 │ │ Go :8082 │ │
│ │ │ │ │ │ │ │
│ │ • JWT 验证 │ │ • Credit 扣费│ │ • 能力注册/注销 │ │
│ │ • API Key │ │ • 余额查询 │ │ • 版本管理 │ │
│ │ • RBAC 角色 │ │ • 流水记录 │ │ • 服务发现 │ │
│ │ • 租户上下文 │ │ • 订阅管理 │ │ • 状态管理 │ │
│ │ • 注册/登录 │ │ • 充值 │ │ • gRPC + REST │ │
│ └──────┬───────┘ └──────┬───────┘ └──────────────┬───────────────┘ │
│ │ │ │ │
│ ┌──────┴───────┐ ┌──────┴───────┐ ┌─────────────┴───────────────┐ │
│ │openapi-gw │ │ metering-svc │ │ skills-service │ │
│ │Go :8083 │ │ Go :8090 │ │ Go :8085 │ │
│ │ │ │ │ │ │ │
│ │• OpenAI API │ │• Kafka消费 │ │• 技能发布/审核 │ │
│ │• 请求拦截链 │ │• PG持久化 │ │• 市场浏览/搜索 │ │
│ │• 流式 SSE │ │• 预聚合 │ │• 购买/分成 │ │
│ │• 用量上报 │ │• 用量查询 │ │• 全文搜索 │ │
│ └──────┬───────┘ └──────────────┘ └─────────────────────────────┘ │
│ │ │
│ ┌──────┴───────┐ ┌──────────────┐ ┌─────────────────────────────┐ │
│ │llm-router │ │im-gateway │ │ admin-service │ │
│ │Go :8091 │ │ Go :8087 │ │ Go :8086 │ │
│ │ │ │ │ │ │ │
│ │• 多平台适配 │ │• 微信/QQ/钉钉│ │• 用户管理 │ │
│ │• 智能路由 │ │• 会话管理 │ │• 租户管理 │ │
│ │• 故障转移 │ │• 消息收发 │ │• 能力审核 │ │
│ │• 连接池 │ │• 上下文注入 │ │• 系统配置 │ │
│ └──────────────┘ └──────────────┘ └─────────────────────────────┘ │
└─────────────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ AI 能力层 (AI Capabilities) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐│
│ │ LangFlow │ │ mcp-hub │ │ Milvus │ │ vLLM ││
│ │ [开源] │ │ [开源] │ │ [开源] │ │ [开源] ││
│ │ Agent 编排 │ │ MCP 服务管理 │ │ 向量数据库 │ │ 模型推理 ││
│ │ :7860 │ │ :3001 │ │ :19530 │ │ :8000 ││
│ └──────────────┘ └──────────────┘ └──────────────┘ └────────────┘│
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 外部 LLM 平台 (External LLM) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐│
│ │ DeepSeek │ │ 千问 │ │ 豆包 │ │ 智谱 │ │ 百度/元宝 ││
│ │ API │ │ API │ │ API │ │ API │ │ API ││
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────────┘│
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 基础设施层 (Infrastructure) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐│
│ │PostgreSQL│ │ Redis 7 │ │ Kafka │ │ Keycloak │ │ Prometheus ││
│ │ 16 │ │ │ │ 3.x │ │ 25+ │ │ + Grafana ││
│ │ 主数据库 │ │ 缓存+Lua │ │ 事件总线 │ │ 认证 │ │ 监控 ││
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────────┘│
└─────────────────────────────────────────────────────────────────────────┘
```
---
## 2. 核心数据流
### 2.1 LLM 调用 + 计费完整流程
```
用户代码 APISIX openapi-gw billing-svc
│ │ │ │
│ POST /v1/chat/completions │ │ │
│ Authorization: Bearer xxx │ │ │
├──────────────────────────→│ │ │
│ │ jwt-auth 验证 │ │
│ │ 提取 tenant_id │ │
│ │ 注入 X-Tenant-Id │ │
│ ├───────────────────→│ │
│ │ │ │
│ │ │ 1. API Key 验证 │
│ │ │ (→ auth-svc) │
│ │ │ │
│ │ │ 2. 余额检查 │
│ │ │ GET /balance │
│ │ ├───────────────────→│
│ │ │ balance: 12580 │
│ │ │←───────────────────│
│ │ │ │
│ │ │ 3. 路由到 LLM │
│ │ │ Router │
│ │ │ │
│ │ │ llm-router │
│ │ │ ├─选择 DeepSeek │
│ │ │ ├─调用 API │
│ │ │ └─返回 + usage │
│ │ │ │
│ │ │ 4. 计费扣减 │
│ │ │ POST /meter │
│ │ │ {tokens: 1280} │
│ │ ├───────────────────→│
│ │ │ Redis Lua 扣费 │
│ │ │ balance: 12580 │
│ │ │ → 11300 │
│ │ │←───────────────────│
│ │ │ │
│ │ │ 5. 异步上报用量 │
│ │ │ → Kafka │
│ │ │ │
│ {choices: [...], │ │ │
│ usage: { │ │ │
│ prompt_tokens: 800, │ │ │
│ completion_tokens: 480│ │ │
│ }} │ │ │
│←──────────────────────────│←───────────────────│ │
│ │ │ │
```
### 2.2 流式 SSE 响应流程
```
用户浏览器 APISIX openapi-gw llm-router
│ │ │ │
│ POST /v1/chat/completions │ │ │
│ stream: true │ │ │
├──────────────────────────→│───────────────────→│───────────────────→│
│ │ │ │
│ │ │ HTTP 200 │
│ │ │ Content-Type: │
│ │ │ text/event-stream │
│←──────────────────────────│←───────────────────│←───────────────────│
│ │ │ │
│ data: {"choices":[{ │ │ │
│ "delta":{"content":"你"}}│ │ │
│←──────────────────────────│←───────────────────│←───────────────────│
│ │ │ │
│ data: {"choices":[{ │ │ │
│ "delta":{"content":"好"}}│ │ │
│←──────────────────────────│←───────────────────│←───────────────────│
│ │ │ │
│ data: [DONE] │ │ │
│←──────────────────────────│←───────────────────│←───────────────────│
│ │ │ │
│ │ │ 4. 计费扣减 │
│ │ │ 5. 上报用量 │
```
---
## 3. 服务间通信
### 3.1 同步调用（HTTP/gRPC）
| 调用方 | 被调用方 | 协议 | 说明 |
|--------|---------|------|------|
| APISIX | 所有后端服务 | HTTP | 路由转发 |
| openapi-gw | auth-service | HTTP | JWT 验证 |
| openapi-gw | billing-svc | HTTP | 余额检查+扣费 |
| openapi-gw | llm-router | HTTP | LLM 调用 |
| openapi-gw | registry-service | gRPC | 能力查询（内部） |
| skills-service | billing-svc | HTTP | 购买扣费 |
| im-gateway | llm-router | HTTP | LLM 调用 |
| registry-service | mcp-hub | HTTP | MCP 同步 |
| registry-service | langflow | HTTP | Agent 同步 |
### 3.2 异步通信（Kafka）
| 生产者 | Topic | 消费者 | 说明 |
|--------|-------|--------|------|
| openapi-gw | usage.events | metering-svc | LLM 用量上报 |
| billing-svc | billing.events | metering-svc | 计费事件 |
| registry-svc | capability.events | mcp-hub, langflow | 能力变更通知 |
### 3.3 缓存策略（Redis）
| Key 模式 | 类型 | TTL | 说明 |
|----------|------|-----|------|
| auth:session:{token} | Hash | 24h | 用户会话 |
| auth:apikey:{key_hash} | Hash | 1h | API Key 缓存 |
| billing:balance:{tenant_id} | String | - | Credit 余额（毫 Credit） |
| billing:idempotency:{tenant_id}:{key} | Hash | 24h | 幂等键 |
| billing:daily:{tenant_id}:{YYYY-MM-DD} | Hash | 7d | 每日统计 |
| billing:subscription:{tenant_id} | Hash | - | 订阅信息 |
| ratelimit:{tenant_id}:{window} | String | 60s | 限流计数 |
| im:session:{platform}:{user_id} | Hash | 24h | IM 会话上下文 |
---
## 4. 数据库架构
### 4.1 PostgreSQL Schema 概览
```
┌─────────────────────────────────────────────────────────┐
│ PostgreSQL 16 │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────────┐ │
│ │ tenants │ │ users │ │ capabilities │ │
│ │ (租户) │←─│ (用户) │ │ (能力) │ │
│ └──────┬──────┘ └─────────────┘ └───────┬────────┘ │
│ │ │ │
│ ┌──────┴──────┐ ┌─────────────┐ ┌───────┴────────┐ │
│ │ subscriptions│ │ api_keys │ │ cap_versions │ │
│ │ (订阅) │ │ (API密钥) │ │ (能力版本) │ │
│ └─────────────┘ └─────────────┘ └────────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────────┐ │
│ │credit_trans │ │ token_usage │ │ skills │ │
│ │(Credit流水) │ │ (Token用量) │ │ (技能) │ │
│ │ 不可变 │ │ 按月分区 │ │ │ │
│ └─────────────┘ └─────────────┘ └───────┬────────┘ │
│ │ │
│ ┌─────────────┐ ┌─────────────┐ ┌───────┴────────┐ │
│ │skill_purchases│ │ im_sessions │ │ im_messages │ │
│ │(技能购买) │ │ (IM会话) │ │ (IM消息) │ │
│ └─────────────┘ └─────────────┘ └────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ All tables have RLS policies based on tenant_id │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
### 4.2 RLS 策略
```sql
-- 所有表启用 RLS
ALTER TABLE tenants ENABLE ROW LEVEL SECURITY;
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
ALTER TABLE capabilities ENABLE ROW LEVEL SECURITY;
-- ... 所有表
-- 通用策略: 基于 tenant_id 隔离
CREATE POLICY tenant_isolation ON capabilities
USING (tenant_id = current_setting('app.tenant_id')::uuid);
-- 管理员可以看所有数据
CREATE POLICY admin_full_access ON capabilities
USING (current_setting('app.user_role') = 'admin');
```
---
## 5. 安全架构
### 5.1 认证流程
```
┌──────────────┐
│ Keycloak │
│ (认证中心) │
└──────┬───────┘
│
┌────────────────┼────────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ 用户登录 │ │ API Key │ │ 服务间 │
│ JWT 签发 │ │ Hash验证 │ │ Client │
│ │ │ │ │ Credentials│
└──────────┘ └──────────┘ └──────────┘
JWT Payload:
{
"sub": "user-uuid",
"tenant_id": "tenant-uuid",
"role": "developer",
"exp": 1719552000,
"iat": 1719548400
}
```
### 5.2 API Key 安全
```
用户创建 Key:
明文 Key: aip_xxxxxxxxxxxxxxxxxxxxxxxx (仅展示一次)
存储: SHA-256(aip_xxx) → db
用户调用:
Header: Authorization: Bearer aip_xxxxxxxxxxxxxxxxxxxxxxxx
验证: SHA-256(bearer_token) → 查 DB 匹配
```
### 5.3 敏感数据加密
| 数据 | 加密方式 | 说明 |
|------|---------|------|
| API Key 明文 | 不存储 | 仅展示一次 |
| API Key 哈希 | SHA-256 | 用于验证 |
| LLM API Key | AES-256-GCM | 存储在 DB |
| 用户密码 | bcrypt | Keycloak 管理 |
| Credit 余额 | 明文（整数） | 需要原子操作 |
---
## 6. 部署架构
### 6.1 开发环境 (Docker Compose)
```yaml
# docker-compose.yml 核心服务
services:
# 基础设施
postgresql: # :5432
redis: # :6379
kafka: # :9092
keycloak: # :8080
apisix: # :9080 (HTTP) / :9443 (HTTPS)
etcd: # :2379
# 自研服务
auth-service: # :8081
registry-service: # :8082
openapi-gateway: # :8083
billing-service: # :8084
skills-service: # :8085
admin-service: # :8086
im-gateway: # :8087
metering-service: # :8090
llm-router: # :8091
# 前端
web: # :3000 (React Dev Server)
admin: # :3001 (React Dev Server)
# 开源 AI 服务
langflow: # :7860
mcp-hub: # :3001
milvus: # :19530
# 监控
prometheus: # :9090
grafana: # :3002
```
### 6.2 生产环境 (Kubernetes)
```
┌─────────────────────────────────────────────────┐
│ Kubernetes Cluster │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ Namespace: aipaaS-prod │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ APISIX │ │ APISIX │ │ APISIX │ │ │
│ │ │ Pod x3 │ │ Pod x3 │ │ Pod x3 │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ auth-svc│ │billing │ │registry │ │ │
│ │ │ x2 │ │ x2 │ │ x2 │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │llm-route│ │openapi │ │skills │ │ │
│ │ │ x2 │ │ x2 │ │ x2 │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ │ │
│ │ HPA: CPU > 70% 时自动扩容 │ │
│ │ PDB: 至少保留 1 个 Pod 可用 │ │
│ └────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ Namespace: aipaaS-data │ │
│ │ PostgreSQL (Primary + Replica) │ │
│ │ Redis (Sentinel) │ │
│ │ Kafka (3 Brokers) │ │
│ │ Milvus (Standalone) │ │
│ └────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ Namespace: aipaaS-monitor │ │
│ │ Prometheus + Grafana + Loki │ │
│ └────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
```
---
## 7. 技术栈汇总
| 层级 | 技术 | 版本 | 许可证 | 用途 |
|------|------|------|--------|------|
| **前端** | React + TypeScript | 18+ / 5+ | MIT | Web UI |
| **UI 框架** | Ant Design Pro | 6+ | MIT | 组件库 |
| **图表** | ECharts | 5+ | Apache 2.0 | 数据可视化 |
| **后端** | Go | 1.22+ | BSD-3 | 核心服务 |
| **AI 服务** | Python | 3.11+ | PSF | LangFlow/MCP |
| **数据库** | PostgreSQL | 16+ | PostgreSQL | 主存储 |
| **缓存** | Redis | 7+ | BSD-3 | 缓存+Lua计费 |
| **消息队列** | Kafka | 3.x+ | Apache 2.0 | 事件总线 |
| **向量库** | Milvus | 2.x+ | Apache 2.0 | RAG |
| **认证** | Keycloak | 25+ | Apache 2.0 | SSO |
| **网关** | Apache APISIX | 3.15+ | Apache 2.0 | API Gateway |
| **Agent** | LangFlow | latest | MIT | 工作流编排 |
| **MCP** | mcp-hub | latest | MIT | MCP 管理 |
| **监控** | Prometheus+Grafana | latest | Apache 2.0 | 可观测性 |
| **开发工具** | MiMo Code | latest | Apache 2.0 | AI 编程 |
---
*文档结束*