yuzhiran-dev
323 lines
13 KiB
Markdown
323 lines
13 KiB
Markdown
# 宇之然 AI - 技术架构设计文档
|
||
|
||
> 版本：v1.0
|
||
> 日期：2026-05-08
|
||
|
||
---
|
||
|
||
## 1. 系统总体架构
|
||
|
||
### 1.1 架构分层
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ 客户端层 │
|
||
│ ┌────────────┐ ┌──────────────┐ ┌────────────┐ │
|
||
│ │ Next.js │ │ Uni-app │ │ 微信小程序 │ │
|
||
│ │ 官网 (SSR) │ │ App (跨平台) │ │ │ │
|
||
│ └────────────┘ └──────────────┘ └────────────┘ │
|
||
└──────────────────────────┬──────────────────────────────────────────┘
|
||
│
|
||
┌──────────────────────────▼──────────────────────────────────────────┐
|
||
│ API 网关层 │
|
||
│ Nginx / 阿里云 SLB → API Gateway │
|
||
│ 限流 / 鉴权 / 日志 / 路由转发 │
|
||
└──────────────────────────┬──────────────────────────────────────────┘
|
||
│
|
||
┌──────────────────────────▼──────────────────────────────────────────┐
|
||
│ 业务服务层 │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ 用户服务 │ │ 内容服务 │ │ 课程服务 │ │ 沙箱服务 │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ 社区服务 │ │ 支付服务 │ │ 搜索服务 │ │ 审核服务 │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||
└──────────────────────────┬──────────────────────────────────────────┘
|
||
│
|
||
┌──────────────────────────▼──────────────────────────────────────────┐
|
||
│ AI 网关层 │
|
||
│ 统一 API → 多模型路由 → 负载均衡 → 结果缓存 │
|
||
│ 通义千问 │ 文心一言 │ GLM │ DeepSeek │ Kimi ... │
|
||
└──────────────────────────┬──────────────────────────────────────────┘
|
||
│
|
||
┌──────────────────────────▼──────────────────────────────────────────┐
|
||
│ 数据层 │
|
||
│ MySQL 8.0 │ Redis 7 │ ES 8.x │ OSS │ RocketMQ │
|
||
│ (主从/读写分离) (缓存/会话) (搜索) (存储) (消息队列) │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 技术选型详述
|
||
|
||
### 2.1 前端（官网）
|
||
|
||
| 技术 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| Next.js | 14+ | React 框架，SSR/SSG 支持 |
|
||
| TypeScript | 5.x | 类型安全 |
|
||
| TailwindCSS | 3.x | 原子化 CSS |
|
||
| Shadcn/ui | latest | UI 组件库 |
|
||
| React Query | 5.x | 数据请求管理 |
|
||
| Zustand | latest | 状态管理 |
|
||
|
||
### 2.2 移动端（App / 小程序）
|
||
|
||
| 技术 | 说明 |
|
||
|------|------|
|
||
| Uni-app / Taro | 跨端框架 |
|
||
| Vue 3 / React | 视框架而定 |
|
||
| Pinia / Zustand | 状态管理 |
|
||
| uView / NutUI | 移动端组件库 |
|
||
|
||
> 推荐 Uni-app + Vue 3，对微信小程序适配最成熟。
|
||
|
||
### 2.3 后端
|
||
|
||
| 技术 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| Node.js | 20 LTS | 运行时 |
|
||
| NestJS | 10.x | Node.js 后端框架 |
|
||
| Prisma | 5.x | ORM |
|
||
| JWT | - | 鉴权 |
|
||
| Zod | latest | 数据校验 |
|
||
|
||
或备选方案：
|
||
|
||
| 技术 | 说明 |
|
||
|------|------|
|
||
| Go + Gin / Fiber | 高性能，适合 AI 网关 |
|
||
| Python + FastAPI | 适合 AI 数据处理任务 |
|
||
|
||
> 建议：核心业务用 NestJS，AI 网关用 Go。
|
||
|
||
### 2.4 数据库
|
||
|
||
| 组件 | 用途 | 部署 |
|
||
|------|------|------|
|
||
| MySQL 8.0 | 业务主库（用户/课程/订单等） | 阿里云 RDS |
|
||
| Redis 7 | 缓存/会话/限流计数器 | 阿里云 Redis |
|
||
| Elasticsearch 8.x | 内容搜索 | 阿里云 ES |
|
||
| 阿里云 OSS | 图片/视频/文件存储 | 阿里云 OSS |
|
||
| RocketMQ | 异步任务/消息通知 | 阿里云 RocketMQ |
|
||
|
||
### 2.5 AI 网关
|
||
|
||
```
|
||
用户请求 → 网关层
|
||
├── 请求校验 → 内容安全审核
|
||
├── 模型路由（基于用户配置/成本/负载）
|
||
│ ├── 通义千问 (qwen-max)
|
||
│ ├── 文心一言 (ERNIE-4.0)
|
||
│ ├── GLM-4
|
||
│ ├── DeepSeek-V3
|
||
│ └── Kimi (moonshot-v1)
|
||
├── 结果缓存（Redis，相同 prompt 命中缓存）
|
||
├── 流式响应处理
|
||
└── 计费/用量统计
|
||
```
|
||
|
||
### 2.6 内容安全
|
||
|
||
| 服务 | 用途 |
|
||
|------|------|
|
||
| 阿里云内容安全 | 文本/图片鉴黄、涉政、违禁检测 |
|
||
| 腾讯云天御 | UGC 内容安全审核 |
|
||
| 自定义敏感词库 | 行业特定敏感词过滤 |
|
||
|
||
---
|
||
|
||
## 3. 数据库设计概要
|
||
|
||
### 3.1 核心表结构
|
||
|
||
```
|
||
users — 用户表
|
||
├── id, phone, email, password_hash, avatar, status, created_at
|
||
├── user_profiles — 用户扩展信息
|
||
└── user_learn_records — 学习记录
|
||
|
||
courses — 课程表
|
||
├── id, title, description, cover, category, price, status
|
||
├── chapters — 章节表
|
||
├── lessons — 课时表
|
||
└── lesson_progress — 学习进度
|
||
|
||
prompts — 提示词表
|
||
├── id, title, content, category, tags, author_id, status
|
||
├── prompt_favorites — 收藏
|
||
└── prompt_comments — 评论
|
||
|
||
tools — AI 工具表
|
||
├── id, name, description, url, category, icon, status
|
||
└── tool_reviews — 评价
|
||
|
||
models — 模型百科表
|
||
├── id, name, provider, params, features, benchmark, status
|
||
└── model_comparisons — 对比评测
|
||
|
||
sandbox_sessions — AI 沙箱会话表
|
||
├── id, user_id, model, messages, tokens, duration, created_at
|
||
└── sandbox_quota — 用户沙箱额度
|
||
|
||
orders — 订单表
|
||
├── id, user_id, amount, plan_type, status, pay_channel, paid_at
|
||
└── subscriptions — 订阅记录
|
||
|
||
contents — 内容（文章/资讯）
|
||
├── id, title, content, category, tags, author, status, view_count
|
||
└── content_comments — 评论
|
||
|
||
admin_users — 管理员表
|
||
├── id, username, password_hash, role, permission, last_login
|
||
└── admin_logs — 操作日志
|
||
```
|
||
|
||
### 3.2 数据库设计原则
|
||
|
||
- **软删除**：所有业务表增加 `deleted_at` 字段
|
||
- **审计字段**：`created_at`、`updated_at` 必备
|
||
- **索引策略**：覆盖常用查询场景，避免全表扫描
|
||
- **分表策略**：`sandbox_sessions` 按用户 ID 分表
|
||
- **读写分离**：主库写入，从库查询
|
||
|
||
---
|
||
|
||
## 4. API 设计规范
|
||
|
||
### 4.1 命名规范
|
||
|
||
```
|
||
GET /api/v1/courses — 课程列表
|
||
GET /api/v1/courses/:id — 课程详情
|
||
POST /api/v1/courses — 创建课程（管理端）
|
||
PUT /api/v1/courses/:id — 更新课程（管理端）
|
||
DELETE /api/v1/courses/:id — 删除课程（管理端）
|
||
|
||
POST /api/v1/auth/login — 登录
|
||
POST /api/v1/auth/register — 注册
|
||
POST /api/v1/auth/refresh — 刷新 token
|
||
|
||
POST /api/v1/sandbox/chat — AI 沙箱对话
|
||
GET /api/v1/sandbox/history — 对话历史
|
||
GET /api/v1/sandbox/quota — 沙箱额度查询
|
||
|
||
POST /api/v1/orders/create — 创建订单
|
||
GET /api/v1/orders/:id — 订单查询
|
||
POST /api/v1/orders/callback — 支付回调
|
||
```
|
||
|
||
### 4.2 通用响应格式
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {},
|
||
"meta": {
|
||
"page": 1,
|
||
"pageSize": 20,
|
||
"total": 100
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.3 鉴权方案
|
||
|
||
- **JWT Token**（Access Token 2h + Refresh Token 7d）
|
||
- 管理后台：Session + Cookie
|
||
- API 签名：管理端 API 需签名校验
|
||
|
||
---
|
||
|
||
## 5. 部署架构
|
||
|
||
```
|
||
┌─────────────┐
|
||
│ DNS │
|
||
│ (阿里云 DNS)│
|
||
└──────┬──────┘
|
||
│
|
||
┌──────▼──────┐
|
||
│ CDN │
|
||
│ (静态资源) │
|
||
└──────┬──────┘
|
||
│
|
||
┌──────▼──────┐
|
||
│ SLB │
|
||
│ (负载均衡) │
|
||
└──────┬──────┘
|
||
│
|
||
┌────────────┼────────────┐
|
||
│ │ │
|
||
┌──────▼──┐ ┌─────▼────┐ ┌────▼────┐
|
||
│ Next.js │ │ NestJS │ │ Admin │
|
||
│ 官网 │ │ API 服务 │ │ Panel │
|
||
└─────────┘ └─────┬────┘ └─────────┘
|
||
│
|
||
┌───────────┼───────────┐
|
||
│ │ │
|
||
┌──────▼──┐ ┌────▼───┐ ┌───▼────┐
|
||
│ MySQL │ │ Redis │ │ ES │
|
||
│ RDS │ │ │ │ │
|
||
└─────────┘ └────────┘ └────────┘
|
||
```
|
||
|
||
### 5.1 环境规划
|
||
|
||
| 环境 | 用途 | 配置 |
|
||
|------|------|------|
|
||
| 开发 (dev) | 本地开发 | 个人电脑 / Docker Compose |
|
||
| 测试 (staging) | 联调测试 | 阿里云 ECS 2C4G |
|
||
| 生产 (production) | 正式运营 | 阿里云 ECS 4C8G × 2 + RDS 2C4G |
|
||
|
||
### 5.2 CI/CD 流程
|
||
|
||
```
|
||
Git Push → GitHub Actions
|
||
├── Lint & Type Check
|
||
├── Unit Test
|
||
├── Build
|
||
└── Deploy to 阿里云
|
||
├── 构建 Docker 镜像
|
||
├── Push 到阿里云 CR
|
||
└── 滚动更新 ECS/Pod
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 性能与安全
|
||
|
||
### 6.1 性能目标
|
||
|
||
| 指标 | 目标 |
|
||
|------|------|
|
||
| API 响应时间 (P95) | < 200ms |
|
||
| 首屏加载时间 | < 1.5s |
|
||
| AI 对话首 Token 延迟 | < 1s |
|
||
| 并发用户 | 支持 1000+ 同时在线 |
|
||
| 系统可用性 | 99.9% |
|
||
|
||
### 6.2 安全措施
|
||
|
||
- HTTPS 全站加密
|
||
- API 限流（单用户 100次/分钟）
|
||
- SQL 注入防护（Prisma ORM 参数化查询）
|
||
- XSS/CSRF 防护
|
||
- 密码 bcrypt 加密
|
||
- 敏感信息脱敏
|
||
- 定期安全扫描 + 渗透测试
|
||
|
||
---
|
||
|
||
## 7. 技术债务与演进路线
|
||
|
||
| 阶段 | 任务 |
|
||
|------|------|
|
||
| MVP | 单体应用快速验证 |
|
||
| V2 | 服务化拆分 |
|
||
| V3 | AI 网关独立部署 |
|
||
| V4 | 引入 K8s 容器编排 |
|
||
| V5 | 多数据中心容灾 |
|