# 整体架构设计
**本文引用的文件**
- [README.md](file://README.md)
- [.plans\audiobook-v2-ux\docs\architecture.md](file://.plans\audiobook-v2-ux\docs\architecture.md)
- [docs\database-structure.md](file://docs\database-structure.md)
- [server\src\app.ts](file://server\src\app.ts)
- [server\src\config\index.ts](file://server\src\config\index.ts)
- [server\package.json](file://server\package.json)
- [my-uniapp-vue3\package.json](file://my-uniapp-vue3\package.json)
- [my-uniapp-vue3\src\main.ts](file://my-uniapp-vue3\src\main.ts)
- [my-uniapp-vue3\src\utils\request.ts](file://my-uniapp-vue3\src\utils\request.ts)
- [server\src\modules\book-generator\book-generator.controller.ts](file://server\src\modules\book-generator\book-generator.controller.ts)
- [server\src\modules\tts\tts.controller.ts](file://server\src\modules\tts\tts.controller.ts)
- [docker-nginx\docker-compose.yml](file://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服务（如阿里云百炼）提供语音合成能力。
```mermaid
graph TB
subgraph "前端层uniapp"
FE_App["应用入口
main.ts"]
FE_Request["请求封装
request.ts"]
end
subgraph "后端层Koa.js"
BE_App["应用入口
server/src/app.ts"]
BE_Router["路由注册
REST + WebSocket"]
BE_Config["配置中心
config/index.ts"]
end
subgraph "数据与第三方服务"
DB["数据库
MySQL + Prisma"]
Storage["文件存储
本地/OSS"]
TTS["TTS服务
阿里云百炼等"]
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](file://server\src\app.ts#L1-L194)
- [server\src\config\index.ts:1-117](file://server\src\config\index.ts#L1-L117)
- [my-uniapp-vue3\src\main.ts:1-32](file://my-uniapp-vue3\src\main.ts#L1-L32)
- [my-uniapp-vue3\src\utils\request.ts:1-207](file://my-uniapp-vue3\src\utils\request.ts#L1-L207)
章节来源
- [README.md:18-52](file://README.md#L18-L52)
- [.plans\audiobook-v2-ux\docs\architecture.md:6-35](file://.plans\audiobook-v2-ux\docs\architecture.md#L6-L35)
## 核心组件
- 前端应用（uniapp）
- 应用入口负责初始化Pinia与用户状态；请求封装统一处理Authorization头、重试、超时、缓存与错误提示。
- 后端服务（Koa.js）
- 应用入口集中注册中间件（CORS、日志、安全防护、限流、静态文件）、路由与健康检查；模块化控制器按业务域划分。
- 数据与第三方服务
- 数据库与文件存储通过配置中心统一管理；TTS服务通过外部供应商提供语音合成能力。
章节来源
- [my-uniapp-vue3\package.json:1-65](file://my-uniapp-vue3\package.json#L1-L65)
- [server\package.json:1-60](file://server\package.json#L1-L60)
- [server\src\app.ts:60-130](file://server\src\app.ts#L60-L130)
- [server\src\config\index.ts:69-117](file://server\src\config\index.ts#L69-L117)
## 架构总览
系统采用三层架构与微服务化理念：
- 前端uniapp应用层：多端一致的UI与交互，统一通过HTTP/HTTPS访问后端API，部分场景使用WebSocket接收生成进度。
- 后端Koa.js服务层：REST API + WebSocket，模块化控制器按业务域划分（认证、TTS、播放器、收藏、偏好、搜索、分类、评论、通知、BGM、音频编辑、书籍生成、视频生成、发布、签到、订阅、支付、历史、反馈等）。
- 数据库与第三方服务层：MySQL（Prisma ORM），文件存储（本地或OSS），TTS服务（阿里云百炼等）。
```mermaid
graph TB
Client["客户端
H5/小程序"] --> APIGW["API网关/反向代理
Nginx"]
APIGW --> Koa["Koa应用
server/src/app.ts"]
Koa --> Modules["业务模块控制器
REST + WebSocket"]
Modules --> DB["数据库
MySQL + Prisma"]
Modules --> OSS["对象存储
本地/OSS"]
Modules --> TTS["TTS服务
阿里云百炼"]
```
图表来源
- [server\src\app.ts:92-130](file://server\src\app.ts#L92-L130)
- [docker-nginx\docker-compose.yml:1-12](file://docker-nginx\docker-compose.yml#L1-L12)
## 详细组件分析
### 前端组件分析（uniapp）
- 应用入口与状态管理
- 初始化Pinia与用户状态，支持H5调试工具（vConsole）。
- 请求封装与错误处理
- 统一设置Authorization头，支持GET/POST/PUT/DELETE，具备重试、超时、缓存与错误提示；对401、429、5xx等进行差异化处理。
```mermaid
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](file://my-uniapp-vue3\src\main.ts#L10-L31)
- [my-uniapp-vue3\src\utils\request.ts:35-99](file://my-uniapp-vue3\src\utils\request.ts#L35-L99)
章节来源
- [my-uniapp-vue3\src\main.ts:1-32](file://my-uniapp-vue3\src\main.ts#L1-L32)
- [my-uniapp-vue3\src\utils\request.ts:1-207](file://my-uniapp-vue3\src\utils\request.ts#L1-L207)
### 后端组件分析（Koa.js）
- 应用入口与中间件
- 注册错误处理、性能监控、日志、安全防护（XSS、SQL注入）、CORS、限流（默认关闭）、静态文件服务（音频/视频）、健康检查与性能指标。
- 路由与模块化控制器
- 统一路由前缀/api，按业务域注册控制器（认证、TTS、播放器、收藏、偏好、搜索、分类、评论、通知、BGM、音频编辑、书籍生成、视频生成、发布、签到、订阅、支付、历史、反馈等）。
- 配置中心
- 统一管理端口、JWT密钥、数据库连接、模型配置（DashScope/TTS）、上传目录与大小限制等。
```mermaid
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](file://server\src\app.ts#L64-L130)
- [server\src\config\index.ts:69-117](file://server\src\config\index.ts#L69-L117)
章节来源
- [server\src\app.ts:1-194](file://server\src\app.ts#L1-L194)
- [server\src\config\index.ts:1-117](file://server\src\config\index.ts#L1-L117)
### 书籍生成与TTS服务组件
- 书籍生成控制器
- 提供批量生成书籍（内容、音频、合并、视频、合并视频）的API，支持取消与状态查询，使用内存Map跟踪运行中的任务。
- TTS控制器
- 提供音色列表、服务商列表、测试数据库连接、异步生成音频、状态查询、预览音色、单/批量下载音频等接口；集成配额检查与使用限制中间件。
```mermaid
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](file://server\src\modules\book-generator\book-generator.controller.ts#L24-L119)
章节来源
- [server\src\modules\book-generator\book-generator.controller.ts:1-199](file://server\src\modules\book-generator\book-generator.controller.ts#L1-L199)
- [server\src\modules\tts\tts.controller.ts:1-274](file://server\src\modules\tts\tts.controller.ts#L1-L274)
### 数据模型与关系
- 书籍体系与学习路径体系双轨并行，支持有声书生成与课程学习两大场景。
- 书籍体系包含Book、BookChapter、Audio、Album、AlbumAudio等表，支持大纲、章节、小节（keyPoints）三级目录结构。
- 学习路径体系包含LearningPath、Subject、Chapter、Section、ContentBlock五级目录结构。
- 提供状态字段说明与常用查询示例，便于业务扩展与性能优化。
```mermaid
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](file://docs\database-structure.md#L22-L128)
- [docs\database-structure.md:131-157](file://docs\database-structure.md#L131-L157)
章节来源
- [docs\database-structure.md:1-402](file://docs\database-structure.md#L1-L402)
## 依赖分析
- 前端依赖
- 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链路、队列、缓存、监控与日志等能力。
```mermaid
graph LR
FE["前端
uniapp"] --> |HTTP/WS| BE["后端
Koa.js"]
BE --> DB["数据库
MySQL"]
BE --> REDIS["缓存
Redis"]
BE --> OSS["存储
OSS/本地"]
BE --> LLM["AI/LLM
LangChain/LangGraph"]
BE --> TTS["TTS
阿里云百炼"]
```
图表来源
- [server\package.json:11-44](file://server\package.json#L11-L44)
- [my-uniapp-vue3\package.json:39-50](file://my-uniapp-vue3\package.json#L39-L50)
章节来源
- [server\package.json:1-60](file://server\package.json#L1-L60)
- [my-uniapp-vue3\package.json:1-65](file://my-uniapp-vue3\package.json#L1-L65)
## 性能考虑
- 中间件与监控
- 性能监控中间件与Sentry错误上报，结合Winston日志输出，便于定位性能瓶颈与异常。
- 限流与安全
- 提供速率限制中间件与安全防护中间件（XSS、SQL注入），默认关闭全局限流，可根据部署环境开启。
- 队列与异步处理
- 书籍生成采用队列与处理器，异步执行生成任务，避免阻塞主线程；WebSocket推送进度，提升用户体验。
- 存储与CDN
- 文件存储支持OSS，结合Nginx反向代理与静态文件服务，提升静态资源访问效率。
章节来源
- [server\src\app.ts:22-25](file://server\src\app.ts#L22-L25)
- [server\src\app.ts:66-83](file://server\src\app.ts#L66-L83)
- [docker-nginx\docker-compose.yml:1-12](file://docker-nginx\docker-compose.yml#L1-L12)
## 故障排查指南
- 健康检查与指标
- 提供/health健康检查与/api/metrics性能指标接口，便于运维快速判断服务状态。
- 错误处理与日志
- 统一错误处理中间件与Sentry错误上报，结合Winston日志输出，定位问题更高效。
- 前端请求封装
- 对401（未登录）、429（请求频繁）、5xx（服务器错误）等进行差异化提示与处理，提升用户感知与可维护性。
章节来源
- [server\src\app.ts:92-98](file://server\src\app.ts#L92-L98)
- [my-uniapp-vue3\src\utils\request.ts:135-159](file://my-uniapp-vue3\src\utils\request.ts#L135-L159)
## 结论
本架构以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](file://README.md#L18-L30)
- [docker-nginx\docker-compose.yml:1-12](file://docker-nginx\docker-compose.yml#L1-L12)