Domů Procházet Nápověda
Přihlásit se
caojunfei
/
audio_codebuddy
1
0
Rozštěpit 0
Soubory Úkoly 0 Pull Requesty 0 Wiki
Větev: master
Větve Značky
audio_codebuddy
/
.qoder
/
repowiki
/
zh
/
content
/
项目概述
/
快速开始指南.md

快速开始指南.md 15 KB
Trvalý odkaz Historie Surový

快速开始指南

本文档引用的文件

  • README.md
  • package.json
  • server/package.json
  • my-uniapp-vue3/package.json
  • server/src/app.ts
  • server/src/config/index.ts
  • my-uniapp-vue3/vite.config.ts
  • server/src/modules/tts/tts.controller.ts
  • server/src/modules/book-generator/book-generator.controller.ts
  • server/prisma/schema.prisma
  • DEPLOY.md
  • docker-nginx/docker-compose.yml
  • server/src/services/ffmpeg.processor.ts
  • server/src/modules/video-generator/video-generator.ffmpeg.ts

目录

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

简介

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

项目结构

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

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
  • server/src/config/index.ts:69-117

章节来源

  • README.md:31-52
  • server/src/app.ts:1-194

核心组件

环境要求

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

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

依赖安装

后端服务依赖

cd server
npm install

前端应用依赖

cd my-uniapp-vue3
npm install

章节来源

  • README.md:56-60
  • server/package.json:1-60
  • my-uniapp-vue3/package.json:1-65

架构概览

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

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
  • server/src/modules/tts/tts.controller.ts:52-127

详细组件分析

后端服务启动流程

1. 环境配置

cd server
cp .env.example .env

2. 安装依赖

npm install

3. 启动开发服务器

npm run dev

4. 服务启动顺序

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

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

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

前端应用启动

H5 开发服务

cd my-uniapp-vue3
npm run dev:h5

微信小程序编译

cd my-uniapp-vue3
npm run build:mp-weixin

开发服务器配置

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

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

章节来源

  • README.md:77-90
  • my-uniapp-vue3/package.json:4-37

核心功能模块

TTS 文本转语音模块

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

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

章节来源

  • server/src/modules/tts/tts.controller.ts:1-274

书籍生成模块

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

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

章节来源

  • server/src/modules/book-generator/book-generator.controller.ts:1-199

依赖分析

后端技术栈

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

前端技术栈

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

章节来源

  • README.md:18-30
  • server/package.json:1-60
  • my-uniapp-vue3/package.json:1-65

性能考虑

数据库设计

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

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

媒体处理优化

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

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

章节来源

  • server/prisma/schema.prisma:1-472
  • server/src/services/ffmpeg.processor.ts:194-378

故障排除指南

常见启动问题

1. 数据库连接失败

症状: 服务启动时报数据库连接错误 解决方案:

# 检查 MySQL 服务状态
systemctl status mysql

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

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

2. FFmpeg 未安装或路径问题

症状: 媒体处理功能报错 解决方案:

# 检查 FFmpeg 是否安装
ffmpeg -version

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

3. 端口被占用

症状: 服务无法绑定到指定端口 解决方案:

# 检查端口占用
lsof -i :3000

# 终止占用进程
kill -9 PID

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

4. 前端代理配置问题

症状: 前端无法访问后端 API 解决方案:

# 检查 Vite 代理配置
cat my-uniapp-vue3/vite.config.ts

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

性能优化建议

1. 数据库优化

  • 为常用查询字段建立索引
  • 使用连接池管理数据库连接
  • 定期清理无用数据

2. 缓存策略

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

3. 文件存储优化

  • 使用 CDN 加速静态资源
  • 实现文件分片上传
  • 定期清理临时文件

章节来源

  • DEPLOY.md:199-251

结论

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

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

附录

首次运行验证步骤

  1. 环境检查

    node --version
npm --version
mysql --version
ffmpeg -version

  2. 后端服务验证

    cd server
curl http://localhost:3000/api/health

  3. 前端应用验证

    cd my-uniapp-vue3
npm run dev:h5

  4. 数据库初始化

    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
  • server/src/modules/tts/tts.controller.ts:13-221