# 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 周，得益于开源组件的复用。

---

*文档结束*