# 环境搭建 **本文档引用的文件** - [README.md](file://README.md) - [DEPLOY.md](file://DEPLOY.md) - [DEPLOY_PROD.md](file://DEPLOY_PROD.md) - [docker-nginx/docker-compose.yml](file://docker-nginx/docker-compose.yml) - [docker-nginx/bookapi.conf](file://docker-nginx/bookapi.conf) - [server/src/config/index.ts](file://server/src/config/index.ts) - [server/src/config/models.json](file://server/src/config/models.json) - [server/src/app.ts](file://server/src/app.ts) - [server/package.json](file://server/package.json) - [server/prisma/schema.prisma](file://server/prisma/schema.prisma) - [server/src/services/redis.service.ts](file://server/src/services/redis.service.ts) - [server/src/services/storage.service.ts](file://server/src/services/storage.service.ts) - [server/src/modules/tts/tts.service.ts](file://server/src/modules/tts/tts.service.ts) - [server/src/modules/video-generator/video-generator.ffmpeg.ts](file://server/src/modules/video-generator/video-generator.ffmpeg.ts) - [my-uniapp-vue3/package.json](file://my-uniapp-vue3/package.json) - [my-uniapp-vue3/src/utils/config.ts](file://my-uniapp-vue3/src/utils/config.ts) ## 目录 1. [引言](#引言) 2. [项目结构](#项目结构) 3. [核心组件](#核心组件) 4. [架构概览](#架构概览) 5. [详细组件分析](#详细组件分析) 6. [依赖关系分析](#依赖关系分析) 7. [性能考虑](#性能考虑) 8. [故障排除指南](#故障排除指南) 9. [结论](#结论) 10. [附录](#附录) ## 引言 本文件为AI有声书生成平台的环境搭建指南，覆盖开发环境、测试环境与生产环境的完整部署流程。内容包括Node.js、MySQL、Redis、FFmpeg等核心依赖的安装与配置，Docker容器化部署方案（含nginx反向代理、服务编排与网络设置），环境变量配置模板、数据库初始化脚本与缓存配置，以及开发工具链、IDE设置与调试环境准备。同时提供环境验证步骤与常见问题解决方案。 ## 项目结构 项目采用前后端分离架构，后端基于Node.js/Koa，前端基于uniapp/Vue3。后端使用Prisma进行数据库建模与迁移，TTS模块支持多家语音合成服务，视频生成功能基于FFmpeg。 ```mermaid graph TB subgraph "前端" FE_MY["my-uniapp-vue3
H5/小程序"] end subgraph "后端" BE_SERVER["server
Koa 应用"] BE_PRISMA["Prisma Schema
MySQL"] BE_REDIS["Redis 缓存"] BE_OSS["阿里云 OSS"] BE_FFMPEG["FFmpeg 音视频处理"] end subgraph "基础设施" NGINX["Nginx 反向代理"] DOCKER["Docker Compose"] end FE_MY --> NGINX NGINX --> BE_SERVER BE_SERVER --> BE_PRISMA BE_SERVER --> BE_REDIS BE_SERVER --> BE_OSS BE_SERVER --> BE_FFMPEG DOCKER --> NGINX ``` **图表来源** - [server/src/app.ts:133-194](file://server/src/app.ts#L133-L194) - [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117) - [server/prisma/schema.prisma:1-472](file://server/prisma/schema.prisma#L1-L472) - [docker-nginx/docker-compose.yml:1-12](file://docker-nginx/docker-compose.yml#L1-L12) **章节来源** - [README.md:31-52](file://README.md#L31-L52) - [server/src/app.ts:133-194](file://server/src/app.ts#L133-L194) ## 核心组件 - Node.js 与 Koa：后端服务框架，负责HTTP路由、中间件与业务逻辑。 - Prisma：数据库ORM，支持MySQL，提供类型安全的数据访问。 - Redis：缓存与会话存储，提升响应速度与用户体验。 - FFmpeg：音视频处理，支持音频合并、视频合成与特效。 - Nginx：反向代理与静态资源服务，提供HTTPS与负载均衡能力。 - Docker：容器化部署，简化环境一致性与服务编排。 **章节来源** - [server/src/app.ts:133-194](file://server/src/app.ts#L133-L194) - [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117) - [server/package.json:11-44](file://server/package.json#L11-L44) ## 架构概览 后端应用启动时依次完成：Sentry初始化、数据库连接、Redis连接测试、存储连接测试、订阅套餐初始化、WebSocket服务初始化、队列处理器初始化与优雅关闭处理。Nginx作为反向代理，将/api前缀转发至后端服务，并提供静态资源服务与HTTPS支持。 ```mermaid sequenceDiagram participant Client as "客户端" participant Nginx as "Nginx 反向代理" participant App as "Koa 应用" participant DB as "MySQL" participant Cache as "Redis" participant Store as "存储(OSS/本地)" Client->>Nginx : 请求 /api/* Nginx->>App : 反向代理到 127.0.0.1 : 3000 App->>DB : 连接与查询 App->>Cache : 读取/写入缓存 App->>Store : 上传/下载文件 App-->>Nginx : 响应 Nginx-->>Client : 返回结果 ``` **图表来源** - [server/src/app.ts:133-194](file://server/src/app.ts#L133-L194) - [server/src/services/redis.service.ts:246-255](file://server/src/services/redis.service.ts#L246-L255) - [server/src/services/storage.service.ts:252-272](file://server/src/services/storage.service.ts#L252-L272) - [docker-nginx/bookapi.conf:5-13](file://docker-nginx/bookapi.conf#L5-L13) ## 详细组件分析 ### 环境变量与配置 - 后端环境变量：端口、数据库URL、JWT密钥、TTS提供商配置、Redis连接参数、存储类型与OSS配置等。 - 前端环境：根据运行平台自动选择API地址，H5环境默认使用相对路径并通过Nginx代理。 ```mermaid flowchart TD Start(["加载 .env"]) --> LoadBE["后端配置加载
config/index.ts"] LoadBE --> LoadFE["前端API地址配置
my-uniapp-vue3/src/utils/config.ts"] LoadFE --> EnvOK["环境变量生效"] ``` **图表来源** - [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117) - [my-uniapp-vue3/src/utils/config.ts:44-72](file://my-uniapp-vue3/src/utils/config.ts#L44-L72) **章节来源** - [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117) - [my-uniapp-vue3/src/utils/config.ts:44-72](file://my-uniapp-vue3/src/utils/config.ts#L44-L72) ### 数据库与模型 - Prisma Schema定义了用户、书籍、章节、订单、播放记录等核心实体及关联关系。 - 支持MySQL数据源，通过DATABASE_URL连接字符串配置。 ```mermaid erDiagram USER { int id PK string phone string openid string nickname string avatar int memberLevel datetime memberExpireAt int dailyUsage string lastUsageDate 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 string failedStage string genStage string status text bookAnalysis } BOOK_CHAPTER { int id PK int bookId int parentId int level int number string title longtext content int wordCount text contentError datetime generatedAt text audioUrl int audioDuration text videoUrl int videoDuration boolean isPublic string genStage text lrcLyrics string status } ORDER { int id PK int userId string orderNo int planId string productType decimal amount string status string paymentMethod string paymentId datetime paidAt datetime createdAt datetime updatedAt } USER ||--o{ BOOK : "拥有" BOOK ||--o{ BOOK_CHAPTER : "包含" USER ||--o{ ORDER : "下单" ``` **图表来源** - [server/prisma/schema.prisma:10-472](file://server/prisma/schema.prisma#L10-L472) **章节来源** - [server/prisma/schema.prisma:1-472](file://server/prisma/schema.prisma#L1-L472) ### 缓存与存储 - Redis服务：提供连接、读写、哈希、计数器、过期控制与批量删除等能力，支持连接失败重试策略。 - 存储服务：统一OSS与本地存储接口，支持音频、视频、封面与通用文件的上传、下载、删除与签名URL生成。 ```mermaid classDiagram class RedisService { +isAvailable() boolean +get(key) string +set(key, value, ttl) boolean +getJSON(key) T +setJSON(key, value, ttl) boolean +del(key) boolean +delPattern(pattern) boolean +hset(key, field, value) boolean +hget(key, field) string +hgetall(key) Record +incr(key) number +expire(key, seconds) boolean +exists(key) boolean +testConnection() boolean +disconnect() void } class StorageService { +setStorageType(type) void +getStorageType() StorageType +uploadAudio(localPath, audioId) string +uploadVideo(localPath, videoId) string +uploadCover(localPath, bookId) string +uploadFile(localPath, category, id) string +uploadBuffer(buffer, objectKey, contentType) string +deleteFile(url) void +deleteDirectory(prefix, id) void +downloadFile(url) Buffer +getSignedUrl(url, expires) string +testConnection() boolean } RedisService <.. StorageService : "缓存/存储依赖" ``` **图表来源** - [server/src/services/redis.service.ts:1-274](file://server/src/services/redis.service.ts#L1-L274) - [server/src/services/storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278) **章节来源** - [server/src/services/redis.service.ts:246-255](file://server/src/services/redis.service.ts#L246-L255) - [server/src/services/storage.service.ts:252-272](file://server/src/services/storage.service.ts#L252-L272) ### TTS与视频生成 - TTS服务：支持阿里云百炼、MiniMax与Mock三种提供商，具备文本分段、并发合成、云端URL处理、LRC歌词生成与AI摘要能力。 - 视频生成：基于FFmpeg实现图片+音频合成、Ken Burns效果、字幕叠加与背景音乐混音。 ```mermaid sequenceDiagram participant Client as "客户端" participant TTS as "TTS服务" participant Provider as "TTS提供商" participant Merge as "音频合并" participant Store as "存储服务" Client->>TTS : 生成音频请求 TTS->>Provider : 分段合成 Provider-->>TTS : 音频片段/云端URL TTS->>Merge : 合并音频 Merge-->>TTS : 输出MP3 TTS->>Store : 上传到OSS/本地 Store-->>TTS : 返回访问URL TTS-->>Client : 返回音频URL ``` **图表来源** - [server/src/modules/tts/tts.service.ts:200-280](file://server/src/modules/tts/tts.service.ts#L200-L280) - [server/src/modules/video-generator/video-generator.ffmpeg.ts:23-118](file://server/src/modules/video-generator/video-generator.ffmpeg.ts#L23-L118) **章节来源** - [server/src/modules/tts/tts.service.ts:160-190](file://server/src/modules/tts/tts.service.ts#L160-L190) - [server/src/modules/video-generator/video-generator.ffmpeg.ts:23-118](file://server/src/modules/video-generator/video-generator.ffmpeg.ts#L23-L118) ### Docker容器化与Nginx反向代理 - Docker Compose：启动nginx容器，挂载bookapi.conf配置，将宿主机80端口映射到容器80端口。 - Nginx配置：将bookapi.rrbrr.com域名的所有请求代理到host.docker.internal:3000（即宿主机的3000端口）。 ```mermaid graph TB subgraph "宿主机" HostPort["端口 80 -> 容器 80"] Conf["bookapi.conf"] App["后端应用:3000"] end subgraph "Docker容器" Nginx["nginx:latest"] end HostPort --> Nginx Conf --> Nginx Nginx --> App ``` **图表来源** - [docker-nginx/docker-compose.yml:1-12](file://docker-nginx/docker-compose.yml#L1-L12) - [docker-nginx/bookapi.conf:1-15](file://docker-nginx/bookapi.conf#L1-L15) **章节来源** - [docker-nginx/docker-compose.yml:1-12](file://docker-nginx/docker-compose.yml#L1-L12) - [docker-nginx/bookapi.conf:1-15](file://docker-nginx/bookapi.conf#L1-L15) ## 依赖关系分析 - 后端依赖：Koa、Prisma、ioredis、axios、bull队列、langchain生态、ffmpeg等。 - 前端依赖：uni-app、Pinia、Vue3、vite等。 - 部署依赖：PM2、Nginx、Docker、MySQL、Redis。 ```mermaid graph TB BE_PKG["server/package.json 依赖"] FE_PKG["my-uniapp-vue3/package.json 依赖"] BE_PKG --> Koa["@koa/*"] BE_PKG --> Prisma["@prisma/*"] BE_PKG --> Redis["ioredis"] BE_PKG --> FFmpeg["fluent-ffmpeg"] BE_PKG --> LangChain["@langchain/*"] BE_PKG --> Bull["bull"] BE_PKG --> Axios["axios"] FE_PKG --> UniApp["@dcloudio/uni-app"] FE_PKG --> Pinia["pinia"] FE_PKG --> Vue["vue"] FE_PKG --> Vite["vite"] ``` **图表来源** - [server/package.json:11-44](file://server/package.json#L11-L44) - [my-uniapp-vue3/package.json:39-63](file://my-uniapp-vue3/package.json#L39-L63) **章节来源** - [server/package.json:11-44](file://server/package.json#L11-L44) - [my-uniapp-vue3/package.json:39-63](file://my-uniapp-vue3/package.json#L39-L63) ## 性能考虑 - 缓存策略：对用户信息、音色列表、书籍详情、热门书籍与会员权益进行缓存，减少数据库压力。 - 并发与限流：全局限流中间件可按需启用；队列处理长耗时任务（如音频生成）。 - 存储优化：OSS直传与签名URL缩短响应路径；本地存储仅用于开发环境。 - FFmpeg参数：使用libx264编码、合理CRF与AAC音频质量，平衡体积与清晰度。 [本节为通用指导，无需具体文件引用] ## 故障排除指南 - 后端无法启动 - 检查端口占用与环境变量文件是否存在。 - 查看PM2日志与后端服务状态。 - 前端无法访问 - 检查Nginx配置语法与站点启用状态。 - 查看Nginx访问/错误日志。 - 数据库连接失败 - 检查MySQL服务状态与连接配置。 - 使用Prisma迁移命令同步数据库结构。 - Redis连接异常 - 检查Redis服务状态与连接参数。 - 使用ping命令测试连通性。 - FFmpeg处理失败 - 确认系统已安装FFmpeg并可被fluent-ffmpeg调用。 - 检查输入文件路径与权限。 **章节来源** - [DEPLOY.md:199-250](file://DEPLOY.md#L199-L250) - [DEPLOY_PROD.md:318-392](file://DEPLOY_PROD.md#L318-L392) ## 结论 通过本指南，您可以在开发、测试与生产环境中快速搭建AI有声书生成平台。建议在开发环境使用本地MySQL与Redis，在生产环境采用Docker容器化部署并结合Nginx反向代理与PM2进程管理，确保高可用与可扩展性。定期验证数据库迁移、缓存与存储连接，并建立完善的日志与监控体系。 [本节为总结性内容，无需具体文件引用] ## 附录 ### 环境变量配置模板（后端） - 服务配置：端口、环境模式 - 数据库：DATABASE_URL（MySQL） - JWT：JWT_SECRET、JWT_EXPIRES_IN - TTS提供商：DASHSCOPE_*、MINIMAX_*等 - Redis：REDIS_HOST、REDIS_PORT、REDIS_PASSWORD、REDIS_DB - 存储：STORAGE_TYPE（oss/local）、OSS_*配置 **章节来源** - [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117) - [DEPLOY_PROD.md:105-144](file://DEPLOY_PROD.md#L105-L144) ### 数据库初始化脚本 - 使用Prisma生成客户端与迁移： - npx prisma generate - npx prisma migrate deploy - 初始化订阅套餐数据：应用启动时自动完成。 **章节来源** - [server/src/app.ts:153-155](file://server/src/app.ts#L153-L155) - [DEPLOY_PROD.md:291-294](file://DEPLOY_PROD.md#L291-L294) ### 缓存配置 - 常用缓存键前缀与TTL： - 用户信息：user:*（300秒） - 音色列表：voice:list（3600秒） - 书籍详情：book:detail:*（600秒） - 热门书籍：book:hot:*（300秒） - 会员权益：member:benefits:*（3600秒） **章节来源** - [server/src/middleware/cache.ts:67-97](file://server/src/middleware/cache.ts#L67-L97) ### 开发工具链与IDE设置 - 前端：HBuilderX/VSCodium，支持uni-app热更新与多端编译。 - 后端：Node.js 18+，TypeScript，PM2用于进程管理。 - 调试：启用Sentry错误监控与Winston日志记录。 **章节来源** - [README.md:18-30](file://README.md#L18-L30) - [server/src/app.ts:64-68](file://server/src/app.ts#L64-L68) ### 环境验证步骤 - 后端健康检查：访问 /api/health - 前端静态资源：访问根路径确认H5页面加载 - Nginx状态：systemctl status nginx - Redis连接：redis-cli ping - 数据库连接：mysql -u root -p -e 'SELECT 1;' **章节来源** - [DEPLOY.md:147-159](file://DEPLOY.md#L147-L159) - [DEPLOY_PROD.md:241-245](file://DEPLOY_PROD.md#L241-L245)