From 8209f15d0a6bdd188c3d268a80b26fee117bde52 Mon Sep 17 00:00:00 2001 From: qyyfw Date: Sat, 27 Jun 2026 11:35:53 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20v2.0=20=E5=85=A8=E9=9D=A2=E4=BF=AE?= =?UTF-8?q?=E8=AE=A2=20=E2=80=94=20=E5=BC=80=E6=BA=90=E4=BC=98=E5=85=88=20?= =?UTF-8?q?+=20=E6=89=81=E5=B9=B3=E5=8C=96=E7=94=A8=E6=88=B7=E6=A8=A1?= =?UTF-8?q?=E5=9E=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 核心变更: - 产品定位: '像用水电一样使用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) --- docs/01-PRD-产品需求文档.md | 599 ++++++++---------------- docs/02-系统架构设计.md | 804 +++++++++++++++++---------------- docs/03-数据库设计.md | 362 +++++---------- docs/04-API接口规范.md | 460 ++++++++----------- docs/05-AGENTS-MiMoCode配置.md | 239 +++++----- 5 files changed, 1031 insertions(+), 1433 deletions(-) diff --git a/docs/01-PRD-产品需求文档.md b/docs/01-PRD-产品需求文档.md index 574aaf0..f478092 100644 --- a/docs/01-PRD-产品需求文档.md +++ b/docs/01-PRD-产品需求文档.md @@ -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 标准协议管理 | --- diff --git a/docs/02-系统架构设计.md b/docs/02-系统架构设计.md index 749c348..7266f90 100644 --- a/docs/02-系统架构设计.md +++ b/docs/02-系统架构设计.md @@ -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 周，得益于开源组件的复用。 --- diff --git a/docs/03-数据库设计.md b/docs/03-数据库设计.md index fcb854b..76634d4 100644 --- a/docs/03-数据库设计.md +++ b/docs/03-数据库设计.md @@ -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 --- diff --git a/docs/04-API接口规范.md b/docs/04-API接口规范.md index 2766114..19a2215 100644 --- a/docs/04-API接口规范.md +++ b/docs/04-API接口规范.md @@ -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) ``` --- diff --git a/docs/05-AGENTS-MiMoCode配置.md b/docs/05-AGENTS-MiMoCode配置.md index 3d87e18..47307e6 100644 --- a/docs/05-AGENTS-MiMoCode配置.md +++ b/docs/05-AGENTS-MiMoCode配置.md @@ -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) -- 所有关键操作有审计日志 +- 所有金额使用整数 (分) +- 所有敏感数据加密 +- **欠费不影响已发布能力**