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/01-PRD-产品需求文档.md
+445
View File
@@ -0,0 +1,445 @@
# AI PaaS 商业平台 — 产品需求文档（PRD）
> 版本: 1.0 | 日期: 2026-06-27
> 产品名: **AIPaaS**（AI能力服务平台）
> 目标用户: 个人开发者 / AI 爱好者 / 小型团队
---
## 1. 产品定位
**一句话描述**: 让任何开发者都能像用水电一样使用 AI 能力——注册即用，按量付费。
**核心价值**:
- **统一入口**: Agent、MCP、Skills、IM Bot、LLM 调用，一个平台全搞定
- **按需付费**: 不买服务器，不养团队，按 Token 用量付费
- **能力交易**: 开发者发布 AI 技能，用户购买使用，平台促成交易
- **多平台接入**: 一个 API Key 调用 DeepSeek/千问/豆包/百度/元宝/智谱
---
## 2. 用户角色
| 角色 | 说明 | 典型操作 |
|------|------|---------|
| **平台管理员** | 平台运营者 | 审核能力、管理用户、配置系统、查看收入 |
| **租户（开发者）** | 注册开发者，创建和发布 AI 能力 | 创建 Agent、发布 Skill、管理 API Key、查看用量 |
| **终端用户** | 使用 AI 能力的最终用户 | 调用 API、购买 Skill、通过 IM Bot 对话 |
---
## 3. 功能模块
### 3.1 用户认证与多租户（Auth）
#### 3.1.1 注册/登录
| 功能 | 说明 | 优先级 |
|------|------|--------|
| 邮箱注册 | 邮箱 + 密码注册，发送验证邮件 | P0 |
| GitHub OAuth | 第三方登录 | P1 |
| 微信扫码登录 | 第三方登录 | P2 |
| 登录 | 邮箱 + 密码，返回 JWT | P0 |
| Token 刷新 | Access Token 过期后用 Refresh Token 续期 | P0 |
| 忘记密码 | 邮箱重置密码 | P0 |
#### 3.1.2 多租户
| 功能 | 说明 | 优先级 |
|------|------|--------|
| 租户隔离 | 每个用户/团队是独立租户，数据严格隔离 | P0 |
| 角色体系 | owner / admin / developer / user 四级角色 | P0 |
| 团队管理 | 邀请成员、分配角色（Phase 2） | P1 |
#### 3.1.3 API Key 管理
| 功能 | 说明 | 优先级 |
|------|------|--------|
| 创建 Key | 用户创建 API Key，用于程序化调用 | P0 |
| 删除 Key | 可随时删除，立即失效 | P0 |
| Key 列表 | 查看所有 Key 的创建时间、最后使用时间 | P0 |
| 用途标识 | 给每个 Key 标记用途（如"我的应用"） | P1 |
---
### 3.2 LLM 智能路由（LLM Router）
#### 3.2.1 多平台对接
| 平台 | 协议 | 模型列表 | 优先级 |
|------|------|---------|--------|
| DeepSeek | OpenAI 兼容 | deepseek-chat, deepseek-reasoner | P0 |
| 千问（阿里云） | OpenAI 兼容 | qwen-turbo, qwen-plus, qwen-max | P0 |
| 豆包（字节） | OpenAI 兼容 | doubao-pro, doubao-lite | P0 |
| 智谱 GLM | OpenAI 兼容 | glm-4, glm-4-flash | P0 |
| 元宝（腾讯） | OpenAI 兼容 | yuanbao-pro, yuanbao-lite | P1 |
| 百度文心 | 自定义（需适配层） | ernie-4.0, ernie-3.5 | P1 |
| 本地 Ollama | OpenAI 兼容 | 用户自定义 | P1 |
#### 3.2.2 智能路由
| 功能 | 说明 | 优先级 |
|------|------|--------|
| 用户选择 | 用户指定使用哪个平台/模型 | P0 |
| 成本优先 | 自动选择当前最便宜的模型 | P1 |
| 延迟优先 | 自动选择响应最快的模型 | P1 |
| 故障转移 | 主模型不可用时自动切换备用模型 | P0 |
| 负载均衡 | 同一模型多个 API Key 时轮询 | P2 |
#### 3.2.3 调用方式
```
POST /v1/chat/completions ← OpenAI 兼容格式，用户直接用
GET /v1/models ← 可用模型列表
POST /v1/embeddings ← 向量嵌入（Phase 2）
```
---
### 3.3 计费系统（Billing）
#### 3.3.1 Credit 模型
| 概念 | 说明 |
|------|------|
| **Credit** | 内部统一计费单位，1 Credit = 1000 tokens |
| **模型系数** | 不同模型消耗不同: deepseek-chat=1.0, deepseek-reasoner=2.0, doubao-pro=1.5 |
| **余额** | 租户 Credit 余额，先扣后服 |
| **充值** | 支持手动充值（支付宝/微信支付） |
| **订阅** | 每月固定 Credit 额度，超出按量计费 |
#### 3.3.2 订阅套餐
| 套餐 | 月费 | 包含 Credits | 超出价格 | QPS 限制 |
|------|------|-------------|---------|---------|
| **Free** | ¥0 | 100 | 不允许超出 | 2 |
| **Pro** | ¥99 | 50,000 | ¥0.01/Credit | 20 |
| **Team** | ¥499 | 300,000 | ¥0.008/Credit | 100 |
| **Enterprise** | 定制 | 定制 | 定制 | 定制 |
#### 3.3.3 计费流程
```
用户调用 API
↓
1. API Key 验证 → 提取 tenant_id
↓
2. 余额检查 → 余额不足返回 402
↓
3. 预扣费（预留最大可能消耗）
↓
4. 调用 LLM Router → 获取实际消耗
↓
5. 结算（实际消耗 vs 预扣，多退少补）
↓
6. 记录流水（不可变审计日志）
↓
7. 返回结果 + 用量信息
```
#### 3.3.4 核心原则
| 原则 | 说明 |
|------|------|
| **先扣后服** | 先扣减余额，再允许调用，绝不允许"调用成功但余额为负" |
| **幂等** | 同一请求多次重试，绝不重复扣费 |
| **原子** | Redis Lua 脚本保证扣费操作原子性 |
| **可审计** | 每笔 Credit 变动都有 trace_id + 原因 |
| **实时可见** | Dashboard 上余额和用量秒级更新 |
---
### 3.4 能力注册中心（Capability Registry）
#### 3.4.1 能力类型
| 类型 | 说明 | 示例 |
|------|------|------|
| **agent** | AI 智能体 | 客服机器人、代码助手、翻译器 |
| **mcp** | MCP 协议服务 | 文件操作、数据库查询、API 调用 |
| **skill** | 可交易技能 | 文案生成、图片分析、数据分析 |
| **llm** | LLM 提供商 | DeepSeek、千问、豆包 |
| **custom** | 自定义 OpenAPI 应用 | 用户自己的 API 服务 |
#### 3.4.2 能力生命周期
```
draft (草稿) → pending_review (待审核) → active (活跃) → deprecated (弃用)
↘ rejected (拒绝)
```
#### 3.4.3 能力元数据
```yaml
name: "智能客服 Agent"
type: agent
version: "1.2.0"
description: "基于 GPT-4 的智能客服，支持多轮对话和知识库检索"
tags: [客服, 多轮对话, 知识库]
endpoint: "https://my-agent.example.com/api"
protocol: rest
pricing:
model: per_token
rate: 2 # 每 1000 tokens 消耗 2 Credits
dependencies:
- capability_id: "milvus-rag"
version: ">=1.0.0"
status: active
```
---
### 3.5 Skills 市场
#### 3.5.1 核心功能
| 功能 | 说明 | 优先级 |
|------|------|--------|
| 发布技能 | 开发者上传技能，填写描述、定价、示例 | P0 |
| 浏览市场 | 按分类、标签、评分、热度浏览 | P0 |
| 搜索技能 | 全文搜索 + 分类过滤 | P0 |
| 购买技能 | 用 Credit 购买，立即可用 | P0 |
| 已购管理 | 查看已购技能列表 | P0 |
| 技能评分 | 用户评分和评论 | P1 |
| 技能试用 | 免费试用 N 次 | P1 |
#### 3.5.2 计费模式
| 模式 | 说明 | 分成 |
|------|------|------|
| per_call | 每次调用扣费 | 平台 25% / 开发者 75% |
| per_token | 按 Token 扣费 | 平台 25% / 开发者 75% |
| subscription | 订阅制（月/年） | 平台 25% / 开发者 75% |
| free | 免费 | 无 |
#### 3.5.3 技能详情页内容
```
名称 / 作者 / 版本 / 价格
简介 / 详细描述
功能列表 / 使用示例
API 文档 / 调用示例
评分 / 评论 / 使用次数
```
---
### 3.6 IM Bot 网关
#### 3.6.1 支持平台
| 平台 | 协议 | 优先级 | 说明 |
|------|------|--------|------|
| 微信 | LangBot / OpenClaw | P0 | 个人微信，扫码登录 |
| QQ | OneBot v11 | P1 | go-cqhttp |
| 钉钉 | 钉钉开放平台 | P1 | 企业机器人 |
| 飞书 | 飞书开放平台 | P2 | 企业机器人 |
| Telegram | Bot API | P2 | 个人机器人 |
#### 3.6.2 核心功能
| 功能 | 说明 | 优先级 |
|------|------|--------|
| 多轮对话 | 维护会话上下文（Redis，24h 过期） | P0 |
| 模型选择 | 用户可切换不同 LLM 模型 | P0 |
| 指令系统 | /help /model /clear /balance 等快捷指令 | P0 |
| 消息格式 | 文本 / Markdown / 图片 | P0 |
| 按钮交互 | 平台支持时提供按钮选择 | P1 |
| 文件处理 | 接收和发送文件（图片、文档） | P2 |
#### 3.6.3 会话管理
```
每个用户 + 每个平台 = 独立会话
会话存储: Redis Hash
上下文窗口: 最近 20 条消息
过期时间: 24 小时无活动自动清除
```
---
### 3.7 用户 Dashboard
#### 3.7.1 页面结构
```
Dashboard
├── 首页概览
│ ├── Credit 余额卡片
│ ├── 今日/本月用量趋势图
│ ├── 快捷操作按钮
│ └── 最近调用记录
├── API Key 管理
│ ├── Key 列表（创建时间/最后使用/状态）
│ ├── 创建新 Key
│ └── 删除 Key
├── 用量详情
│ ├── 按日/周/月图表
│ ├── 按模型分类统计
│ ├── 按能力分类统计
│ └── 导出 CSV
├── 账单中心
│ ├── Credit 流水记录
│ ├── 订阅管理（升级/降级/取消）
│ └── 充值历史
├── 我的能力
│ ├── 已创建的能力列表
│ ├── 创建新能力
│ └── 能力统计（调用量/收入）
├── 市场
│ ├── 浏览技能
│ ├── 搜索技能
│ └── 已购技能
└── 设置
├── 个人信息
├── 修改密码
└── 通知偏好
```
#### 3.7.2 首页概览卡片
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Credit 余额 │ │ 今日调用次数 │ │ 今日消耗 │ │ 当前套餐 │
│ 12,580 │ │ 342 次 │ │ 1,280 Credits│ │ Pro │
│ [充值] [升级] │ │ ↑12% vs 昨日 │ │ ↓5% vs 昨日 │ │ 到期: 07-27 │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
```
---
### 3.8 管理后台
#### 3.8.1 页面结构
```
Admin Console
├── 仪表盘
│ ├── 核心指标（用户数/API调用量/收入）
│ ├── 趋势图表
│ └── 系统状态
├── 用户管理
│ ├── 用户列表（搜索/过滤/分页）
│ ├── 用户详情
│ └── 封禁/解封
├── 租户管理
│ ├── 租户列表
│ ├── 租户详情（订阅/用量/余额）
│ └── 调整余额
├── 能力审核
│ ├── 待审核列表
│ ├── 审核详情
│ └── 通过/拒绝
├── 系统配置
│ ├── LLM 提供商配置
│ ├── 订阅套餐配置
│ └── 全局限流配置
└── 数据分析
├── API 调用趋势
├── 热门能力排行
└── 收入报表
```
---
### 3.9 MCP Hub 集成
| 功能 | 说明 | 优先级 |
|------|------|--------|
| MCP Server 注册 | 开发者注册自己的 MCP Server | P0 |
| 工具列表 | 查看已注册 MCP Server 提供的工具 | P0 |
| 工具调用 | 通过平台调用 MCP 工具（经过计费） | P0 |
| Server 市场 | 浏览和使用社区 MCP Server | P1 |
---
### 3.10 Agent 编排（LangFlow 集成）
| 功能 | 说明 | 优先级 |
|------|------|--------|
| 可视化编辑器 | 嵌入 LangFlow 的 Flow 编辑器 | P1 |
| Flow 发布 | 将 Flow 发布为可调用的 Agent | P0 |
| Flow 运行 | API 调用运行 Flow（经过计费） | P0 |
| Flow 模板 | 预置常用 Flow 模板 | P2 |
---
### 3.11 ACP 协议（Phase 4）
| 功能 | 说明 | 优先级 |
|------|------|--------|
| Agent 发现 | 发现已注册的 Agent | P1 |
| Agent 通信 | Agent 间发送消息 | P1 |
| 工作流编排 | 多 Agent 协作完成复杂任务 | P2 |
---
## 4. 非功能需求
### 4.1 性能要求
| 指标 | 目标值 |
|------|--------|
| API 响应时间 (P95) | < 200ms（不含 LLM 调用） |
| LLM 调用响应时间 (P95) | < 5s（流式首 token < 1s） |
| 并发用户数 | 1000+ |
| API QPS | 500+ |
| 计费延迟 | < 100ms（Redis Lua） |
### 4.2 安全要求
| 要求 | 说明 |
|------|------|
| 数据加密 | 传输 HTTPS，存储敏感字段 AES-256 |
| 多租户隔离 | PostgreSQL RLS，数据严格隔离 |
| API Key 安全 | 哈希存储，仅展示一次 |
| 限流防刷 | 按租户/Key 限流，防止滥用 |
| 审计日志 | 所有关键操作可追溯 |
### 4.3 可用性要求
| 指标 | 目标值 |
|------|--------|
| 系统可用性 | 99.9% |
| 数据备份 | 每日自动备份 |
| 故障恢复 | RPO < 1h, RTO < 4h |
---
## 5. Phase 交付范围
### Phase 1（Week 1-4）: 基座
- ✅ 注册/登录/鉴权
- ✅ 多租户隔离
- ✅ 数据库 Schema
- ✅ API Gateway 基础路由
- ✅ 项目骨架可运行
### Phase 2（Week 5-8）: 核心引擎
- ✅ LLM Router（7 个平台对接）
- ✅ Token 计费引擎
- ✅ 用量追踪
- ✅ OpenAI 兼容 API
- ✅ 流式响应 SSE
### Phase 3（Week 9-12）: 能力治理
- ✅ Capability Registry
- ✅ Skills 市场
- ✅ 用户 Dashboard
- ✅ 管理后台
### Phase 4（Week 13-16）: 生态扩展
- ✅ IM Bot 网关（微信/QQ/钉钉）
- ✅ MCP Hub 集成
- ✅ LangFlow Agent 集成
- ✅ ACP 协议基础
### Phase 5（Week 17-20）: 集成上线
- ✅ 全链路测试
- ✅ 生产部署
- ✅ 监控告警
- ✅ 完整文档
---
*文档结束*
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 编程 |
---
*文档结束*
docs/03-数据库设计.md
+443
View File
@@ -0,0 +1,443 @@
# AI PaaS 商业平台 — 数据库设计
> 版本: 1.0 | 日期: 2026-06-27
> 数据库: PostgreSQL 16+ | 缓存: Redis 7+
---
## 1. ER 关系图
```
tenants ──1:N──→ users
tenants ──1:N──→ capabilities
tenants ──1:N──→ subscriptions
tenants ──1:N──→ credit_transactions
tenants ──1:N──→ token_usage
tenants ──1:N──→ skills
tenants ──1:N──→ im_sessions
users ──1:N──→ api_keys
users ──1:N──→ skill_purchases
capabilities ──1:N──→ capability_versions
skills ──1:N──→ skill_purchases
im_sessions ──1:N──→ im_messages
```
---
## 2. 表定义
### 2.1 tenants（租户）
```sql
CREATE TABLE tenants (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
slug VARCHAR(100) NOT NULL UNIQUE, -- URL 友好标识
plan VARCHAR(20) NOT NULL DEFAULT 'free', -- free/pro/team/enterprise
credit_balance BIGINT NOT NULL DEFAULT 0, -- 毫 Credit (1 Credit = 1000)
credit_included BIGINT NOT NULL DEFAULT 100000, -- 月包含 Credit (毫)
credit_used BIGINT NOT NULL DEFAULT 0, -- 本月已用 (毫)
status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/suspended/deleted
settings JSONB DEFAULT '{}', -- 租户配置
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE INDEX idx_tenants_slug ON tenants(slug);
CREATE INDEX idx_tenants_status ON tenants(status);
-- RLS
ALTER TABLE tenants ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON tenants
USING (id = current_setting('app.tenant_id')::uuid);
```
### 2.2 users（用户）
```sql
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
email VARCHAR(255) NOT NULL,
password_hash VARCHAR(255), -- Keycloak 管理时可为空
name VARCHAR(255) NOT NULL,
role VARCHAR(20) NOT NULL DEFAULT 'user', -- owner/admin/developer/user
avatar_url VARCHAR(500),
status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/suspended/deleted
last_login_at TIMESTAMP WITH TIME ZONE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
UNIQUE(tenant_id, email)
);
CREATE INDEX idx_users_tenant ON users(tenant_id);
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_role ON users(role);
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON users
USING (tenant_id = current_setting('app.tenant_id')::uuid);
```
### 2.3 api_keys（API 密钥）
```sql
CREATE TABLE api_keys (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
name VARCHAR(255) NOT NULL, -- 用途标识
key_hash VARCHAR(64) NOT NULL UNIQUE, -- SHA-256 哈希
key_prefix VARCHAR(10) NOT NULL, -- 前缀 aip_xxxx
scopes TEXT[] DEFAULT '{}', -- 权限范围
last_used_at TIMESTAMP WITH TIME ZONE,
expires_at TIMESTAMP WITH TIME ZONE, -- 可选过期时间
status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/revoked
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE INDEX idx_api_keys_tenant ON api_keys(tenant_id);
CREATE INDEX idx_api_keys_hash ON api_keys(key_hash);
CREATE INDEX idx_api_keys_user ON api_keys(user_id);
ALTER TABLE api_keys ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON api_keys
USING (tenant_id = current_setting('app.tenant_id')::uuid);
```
### 2.4 subscriptions（订阅）
```sql
CREATE TABLE subscriptions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
plan VARCHAR(20) NOT NULL, -- free/pro/team/enterprise
credits_included BIGINT NOT NULL, -- 月包含 Credit (毫)
credits_used BIGINT NOT NULL DEFAULT 0, -- 本月已用
price_cents INTEGER NOT NULL DEFAULT 0, -- 月费 (分)
billing_cycle VARCHAR(10) NOT NULL DEFAULT 'monthly', -- monthly/yearly
period_start TIMESTAMP WITH TIME ZONE NOT NULL,
period_end TIMESTAMP WITH TIME ZONE NOT NULL,
status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/cancelled/expired
stripe_sub_id VARCHAR(255), -- Stripe 订阅 ID
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE INDEX idx_subscriptions_tenant ON subscriptions(tenant_id);
CREATE INDEX idx_subscriptions_status ON subscriptions(status);
CREATE INDEX idx_subscriptions_period ON subscriptions(period_start, period_end);
ALTER TABLE subscriptions ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON subscriptions
USING (tenant_id = current_setting('app.tenant_id')::uuid);
```
### 2.5 credit_transactions（Credit 流水 — 不可变）
```sql
CREATE TABLE credit_transactions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
type VARCHAR(30) NOT NULL, -- usage/topup/subscription/bonus/refund
amount BIGINT NOT NULL, -- 变动量 (毫 Credit)，正=加，负=减
balance_after BIGINT NOT NULL, -- 变动后余额
description TEXT, -- 描述
trace_id VARCHAR(64), -- 关联的调用 trace
idempotency_key VARCHAR(64) UNIQUE, -- 幂等键 (防重复扣费)
reference_type VARCHAR(30), -- llm_call/skill_purchase/topup/subscription
reference_id UUID, -- 关联 ID
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-- 不可变: 无 updated_at, 无 DELETE
);
CREATE INDEX idx_credit_tx_tenant ON credit_transactions(tenant_id);
CREATE INDEX idx_credit_tx_type ON credit_transactions(type);
CREATE INDEX idx_credit_tx_created ON credit_transactions(created_at);
CREATE INDEX idx_credit_tx_trace ON credit_transactions(trace_id);
-- 不可变表: 禁用 UPDATE 和 DELETE
CREATE RULE credit_tx_no_update AS ON UPDATE TO credit_transactions DO INSTEAD NOTHING;
CREATE RULE credit_tx_no_delete AS ON DELETE TO credit_transactions DO INSTEAD NOTHING;
ALTER TABLE credit_transactions ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON credit_transactions
USING (tenant_id = current_setting('app.tenant_id')::uuid);
```
### 2.6 token_usage（Token 用量 — 按月分区）
```sql
-- 主表 (自动分区)
CREATE TABLE token_usage (
id UUID NOT NULL DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL,
capability_id UUID,
user_id UUID,
model VARCHAR(100) NOT NULL, -- deepseek-chat, qwen-turbo
provider VARCHAR(50) NOT NULL, -- deepseek, qianwen, doubao
prompt_tokens INTEGER NOT NULL,
completion_tokens INTEGER NOT NULL,
total_tokens INTEGER NOT NULL,
cost_credits BIGINT NOT NULL, -- 消耗 Credit (毫)
trace_id VARCHAR(64),
metadata JSONB DEFAULT '{}',
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
PRIMARY KEY (id, created_at)
) PARTITION BY RANGE (created_at);
-- 按月创建分区
CREATE TABLE token_usage_2026_07 PARTITION OF token_usage
FOR VALUES FROM ('2026-07-01') TO ('2026-08-01');
CREATE TABLE token_usage_2026_08 PARTITION OF token_usage
FOR VALUES FROM ('2026-08-01') TO ('2026-09-01');
-- ... 自动创建未来分区
CREATE INDEX idx_token_usage_tenant ON token_usage(tenant_id, created_at);
CREATE INDEX idx_token_usage_model ON token_usage(model, created_at);
CREATE INDEX idx_token_usage_trace ON token_usage(trace_id);
-- 不可变表
CREATE RULE token_usage_no_update AS ON UPDATE TO token_usage DO INSTEAD NOTHING;
CREATE RULE token_usage_no_delete AS ON DELETE TO token_usage DO INSTEAD NOTHING;
```
### 2.7 capabilities（能力）
```sql
CREATE TABLE capabilities (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
name VARCHAR(255) NOT NULL,
type VARCHAR(30) NOT NULL, -- agent/mcp/skill/llm/custom
version VARCHAR(50) NOT NULL, -- SemVer
description TEXT,
tags TEXT[] DEFAULT '{}',
endpoint VARCHAR(500), -- 调用地址
protocol VARCHAR(20) DEFAULT 'rest', -- rest/grpc/websocket
pricing_config JSONB DEFAULT '{}', -- 计费配置
dependencies JSONB DEFAULT '[]', -- 依赖的其他能力
owner_id UUID REFERENCES users(id),
status VARCHAR(20) NOT NULL DEFAULT 'draft', -- draft/pending_review/active/deprecated/rejected
review_note TEXT, -- 审核备注
view_count INTEGER DEFAULT 0, -- 浏览次数
invoke_count BIGINT DEFAULT 0, -- 调用次数
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
UNIQUE(tenant_id, name, version)
);
CREATE INDEX idx_capabilities_tenant ON capabilities(tenant_id);
CREATE INDEX idx_capabilities_type ON capabilities(type);
CREATE INDEX idx_capabilities_status ON capabilities(status);
CREATE INDEX idx_capabilities_tags ON capabilities USING GIN(tags);
ALTER TABLE capabilities ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON capabilities
USING (tenant_id = current_setting('app.tenant_id')::uuid);
```
### 2.8 capability_versions（能力版本）
```sql
CREATE TABLE capability_versions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
capability_id UUID NOT NULL REFERENCES capabilities(id) ON DELETE CASCADE,
version VARCHAR(50) NOT NULL,
endpoint VARCHAR(500),
changelog TEXT,
status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/deprecated
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
UNIQUE(capability_id, version)
);
CREATE INDEX idx_cap_versions_cap ON capability_versions(capability_id);
```
### 2.9 skills（技能）
```sql
CREATE TABLE skills (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
name VARCHAR(255) NOT NULL,
description TEXT,
category VARCHAR(50), -- 分类
tags TEXT[] DEFAULT '{}',
pricing_model VARCHAR(20) NOT NULL DEFAULT 'per_call', -- per_call/per_token/subscription/free
price_credits BIGINT NOT NULL DEFAULT 0, -- 价格 (毫 Credit)
developer_share NUMERIC(3,2) DEFAULT 0.75, -- 开发者分成比例
endpoint VARCHAR(500), -- API 地址
documentation TEXT, -- 使用文档
icon_url VARCHAR(500),
status VARCHAR(20) NOT NULL DEFAULT 'draft', -- draft/active/suspended/deleted
rating NUMERIC(3,2) DEFAULT 0, -- 评分
rating_count INTEGER DEFAULT 0, -- 评分人数
view_count INTEGER DEFAULT 0, -- 浏览次数
purchase_count INTEGER DEFAULT 0, -- 购买次数
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE INDEX idx_skills_tenant ON skills(tenant_id);
CREATE INDEX idx_skills_category ON skills(category);
CREATE INDEX idx_skills_status ON skills(status);
CREATE INDEX idx_skills_tags ON skills USING GIN(tags);
CREATE INDEX idx_skills_rating ON skills(rating DESC);
CREATE INDEX idx_skills_name_search ON skills USING GIN(to_tsvector('simple', name || ' ' || COALESCE(description, '')));
ALTER TABLE skills ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON skills
USING (tenant_id = current_setting('app.tenant_id')::uuid);
```
### 2.10 skill_purchases（技能购买）
```sql
CREATE TABLE skill_purchases (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
user_id UUID NOT NULL REFERENCES users(id),
skill_id UUID NOT NULL REFERENCES skills(id),
developer_id UUID NOT NULL, -- 开发者 user_id
amount_credits BIGINT NOT NULL, -- 支付金额 (毫 Credit)
platform_share BIGINT NOT NULL, -- 平台分成
developer_share BIGINT NOT NULL, -- 开发者分成
status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/refunded
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE INDEX idx_skill_purchases_user ON skill_purchases(user_id);
CREATE INDEX idx_skill_purchases_skill ON skill_purchases(skill_id);
CREATE INDEX idx_skill_purchases_tenant ON skill_purchases(tenant_id);
```
### 2.11 im_sessions（IM 会话）
```sql
CREATE TABLE im_sessions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
platform VARCHAR(20) NOT NULL, -- wechat/qq/dingtalk/feishu
user_identifier VARCHAR(255) NOT NULL, -- 平台用户标识
user_name VARCHAR(255), -- 平台用户名
bot_id VARCHAR(255), -- 机器人标识
model VARCHAR(100) DEFAULT 'deepseek-chat', -- 当前使用模型
status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/closed
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
last_active_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE INDEX idx_im_sessions_tenant ON im_sessions(tenant_id);
CREATE INDEX idx_im_sessions_platform ON im_sessions(platform, user_identifier);
ALTER TABLE im_sessions ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON im_sessions
USING (tenant_id = current_setting('app.tenant_id')::uuid);
```
### 2.12 im_messages（IM 消息）
```sql
CREATE TABLE im_messages (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
session_id UUID NOT NULL REFERENCES im_sessions(id),
role VARCHAR(10) NOT NULL, -- user/assistant/system
content TEXT NOT NULL,
model VARCHAR(100), -- 使用的模型
tokens_used INTEGER,
cost_credits BIGINT,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE INDEX idx_im_messages_session ON im_messages(session_id, created_at);
```
---
## 3. Redis 数据结构
### 3.1 计费相关
```
# Credit 余额 (毫 Credit)
billing:balance:{tenant_id} → "12580000"
# 类型: String
# 操作: GET / DECRBY (Lua 原子)
# TTL: 永不过期
# 幂等键
billing:idempotency:{tenant_id}:{idempotency_key} → {
"result": "success",
"amount": -1280,
"trace_id": "abc-123"
}
# 类型: Hash
# TTL: 24 小时
# 每日统计
billing:daily:{tenant_id}:{YYYY-MM-DD} → {
"calls": "342",
"tokens": "456000",
"credits": "1280000"
}
# 类型: Hash
# TTL: 7 天
# 订阅信息
billing:subscription:{tenant_id} → {
"plan": "pro",
"credits_included": "50000000",
"credits_used": "12800000",
"period_end": "2026-07-27T00:00:00Z"
}
# 类型: Hash
# TTL: 永不过期
```
### 3.2 限流相关
```
# 滑动窗口限流
ratelimit:{tenant_id}:{window_key} → "1" (INCR)
# 类型: String
# TTL: 窗口大小 (如 60s)
```
### 3.3 IM 会话
```
# 会话上下文
im:session:{platform}:{user_id} → {
"tenant_id": "xxx",
"model": "deepseek-chat",
"messages": "[{role,content}, ...]" # 最近 20 条
}
# 类型: Hash
# TTL: 24 小时
```
---
## 4. Migration 策略
```
migrations/
├── 001_init.sql # 所有表 + RLS + 索引
├── 002_seed_data.sql # 开发环境种子数据
├── 003_add_partitions.sql # token_usage 分区
└── 004_add_fulltext.sql # 全文搜索索引
```
**规则**:
- Migration 文件名: `{序号}_{描述}.sql`
- 不允许修改已执行的 Migration
- 每个 Migration 必须可回滚
- 生产环境 Migration 必须在低峰期执行
---
*文档结束*
docs/04-API接口规范.md
+572
View File
@@ -0,0 +1,572 @@
# AI PaaS 商业平台 — API 接口规范
> 版本: 1.0 | 日期: 2026-06-27
> 规范: OpenAPI 3.0 | Base URL: https://api.aipaas.com
---
## 1. 通用约定
### 1.1 认证方式
| 方式 | Header | 说明 |
|------|--------|------|
| JWT | `Authorization: Bearer {access_token}` | Web 前端登录后使用 |
| API Key | `Authorization: Bearer aip_{key}` | 程序化调用 |
### 1.2 响应格式
```json
// 成功
{
"code": 0,
"message": "success",
"data": { ... }
}
// 分页
{
"code": 0,
"message": "success",
"data": {
"items": [...],
"total": 100,
"page": 1,
"page_size": 20
}
}
// 错误
{
"code": 40001,
"message": "Insufficient balance",
"data": null
}
```
### 1.3 错误码
| 错误码 | HTTP Status | 说明 |
|--------|------------|------|
| 0 | 200 | 成功 |
| 40001 | 400 | 请求参数错误 |
| 40101 | 401 | 未认证 |
| 40102 | 401 | API Key 无效 |
| 40301 | 403 | 权限不足 |
| 40401 | 404 | 资源不存在 |
| 40201 | 402 | Credit 余额不足 |
| 42901 | 429 | 请求频率超限 |
| 50001 | 500 | 服务内部错误 |
| 50201 | 502 | 上游服务不可用 |
---
## 2. Auth 接口
### POST /api/v1/auth/register
```yaml
description: 用户注册
request:
body:
email: string (required)
password: string (required, min 8)
name: string (required)
response:
200:
data:
user_id: uuid
email: string
tenant_id: uuid
```
### POST /api/v1/auth/login
```yaml
description: 用户登录
request:
body:
email: string (required)
password: string (required)
response:
200:
data:
access_token: string (JWT, 1h)
refresh_token: string (JWT, 7d)
expires_in: integer (seconds)
user:
id: uuid
name: string
email: string
role: string
tenant_id: uuid
```
### POST /api/v1/auth/refresh
```yaml
description: 刷新 Token
request:
body:
refresh_token: string (required)
response:
200:
data:
access_token: string
expires_in: integer
```
### GET /api/v1/auth/me
```yaml
description: 获取当前用户信息
auth: JWT
response:
200:
data:
id: uuid
name: string
email: string
role: string
tenant_id: uuid
tenant:
name: string
plan: string
credit_balance: integer
```
---
## 3. API Key 接口
### POST /api/v1/apikeys
```yaml
description: 创建 API Key
auth: JWT
request:
body:
name: string (required) # 用途标识
response:
200:
data:
id: uuid
name: string
key: string # 仅此一次展示明文
key_prefix: string # aip_xxxx
created_at: datetime
```
### GET /api/v1/apikeys
```yaml
description: API Key 列表
auth: JWT
response:
200:
data:
items:
- id: uuid
name: string
key_prefix: string
last_used_at: datetime
status: string
created_at: datetime
```
### DELETE /api/v1/apikeys/{id}
```yaml
description: 删除 API Key
auth: JWT
response:
200: { code: 0, message: "success" }
```
---
## 4. LLM 调用接口（OpenAI 兼容）
### POST /v1/chat/completions
```yaml
description: Chat Completion (OpenAI 兼容格式)
auth: API Key 或 JWT
request:
body:
model: string (required) # deepseek-chat, qwen-turbo, etc.
messages:
- role: string # system/user/assistant
content: string
temperature: number (optional, 0-2, default 1)
max_tokens: integer (optional)
stream: boolean (optional, default false)
top_p: number (optional)
stop: string | array (optional)
response:
200:
# 非流式
id: string
object: "chat.completion"
model: string
choices:
- index: 0
message:
role: "assistant"
content: string
finish_reason: "stop"
usage:
prompt_tokens: integer
completion_tokens: integer
total_tokens: integer
# 流式 (SSE)
# Content-Type: text/event-stream
# data: {"id":"...","choices":[{"delta":{"content":"token"}}]}
# data: [DONE]
```
### GET /v1/models
```yaml
description: 可用模型列表
auth: API Key 或 JWT
response:
200:
data:
- id: "deepseek-chat"
object: "model"
provider: "deepseek"
pricing:
credits_per_1k: 1.0
- id: "qwen-turbo"
object: "model"
provider: "qianwen"
pricing:
credits_per_1k: 0.8
```
---
## 5. Billing 接口
### GET /api/v1/billing/balance
```yaml
description: 查询 Credit 余额
auth: JWT
response:
200:
data:
balance: integer # 当前余额 (毫 Credit)
balance_display: number # 显示余额 (Credit)
plan: string
credits_included: integer
credits_used: integer
period_end: datetime
```
### POST /api/v1/billing/topup
```yaml
description: 充值
auth: JWT
request:
body:
amount: integer (required) # 充值金额 (分)
payment_method: string # alipay/wechat
response:
200:
data:
order_id: string
payment_url: string # 支付链接
```
### GET /api/v1/billing/transactions
```yaml
description: Credit 流水查询
auth: JWT
request:
query:
page: integer (default 1)
page_size: integer (default 20)
type: string (optional) # usage/topup/subscription
start_date: date (optional)
end_date: date (optional)
response:
200:
data:
items:
- id: uuid
type: string
amount: integer
balance_after: integer
description: string
trace_id: string
created_at: datetime
total: integer
page: integer
page_size: integer
```
### POST /api/v1/billing/subscribe
```yaml
description: 订阅管理
auth: JWT
request:
body:
plan: string (required) # pro/team
billing_cycle: string # monthly/yearly
response:
200:
data:
subscription_id: uuid
plan: string
price_cents: integer
credits_included: integer
period_start: datetime
period_end: datetime
```
---
## 6. Capability Registry 接口
### POST /api/v1/capabilities
```yaml
description: 注册新能力
auth: JWT
request:
body:
name: string (required)
type: string (required) # agent/mcp/skill/llm/custom
version: string (required) # SemVer
description: string
tags: array[string]
endpoint: string
protocol: string # rest/grpc/websocket
pricing_config: object
response:
200:
data:
id: uuid
status: "draft"
```
### GET /api/v1/capabilities
```yaml
description: 能力列表
auth: JWT 或 API Key
request:
query:
type: string (optional)
status: string (optional)
tags: string (optional) # 逗号分隔
page: integer
page_size: integer
response:
200:
data:
items:
- id: uuid
name: string
type: string
version: string
status: string
tags: array[string]
invoke_count: integer
created_at: datetime
```
### GET /api/v1/capabilities/{id}
```yaml
description: 能力详情
auth: JWT 或 API Key
response:
200:
data:
id: uuid
name: string
type: string
version: string
description: string
tags: array[string]
endpoint: string
protocol: string
pricing_config: object
status: string
invoke_count: integer
created_at: datetime
```
### PUT /api/v1/capabilities/{id}
```yaml
description: 更新能力
auth: JWT
request:
body:
name: string (optional)
description: string (optional)
tags: array[string] (optional)
endpoint: string (optional)
pricing_config: object (optional)
```
### DELETE /api/v1/capabilities/{id}
```yaml
description: 注销能力
auth: JWT
```
### POST /api/v1/capabilities/{id}/versions
```yaml
description: 发布新版本
auth: JWT
request:
body:
version: string (required)
endpoint: string
changelog: string
```
---
## 7. Skills 市场接口
### POST /api/v1/skills
```yaml
description: 发布技能
auth: JWT
request:
body:
name: string (required)
description: string
category: string
tags: array[string]
pricing_model: string # per_call/per_token/subscription/free
price_credits: integer
endpoint: string
documentation: string
response:
200:
data:
id: uuid
```
### GET /api/v1/skills
```yaml
description: 市场列表
auth: 公开
request:
query:
q: string (optional) # 搜索关键词
category: string (optional)
tags: string (optional)
sort: string # rating/popular/newest
page: integer
page_size: integer
response:
200:
data:
items:
- id: uuid
name: string
description: string
category: string
pricing_model: string
price_credits: integer
rating: number
purchase_count: integer
developer:
name: string
```
### POST /api/v1/skills/{id}/purchase
```yaml
description: 购买技能
auth: JWT
request:
body:
# 无需参数，自动扣费
response:
200:
data:
purchase_id: uuid
credits_deducted: integer
balance_after: integer
```
### GET /api/v1/skills/purchased
```yaml
description: 已购技能列表
auth: JWT
response:
200:
data:
items:
- skill_id: uuid
name: string
purchased_at: datetime
```
---
## 8. IM Bot 接口
### POST /api/v1/im/callback/{platform}
```yaml
description: 平台回调 (Webhook)
auth: 平台签名验证
request:
body: 平台消息格式 (各平台不同)
response:
200: 平台要求的响应格式
```
### GET /api/v1/im/sessions
```yaml
description: 会话列表
auth: JWT
response:
200:
data:
items:
- id: uuid
platform: string
user_identifier: string
user_name: string
model: string
last_active_at: datetime
```
---
## 9. Admin 接口
### GET /api/v1/admin/dashboard
```yaml
description: 管理仪表盘
auth: JWT (admin 角色)
response:
200:
data:
total_users: integer
total_tenants: integer
total_api_calls: integer (今日)
total_revenue: integer (本月)
system_status: object
```
### GET /api/v1/admin/users
```yaml
description: 用户列表
auth: JWT (admin 角色)
request:
query:
q: string (optional)
status: string (optional)
page: integer
page_size: integer
```
### POST /api/v1/admin/capabilities/{id}/review
```yaml
description: 能力审核
auth: JWT (admin 角色)
request:
body:
action: string # approve/reject
note: string
```
---
*文档结束*
docs/05-AGENTS-MiMoCode配置.md
+186
View File
@@ -0,0 +1,186 @@
# AI PaaS Platform — AGENTS.md（MiMo Code 核心配置）
> 此文件放在项目根目录 `.mimocode/AGENTS.md`，MiMo Code 每次启动时自动加载。
> 这是 MiMo Code 理解整个项目的唯一上下文来源——写得越精确，生成的代码质量越高。
---
# AI PaaS 商业平台
## 项目概述
面向个人开发者的 AI 能力服务平台。提供 Agent、MCP、Skills、IM Bot、LLM 调用等 AI 能力，支持按 Token 计费和订阅制收费。
## 架构模式
微服务架构 + 事件驱动。核心业务自研，基础设施开源。
## 技术栈
- **后端核心**: Go 1.22+ (所有核心服务)
- **AI 服务**: Python 3.11+ (LangFlow, MCP Hub 集成)
- **前端**: React 18 + TypeScript 5+ + Ant Design Pro 6 + ECharts
- **数据库**: PostgreSQL 16 (RLS 多租户隔离)
- **缓存**: Redis 7 (Lua 原子计费)
- **消息队列**: Kafka 3.x (用量上报)
- **向量库**: Milvus 2.x (RAG)
- **认证**: Keycloak 25+ (JWT + API Key)
- **网关**: Apache APISIX 3.15+ (API Gateway)
- **Agent**: LangFlow (工作流编排)
- **MCP**: mcp-hub (MCP 服务管理)
- **监控**: Prometheus + Grafana
## 项目结构
```
ai-paas-platform/
├── .mimocode/
│ └── AGENTS.md ← 本文件
├── docs/ ← 设计文档
│ ├── 01-PRD-产品需求文档.md
│ ├── 02-系统架构设计.md
│ ├── 03-数据库设计.md
│ └── 04-API接口规范.md
├── packages/ ← 前端应用
│ ├── web/ ← 用户 Dashboard (React)
│ └── admin/ ← 管理后台 (React)
├── services/ ← 后端服务 (Go)
│ ├── auth/ ← 认证服务 (:8081)
│ ├── registry/ ← 能力注册中心 (:8082)
│ ├── openapi-gateway/ ← OpenAI 兼容网关 (:8083)
│ ├── billing/ ← 计费引擎 (:8084)
│ ├── skills/ ← Skills 市场 (:8085)
│ ├── admin/ ← 管理后台 API (:8086)
│ ├── im-gateway/ ← IM Bot 网关 (:8087)
│ ├── metering/ ← 用量追踪 (:8090)
│ └── llm-router/ ← LLM 智能路由 (:8091)
├── infra/ ← 基础设施配置
│ ├── keycloak/
│ ├── postgresql/
│ ├── redis/
│ ├── kafka/
│ ├── milvus/
│ └── apisix/
├── deploy/ ← 部署配置
│ ├── docker-compose.yml
│ └── k8s/
└── migrations/ ← 数据库 Migration
├── 001_init.sql
└── ...
```
## 开发规范
### Go 服务
- 遵循 Effective Go + gofmt + golangci-lint
- 每个服务独立 main.go，可独立编译运行
- 服务间通信: 同步用 HTTP/gRPC，异步用 Kafka
- 错误处理: 统一错误码，返回 `{code, message, data}` 格式
- 配置管理: 环境变量 + YAML 配置文件
- 日志: 结构化 JSON 日志 (slog)
### TypeScript 前端
- 遵循 eslint + prettier
- 组件: React 函数组件 + Hooks
- 状态管理: React Query (服务端) + Zustand (客户端)
- 路由: React Router v6
- 样式: Ant Design Pro 内置 + CSS Modules
### Python AI 服务
- 遵循 ruff + black
- 类型注解: 必须
- 异步: asyncio
### 数据库
- 所有表启用 RLS，策略基于 tenant_id
- 所有金额使用整数 (毫 Credit)，避免浮点
- Migration 文件名: `{序号}_{描述}.sql`
- 不可变表: credit_transactions, token_usage (无 UPDATE/DELETE)
### Git
- 分支: main (生产), develop (开发), feature/* (功能)
- 提交: Conventional Commits (feat/fix/docs/chore/test)
- PR: 必须通过 CI + Code Review
### 测试
- Go: testing + testify, 覆盖率 > 80%
- TypeScript: vitest + playwright
- 单元测试: 每个服务的核心逻辑
- 集成测试: 服务间调用链
## 核心模块说明
### auth-service (:8081)
- Keycloak 适配器
- JWT 验证中间件
- API Key 验证 (SHA-256 哈希查 DB)
- 租户上下文提取 (JWT claim → tenant_id)
- RBAC: owner > admin > developer > user
### llm-router (:8091)
- 多平台 LLM 对接 (OpenAI 兼容格式)
- 7 个平台: DeepSeek, 千问, 豆包, 智谱, 元宝, 百度, Ollama
- 智能路由: 用户选择 / 成本优先 / 延迟优先
- 故障转移: 主模型不可用自动切换
- 流式响应: SSE 透传
- API Key 加密存储 (AES-256-GCM)
### billing (:8084)
- Credit 模型: 1 Credit = 1000 tokens
- 模型系数: deepseek-chat=1.0, deepseek-reasoner=2.0, doubao-pro=1.5
- Redis Lua 原子操作: 先扣后服 + 幂等 + 可审计
- 订阅套餐: Free/Pro/Team/Enterprise
- 每日对账: Redis ↔ PostgreSQL 一致性检查
### registry (:8082)
- 能力 CRUD (REST + gRPC 双协议)
- 能力类型: agent/mcp/skill/llm/custom
- 版本管理: SemVer
- 状态: draft → pending_review → active → deprecated
- 服务发现: 按类型/标签/状态查询
### metering (:8090)
- Kafka Consumer: 消费 usage.events
- PostgreSQL 持久化: token_usage 表 (按月分区)
- 预聚合: 每小时刷新 usage_summaries
- 用量查询: 按日/周/月/模型/能力统计
### skills (:8085)
- 技能发布/审核/交易
- 计费模式: per_call/per_token/subscription/free
- 分成: 平台 25% / 开发者 75%
- 全文搜索: PostgreSQL GIN 索引
### im-gateway (:8087)
- 多平台适配器: 微信(LangBot) / QQ(OneBot) / 钉钉
- 会话管理: Redis Hash, 24h 过期
- 上下文窗口: 最近 20 条消息
- 指令系统: /help /model /clear /balance
### openapi-gateway (:8083)
- OpenAI 兼容 API: POST /v1/chat/completions
- 请求拦截链: Auth → Balance → LLM → Billing → Response
- 流式 SSE 支持
- 用量异步上报 Kafka
## 计费原则（最重要）
1. **先扣后服**: 先扣减余额，再允许调用
2. **幂等**: 通过 idempotency_key 防重复扣费
3. **原子**: Redis Lua 脚本保证原子性
4. **可审计**: 每笔变动有 trace_id + 原因
5. **实时可见**: Dashboard 余额秒级更新
## LLM 对接
- 统一 OpenAI 兼容格式: POST /v1/chat/completions
- 百度需适配层 (非标准 API)
- 其他平台直接兼容
- 流式: SSE (text/event-stream)
## 部署
- 开发: docker-compose.yml (一键启动)
- 生产: Kubernetes + Helm Charts
- 监控: Prometheus + Grafana
- 日志: 结构化 JSON → Loki
## 重要约束
- 所有 API 必须有 OpenAPI 3.0 规范
- 所有数据库变更必须有 Migration
- 所有金额使用整数 (毫 Credit)
- 所有敏感数据加密 (AES-256)
- 所有关键操作有审计日志