yuzhiran-dev
538de50bb1
- Prisma User 模型新增 username 字段（唯一索引） - 注册先查重复再创建，返回友好中文提示（非 500） - 登录支持用户名/手机号/邮箱三种方式 - 前端注册表单增加用户名输入框，预校验 2-20 位格式 - 新增 scripts/deploy.sh：一键构建并部署主站+镜像站+重启后端+重载 Nginx - 镜像站 www.yuzhiran.com.cn Nginx 配置与主站同步 - AI 助手架构升级：用户端/管理后台均采用完整 Tool Calling 架构 - 新增 UserAiAssistantService（18 工具）+ AiAssistantController - admin 助手新增 search + mark-all-notifications-read 工具 - 修复注册 500 错误：catch Prisma P2002 → BadRequestException - Baidu Analytics Script 注入 root layout
11 KiB
Executable File
11 KiB
Executable File
宇之然 AI - 技术架构设计文档
版本：v1.1 日期：2026-05-29
1. 系统总体架构
1.1 架构分层
┌─────────────────────────────────────────────────────────────────────┐
│ 客户端层 │
│ ┌────────────────────┐ ┌──────────────────┐ │
│ │ Next.js │ │ 微信小程序 │ │
│ │ 官网 (静态导出) │ │ (规划中) │ │
│ └────────────────────┘ └──────────────────┘ │
└──────────────────────────┬──────────────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────────────┐
│ API 网关层 (NestJS) │
│ Nginx → PM2 → NestJS │
│ 限流 / JWT 鉴权 / 日志 / 路由转发 │
└──────────────────────────┬──────────────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────────────┐
│ 业务服务层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 用户服务 │ │ 内容服务 │ │ 课程服务 │ │ 沙箱服务 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 社区服务 │ │ 支付服务 │ │ 搜索服务 │ │ 审核服务 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────────┬──────────────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────────────┐
│ AI 网关层 │
│ 统一 API → 模型路由 → 流式响应 │
│ qnaigc 兼容接口 → DeepSeek / SenseNova / 其他 OpenAI 兼容模型 │
└──────────────────────────┬──────────────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────────────┐
│ 数据层 │
│ MySQL 8.0 │ Redis 7 │
│ (主库) │ (缓存/会话) │
└─────────────────────────────────────────────────────────────────────┘
2. 技术选型详述
2.1 前端（官网）
| 技术 | 版本 | 说明 |
|---|---|---|
| Next.js | 14+ | React 框架，静态导出 (output: 'export') |
| TypeScript | 5.x | 类型安全 |
| TailwindCSS | 3.x | 原子化 CSS |
| Shadcn/ui | latest | UI 组件库 |
| next-themes | latest | 暗黑模式切换 |
2.2 移动端（规划中）
| 技术 | 说明 |
|---|---|
| 微信小程序 | 后续规划 |
| Taro / uni-app | 评估中 |
2.3 后端
| 技术 | 版本 | 说明 |
|---|---|---|
| Node.js | 20 LTS | 运行时 |
| NestJS | 10.x | Node.js 后端框架 |
| Prisma | 5.x | ORM（MySQL） |
| JWT | - | 鉴权（Access Token 2h + Refresh Token 7d） |
2.4 数据库
| 组件 | 用途 | 部署 |
|---|---|---|
| MySQL 8.0 | 业务主库（用户/课程/订单等） | 本地 / 云 RDS |
| Redis 7 | 缓存/会话/限流计数器 | 本地 / 云 Redis |
2.5 AI 网关
用户请求 → AIGatewayService
├── 模型路由（基于 modelMap 配置）
│ ├── general → OPENAI_MODEL (default: deepseek/deepseek-v4-flash)
│ ├── deepseek-v4-flash → deepseek/deepseek-v4-flash
│ └── sensenova-6.7-flash-lite → sensenova-6.7-flash-lite
├── 流式响应 (ReadableStream SSE)
└── 用量统计
AI 通过 OpenAI 兼容 API (api.qnaigc.com) 统一接入，不直接对接各模型厂商。
3. 数据库设计概要
3.1 核心表结构 (Prisma Schema)
users — 用户表
├── id, phone, email, password_hash, avatar, status, created_at
├── profiles — 用户扩展信息
└── 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 — 操作日志
skills — 技能包表
├── id, name, description, category, difficulty, system_prompt, icon
└── skill_tasks — 练习任务
3.2 Schema 管理
- 使用 Prisma Migrate 管理 schema 变更
- migration 文件位于
backend/prisma/migrations/ - 种子数据在
backend/prisma/seed.ts
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 — 支付回调
GET /api/v1/skills — 技能列表（支持过滤）
GET /api/v1/skills/:id — 技能详情
GET /api/v1/skills/categories — 技能分类
GET /api/v1/skills/difficulties — 难度等级
4.2 通用响应格式
{
"code": 0,
"message": "success",
"data": {},
"meta": {
"page": 1,
"pageSize": 20,
"total": 100
}
}
5. 部署架构
5.1 当前部署
┌─────────────┐
│ PM2 │
│ (进程管理) │
└──────┬──────┘
│
┌───────────┼───────────┐
│ │ │
┌──────▼──┐ ┌─────▼────┐ ┌───▼────┐
│ Node.js │ │ NestJS │ │ Redis │
│ server.js│ │ API 服务 │ │ │
│ (静态) │ │ PM2 │ └────────┘
└─────────┘ └─────┬────┘
│
┌──────▼──────┐
│ MySQL │
│ 8.0 │
└─────────────┘
| 服务 | 端口 | 管理方式 |
|---|---|---|
| 前端 (静态文件) | 3000 | PM2: node server.js |
| 后端 (NestJS) | 4000 | PM2: node dist/main.js |
| MySQL | 3306 | 系统服务 |
| Redis | 6379 | 系统服务 |
5.2 构建流程
# 前端
npm run build → out/ (静态文件)
pm2 restart frontend
# 后端
npx nest build → dist/
pm2 restart backend --update-env
5.3 环境
| 环境 | 用途 |
|---|---|
| 开发 (dev) | 本地 npm run dev / npm run start:dev |
| 生产 (production) | PM2 + 静态导出 |
6. 性能与安全
6.1 性能目标
| 指标 | 目标 |
|---|---|
| API 响应时间 (P95) | < 200ms |
| 首屏加载时间 | < 1.5s |
| AI 对话首 Token 延迟 | < 1s |
| 静态页面加载 | 即时（CDN 缓存） |
6.2 安全措施
- HTTPS 全站加密
- JWT 鉴权（沙箱等核心 API）
- API 限流
- 密码 bcrypt 加密
- 敏感信息脱敏
7. 技术债务与演进路线
| 阶段 | 任务 |
|---|---|
| 当前 | 单体 NestJS + Next.js 静态导出 |
| V2 | AI 网关独立部署 |
| V3 | 微信小程序上线 |
| V4 | 服务化拆分 |