# 快速开始指南

<cite>
**本文档引用的文件**
- [README.md](file://README.md)
- [package.json](file://package.json)
- [server/package.json](file://server/package.json)
- [my-uniapp-vue3/package.json](file://my-uniapp-vue3/package.json)
- [server/src/app.ts](file://server/src/app.ts)
- [server/src/config/index.ts](file://server/src/config/index.ts)
- [my-uniapp-vue3/vite.config.ts](file://my-uniapp-vue3/vite.config.ts)
- [server/src/modules/tts/tts.controller.ts](file://server/src/modules/tts/tts.controller.ts)
- [server/src/modules/book-generator/book-generator.controller.ts](file://server/src/modules/book-generator/book-generator.controller.ts)
- [server/prisma/schema.prisma](file://server/prisma/schema.prisma)
- [DEPLOY.md](file://DEPLOY.md)
- [docker-nginx/docker-compose.yml](file://docker-nginx/docker-compose.yml)
- [server/src/services/ffmpeg.processor.ts](file://server/src/services/ffmpeg.processor.ts)
- [server/src/modules/video-generator/video-generator.ffmpeg.ts](file://server/src/modules/video-generator/video-generator.ffmpeg.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介

AI有声书生成平台是一个面向内容创作者的音频制作工具，帮助自媒体作者、小说爱好者、学习者低成本制作音频内容。该平台支持将文字转换为高质量音频，提供多种音色选择、参数调节、在线播放、历史管理和会员体系等核心功能。

## 项目结构

该项目采用前后端分离架构，包含以下主要组件：

```mermaid
graph TB
subgraph "前端应用"
H5[H5 应用]
MP[微信小程序]
UniApp[UniApp 框架]
end
subgraph "后端服务"
Koa[Koa 2.x 服务器]
MySQL[(MySQL 数据库)]
Redis[(Redis 缓存)]
OSS[(对象存储)]
end
subgraph "媒体处理"
FFmpeg[FFmpeg 音频处理]
LangChain[LangChain AI 集成]
end
H5 --> Koa
MP --> Koa
UniApp --> Koa
Koa --> MySQL
Koa --> Redis
Koa --> OSS
Koa --> FFmpeg
Koa --> LangChain
```

**图表来源**
- [server/src/app.ts:1-194](file://server/src/app.ts#L1-L194)
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)

**章节来源**
- [README.md:31-52](file://README.md#L31-L52)
- [server/src/app.ts:1-194](file://server/src/app.ts#L1-L194)

## 核心组件

### 环境要求

项目对开发环境有以下最低要求：

- **Node.js**: 版本 18 或更高
- **数据库**: MySQL 8.0 或更高（注意：代码中实际使用的是 MySQL，而非 MongoDB 6.0）
- **FFmpeg**: 用于音频处理和视频生成
- **操作系统**: Windows、macOS 或 Linux

### 依赖安装

#### 后端服务依赖
```bash
cd server
npm install
```

#### 前端应用依赖
```bash
cd my-uniapp-vue3
npm install
```

**章节来源**
- [README.md:56-60](file://README.md#L56-L60)
- [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)

## 架构概览

系统采用微服务架构，后端基于 Koa 2.x 框架构建，前端使用 UniApp 框架支持多端部署。

```mermaid
sequenceDiagram
participant Client as "客户端应用"
participant Frontend as "前端应用"
participant Backend as "后端服务"
participant Database as "数据库"
participant Storage as "存储服务"
participant MediaProc as "媒体处理"
Client->>Frontend : 用户交互
Frontend->>Backend : API 请求
Backend->>Database : 数据查询/更新
Database-->>Backend : 数据响应
Backend->>Storage : 文件上传/下载
Storage-->>Backend : 文件信息
Backend->>MediaProc : 音频/视频处理
MediaProc-->>Backend : 处理结果
Backend-->>Frontend : API 响应
Frontend-->>Client : 用户界面更新
```

**图表来源**
- [server/src/app.ts:133-194](file://server/src/app.ts#L133-L194)
- [server/src/modules/tts/tts.controller.ts:52-127](file://server/src/modules/tts/tts.controller.ts#L52-L127)

## 详细组件分析

### 后端服务启动流程

#### 1. 环境配置
```bash
cd server
cp .env.example .env
```

#### 2. 安装依赖
```bash
npm install
```

#### 3. 启动开发服务器
```bash
npm run dev
```

#### 4. 服务启动顺序
后端服务启动时会按以下顺序初始化各个组件：

```mermaid
flowchart TD
Start([启动服务]) --> InitSentry["初始化 Sentry 错误监控"]
InitSentry --> ConnectDB["连接 MySQL 数据库"]
ConnectDB --> TestRedis["测试 Redis 连接"]
TestRedis --> TestStorage["测试存储连接"]
TestStorage --> InitPlans["初始化订阅套餐"]
InitPlans --> InitWS["初始化 WebSocket 服务"]
InitWS --> StartServer["启动 HTTP 服务器"]
StartServer --> InitQueue["初始化任务队列"]
InitQueue --> ResumeTasks["恢复中断任务"]
ResumeTasks --> Ready([服务就绪])
```

**图表来源**
- [server/src/app.ts:133-194](file://server/src/app.ts#L133-L194)

#### 5. 环境变量配置
后端服务支持以下关键环境变量：

| 变量名 | 描述 | 默认值 |
|--------|------|--------|
| PORT | 服务器端口号 | 3000 |
| NODE_ENV | 运行环境 | development |
| DATABASE_URL | MySQL 连接字符串 | mysql://root:password@localhost:3306/audio-book |
| JWT_SECRET | JWT 密钥 | my-jwt-secret-key-2024 |
| DASHSCOPE_API_KEY | 百炼 API 密钥 | 空字符串 |
| STORAGE_TYPE | 存储类型 | local |

**章节来源**
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)

### 前端应用启动

#### H5 开发服务
```bash
cd my-uniapp-vue3
npm run dev:h5
```

#### 微信小程序编译
```bash
cd my-uniapp-vue3
npm run build:mp-weixin
```

#### 开发服务器配置
前端开发服务器通过 Vite 配置了 API 代理：

```mermaid
graph LR
subgraph "前端开发服务器"
Vite[Vite 开发服务器]
Proxy[代理配置]
end
subgraph "后端 API 服务器"
API[API 端点]
Uploads[文件上传]
Videos[视频资源]
end
Vite --> Proxy
Proxy --> API
Proxy --> Uploads
Proxy --> Videos
```

**图表来源**
- [my-uniapp-vue3/vite.config.ts:7-23](file://my-uniapp-vue3/vite.config.ts#L7-L23)

**章节来源**
- [README.md:77-90](file://README.md#L77-L90)
- [my-uniapp-vue3/package.json:4-37](file://my-uniapp-vue3/package.json#L4-L37)

### 核心功能模块

#### TTS 文本转语音模块
TTS 模块提供完整的文本转语音功能，支持多种音色和参数调节：

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "TTS API"
participant Service as "TTS 服务"
participant Provider as "语音提供商"
participant Queue as "任务队列"
Client->>API : POST /api/tts/generate
API->>Service : 验证参数和配额
Service->>Provider : 生成音频
Provider-->>Service : 音频文件
Service->>Queue : 存储文件信息
Service-->>API : 返回任务ID
API-->>Client : 音频生成任务已创建
Note over Client,Queue : 异步处理完成后通知客户端
```

**图表来源**
- [server/src/modules/tts/tts.controller.ts:52-127](file://server/src/modules/tts/tts.controller.ts#L52-L127)

**章节来源**
- [server/src/modules/tts/tts.controller.ts:1-274](file://server/src/modules/tts/tts.controller.ts#L1-L274)

#### 书籍生成模块
支持一键完整生成书籍，包含内容生成、音频处理、视频生成等步骤：

```mermaid
flowchart TD
Start([开始批量生成]) --> ValidateBook["验证书籍存在"]
ValidateBook --> CheckTask["检查是否有运行中的任务"]
CheckTask --> CreateTask["创建批量生成任务"]
CreateTask --> Steps["执行生成步骤"]
Steps --> Content["生成内容"]
Content --> Audio["生成音频"]
Audio --> MergeAudio["合并音频"]
MergeAudio --> Video["生成视频"]
Video --> MergeVideo["合并视频"]
MergeVideo --> Complete([任务完成])
CheckTask --> |有任务| Error([返回错误])
ValidateBook --> |书籍不存在| Error
```

**图表来源**
- [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)

## 依赖分析

### 后端技术栈

```mermaid
graph TB
subgraph "核心框架"
Koa[Koa 2.x]
TypeScript[TypeScript]
Prisma[Prisma ORM]
end
subgraph "数据库"
MySQL[MySQL]
Redis[Redis]
end
subgraph "AI 集成"
LangChain[LangChain]
OpenAI[OpenAI]
DashScope[DashScope]
end
subgraph "媒体处理"
FFmpeg[FFmpeg]
Bull[Bull 队列]
end
subgraph "第三方服务"
AliOSS[阿里云 OSS]
Alipay[支付宝]
WeChatPay[微信支付]
end
Koa --> Prisma
Koa --> LangChain
Koa --> FFmpeg
Koa --> Redis
Prisma --> MySQL
LangChain --> OpenAI
LangChain --> DashScope
FFmpeg --> AliOSS
Koa --> AliOSS
```

**图表来源**
- [server/package.json:11-44](file://server/package.json#L11-L44)

### 前端技术栈

```mermaid
graph TB
subgraph "框架层"
UniApp[UniApp 3.0]
Vue3[Vue 3]
TypeScript[TypeScript]
end
subgraph "状态管理"
Pinia[Pinia]
end
subgraph "构建工具"
Vite[Vite]
HBuilder[HBuilder]
end
subgraph "UI 组件"
Components[自定义组件]
Utils[工具函数]
end
UniApp --> Vue3
Vue3 --> Pinia
UniApp --> Vite
UniApp --> Components
UniApp --> Utils
```

**图表来源**
- [my-uniapp-vue3/package.json:39-63](file://my-uniapp-vue3/package.json#L39-L63)

**章节来源**
- [README.md:18-30](file://README.md#L18-L30)
- [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)

## 性能考虑

### 数据库设计
系统使用 MySQL 作为主数据库，通过 Prisma ORM 进行数据访问。数据库表结构设计支持以下核心实体：

```mermaid
erDiagram
USER {
int id PK
string phone UK
string openid UK
string nickname
string avatar
int memberLevel
datetime memberExpireAt
int dailyUsage
string lastUsageDate
datetime createdAt
datetime updatedAt
}
AUDIO_RECORD {
int id PK
int userId
string audioId UK
string title
string text
int wordCount
string voiceId
string voiceParams
string audioUrl
int audioDuration
int audioSize
string status
string errorMsg
datetime createdAt
datetime updatedAt
}
BOOK {
int id PK
int userId
string title
string subtitle
text description
string coverUrl
string targetAudience
string style
string bookScale
int totalChapters
int estimatedWords
int progress
boolean isPublished
longtext outlineJson
text foreword
text afterword
text errorMsg
datetime createdAt
datetime updatedAt
}
BOOK_CHAPTER {
int id PK
int bookId FK
int parentId
int level
int number
string title
text summary
text keyPoints
int estimatedWords
longtext content
int wordCount
text contentError
datetime generatedAt
string audioUrl
int audioDuration
string videoUrl
int videoDuration
boolean isPublic
string genStage
string status
longtext lrcLyrics
datetime createdAt
datetime updatedAt
}
USER ||--o{ AUDIO_RECORD : creates
USER ||--o{ BOOK : creates
BOOK ||--o{ BOOK_CHAPTER : contains
```

**图表来源**
- [server/prisma/schema.prisma:10-472](file://server/prisma/schema.prisma#L10-L472)

### 媒体处理优化
系统集成了 FFmpeg 进行音频和视频处理，支持多种格式转换和批量处理：

```mermaid
flowchart TD
Input[输入文件] --> Download[下载到本地]
Download --> Probe[检测媒体信息]
Probe --> Convert{格式转换?}
Convert --> |是| FormatConvert[格式转换]
Convert --> |否| Process[直接处理]
FormatConvert --> Process
Process --> Filter[应用滤镜/效果]
Filter --> Output[输出文件]
Output --> Cleanup[清理临时文件]
Cleanup --> Done[完成]
```

**图表来源**
- [server/src/services/ffmpeg.processor.ts:217-378](file://server/src/services/ffmpeg.processor.ts#L217-L378)

**章节来源**
- [server/prisma/schema.prisma:1-472](file://server/prisma/schema.prisma#L1-L472)
- [server/src/services/ffmpeg.processor.ts:194-378](file://server/src/services/ffmpeg.processor.ts#L194-L378)

## 故障排除指南

### 常见启动问题

#### 1. 数据库连接失败
**症状**: 服务启动时报数据库连接错误
**解决方案**:
```bash
# 检查 MySQL 服务状态
systemctl status mysql

# 验证连接字符串
cat server/.env | grep DATABASE_URL

# 测试数据库连接
mysql -h localhost -P 3306 -u root -p
```

#### 2. FFmpeg 未安装或路径问题
**症状**: 媒体处理功能报错
**解决方案**:
```bash
# 检查 FFmpeg 是否安装
ffmpeg -version

# 添加到系统 PATH 或配置环境变量
export PATH=$PATH:/usr/local/bin
```

#### 3. 端口被占用
**症状**: 服务无法绑定到指定端口
**解决方案**:
```bash
# 检查端口占用
lsof -i :3000

# 终止占用进程
kill -9 PID

# 或修改端口配置
echo "PORT=3001" >> server/.env
```

#### 4. 前端代理配置问题
**症状**: 前端无法访问后端 API
**解决方案**:
```bash
# 检查 Vite 代理配置
cat my-uniapp-vue3/vite.config.ts

# 确保后端服务已启动
curl http://localhost:3000/api/health
```

### 性能优化建议

#### 1. 数据库优化
- 为常用查询字段建立索引
- 使用连接池管理数据库连接
- 定期清理无用数据

#### 2. 缓存策略
- 使用 Redis 缓存热点数据
- 实现合理的缓存失效策略
- 监控缓存命中率

#### 3. 文件存储优化
- 使用 CDN 加速静态资源
- 实现文件分片上传
- 定期清理临时文件

**章节来源**
- [DEPLOY.md:199-251](file://DEPLOY.md#L199-L251)

## 结论

AI有声书生成平台提供了完整的音频内容创作解决方案。通过合理的架构设计和技术选型，该平台能够支持多端部署、高性能处理和良好的扩展性。

开发者可以按照本指南快速搭建开发环境，理解系统的整体架构，并根据具体需求进行定制开发。建议在开发过程中重点关注数据库设计、媒体处理性能和用户体验优化等方面。

## 附录

### 首次运行验证步骤

1. **环境检查**
   ```bash
   node --version
   npm --version
   mysql --version
   ffmpeg -version
   ```

2. **后端服务验证**
   ```bash
   cd server
   curl http://localhost:3000/api/health
   ```

3. **前端应用验证**
   ```bash
   cd my-uniapp-vue3
   npm run dev:h5
   ```

4. **数据库初始化**
   ```bash
   cd server
   npx prisma migrate dev
   npx prisma generate
   ```

### 基本功能测试方法

1. **TTS 功能测试**
   - 调用 `/api/tts/voices` 获取音色列表
   - 调用 `/api/tts/generate` 生成音频
   - 调用 `/api/tts/status/:audioId` 查询状态

2. **用户认证测试**
   - 调用 `/api/auth/send-code` 发送验证码
   - 调用 `/api/auth/login` 用户登录
   - 调用 `/api/auth/user-info` 获取用户信息

3. **媒体处理测试**
   - 上传音频文件到 `/uploads` 目录
   - 调用 FFmpeg 处理接口进行格式转换
   - 验证生成的媒体文件质量

**章节来源**
- [README.md:114-135](file://README.md#L114-L135)
- [server/src/modules/tts/tts.controller.ts:13-221](file://server/src/modules/tts/tts.controller.ts#L13-L221)