qyyfw
a9e141b695
- 新增 docs/smsbao-integration.md（完整集成文档+代码示例） - 更新 PRD：注册/登录使用短信宝发送验证码 - 更新架构设计：技术栈+选型矩阵+配置说明 - 更新 API 规范：新增 /send-code 接口 - 更新 AGENTS.md：短信服务配置说明 短信宝 API: - 发送: GET https://api.smsbao.com/sms?u=&p=&m=&c= - 查询: GET http://api.smsbao.com/query?u=&p= - 签名格式: 【QihuAI】您的验证码是123456
496 lines
19 KiB
Markdown
496 lines
19 KiB
Markdown
# AI PaaS 商业平台 — 系统架构设计
|
||
|
||
> 版本: 2.0 | 日期: 2026-06-27
|
||
> 状态: 已修订（基于用户反馈：开源优先 + AI 生态兼容）
|
||
|
||
---
|
||
|
||
## 1. 设计原则
|
||
|
||
### 1.1 核心原则（v2.0 强化）
|
||
|
||
```
|
||
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，本地部署事实标准 |
|
||
| **短信服务** | 阿里云短信 | 短信宝 | **短信宝** | 简单 HTTP GET 接口，快速接入 |
|
||
| **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) │ │ (本地) │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||
└──────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 核心服务拆分
|
||
|
||
### 3.1 服务列表（v2.0 简化）
|
||
|
||
| 服务 | 技术 | 端口 | 职责 | 开源/自研 |
|
||
|------|------|------|------|----------|
|
||
| **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 市场
|
||
```
|
||
|
||
**请求处理链路（LLM 调用）:**
|
||
```
|
||
用户请求 → 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
|
||
# 用户管理: 列表/详情/状态变更
|
||
# 能力审核: 审批/拒绝
|
||
# 财务管理: 流水/提现/对账
|
||
# 系统监控: 健康检查/配置管理
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 数据流向
|
||
|
||
### 5.1 LLM 调用主流程
|
||
```
|
||
用户 → Web/CLI/API
|
||
→ APISIX (限流/路由)
|
||
→ ai-paas-gateway (鉴权/计费/转发)
|
||
→ NEW API (模型路由)
|
||
→ DeepSeek/千问/豆包... (实际推理)
|
||
→ 响应流式返回用户
|
||
→ 异步: 用量事件 → Kafka → ai-paas-metering → PostgreSQL
|
||
```
|
||
|
||
### 5.2 能力发布流程
|
||
```
|
||
开发者 → Web Dashboard
|
||
→ ai-paas-registry (创建能力)
|
||
→ 管理员审核
|
||
→ ai-paas-skills (上架市场)
|
||
→ 用户浏览/购买
|
||
→ ai-paas-billing (扣费/分成)
|
||
```
|
||
|
||
### 5.3 认证流程
|
||
```
|
||
用户 → Web App
|
||
→ Casdoor (注册/登录)
|
||
→ 阿里云实名认证 API (身份验证)
|
||
→ ai-paas-gateway (更新用户状态)
|
||
→ JWT Token 签发
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 开源组件集成方案
|
||
|
||
### 6.0 SMS Bao (短信服务)
|
||
|
||
```
|
||
接入方式: HTTP GET 接口（无需 SDK）
|
||
接口地址: https://api.smsbao.com/sms
|
||
认证方式: ApiKey 或 MD5 密码
|
||
配置文件: infra/smsbao/config.yaml
|
||
smsbao:
|
||
username: "your_username"
|
||
api_key: "your_api_key" # 优先使用 ApiKey
|
||
sign_name: "QihuAI" # 短信签名
|
||
api_url: "https://api.smsbao.com/sms"
|
||
query_url: "http://api.smsbao.com/query"
|
||
code_length: 6 # 验证码长度
|
||
code_ttl: 300 # 验证码有效期（秒）
|
||
rate_limit: 60 # 同号码发送间隔（秒）
|
||
daily_limit: 10 # 同号码每日上限
|
||
```
|
||
|
||
### 6.1 Casdoor (SSO 认证中心)
|
||
|
||
```
|
||
部署方式: Docker Compose
|
||
对接方式: OAuth2 / OIDC
|
||
功能:
|
||
- 用户注册/登录 (手机号/邮箱/微信)
|
||
- JWT Token 签发与验证
|
||
- 第三方登录 (微信/钉钉/飞书)
|
||
- 用户管理界面
|
||
- RBAC 权限管理
|
||
集成点:
|
||
- ai-paas-gateway 调用 Casdoor API 验证 Token
|
||
- NEW API 配置 Casdoor 作为认证后端
|
||
```
|
||
|
||
### 6.2 NEW API (LLM 网关)
|
||
|
||
```
|
||
部署方式: Docker Compose
|
||
对接方式: OpenAI 兼容 API
|
||
功能:
|
||
- 多模型统一管理 (DeepSeek/千问/豆包/智谱/元宝/百度)
|
||
- 负载均衡与故障转移
|
||
- 流式 SSE 透传
|
||
- 用量统计与配额管理
|
||
- 渠道管理 (API Key 池)
|
||
集成点:
|
||
- ai-paas-gateway 作为唯一上游调用 NEW API
|
||
- NEW API 配置各 LLM 平台的 API Key
|
||
- NEW API 的用量数据同步到 ai-paas-metering
|
||
```
|
||
|
||
### 6.3 Ollama (本地 LLM)
|
||
|
||
```
|
||
部署方式: 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
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 数据库架构
|
||
|
||
### 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
|
||
services:
|
||
# 基础设施
|
||
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:
|
||
build: ./packages/web
|
||
```
|
||
|
||
### 8.2 生产环境
|
||
|
||
```
|
||
Kubernetes + Helm Charts
|
||
├── 基础设施: PostgreSQL HA / Redis Sentinel / Kafka Cluster
|
||
├── 开源组件: Casdoor / NEW API / Ollama (GPU Node) / APISIX
|
||
├── 自研服务: FastAPI × N replicas (HPA 自动伸缩)
|
||
├── 监控: Prometheus + Grafana
|
||
└── 日志: Loki + Promtail
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 安全架构
|
||
|
||
### 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 周，得益于开源组件的复用。
|
||
|
||
---
|
||
|
||
*文档结束*
|