ai-paas-comparison/docs/02-系统架构设计.md

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，本地部署事实标准
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

这是整个平台的核心调度中心，所有业务请求经过这里。

# 技术选型: 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

# 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

# 能力 CRUD + 版本管理
# 支持: agent/mcp/skill/llm/custom 五种类型
# 状态机: draft → pending_review → active → deprecated

# 能力发现: 按类型/标签/评分/使用量查询
# 能力验证: 注册时自动健康检查
# 能力版本: SemVer 版本管理

4.4 ai-paas-skills（Skills 市场）— FastAPI

# 全文搜索: PostgreSQL GIN 索引
# 技能交易: 扣费 → 分成 → 授权
# 评分系统: 1-5 星 + 文字评价
# 开发者后台: 发布/管理/收益统计

4.5 ai-paas-metering（用量追踪）— FastAPI

# Kafka Consumer: 消费 usage.events
# PostgreSQL 持久化: token_usage 表 (按月分区)
# 预聚合: 每小时刷新 usage_summaries
# 用量查询: 按日/周/月/模型/能力统计
# 账单生成: 月度账单自动计算

4.6 ai-paas-admin（管理后台）— FastAPI

# 用户管理: 列表/详情/状态变更
# 能力审核: 审批/拒绝
# 财务管理: 流水/提现/对账
# 系统监控: 健康检查/配置管理

---

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.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)

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

---

文档结束