audio_codebuddy/.qoder/repowiki/zh/content/系统架构/整体架构设计.md

整体架构设计

本文引用的文件

• README.md
• .plans\audiobook-v2-ux\docs\architecture.md
• docs\database-structure.md
• server\src\app.ts
• server\src\config\index.ts
• server\package.json
• my-uniapp-vue3\package.json
• my-uniapp-vue3\src\main.ts
• my-uniapp-vue3\src\utils\request.ts
• server\src\modules\book-generator\book-generator.controller.ts
• server\src\modules\tts\tts.controller.ts
• docker-nginx\docker-compose.yml

目录

1. 引言
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖分析
7. 性能考虑
8. 故障排查指南
9. 结论
10. 附录

引言

本文件为“AI有声书生成平台”的整体架构设计文档，面向前端uniapp应用层、后端Koa.js服务层、数据库与第三方服务层的三层架构，结合微服务化理念（模块化服务划分、服务间通信机制、API网关设计）、水平扩展能力（负载均衡、服务发现、容器化部署）、系统安全架构（身份认证、授权控制、数据加密），并提供系统架构图与用户请求完整流转路径，帮助开发者与运维人员快速理解与落地。

项目结构

项目采用前后端分离的三层架构：

• 前端：基于uniapp + Vue 3 + TypeScript，支持H5与多端小程序，使用Pinia进行状态管理。
• 后端：基于Node.js + Koa 2.x，模块化拆分业务域，统一通过REST路由暴露API，并内置WebSocket用于生成进度推送。

• 数据与第三方服务：数据库采用MySQL（Prisma ORM），文件存储支持本地或OSS，AI服务通过外部TTS服务（如阿里云百炼）提供语音合成能力。

  graph TB
  subgraph "前端层uniapp"
  FE_App["应用入口<br/>main.ts"]
  FE_Request["请求封装<br/>request.ts"]
  end
  subgraph "后端层Koa.js"
  BE_App["应用入口<br/>server/src/app.ts"]
  BE_Router["路由注册<br/>REST + WebSocket"]
  BE_Config["配置中心<br/>config/index.ts"]
  end
  subgraph "数据与第三方服务"
  DB["数据库<br/>MySQL + Prisma"]
  Storage["文件存储<br/>本地/OSS"]
  TTS["TTS服务<br/>阿里云百炼等"]
  end
  FE_App --> FE_Request
  FE_Request --> BE_Router
  BE_Router --> BE_App
  BE_App --> BE_Config
  BE_App --> DB
  BE_App --> Storage
  BE_App --> TTS
  

图表来源

• server\src\app.ts:1-194
• server\src\config\index.ts:1-117
• my-uniapp-vue3\src\main.ts:1-32
• my-uniapp-vue3\src\utils\request.ts:1-207

章节来源

• README.md:18-52
• .plans\audiobook-v2-ux\docs\architecture.md:6-35

核心组件

• 前端应用（uniapp）
  • 应用入口负责初始化Pinia与用户状态；请求封装统一处理Authorization头、重试、超时、缓存与错误提示。
• 后端服务（Koa.js）
  • 应用入口集中注册中间件（CORS、日志、安全防护、限流、静态文件）、路由与健康检查；模块化控制器按业务域划分。
• 数据与第三方服务
  • 数据库与文件存储通过配置中心统一管理；TTS服务通过外部供应商提供语音合成能力。

章节来源

• my-uniapp-vue3\package.json:1-65
• server\package.json:1-60
• server\src\app.ts:60-130
• server\src\config\index.ts:69-117

架构总览

系统采用三层架构与微服务化理念：

• 前端uniapp应用层：多端一致的UI与交互，统一通过HTTP/HTTPS访问后端API，部分场景使用WebSocket接收生成进度。
• 后端Koa.js服务层：REST API + WebSocket，模块化控制器按业务域划分（认证、TTS、播放器、收藏、偏好、搜索、分类、评论、通知、BGM、音频编辑、书籍生成、视频生成、发布、签到、订阅、支付、历史、反馈等）。

• 数据库与第三方服务层：MySQL（Prisma ORM），文件存储（本地或OSS），TTS服务（阿里云百炼等）。

  graph TB
  Client["客户端<br/>H5/小程序"] --> APIGW["API网关/反向代理<br/>Nginx"]
  APIGW --> Koa["Koa应用<br/>server/src/app.ts"]
  Koa --> Modules["业务模块控制器<br/>REST + WebSocket"]
  Modules --> DB["数据库<br/>MySQL + Prisma"]
  Modules --> OSS["对象存储<br/>本地/OSS"]
  Modules --> TTS["TTS服务<br/>阿里云百炼"]
  

图表来源

• server\src\app.ts:92-130
• docker-nginx\docker-compose.yml:1-12

详细组件分析

前端组件分析（uniapp）

• 应用入口与状态管理
  • 初始化Pinia与用户状态，支持H5调试工具（vConsole）。

• 请求封装与错误处理

  • 统一设置Authorization头，支持GET/POST/PUT/DELETE，具备重试、超时、缓存与错误提示；对401、429、5xx等进行差异化处理。

    sequenceDiagram
    participant U as "用户"
    participant APP as "uniapp应用"
    participant REQ as "请求封装"
    participant API as "后端API"
    participant WS as "WebSocket(可选)"
    U->>APP : 触发操作
    APP->>REQ : request(url, options)
    REQ->>REQ : 设置Authorization/缓存/重试
    REQ->>API : HTTP请求
    API-->>REQ : 返回{code,data}
    REQ-->>APP : 成功/失败处理
    API-->>WS : 生成进度推送(可选)
    WS-->>APP : 推送进度
    

图表来源

• my-uniapp-vue3\src\main.ts:10-31
• my-uniapp-vue3\src\utils\request.ts:35-99

章节来源

• my-uniapp-vue3\src\main.ts:1-32
• my-uniapp-vue3\src\utils\request.ts:1-207

后端组件分析（Koa.js）

• 应用入口与中间件
  • 注册错误处理、性能监控、日志、安全防护（XSS、SQL注入）、CORS、限流（默认关闭）、静态文件服务（音频/视频）、健康检查与性能指标。
• 路由与模块化控制器
  • 统一路由前缀/api，按业务域注册控制器（认证、TTS、播放器、收藏、偏好、搜索、分类、评论、通知、BGM、音频编辑、书籍生成、视频生成、发布、签到、订阅、支付、历史、反馈等）。

• 配置中心

  • 统一管理端口、JWT密钥、数据库连接、模型配置（DashScope/TTS）、上传目录与大小限制等。

    flowchart TD
    Start(["请求进入"]) --> CORS["CORS/日志/安全防护"]
    CORS --> Body["解析请求体/静态文件"]
    Body --> Route["路由匹配 /api/*"]
    Route --> Ctrl{"控制器分发"}
    Ctrl --> |认证| AuthCtrl["auth.controller"]
    Ctrl --> |TTS| TTSCtrl["tts.controller"]
    Ctrl --> |书籍生成| BGCtrl["book-generator.controller"]
    Ctrl --> |其他模块| OtherCtrl["..."]
    AuthCtrl --> DB["数据库/存储"]
    TTSCtrl --> DB
    BGCtrl --> DB
    OtherCtrl --> DB
    DB --> Resp["返回响应"]
    Resp --> End(["结束"])
    

图表来源

• server\src\app.ts:64-130
• server\src\config\index.ts:69-117

章节来源

• server\src\app.ts:1-194
• server\src\config\index.ts:1-117

书籍生成与TTS服务组件

• 书籍生成控制器
  • 提供批量生成书籍（内容、音频、合并、视频、合并视频）的API，支持取消与状态查询，使用内存Map跟踪运行中的任务。

• TTS控制器

  • 提供音色列表、服务商列表、测试数据库连接、异步生成音频、状态查询、预览音色、单/批量下载音频等接口；集成配额检查与使用限制中间件。

    sequenceDiagram
    participant FE as "前端"
    participant API as "后端API"
    participant BG as "书籍生成控制器"
    participant Svc as "书籍生成服务"
    participant DB as "数据库"
    participant WS as "WebSocket"
    FE->>API : POST /api/book-generator/books/ : id/batch-generate
    API->>BG : 校验书籍/步骤/并发
    BG->>Svc : 创建批量生成任务
    Svc->>DB : 更新状态/持久化
    Svc-->>WS : 推送进度
    WS-->>FE : 生成进度
    Svc-->>API : 返回任务ID
    API-->>FE : {code,message,data}
    

图表来源

• server\src\modules\book-generator\book-generator.controller.ts:24-119

章节来源

• server\src\modules\book-generator\book-generator.controller.ts:1-199
• server\src\modules\tts\tts.controller.ts:1-274

数据模型与关系

• 书籍体系与学习路径体系双轨并行，支持有声书生成与课程学习两大场景。
• 书籍体系包含Book、BookChapter、Audio、Album、AlbumAudio等表，支持大纲、章节、小节（keyPoints）三级目录结构。
• 学习路径体系包含LearningPath、Subject、Chapter、Section、ContentBlock五级目录结构。

• 提供状态字段说明与常用查询示例，便于业务扩展与性能优化。

  erDiagram
  BOOK {
  int id PK
  int user_id
  varchar title
  int total_chapters
  enum status
  json outline_json
  int album_id
  }
  BOOK_CHAPTER {
  int id PK
  int book_id FK
  int number
  varchar title
  text key_points
  enum status
  int audio_id
  }
  AUDIO {
  int id PK
  int user_id
  varchar title
  text audio_url
  int audio_duration
  enum status
  }
  ALBUM {
  int id PK
  int user_id
  varchar name
  enum type
  }
  ALBUM_AUDIO {
  int id PK
  int album_id FK
  int audio_id FK
  int order_index
  }
  BOOK ||--o{ BOOK_CHAPTER : "包含"
  BOOK ||--o{ AUDIO : "生成"
  ALBUM ||--o{ ALBUM_AUDIO : "包含"
  AUDIO ||--|| ALBUM_AUDIO : "被包含"
  

图表来源

• docs\database-structure.md:22-128
• docs\database-structure.md:131-157

章节来源

• docs\database-structure.md:1-402

依赖分析

• 前端依赖
  • uni-app生态、Vue 3、TypeScript、Pinia、vconsole等，支持多端构建与开发调试。

• 后端依赖

  • Koa、@koa/router、@koa/cors、koa-body、koa-mount、koa-static、Prisma、LangChain/LangGraph、Bull队列、ioredis、Axios、Sentry、Winston、WebSocket等，覆盖Web框架、ORM、AI链路、队列、缓存、监控与日志等能力。

    graph LR
    FE["前端<br/>uniapp"] --> |HTTP/WS| BE["后端<br/>Koa.js"]
    BE --> DB["数据库<br/>MySQL"]
    BE --> REDIS["缓存<br/>Redis"]
    BE --> OSS["存储<br/>OSS/本地"]
    BE --> LLM["AI/LLM<br/>LangChain/LangGraph"]
    BE --> TTS["TTS<br/>阿里云百炼"]
    

图表来源

• server\package.json:11-44
• my-uniapp-vue3\package.json:39-50

章节来源

• server\package.json:1-60
• my-uniapp-vue3\package.json:1-65

性能考虑

• 中间件与监控
  • 性能监控中间件与Sentry错误上报，结合Winston日志输出，便于定位性能瓶颈与异常。
• 限流与安全
  • 提供速率限制中间件与安全防护中间件（XSS、SQL注入），默认关闭全局限流，可根据部署环境开启。
• 队列与异步处理
  • 书籍生成采用队列与处理器，异步执行生成任务，避免阻塞主线程；WebSocket推送进度，提升用户体验。
• 存储与CDN
  • 文件存储支持OSS，结合Nginx反向代理与静态文件服务，提升静态资源访问效率。

章节来源

• server\src\app.ts:22-25
• server\src\app.ts:66-83
• docker-nginx\docker-compose.yml:1-12

故障排查指南

• 健康检查与指标
  • 提供/health健康检查与/api/metrics性能指标接口，便于运维快速判断服务状态。
• 错误处理与日志
  • 统一错误处理中间件与Sentry错误上报，结合Winston日志输出，定位问题更高效。
• 前端请求封装
  • 对401（未登录）、429（请求频繁）、5xx（服务器错误）等进行差异化提示与处理，提升用户感知与可维护性。

章节来源

• server\src\app.ts:92-98
• my-uniapp-vue3\src\utils\request.ts:135-159

结论

本架构以uniapp前端与Koa.js后端为核心，配合MySQL与对象存储，以及外部TTS服务，实现了从文本到音频、从音频到视频的完整生成链路。通过模块化控制器、队列与WebSocket推送、统一配置中心与中间件体系，系统具备良好的可扩展性与可维护性。结合Nginx反向代理与Docker容器化部署，可进一步提升系统的高可用与弹性伸缩能力。

附录

• API与技术栈参考
  • 前端：uni-app + Vue 3 + TypeScript + Pinia
  • 后端：Node.js + Koa 2.x + Prisma ORM + LangChain/LangGraph
  • 数据库：MySQL（Prisma ORM）
  • 存储：本地/阿里云OSS
  • 第三方服务：阿里云百炼TTS
• 部署与容器化
  • Nginx反向代理配置与容器编排，便于水平扩展与服务发现。

章节来源

• README.md:18-30
• docker-nginx\docker-compose.yml:1-12