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