# 宇之然 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 通用响应格式 ```json { "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 | 服务化拆分 |