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

docs: v2.0 全面修订 — 开源优先 + 扁平化用户模型

Browse Source 
核心变更:
- 产品定位: '像用水电一样使用AI能力，注册即用，按量付费'
- 用户模型: 去掉租户概念，扁平化为 订阅用户/非订阅用户
- 认证: Casdoor SSO + 阿里云实名认证（替代 Keycloak）
- LLM 网关: NEW API 开源（替代自研 Go 网关）
- AI 服务: FastAPI（替代 Go 自研，AI 生态更兼容）
- 新增: 欠费不影响已发布能力（核心商业规则）
- 新增: 开发者提现模块
- 开发周期: 20周 → 15周（开源组件复用）

文档列表:
- 01-PRD-产品需求文档.md (v2.0)
- 02-系统架构设计.md (v2.0)
- 03-数据库设计.md (v2.0)
- 04-API接口规范.md (v2.0)
- 05-AGENTS-MiMoCode配置.md (v2.0)
This commit is contained in:
qyyfw committed 2026-06-27 11:35:53 +00:00
1 parent d9a8a0e93c
commit 8209f15d0a
5 files changed
+1031 -1433
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/01-PRD-产品需求文档.md
+194 -405
View File
@@ -1,444 +1,233 @@
# AI PaaS 商业平台 — 产品需求文档（PRD）
# AI PaaS 商业平台 — 产品需求文档 (PRD)
> 版本: 1.0 | 日期: 2026-06-27
> 产品名: **AIPaaS**（AI能力服务平台）
> 目标用户: 个人开发者 / AI 爱好者 / 小型团队
> 版本: 2.0 | 日期: 2026-06-27
> 状态: 已修订（基于用户反馈）
---
## 1. 产品定位
## 1. 产品概述
**一句话描述**: 让任何开发者都能像用水电一样使用 AI 能力——注册即用，按量付费。
### 一句话描述
> **让任何 AI 使用者都能像用水电一样使用 AI 能力，注册即用，按量付费。**
**核心价值**:
- **统一入口**: Agent、MCP、Skills、IM Bot、LLM 调用，一个平台全搞定
- **按需付费**: 不买服务器，不养团队，按 Token 用量付费
- **能力交易**: 开发者发布 AI 技能，用户购买使用，平台促成交易
- **多平台接入**: 一个 API Key 调用 DeepSeek/千问/豆包/百度/元宝/智谱
### 产品定位
AI PaaS 商业平台是一个 **AI 能力的"水电煤"基础设施**。用户注册后即可使用平台提供的各种 AI 能力（LLM 对话、Agent 工作流、MCP 工具链、Skills 技能），所有能力按 Token/调用次数计费，用多少付多少。
### 核心价值主张
- **注册即用**: 无需自建模型、无需部署服务，注册账号即可调用 7+ 个 LLM 平台的能力
- **按量付费**: 用多少 Token 付多少钱，零浪费
- **能力市场**: 浏览、购买、使用其他开发者发布的 AI 技能
- **开放生态**: 开发者可以发布自己的 AI 能力/技能到市场，获得分成收入
### 目标用户
- **AI 使用者**: 个人开发者、独立开发者、技术爱好者 — 需要便捷的 AI 能力调用
- **AI 开发者**: 能力/技能的创作者 — 需要分发渠道和变现途径
**不区分企业和个人，不区分租户概念，只有一个用户角色。**
---
## 2. 用户角色
## 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 调用方式
### 2.1 扁平化用户体系（v2.0 核心调整）
```
POST /v1/chat/completions ← OpenAI 兼容格式，用户直接用
GET /v1/models ← 可用模型列表
POST /v1/embeddings ← 向量嵌入（Phase 2）
用户注册 → 实名认证 → 基础用户
用户订阅 → 订阅用户（自动获得能力创建/发布权限）
```
**原则：只有一个用户角色，无租户概念。**
### 2.2 用户状态机
```
注册 → 未认证（仅使用基础 LLM 调用）
→ 实名认证通过 → 认证用户
→ 订阅月费 → 订阅用户（解锁能力创建/发布）
→ 欠费 → 保留已发布能力，限制新创建
```
### 2.3 权限矩阵
| 功能 | 未认证用户 | 认证用户 | 订阅用户 | 欠费用户 |
|------|----------|---------|---------|---------|
| LLM 对话调用 | ✅ 基础额度 | ✅ 标准额度 | ✅ 扩展额度 | ✅ 基础额度 |
| 使用 Skills 技能 | ✅ | ✅ | ✅ | ✅ |
| 购买 Skills 技能 | ✅ | ✅ | ✅ | ✅ |
| 创建 AI 能力 | ❌ | ❌ | ✅ | ❌（新建） |
| 发布 AI 能力到市场 | ❌ | ❌ | ✅ | ❌（新建） |
| **已发布能力保持在线** | — | — | ✅ | **✅ 不受影响** |
| 获取分成收入 | ❌ | ❌ | ✅ | ✅（已有余额） |
> **核心规则：欠费后，已发布的 AI 应用保持在线不被下架。这是对开发者的承诺。**
---
### 3.3 计费系统（Billing）
## 3. 用户认证流程
#### 3.3.1 Credit 模型
### 3.1 注册与登录
| 概念 | 说明 |
|------|------|
| **Credit** | 内部统一计费单位，1 Credit = 1000 tokens |
| **模型系数** | 不同模型消耗不同: deepseek-chat=1.0, deepseek-reasoner=2.0, doubao-pro=1.5 |
| **余额** | 租户 Credit 余额，先扣后服 |
| **充值** | 支持手动充值（支付宝/微信支付） |
| **订阅** | 每月固定 Credit 额度，超出按量计费 |
#### 注册方式
1. **手机号 + 验证码**（主推）
2. **邮箱 + 密码**（备用）
3. **第三方登录**: 微信扫码（通过 Casdoor SSO 对接）
#### 3.3.2 订阅套餐
#### 登录方式
1. 手机号 + 验证码
2. 邮箱 + 密码
3. 微信扫码
4. API Key（程序化调用，无需登录态）
| 套餐 | 月费 | 包含 Credits | 超出价格 | QPS 限制 |
|------|------|-------------|---------|---------|
| **Free** | ¥0 | 100 | 不允许超出 | 2 |
| **Pro** | ¥99 | 50,000 | ¥0.01/Credit | 20 |
| **Team** | ¥499 | 300,000 | ¥0.008/Credit | 100 |
| **Enterprise** | 定制 | 定制 | 定制 | 定制 |
### 3.2 实名认证（阿里云接口）
#### 3.3.3 计费流程
用户需要完成实名认证才能发布能力。对接阿里云实名认证 API：
```
用户调用 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 服务 |
| L0 - 未认证 | 仅注册 | 基础 LLM 调用（每日限次） |
| L1 - 已实名 | 通过阿里云实名认证 | 标准 LLM 调用 + 使用/购买 Skills |
| L2 - 订阅用户 | L1 + 支付月费 | 创建/发布 AI 能力 + 获得分成 |
#### 3.4.2 能力生命周期
### 3.3 SSO 单点登录（Casdoor）
```
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
```
使用 Casdoor 开源项目作为统一认证中心：
- 支持 OAuth2 / OIDC / SAML
- 可对接微信、钉钉、飞书等社交登录
- 提供统一的用户管理和 Token 签发
- 可独立部署，也可嵌入现有系统
---
### 3.5 Skills 市场
## 4. 订阅与计费
#### 3.5.1 核心功能
### 4.1 订阅套餐
| 功能 | 说明 | 优先级 |
|------|------|--------|
| 发布技能 | 开发者上传技能，填写描述、定价、示例 | P0 |
| 浏览市场 | 按分类、标签、评分、热度浏览 | P0 |
| 搜索技能 | 全文搜索 + 分类过滤 | P0 |
| 购买技能 | 用 Credit 购买，立即可用 | P0 |
| 已购管理 | 查看已购技能列表 | P0 |
| 技能评分 | 用户评分和评论 | P1 |
| 技能试用 | 免费试用 N 次 | P1 |
| 套餐 | 月费 | 包含额度 | 能力创建 | 发布能力 | 分成比例 |
|------|------|---------|---------|---------|---------|
| 免费 | 0 | 每日 50 次 LLM 调用 | ❌ | ❌ | — |
| 开发者 | ¥29/月 | 每月 50 万 Token | ✅ 3 个 | ✅ | 70% |
| 专业版 | ¥99/月 | 每月 200 万 Token | ✅ 10 个 | ✅ | 75% |
| 旗舰版 | ¥299/月 | 每月 1000 万 Token | ✅ 无限制 | ✅ | 80% |
#### 3.5.2 计费模式
### 4.2 Token 包（按量加购）
| 模式 | 说明 | 分成 |
订阅额度用完后，可购买 Token 包：
- ¥10 = 10 万 Token
- ¥50 = 60 万 Token（送 10 万）
- ¥100 = 130 万 Token（送 30 万）
### 4.3 欠费处理
```
订阅到期 / 余额为 0
→ 进入「欠费保护期」（7 天）
→ 保护期内：已发布能力保持在线，但不能新建/修改
→ 保护期后：已发布能力转为「暂停」（数据保留，恢复订阅即可重新上线）
→ 续费后：已发布能力自动恢复
```
### 4.4 分成结算
- 平台抽成: 20%-30%（根据订阅等级）
- 开发者分成: 70%-80%
- 结算周期: 月结
- 最低提现: ¥100
- 提现方式: 支付宝 / 银行卡
---
## 5. 功能模块
### 5.1 LLM 对话能力
- 预置 7+ 个 LLM 平台接入（NEW API 统一管理）
- 支持 DeepSeek、千问、豆包、智谱、元宝、百度文心、Ollama 本地模型
- OpenAI 兼容 API 格式
- 流式/非流式响应
- 模型切换、参数调节
### 5.2 Skills 技能市场
- 浏览、搜索、购买 AI 技能
- 技能详情页（描述、价格、评分、使用量）
- 一键调用（平台内集成）
- 开发者发布技能（订阅用户权限）
- 技能审核流程
### 5.3 Agent 工作流
- 可视化 Agent 编排（基于开源方案）
- 预置常用 Agent 模板
- 支持自定义工具链
### 5.4 MCP 工具链
- MCP Server 注册与管理
- MCP 工具市场
- 工具组合调用
### 5.5 IM Bot
- 微信/QQ/钉钉/飞书 多平台对接
- 会话管理与上下文记忆
- 多模型切换
---
## 6. 非功能需求
### 6.1 性能
- LLM 首 token 延迟 < 500ms
- API 平均响应 < 200ms
- 并发支持 1000+ 用户
### 6.2 安全
- 用户密码 bcrypt 加密
- API Key SHA-256 哈希存储
- 实名信息 AES-256 加密存储
- HTTPS 全站加密
- RBAC 权限控制
### 6.3 可用性
- 系统可用性 > 99.9%
- 数据库主从备份
- 关键操作幂等
- 欠费不影响已发布能力
---
## 7. 开源选型原则（v2.0 新增）
### 7.1 选型优先级
```
1. 社区活跃度（GitHub Stars、Contributors、Release 频率）
2. AI 生态兼容性（能否无缝对接主流 AI 框架）
3. 技术先进性（语言、架构是否符合当前趋势）
4. 标准化程度（是否遵循行业标准/协议）
5. 功能完备性（是否开箱即用）
6. 许可证（是否允许商用）
```
### 7.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）: 集成上线
- ✅ 全链路测试
- ✅ 生产部署
- ✅ 监控告警
- ✅ 完整文档
| LLM 网关 | **NEW API** (songquanpeng/one-api) | 14k+ Stars，OpenAI 兼容，多模型管理，开箱即用 |
| SSO 认证 | **Casdoor** (casdoor/casdoor) | 10k+ Stars，OAuth2/OIDC，多社交登录，管理界面完善 |
| 实名认证 | **阿里云实名认证 API** | 国内最权威，接口稳定，成本低 |
| AI 服务框架 | **FastAPI** (tiangolo/fastapi) | 79k+ Stars，异步高性能，AI 生态标准框架 |
| 本地 LLM | **Ollama** (ollama/ollama) | 130k+ Stars，本地部署标准，模型生态丰富 |
| Agent 编排 | **LangFlow** (langflow-ai/langflow) | 可视化工作流，LangChain 生态 |
| MCP 管理 | **mcp-hub** | MCP 标准协议管理 |
---
docs/02-系统架构设计.md
+413 -391
View File
@@ -1,452 +1,474 @@
# AI PaaS 商业平台 — 系统架构设计
> 版本: 1.0 | 日期: 2026-06-27
> 基于: 5 平台交叉验证共识 + 方案二（稳扎稳打）
> 版本: 2.0 | 日期: 2026-06-27
> 状态: 已修订（基于用户反馈：开源优先 + AI 生态兼容）
---
## 1. 架构总览
## 1. 设计原则
### 1.1 分层架构图
### 1.1 核心原则（v2.0 强化）
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 用户入口层 (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 │ │ 事件总线 │ │ 认证 │ │ 监控 ││
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────────┘│
└─────────────────────────────────────────────────────────────────────────┘
1. 开源优先: 能用开源就不自研，社区活跃 > 自己造轮子
2. AI 生态兼容: 所有选型必须兼容当前 AI 生态标准（OpenAI 格式、MCP 协议等）
3. 标准化: 遵循行业标准协议，确保未来可扩展
4. 扁平化: 不搞多租户复杂度，一个用户体系走天下
5. 渐进式: 先跑通核心链路，再逐步丰富功能
```
### 1.2 技术选型决策矩阵
| 组件 | 选项 A | 选项 B | 决策 | 理由 |
|------|--------|--------|------|------|
| **LLM 网关** | 自研 Go | NEW API 开源 | **NEW API** | 14k Stars，开箱即用，省 6 周开发 |
| **SSO 认证** | Keycloak | Casdoor | **Casdoor** | 国内生态更好，微信/钉钉对接完善 |
| **实名认证** | 自建 OCR | 阿里云 API | **阿里云** | 国内最权威，接口稳定 |
| **AI 服务框架** | Go 自研 | FastAPI | **FastAPI** | AI 生态标准，79k Stars，异步高性能 |
| **本地 LLM** | 自建 | Ollama | **Ollama** | 130k Stars，本地部署事实标准 |
| **API 网关** | 自研 | APISIX | **APISIX** | 高性能，插件丰富，国内团队 |
| **数据库** | MySQL | PostgreSQL | **PostgreSQL** | JSONB + RLS，功能更强 |
| **缓存** | Memcached | Redis | **Redis** | Lua 脚本支持，原子计费必备 |
| **消息队列** | RabbitMQ | Kafka | **Kafka** | 用量数据天然适合日志型存储 |
---
## 2. 整体架构
```
┌──────────────────────────────────────────────────────────────────────┐
│ 用户入口层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Web App │ │ CLI Tool │ │ REST API │ │ IM Bot │ │ MCP Hub │ │
│ │ (React) │ │ │ │ │ │(微信/QQ) │ │ │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ └────────────┴────────────┴────────────┴────────────┘ │
└────────────────────────────────┬─────────────────────────────────────┘
│
┌────────────────────────────────▼─────────────────────────────────────┐
│ API 网关层 (APISIX) │
│ 认证鉴权 → 限流 → 路由 → 日志 → 监控 │
└────────────────────────────────┬─────────────────────────────────────┘
│
┌────────────────────────────────▼─────────────────────────────────────┐
│ 核心服务层 │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Casdoor (SSO 认证中心) │ │
│ │ 注册/登录 → JWT 签发 → 用户管理 → 第三方登录(微信/钉钉) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ FastAPI AI 中间件层 │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ 计费引擎 │ │ 能力注册 │ │ Skills │ │ 用量追踪 │ │ │
│ │ │ (Redis │ │ 中心 │ │ 市场 │ │ (Kafka) │ │ │
│ │ │ Lua) │ │ │ │ │ │ │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ NEW API (LLM 网关) │ │
│ │ 多模型管理 → 负载均衡 → 故障转移 → 流式透传 → 用量统计 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────┬─────────────────────────────────────┘
│
┌────────────────────────────────▼─────────────────────────────────────┐
│ AI 能力层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ DeepSeek │ │ 千问 │ │ 豆包 │ │ 智谱 │ │ Ollama │ │
│ │ (API) │ │ (API) │ │ (API) │ │ (API) │ │ (本地) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────────────────────────────────────────────────────┘
```
---
## 2. 核心数据流
## 3. 核心服务拆分
### 2.1 LLM 调用 + 计费完整流程
### 3.1 服务列表（v2.0 简化）
```
用户代码 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│ │ │
│ }} │ │ │
│←──────────────────────────│←───────────────────│ │
│ │ │ │
| 服务 | 技术 | 端口 | 职责 | 开源/自研 |
|------|------|------|------|----------|
| **Casdoor** | Go | 8000 | SSO 认证中心 | 开源 |
| **NEW API** | Go | 3000 | LLM 网关 | 开源 |
| **ai-paas-gateway** | FastAPI | 8080 | 核心业务网关 | **自研** |
| **ai-paas-billing** | FastAPI | 8081 | 计费引擎 | **自研** |
| **ai-paas-registry** | FastAPI | 8082 | 能力注册中心 | **自研** |
| **ai-paas-skills** | FastAPI | 8083 | Skills 市场 | **自研** |
| **ai-paas-metering** | FastAPI | 8084 | 用量追踪 | **自研** |
| **ai-paas-admin** | FastAPI | 8085 | 管理后台 API | **自研** |
| **APISIX** | Lua/C | 9080 | API 网关 | 开源 |
| **Ollama** | Go | 11434 | 本地 LLM 推理 | 开源 |
| **LangFlow** | Python | 7860 | Agent 编排 | 开源 |
> **v2.0 变化**: 原 9 个自研 Go 服务 → 简化为 6 个 FastAPI 服务 + 3 个开源组件。
---
## 4. 自研服务详细设计
### 4.1 ai-paas-gateway（核心业务网关）— FastAPI
这是整个平台的**核心调度中心**，所有业务请求经过这里。
```python
# 技术选型: FastAPI (Python 3.11+)
# 为什么 FastAPI:
# 1. AI 生态标准框架，LangChain/LlamaIndex 原生支持
# 2. 异步高性能，自带 OpenAPI 文档
# 3. 类型安全 (Pydantic)，开发效率高
# 4. 社区极其活跃 (79k Stars)
# 5. 部署简单 (uvicorn + Docker)
# 核心路由:
POST /v1/chat/completions → 转发到 NEW API，前置计费/鉴权
GET /v1/models → 转发到 NEW API
GET /api/v1/user/profile → 用户信息
POST /api/v1/auth/* → 转发到 Casdoor
GET /api/v1/billing/* → 计费查询
GET /api/v1/capabilities/* → 能力注册
GET /api/v1/skills/* → Skills 市场
```
### 2.2 流式 SSE 响应流程
**请求处理链路（LLM 调用）:**
```
用户浏览器 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. 上报用量 │
用户请求 → APISIX → ai-paas-gateway
1. JWT/API Key 验证 (调用 Casdoor)
2. 用户状态检查 (订阅/欠费)
3. Credit 余额检查 (Redis)
4. 扣减 Credit (Redis Lua 原子操作)
5. 转发到 NEW API
6. 返回响应 (流式 SSE 透传)
7. 异步上报用量 (Kafka)
```
### 4.2 ai-paas-billing（计费引擎）— FastAPI
```python
# Redis Lua 原子脚本 (先扣后服)
"""
-- deduct_credit.lua
local balance = tonumber(redis.call('GET', KEYS[1]) or '0')
local amount = tonumber(ARGV[1])
local idempotency_key = ARGV[2]
-- 幂等检查
if redis.call('EXISTS', 'billing:idempotency:' .. idempotency_key) == 1 then
return redis.call('GET', 'billing:idempotency:' .. idempotency_key)
end
if balance < amount then
return 'INSUFFICIENT_BALANCE'
end
local new_balance = balance - amount
redis.call('SET', KEYS[1], new_balance)
redis.call('SETEX', 'billing:idempotency:' .. idempotency_key, 86400, 'OK')
return 'OK:' .. new_balance
"""
```
### 4.3 ai-paas-registry（能力注册中心）— FastAPI
```python
# 能力 CRUD + 版本管理
# 支持: agent/mcp/skill/llm/custom 五种类型
# 状态机: draft → pending_review → active → deprecated
# 能力发现: 按类型/标签/评分/使用量查询
# 能力验证: 注册时自动健康检查
# 能力版本: SemVer 版本管理
```
### 4.4 ai-paas-skills（Skills 市场）— FastAPI
```python
# 全文搜索: PostgreSQL GIN 索引
# 技能交易: 扣费 → 分成 → 授权
# 评分系统: 1-5 星 + 文字评价
# 开发者后台: 发布/管理/收益统计
```
### 4.5 ai-paas-metering（用量追踪）— FastAPI
```python
# Kafka Consumer: 消费 usage.events
# PostgreSQL 持久化: token_usage 表 (按月分区)
# 预聚合: 每小时刷新 usage_summaries
# 用量查询: 按日/周/月/模型/能力统计
# 账单生成: 月度账单自动计算
```
### 4.6 ai-paas-admin（管理后台）— FastAPI
```python
# 用户管理: 列表/详情/状态变更
# 能力审核: 审批/拒绝
# 财务管理: 流水/提现/对账
# 系统监控: 健康检查/配置管理
```
---
## 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 概览
## 5. 数据流向
### 5.1 LLM 调用主流程
```
┌─────────────────────────────────────────────────────────┐
│ 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 │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
用户 → Web/CLI/API
→ APISIX (限流/路由)
→ ai-paas-gateway (鉴权/计费/转发)
→ NEW API (模型路由)
→ DeepSeek/千问/豆包... (实际推理)
→ 响应流式返回用户
→ 异步: 用量事件 → Kafka → ai-paas-metering → PostgreSQL
```
### 4.2 RLS 策略
### 5.2 能力发布流程
```
开发者 → Web Dashboard
→ ai-paas-registry (创建能力)
→ 管理员审核
→ ai-paas-skills (上架市场)
→ 用户浏览/购买
→ ai-paas-billing (扣费/分成)
```
```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.3 认证流程
```
用户 → Web App
→ Casdoor (注册/登录)
→ 阿里云实名认证 API (身份验证)
→ ai-paas-gateway (更新用户状态)
→ JWT Token 签发
```
---
## 5. 安全架构
## 6. 开源组件集成方案
### 5.1 认证流程
### 6.1 Casdoor (SSO 认证中心)
```
┌──────────────┐
│ Keycloak │
│ (认证中心) │
└──────┬───────┘
│
┌────────────────┼────────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ 用户登录 │ │ API Key │ │ 服务间 │
│ JWT 签发 │ │ Hash验证 │ │ Client │
│ │ │ │ │ Credentials│
└──────────┘ └──────────┘ └──────────┘
JWT Payload:
{
"sub": "user-uuid",
"tenant_id": "tenant-uuid",
"role": "developer",
"exp": 1719552000,
"iat": 1719548400
}
部署方式: Docker Compose
对接方式: OAuth2 / OIDC
功能:
- 用户注册/登录 (手机号/邮箱/微信)
- JWT Token 签发与验证
- 第三方登录 (微信/钉钉/飞书)
- 用户管理界面
- RBAC 权限管理
集成点:
- ai-paas-gateway 调用 Casdoor API 验证 Token
- NEW API 配置 Casdoor 作为认证后端
```
### 5.2 API Key 安全
### 6.2 NEW API (LLM 网关)
```
用户创建 Key:
明文 Key: aip_xxxxxxxxxxxxxxxxxxxxxxxx (仅展示一次)
存储: SHA-256(aip_xxx) → db
用户调用:
Header: Authorization: Bearer aip_xxxxxxxxxxxxxxxxxxxxxxxx
验证: SHA-256(bearer_token) → 查 DB 匹配
部署方式: Docker Compose
对接方式: OpenAI 兼容 API
功能:
- 多模型统一管理 (DeepSeek/千问/豆包/智谱/元宝/百度)
- 负载均衡与故障转移
- 流式 SSE 透传
- 用量统计与配额管理
- 渠道管理 (API Key 池)
集成点:
- ai-paas-gateway 作为唯一上游调用 NEW API
- NEW API 配置各 LLM 平台的 API Key
- NEW API 的用量数据同步到 ai-paas-metering
```
### 5.3 敏感数据加密
### 6.3 Ollama (本地 LLM)
| 数据 | 加密方式 | 说明 |
|------|---------|------|
| API Key 明文 | 不存储 | 仅展示一次 |
| API Key 哈希 | SHA-256 | 用于验证 |
| LLM API Key | AES-256-GCM | 存储在 DB |
| 用户密码 | bcrypt | Keycloak 管理 |
| Credit 余额 | 明文（整数） | 需要原子操作 |
```
部署方式: Docker + GPU 直通
支持模型: Qwen2.5, Llama3, Mistral, Phi3 等
功能:
- 本地模型推理 (离线可用)
- 模型拉取/管理
- OpenAI 兼容 API
集成点:
- NEW API 添加 Ollama 作为渠道
- 提供「本地模型」标签，免费/低价使用
```
### 6.4 LangFlow (Agent 编排)
```
部署方式: Docker Compose
功能:
- 可视化 Agent 工作流编排
- 预置 Agent 模板
- 自定义工具链
集成点:
- ai-paas-registry 注册 LangFlow 工作流为 Agent 能力
- 调用链: 用户 → gateway → LangFlow → LLM
```
### 6.5 APISIX (API 网关)
```
部署方式: Docker Compose
功能:
- 请求路由与负载均衡
- 限流限速 (多维度)
- 认证鉴权 (JWT/API Key)
- 日志采集与监控
- 插件扩展
集成点:
- 所有外部请求入口
- 路由规则: /v1/chat/* → gateway, /api/* → gateway
- 鉴权插件对接 Casdoor
```
---
## 6. 部署架构
## 7. 数据库架构
### 6.1 开发环境 (Docker Compose)
### 7.1 数据存储选型
| 存储 | 用途 | 选型理由 |
|------|------|---------|
| PostgreSQL 16 | 主数据库 | JSONB + RLS + 全文搜索 |
| Redis 7 | 缓存/计费/会话 | Lua 原子操作 |
| Kafka 3.x | 用量事件流 | 高吞吐日志型存储 |
### 7.2 核心数据表（扁平化设计，无租户概念）
| 表名 | 用途 | 关键字段 |
|------|------|---------|
| users | 用户 | id, phone, email, name, role, verified, subscribed |
| api_keys | API 密钥 | id, user_id, key_hash, scopes |
| subscriptions | 订阅 | id, user_id, plan, credits_included, credits_used |
| credit_transactions | Credit 流水 | id, user_id, type, amount, balance_after |
| token_usage | Token 用量 | id, user_id, model, tokens, cost |
| capabilities | AI 能力 | id, user_id, name, type, status |
| skills | 技能市场 | id, developer_id, name, pricing, rating |
| skill_purchases | 技能购买 | id, user_id, skill_id, amount |
> **注意**: v2.0 去掉了 `tenants` 表和所有 `tenant_id` 字段，所有表直接挂在 `user_id` 下。
---
## 8. 部署架构
### 8.1 开发环境 (docker-compose.yml)
```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
postgres:
image: postgres:16
redis:
image: redis:7-alpine
kafka:
image: confluentinc/cp-kafka:7.6.0
# 开源组件
casdoor:
image: casbin/casdoor:latest
new-api:
image: justsong/one-api:latest
ollama:
image: ollama/ollama:latest
apisix:
image: apache/apisix:3.15.0
# 自研服务 (FastAPI)
ai-paas-gateway:
build: ./services/gateway
ai-paas-billing:
build: ./services/billing
ai-paas-registry:
build: ./services/registry
ai-paas-skills:
build: ./services/skills
ai-paas-metering:
build: ./services/metering
ai-paas-admin:
build: ./services/admin
# 前端
web: # :3000 (React Dev Server)
admin: # :3001 (React Dev Server)
# 开源 AI 服务
langflow: # :7860
mcp-hub: # :3001
milvus: # :19530
# 监控
prometheus: # :9090
grafana: # :3002
web:
build: ./packages/web
```
### 6.2 生产环境 (Kubernetes)
### 8.2 生产环境
```
┌─────────────────────────────────────────────────┐
│ 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 │ │
│ └────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
Kubernetes + Helm Charts
├── 基础设施: PostgreSQL HA / Redis Sentinel / Kafka Cluster
├── 开源组件: Casdoor / NEW API / Ollama (GPU Node) / APISIX
├── 自研服务: FastAPI × N replicas (HPA 自动伸缩)
├── 监控: Prometheus + Grafana
└── 日志: Loki + Promtail
```
---
## 7. 技术栈汇总
## 9. 安全架构
| 层级 | 技术 | 版本 | 许可证 | 用途 |
|------|------|------|--------|------|
| **前端** | 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 编程 |
### 9.1 认证链路
```
外部请求 → APISIX
→ JWT 验证 (Casdoor 签发)
→ API Key 验证 (查 PostgreSQL)
→ 用户状态检查
```
### 9.2 数据安全
- 实名信息: AES-256 加密存储
- API Key: SHA-256 哈希存储
- 密码: bcrypt 加密
- 通信: HTTPS 全站加密
### 9.3 接口安全
- 限流: IP + 用户 + 接口多维度
- 防重放: 请求签名 + 时间戳
- 输入校验: Pydantic 强类型校验
---
## 10. 开发路线图（v2.0 调整）
### Phase 1（第 1-3 周）: 基座搭建
- 部署 Casdoor + NEW API + APISIX + PostgreSQL + Redis
- 开发 ai-paas-gateway 核心路由
- 实现 JWT 认证 + API Key 管理
- 实现基础 LLM 调用链路 (gateway → NEW API → LLM)
- **里程碑**: 用户注册 → 登录 → 调用 LLM 对话
### Phase 2（第 4-6 周）: 计费引擎
- 开发 ai-paas-billing
- Redis Lua 原子扣费
- 订阅管理 (套餐/充值/欠费)
- 用量追踪 (Kafka → metering)
- **里程碑**: 用户充值 → 调用扣费 → 账单可查
### Phase 3（第 7-9 周）: 能力市场
- 开发 ai-paas-registry (能力 CRUD)
- 开发 ai-paas-skills (技能交易)
- 阿里云实名认证对接
- 能力审核流程
- **里程碑**: 开发者发布能力 → 用户购买使用
### Phase 4（第 10-12 周）: 生态扩展
- Ollama 本地模型集成
- IM Bot 多平台对接
- MCP 工具链集成
- LangFlow Agent 编排
- **里程碑**: 全生态打通
### Phase 5（第 13-15 周）: 上线准备
- 全链路测试
- 性能压测
- 监控告警
- 文档完善
- **里程碑**: 正式上线
> **v2.0 变化**: 原 20 周 → 缩短为 15 周，得益于开源组件的复用。
---
docs/03-数据库设计.md
+119 -243
View File
@@ -1,6 +1,7 @@
# AI PaaS 商业平台 — 数据库设计
> 版本: 1.0 | 日期: 2026-06-27
> 版本: 2.0 | 日期: 2026-06-27
> 状态: 已修订（扁平化：去掉租户，直接挂在用户下）
> 数据库: PostgreSQL 16+ | 缓存: Redis 7+
---
@@ -8,239 +9,181 @@
## 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
users ──1:1──→ subscriptions
users ──1:N──→ credit_transactions
users ──1:N──→ token_usage
users ──1:N──→ capabilities (开发者发布)
users ──1:N──→ skills (开发者发布)
users ──1:N──→ skill_purchases (用户购买)
skills ──1:N──→ skill_purchases
im_sessions ──1:N──→ im_messages
capabilities ──1:N──→ capability_versions
```
---
## 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（用户）
### 2.1 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),
phone VARCHAR(20) UNIQUE, -- 手机号（主登录方式）
email VARCHAR(255) UNIQUE, -- 邮箱（备用登录）
password_hash VARCHAR(255), -- 密码哈希（邮箱登录时）
name VARCHAR(255) NOT NULL, -- 显示名称
real_name VARCHAR(100), -- 真实姓名（实名认证后）
id_card_hash VARCHAR(64), -- 身份证号哈希（实名认证后）
avatar_url VARCHAR(500), -- 头像
role VARCHAR(20) NOT NULL DEFAULT 'user', -- user/admin
verified BOOLEAN DEFAULT FALSE, -- 是否完成实名认证
subscribed BOOLEAN DEFAULT FALSE, -- 是否为订阅用户
status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/suspended/deleted
casdoor_id VARCHAR(255), -- Casdoor 关联 ID
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)
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE INDEX idx_users_tenant ON users(tenant_id);
CREATE INDEX idx_users_phone ON users(phone);
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);
CREATE INDEX idx_users_status ON users(status);
CREATE INDEX idx_users_verified ON users(verified);
CREATE INDEX idx_users_subscribed ON users(subscribed);
CREATE INDEX idx_users_casdoor ON users(casdoor_id);
```
### 2.3 api_keys（API 密钥）
### 2.2 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
expires_at TIMESTAMP WITH TIME ZONE,
status VARCHAR(20) NOT NULL DEFAULT 'active',
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);
CREATE INDEX idx_api_keys_hash ON api_keys(key_hash);
```
### 2.4 subscriptions（订阅）
### 2.3 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, -- 本月已用
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
plan VARCHAR(20) NOT NULL DEFAULT 'free', -- free/developer/pro/flagship
credits_included BIGINT NOT NULL DEFAULT 0, -- 月包含 Token 数
credits_used BIGINT NOT NULL DEFAULT 0, -- 本月已用 Token
price_cents INTEGER NOT NULL DEFAULT 0, -- 月费 (分)
billing_cycle VARCHAR(10) NOT NULL DEFAULT 'monthly', -- monthly/yearly
billing_cycle VARCHAR(10) NOT NULL DEFAULT 'monthly',
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
status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/cancelled/expired/grace
grace_end TIMESTAMP WITH TIME ZONE, -- 欠费保护期截止
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
UNIQUE(user_id)
);
CREATE INDEX idx_subscriptions_tenant ON subscriptions(tenant_id);
CREATE INDEX idx_subscriptions_user ON subscriptions(user_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 流水 — 不可变）
### 2.4 credit_transactions（Credit 流水 — 不可变）
```sql
CREATE TABLE credit_transactions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
user_id UUID NOT NULL REFERENCES users(id),
type VARCHAR(30) NOT NULL, -- usage/topup/subscription/bonus/refund
amount BIGINT NOT NULL, -- 变动量 (毫 Credit)，正=加，负=减
amount BIGINT NOT NULL, -- 变动量 (分)，正=加，负=减
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
description TEXT,
trace_id VARCHAR(64),
idempotency_key VARCHAR(64) UNIQUE,
reference_type VARCHAR(30), -- llm_call/skill_purchase/topup
reference_id UUID,
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_user ON credit_transactions(user_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 用量 — 按月分区）
### 2.5 token_usage（Token 用量 — 按月分区）
```sql
-- 主表 (自动分区)
CREATE TABLE token_usage (
id UUID NOT NULL DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL,
user_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
model VARCHAR(100) NOT NULL,
provider VARCHAR(50) NOT NULL,
prompt_tokens INTEGER NOT NULL,
completion_tokens INTEGER NOT NULL,
total_tokens INTEGER NOT NULL,
cost_credits BIGINT NOT NULL, -- 消耗 Credit (毫)
cost_cents BIGINT NOT NULL, -- 消耗费用 (分)
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_user ON token_usage(user_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（能力）
### 2.6 capabilities（AI 能力）
```sql
CREATE TABLE capabilities (
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,
type VARCHAR(30) NOT NULL, -- agent/mcp/skill/llm/custom
version VARCHAR(50) NOT NULL, -- SemVer
version VARCHAR(50) NOT NULL,
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, -- 调用次数
endpoint VARCHAR(500),
protocol VARCHAR(20) DEFAULT 'rest',
pricing_config JSONB DEFAULT '{}',
dependencies JSONB DEFAULT '[]',
status VARCHAR(20) NOT NULL DEFAULT 'draft',
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)
UNIQUE(user_id, name, version)
);
CREATE INDEX idx_capabilities_tenant ON capabilities(tenant_id);
CREATE INDEX idx_capabilities_user ON capabilities(user_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（能力版本）
### 2.7 capability_versions（能力版本）
```sql
CREATE TABLE capability_versions (
@@ -249,175 +192,108 @@ CREATE TABLE capability_versions (
version VARCHAR(50) NOT NULL,
endpoint VARCHAR(500),
changelog TEXT,
status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/deprecated
status VARCHAR(20) NOT NULL DEFAULT 'active',
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（技能）
### 2.8 skills（技能市场）
```sql
CREATE TABLE skills (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
developer_id UUID NOT NULL REFERENCES users(id),
name VARCHAR(255) NOT NULL,
description TEXT,
category VARCHAR(50), -- 分类
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)
pricing_model VARCHAR(20) NOT NULL DEFAULT 'per_call',
price_credits BIGINT NOT NULL DEFAULT 0,
platform_share NUMERIC(3,2) DEFAULT 0.25, -- 平台分成比例
developer_share NUMERIC(3,2) DEFAULT 0.75, -- 开发者分成比例
endpoint VARCHAR(500), -- API 地址
documentation TEXT, -- 使用文档
endpoint VARCHAR(500),
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, -- 购买次数
status VARCHAR(20) NOT NULL DEFAULT 'draft',
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_developer ON skills(developer_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);
CREATE INDEX idx_skills_name_search ON skills USING GIN(
to_tsvector('simple', name || ' ' || COALESCE(description, ''))
);
```
### 2.10 skill_purchases（技能购买）
### 2.9 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
developer_id UUID NOT NULL,
amount_cents BIGINT NOT NULL,
platform_share BIGINT NOT NULL,
developer_share BIGINT NOT NULL,
status VARCHAR(20) NOT NULL DEFAULT 'active',
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 会话）
### 2.10 developer_payouts（开发者提现）
```sql
CREATE TABLE im_sessions (
CREATE TABLE developer_payouts (
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,
developer_id UUID NOT NULL REFERENCES users(id),
amount_cents BIGINT NOT NULL,
method VARCHAR(20) NOT NULL, -- alipay/bank
account_info JSONB NOT NULL, -- 加密的收款信息
status VARCHAR(20) NOT NULL DEFAULT 'pending', -- pending/paid/rejected
paid_at TIMESTAMP WITH TIME ZONE,
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: 永不过期
# Credit 余额 (分)
billing:balance:{user_id} → "125800"
# 幂等键
billing:idempotency:{tenant_id}:{idempotency_key} → {
"result": "success",
"amount": -1280,
"trace_id": "abc-123"
}
# 类型: Hash
# TTL: 24 小时
billing:idempotency:{user_id}:{key} → "OK"
# TTL: 24h
# 每日统计
billing:daily:{tenant_id}:{YYYY-MM-DD} → {
"calls": "342",
"tokens": "456000",
"credits": "1280000"
}
# 类型: Hash
# TTL: 7 天
billing:daily:{user_id}:{YYYY-MM-DD} → { calls, tokens, cost }
# TTL: 7d
# 订阅信息
billing:subscription:{tenant_id} → {
"plan": "pro",
"credits_included": "50000000",
"credits_used": "12800000",
"period_end": "2026-07-27T00:00:00Z"
}
# 类型: Hash
# 订阅信息缓存
billing:subscription:{user_id} → { plan, credits_included, credits_used, period_end }
# TTL: 永不过期
```
### 3.2 限流相关
# 限流
ratelimit:{user_id}:{window} → count
# TTL: 窗口大小
```
# 滑动窗口限流
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 小时
# IM 会话上下文
im:session:{platform}:{user_id} → { messages: [...] }
# TTL: 24h
```
---
@@ -426,7 +302,7 @@ im:session:{platform}:{user_id} → {
```
migrations/
├── 001_init.sql # 所有表 + RLS + 索引
├── 001_init.sql # 所有表
├── 002_seed_data.sql # 开发环境种子数据
├── 003_add_partitions.sql # token_usage 分区
└── 004_add_fulltext.sql # 全文搜索索引
@@ -436,7 +312,7 @@ migrations/
- Migration 文件名: `{序号}_{描述}.sql`
- 不允许修改已执行的 Migration
- 每个 Migration 必须可回滚
- 生产环境 Migration 必须在低峰期执行
- 不可变表 (credit_transactions, token_usage): 无 UPDATE/DELETE
---
docs/04-API接口规范.md
+199 -261
View File
@@ -1,6 +1,7 @@
# AI PaaS 商业平台 — API 接口规范
> 版本: 1.0 | 日期: 2026-06-27
> 版本: 2.0 | 日期: 2026-06-27
> 状态: 已修订（扁平化用户模型 + Casdoor/NEW API 集成）
> 规范: OpenAPI 3.0 | Base URL: https://api.aipaas.com
---
@@ -11,93 +12,80 @@
| 方式 | Header | 说明 |
|------|--------|------|
| JWT | `Authorization: Bearer {access_token}` | Web 前端登录后使用 |
| JWT | `Authorization: Bearer {access_token}` | Casdoor 签发，Web 前端使用 |
| API Key | `Authorization: Bearer aip_{key}` | 程序化调用 |
### 1.2 响应格式
```json
// 成功
{
"code": 0,
"message": "success",
"data": { ... }
}
{ "code": 0, "message": "success", "data": { ... } }
// 分页
{
"code": 0,
"message": "success",
"data": {
"items": [...],
"total": 100,
"page": 1,
"page_size": 20
}
}
{ "code": 0, "message": "success", "data": { "items": [...], "total": 100, "page": 1, "page_size": 20 } }
// 错误
{
"code": 40001,
"message": "Insufficient balance",
"data": null
}
{ "code": 40001, "message": "Insufficient balance", "data": null }
```
### 1.3 错误码
| 错误码 | HTTP Status | 说明 |
|--------|------------|------|
| 错误码 | HTTP | 说明 |
|--------|------|------|
| 0 | 200 | 成功 |
| 40001 | 400 | 请求参数错误 |
| 40001 | 400 | 参数错误 |
| 40101 | 401 | 未认证 |
| 40102 | 401 | API Key 无效 |
| 40301 | 403 | 权限不足 |
| 40301 | 403 | 权限不足（需订阅） |
| 40401 | 404 | 资源不存在 |
| 40201 | 402 | Credit 余额不足 |
| 42901 | 429 | 请求频率超限 |
| 50001 | 500 | 服务内部错误 |
| 50201 | 502 | 上游服务不可用 |
| 40201 | 402 | 余额不足 |
| 40302 | 403 | 未实名认证 |
| 42901 | 429 | 频率超限 |
---
## 2. Auth 接口
## 2. 认证接口（Casdoor 代理）
### POST /api/v1/auth/register
```yaml
description: 用户注册
description: 注册（手机号 + 验证码）
request:
body:
email: string (required)
password: string (required, min 8)
name: string (required)
phone: string (required)
code: string (required, 6位验证码)
name: string (optional, 默认 "用户_{phone后4位}")
response:
200:
data:
user_id: uuid
email: string
tenant_id: uuid
access_token: string (JWT, 由 Casdoor 签发)
refresh_token: string
```
### POST /api/v1/auth/login
```yaml
description: 用户登录
description: 登录（手机号 + 验证码）
request:
body:
phone: string (required)
code: string (required)
response:
200:
data:
access_token: string
refresh_token: string
expires_in: integer
user: { id, name, phone, verified, subscribed }
```
### POST /api/v1/auth/login/email
```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
response: 同上
```
### POST /api/v1/auth/refresh
@@ -122,18 +110,47 @@ response:
data:
id: uuid
name: string
phone: string (脱敏)
email: string
role: string
tenant_id: uuid
tenant:
name: string
verified: boolean # 是否实名认证
subscribed: boolean # 是否订阅用户
subscription: # 订阅详情（如有）
plan: string
credit_balance: integer
credits_included: integer
credits_used: integer
period_end: datetime
grace_end: datetime # 欠费保护期
```
---
## 3. API Key 接口
## 3. 实名认证接口
### POST /api/v1/auth/verify
```yaml
description: 实名认证（调用阿里云实名认证 API）
auth: JWT
request:
body:
real_name: string (required) # 真实姓名
id_card: string (required) # 身份证号
response:
200:
data:
verified: true
message: "实名认证成功"
400:
code: 40001
message: "身份证号格式错误"
400:
code: 40303
message: "实名认证失败，姓名与身份证号不匹配"
```
---
## 4. API Key 管理
### POST /api/v1/apikeys
```yaml
@@ -141,14 +158,14 @@ description: 创建 API Key
auth: JWT
request:
body:
name: string (required) # 用途标识
name: string (required)
response:
200:
data:
id: uuid
name: string
key: string # 仅此一次展示明文
key_prefix: string # aip_xxxx
key: string # 仅此一次展示明文 aip_xxxxxxxxxxxx
key_prefix: string
created_at: datetime
```
@@ -160,180 +177,147 @@ response:
200:
data:
items:
- id: uuid
name: string
key_prefix: string
last_used_at: datetime
status: string
created_at: datetime
- id, name, key_prefix, last_used_at, status, created_at
```
### DELETE /api/v1/apikeys/{id}
```yaml
description: 删除 API Key
auth: JWT
response:
200: { code: 0, message: "success" }
```
---
## 4. LLM 调用接口（OpenAI 兼容）
## 5. LLM 调用接口（OpenAI 兼容，通过 NEW API）
### POST /v1/chat/completions
```yaml
description: Chat Completion (OpenAI 兼容格式)
auth: API Key 或 JWT
description: Chat Completion（OpenAI 兼容格式，代理到 NEW API）
auth: JWT 或 API Key
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)
model: string (required)
messages: [{ role, content }]
temperature: number (0-2, default 1)
max_tokens: integer
stream: boolean (default false)
top_p: number
response:
200:
# 非流式
id: string
object: "chat.completion"
model: string
choices:
- index: 0
message:
role: "assistant"
content: string
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]
# 流式: SSE (text/event-stream)
```
### GET /v1/models
```yaml
description: 可用模型列表
auth: API Key 或 JWT
description: 可用模型列表（从 NEW API 获取）
auth: JWT 或 API Key
response:
200:
data:
- id: "deepseek-chat"
object: "model"
provider: "deepseek"
pricing:
credits_per_1k: 1.0
pricing: { credits_per_1k: 1.0 }
- id: "qwen-turbo"
object: "model"
provider: "qianwen"
pricing:
credits_per_1k: 0.8
pricing: { credits_per_1k: 0.8 }
- id: "ollama-qwen2.5"
provider: "ollama"
pricing: { credits_per_1k: 0.1 }
```
---
## 5. Billing 接口
## 6. 计费与订阅
### GET /api/v1/billing/balance
```yaml
description: 查询 Credit 余额
description: 查询余额
auth: JWT
response:
200:
data:
balance: integer # 当前余额 (毫 Credit)
balance_display: number # 显示余额 (Credit)
balance: integer # 当前余额 (分)
balance_display: string # "¥125.80"
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
plan: string (required) # developer/pro/flagship
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
payment_url: string # 支付链接
```
### POST /api/v1/billing/topup
```yaml
description: 充值 Token 包
auth: JWT
request:
body:
package: string (required) # 10/50/100
payment_method: string # alipay/wechat
response:
200:
data:
order_id: string
payment_url: string
```
### GET /api/v1/billing/transactions
```yaml
description: 流水查询
auth: JWT
request:
query:
page, page_size, type, start_date, end_date
response:
200:
data:
items: [{ id, type, amount, balance_after, description, trace_id, created_at }]
total, page, page_size
```
---
## 6. Capability Registry 接口
## 7. 能力注册
### POST /api/v1/capabilities
```yaml
description: 注册新能力
description: 创建能力（需订阅用户）
auth: JWT
precondition: subscribed == true
request:
body:
name: string (required)
type: string (required) # agent/mcp/skill/llm/custom
version: string (required) # SemVer
type: string (required) # agent/mcp/skill/llm/custom
version: string (required)
description: string
tags: array[string]
endpoint: string
protocol: string # rest/grpc/websocket
pricing_config: object
response:
200:
data:
@@ -344,65 +328,31 @@ response:
### GET /api/v1/capabilities
```yaml
description: 能力列表
auth: JWT 或 API Key
auth: 公开
request:
query:
type: string (optional)
status: string (optional)
tags: string (optional) # 逗号分隔
page: integer
page_size: integer
type, status, tags, page, page_size
response:
200:
data:
items:
- id: uuid
name: string
type: string
version: string
status: string
tags: array[string]
invoke_count: integer
created_at: datetime
items: [{ id, name, type, version, status, tags, invoke_count, created_at }]
```
### 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
auth: 公开
```
### PUT /api/v1/capabilities/{id}
```yaml
description: 更新能力
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: 注销能力
description: 注销能力（已发布的保持在线，标记 deprecated）
auth: JWT
```
@@ -417,56 +367,51 @@ request:
changelog: string
```
### POST /api/v1/capabilities/{id}/review
```yaml
description: 提交审核（管理员）
auth: JWT (admin)
request:
body:
action: string # approve/reject
note: string
```
---
## 7. Skills 市场接口
## 8. Skills 市场
### POST /api/v1/skills
```yaml
description: 发布技能
description: 发布技能（需订阅）
auth: JWT
precondition: subscribed == true
request:
body:
name: string (required)
description: string
category: string
tags: array[string]
pricing_model: string # per_call/per_token/subscription/free
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: 市场列表
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
q: string (搜索)
category, tags, sort (rating/popular/newest), page, page_size
```
### GET /api/v1/skills/{id}
```yaml
description: 技能详情
auth: 公开
```
### POST /api/v1/skills/{id}/purchase
@@ -474,8 +419,7 @@ response:
description: 购买技能
auth: JWT
request:
body:
# 无需参数，自动扣费
body: # 无需参数，自动扣费
response:
200:
data:
@@ -486,85 +430,79 @@ response:
### GET /api/v1/skills/purchased
```yaml
description: 已购技能列表
description: 已购技能
auth: JWT
```
### GET /api/v1/skills/developer/dashboard
```yaml
description: 开发者仪表盘
auth: JWT (subscribed)
response:
200:
data:
items:
- skill_id: uuid
name: string
purchased_at: datetime
total_skills: integer
total_purchases: integer
total_revenue: integer
pending_payout: integer
```
---
## 8. IM Bot 接口
## 9. 开发者提现
### POST /api/v1/im/callback/{platform}
### POST /api/v1/developer/payout
```yaml
description: 平台回调 (Webhook)
auth: 平台签名验证
description: 申请提现
auth: JWT (subscribed)
request:
body: 平台消息格式 (各平台不同)
response:
200: 平台要求的响应格式
body:
amount_cents: integer (required, min 10000 = ¥100)
method: string # alipay/bank
account_info: object # 收款信息（加密传输）
```
### GET /api/v1/im/sessions
### GET /api/v1/developer/payouts
```yaml
description: 会话列表
auth: JWT
response:
200:
data:
items:
- id: uuid
platform: string
user_identifier: string
user_name: string
model: string
last_active_at: datetime
description: 提现记录
auth: JWT (subscribed)
```
---
## 9. Admin 接口
## 10. 管理后台
### GET /api/v1/admin/dashboard
```yaml
description: 管理仪表盘
auth: JWT (admin 角色)
auth: JWT (admin)
response:
200:
data:
total_users: integer
total_tenants: integer
total_subscribers: integer
total_api_calls: integer (今日)
total_revenue: integer (本月)
pending_reviews: 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
auth: JWT (admin)
```
### POST /api/v1/admin/capabilities/{id}/review
```yaml
description: 能力审核
auth: JWT (admin 角色)
request:
body:
action: string # approve/reject
note: string
auth: JWT (admin)
```
### POST /api/v1/admin/users/{id}/suspend
```yaml
description: 封禁用户
auth: JWT (admin)
```
---
docs/05-AGENTS-MiMoCode配置.md
+106 -133
View File
@@ -1,186 +1,159 @@
# AI PaaS Platform — AGENTS.md（MiMo Code 核心配置）
# AI PaaS Platform — AGENTS.md (v2.0)
> 此文件放在项目根目录 `.mimocode/AGENTS.md`，MiMo Code 每次启动时自动加载。
> 这是 MiMo Code 理解整个项目的唯一上下文来源——写得越精确，生成的代码质量越高。
> 放置于 `.mimocode/AGENTS.md`，MiMo Code 每次启动自动加载。
---
# AI PaaS 商业平台
## 项目概述
面向个人开发者的 AI 能力服务平台。提供 Agent、MCP、Skills、IM Bot、LLM 调用等 AI 能力，支持按 Token 计费和订阅制收费。
## 一句话描述
**让任何 AI 使用者都能像用水电一样使用 AI 能力，注册即用，按量付费。**
## 架构模式
微服务架构 + 事件驱动。核心业务自研，基础设施开源。
## 用户模型
- 扁平化：只有用户，没有租户概念
- 权限分级：未认证 → 已实名 → 订阅用户
- 订阅用户：完成实名认证 + 支付月费，自动获得创建/发布 AI 能力权限
- **核心规则：欠费不影响已发布能力**
## 技术栈
- **后端核心**: Go 1.22+ (所有核心服务)
- **AI 服务**: Python 3.11+ (LangFlow, MCP Hub 集成)
- **前端**: React 18 + TypeScript 5+ + Ant Design Pro 6 + ECharts
- **数据库**: PostgreSQL 16 (RLS 多租户隔离)
- **AI 服务层**: Python 3.11+ (FastAPI) — 所有自研业务服务
- **LLM 网关**: NEW API (Go, 开源) — 多模型统一管理
- **SSO 认证**: Casdoor (Go, 开源) — OAuth2/OIDC/社交登录
- **API 网关**: APISIX (Lua, 开源) — 路由/限流/鉴权
- **本地 LLM**: Ollama (Go, 开源) — 本地模型推理
- **Agent 编排**: LangFlow (Python, 开源) — 可视化工作流
- **前端**: React 18 + TypeScript + Ant Design Pro + ECharts
- **数据库**: PostgreSQL 16
- **缓存**: 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
- **实名认证**: 阿里云实名认证 API
## 项目结构
```
ai-paas-platform/
├── .mimocode/
│ └── AGENTS.md ← 本文件
├── docs/ ← 设计文档
│ └── 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/
├── packages/
│ └── web/ ← React Dashboard
├── services/
│ ├── gateway/ ← FastAPI 核心网关 (:8080)
│ ├── billing/ ← FastAPI 计费引擎 (:8081)
│ ├── registry/ ← FastAPI 能力注册 (:8082)
│ ├── skills/ ← FastAPI Skills 市场 (:8083)
│ ├── metering/ ← FastAPI 用量追踪 (:8084)
│ └── admin/ ← FastAPI 管理后台 (:8085)
├── infra/
│ ├── casdoor/ ← Casdoor 配置
│ ├── new-api/ ← NEW API 配置
│ ├── ollama/ ← Ollama 配置
│ ├── apisix/ ← APISIX 配置
│ ├── postgresql/ ← 数据库初始化
│ ├── redis/
│ ├── kafka/
│ ├── milvus/
│ └── apisix/
├── deploy/ ← 部署配置
│ ├── docker-compose.yml
│ └── kafka/
├── deploy/
│ ├── docker-compose.yml ← 一键启动开发环境
│ └── k8s/
└── migrations/ ← 数据库 Migration
├── 001_init.sql
└── ...
├── migrations/
└── pyproject.toml
```
## 开发规范
### Go 服务
- 遵循 Effective Go + gofmt + golangci-lint
- 每个服务独立 main.go，可独立编译运行
- 服务间通信: 同步用 HTTP/gRPC，异步用 Kafka
- 错误处理: 统一错误码，返回 `{code, message, data}` 格式
- 配置管理: 环境变量 + YAML 配置文件
- 日志: 结构化 JSON 日志 (slog)
### Python 服务 (FastAPI)
- 遵循 ruff + black 格式化
- 每个服务独立目录，可独立运行
- 服务间通信: 同步 HTTP，异步 Kafka
- 错误处理: 统一 `{code, message, data}` 格式
- 配置管理: 环境变量 + .env 文件
- 日志: structlog (结构化 JSON)
- 类型注解: 必须 (Pydantic v2)
- 测试: pytest + httpx, 覆盖率 > 80%
### TypeScript 前端
- 遵循 eslint + prettier
- 组件: React 函数组件 + Hooks
- 状态管理: React Query (服务端) + Zustand (客户端)
- 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)
- 样式: Ant Design Pro 内置
### Git
- 分支: main (生产), develop (开发), feature/* (功能)
- 分支: main, develop, feature/*
- 提交: Conventional Commits (feat/fix/docs/chore/test)
- PR: 必须通过 CI + Code Review
- PR: 必须通过 CI
### 测试
- Go: testing + testify, 覆盖率 > 80%
- TypeScript: vitest + playwright
- 单元测试: 每个服务的核心逻辑
- 集成测试: 服务间调用链
## 核心服务说明
## 核心模块说明
### ai-paas-gateway (:8080)
- 所有业务请求入口
- JWT 验证 (对接 Casdoor)
- API Key 验证 (SHA-256 查 DB)
- 用户状态检查 (订阅/欠费)
- LLM 调用代理: gateway → NEW API → LLM
- 流式 SSE 透传
- 用量异步上报 (Kafka)
### auth-service (:8081)
- Keycloak 适配器
- JWT 验证中间件
- API Key 验证 (SHA-256 哈希查 DB)
- 租户上下文提取 (JWT claim → tenant_id)
- RBAC: owner > admin > developer > user
### ai-paas-billing (:8081)
- Redis Lua 原子操作
- 先扣后服 + 幂等 + 可审计
- 订阅管理 (Free/Developer/Pro/Flagship)
- Token 包充值
- 欠费保护期 (7 天)
- 开发者分成结算
### 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 双协议)
### ai-paas-registry (:8082)
- 能力 CRUD
- 能力类型: agent/mcp/skill/llm/custom
- 版本管理: SemVer
- 状态: draft → pending_review → active → deprecated
- 服务发现: 按类型/标签/状态查询
- **欠费时已发布能力保持 active**
### metering (:8090)
- Kafka Consumer: 消费 usage.events
- PostgreSQL 持久化: token_usage 表 (按月分区)
- 预聚合: 每小时刷新 usage_summaries
- 用量查询: 按日/周/月/模型/能力统计
### skills (:8085)
- 技能发布/审核/交易
- 计费模式: per_call/per_token/subscription/free
### ai-paas-skills (:8083)
- 技能市场浏览/搜索/购买
- 开发者发布技能
- 分成: 平台 25% / 开发者 75%
- 全文搜索: PostgreSQL GIN 索引
- 全文搜索 (PostgreSQL GIN)
- 评分系统
### im-gateway (:8087)
- 多平台适配器: 微信(LangBot) / QQ(OneBot) / 钉钉
- 会话管理: Redis Hash, 24h 过期
- 上下文窗口: 最近 20 条消息
- 指令系统: /help /model /clear /balance
### ai-paas-metering (:8084)
- Kafka Consumer
- PostgreSQL 持久化
- 按月分区表
- 预聚合统计
### openapi-gateway (:8083)
- OpenAI 兼容 API: POST /v1/chat/completions
- 请求拦截链: Auth → Balance → LLM → Billing → Response
- 流式 SSE 支持
- 用量异步上报 Kafka
### ai-paas-admin (:8085)
- 用户管理
- 能力审核
- 财务管理
- 系统监控
## 计费原则（最重要）
1. **先扣后服**: 先扣减余额，再允许调用
2. **幂等**: 通过 idempotency_key 防重复扣费
3. **原子**: Redis Lua 脚本保证原子性
4. **可审计**: 每笔变动有 trace_id + 原因
5. **实时可见**: Dashboard 余额秒级更新
2. **幂等**: idempotency_key 防重复扣费
3. **原子**: Redis Lua 保证原子性
4. **可审计**: 每笔变动有 trace_id
5. **欠费保护**: 已发布能力不被下架
## LLM 对接
- 统一 OpenAI 兼容格式: POST /v1/chat/completions
- 百度需适配层 (非标准 API)
- 其他平台直接兼容
- 统一通过 NEW API 代理
- NEW API 配置各平台 API Key
- 格式: OpenAI 兼容 (POST /v1/chat/completions)
- 流式: SSE (text/event-stream)
- 百度需适配层 (NEW API 内置)
## 部署
- 开发: docker-compose.yml (一键启动)
- 生产: Kubernetes + Helm Charts
- 监控: Prometheus + Grafana
- 日志: 结构化 JSON → Loki
## 实名认证
- 阿里云实名认证 API
- 用户提交: 真实姓名 + 身份证号
- 验证通过: 标记 verified = true
- 信息加密存储 (AES-256)
## 重要约束
- 所有 API 必须有 OpenAPI 3.0 规范
- 所有 API 必须有 OpenAPI 文档 (FastAPI 自动生成)
- 所有数据库变更必须有 Migration
- 所有金额使用整数 (毫 Credit)
- 所有敏感数据加密 (AES-256)
- 所有关键操作有审计日志
- 所有金额使用整数 (分)
- 所有敏感数据加密
- **欠费不影响已发布能力**