Inicio Explorar Ayuda
Iniciar sesión
caojunfei
/
audio_codebuddy
1
0
Fork 0
Archivos Incidencias 0 Pull Requests 0 Wiki
Rama: master
Ramas Etiquetas
audio_codebuddy
/
.qoder
/
repowiki
/
zh
/
content
/
系统架构
/
系统架构.md

系统架构.md 18 KB
Permalink Histórico Raw

系统架构

本文引用的文件

  • README.md
  • my-uniapp-vue3/package.json
  • server/package.json
  • server/src/app.ts
  • deploy-package/server/app.js
  • server/src/modules/auth/auth.controller.ts
  • server/src/modules/tts/tts.controller.ts
  • server/src/modules/member/member.controller.ts
  • server/src/modules/book-generator/book-generator.controller.ts
  • server/src/modules/video-generator/video-generator.controller.ts
  • server/src/services/ffmpeg.processor.ts
  • server/src/config/index.ts
  • server/prisma/schema.prisma
  • my-uniapp-vue3/src/main.ts
  • my-uniapp-vue3/src/utils/request.ts
  • docker-nginx/docker-compose.yml
  • docker-nginx/bookapi.conf

目录

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

引言

本系统是一个“AI有声书生成平台”，采用前后端分离架构：前端基于 uniapp + Vue 3 + TypeScript，后端基于 Koa.js，数据库采用 Prisma + MySQL，音频处理通过 FFmpeg 与对象存储结合。系统支持 TTS 文本转音频、会员体系、书籍批量生成（内容-音频-视频）、视频生成与合并、播放器与播放列表、搜索与偏好设置等能力。

项目结构

  • 前端（uniapp + Vue 3 + TypeScript）
    • 应用入口与状态管理：src/main.ts、store/
    • 页面与组件：src/pages、src/components
    • 工具与网络请求：src/utils/request.ts、config.ts 等
    • 构建脚本：my-uniapp-vue3/package.json
  • 后端（Koa.js + TypeScript）
    • 应用入口与中间件：server/src/app.ts
    • 模块化路由：server/src/modules//.controller.ts
    • 服务层与工具：server/src/services/*
    • 配置与模型：server/src/config、server/prisma/schema.prisma
    • 构建脚本：server/package.json
  • 部署与反向代理
    • Nginx 反代：docker-nginx/bookapi.conf、docker-compose.yml

  • 文档与说明

    • README.md 展示技术栈、API 与快速开始

      graph TB
subgraph "前端(uniapp)"
FE_App["应用入口<br/>src/main.ts"]
FE_Utils["网络请求<br/>src/utils/request.ts"]
FE_Router["页面与组件<br/>src/pages/*, src/components/*"]
end
subgraph "后端(Koa.js)"
BE_App["应用入口<br/>server/src/app.ts"]
BE_Modules["业务模块路由<br/>modules/*/*.controller.ts"]
BE_Services["服务与工具<br/>services/*"]
BE_DB["数据模型<br/>prisma/schema.prisma"]
BE_Config["配置<br/>src/config/index.ts"]
end
subgraph "基础设施"
Nginx["Nginx 反向代理<br/>docker-nginx/bookapi.conf"]
Docker["Docker Compose<br/>docker-compose.yml"]
Storage["对象存储/本地存储"]
FFmpeg["FFmpeg 处理器<br/>services/ffmpeg.processor.ts"]
end
FE_App --> FE_Utils
FE_Router --> FE_Utils
FE_Utils --> Nginx
Nginx --> BE_App
BE_App --> BE_Modules
BE_Modules --> BE_Services
BE_Services --> BE_DB
BE_Services --> Storage
BE_Services --> FFmpeg
Docker --> Nginx

图表来源

  • server/src/app.ts:57-130
  • my-uniapp-vue3/src/main.ts:10-31
  • my-uniapp-vue3/src/utils/request.ts:35-99
  • docker-nginx/bookapi.conf:1-15

章节来源

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

核心组件

  • 前端应用（uniapp + Vue 3 + TypeScript）
    • 使用 Pinia 管理状态，提供 H5 与微信小程序等多端运行
    • 通过统一请求封装与调试日志，支持重试、缓存与错误提示
  • 后端服务（Koa.js）
    • 中间件链路：错误处理、CORS、日志、安全防护、限流、性能监控
    • 路由按模块划分：认证、TTS、会员、播放器、收藏、偏好、搜索、分类、评论、通知、模板、BGM、音频编辑、书籍生成、视频生成等
    • 配置集中管理：端口、JWT、DashScope TTS、模型列表、上传目录等
    • 数据持久化：Prisma + MySQL，模型覆盖用户、书籍、章节、音频、视频、订单、订阅等
  • 音频处理（FFmpeg）
    • 支持远程 URL 下载、合并、格式转换、裁剪、音量调整、音视频合并等
    • 自动上传至对象存储或本地存储
  • 部署与反向代理
    • Nginx 反向代理到后端 3000 端口，便于域名访问与 HTTPS 协议透传

章节来源

  • my-uniapp-vue3/src/main.ts:10-31
  • my-uniapp-vue3/src/utils/request.ts:35-99
  • server/src/app.ts:64-130
  • server/src/config/index.ts:69-117
  • server/prisma/schema.prisma:10-472
  • server/src/services/ffmpeg.processor.ts:24-379
  • docker-nginx/bookapi.conf:1-15

架构总览

系统采用“前端 uniapp + 后端 Koa + 数据库 MySQL + 第三方服务/工具”的分层架构。前端通过 HTTP/HTTPS 与后端交互；后端通过 Prisma 访问 MySQL；音频处理通过 FFmpeg 与对象存储协同；Nginx 作为反向代理统一入口。

graph TB
Client["客户端(H5/小程序)"]
FE["前端 uniapp 应用"]
API["Koa 后端服务"]
DB["MySQL 数据库"]
OSS["对象存储(本地/阿里云OSS)"]
FFMPEG["FFmpeg 处理器"]
Nginx["Nginx 反向代理"]
Client --> FE
FE --> Nginx
Nginx --> API
API --> DB
API --> OSS
API --> FFMPEG
FFMPEG --> OSS

图表来源

  • server/src/app.ts:133-194
  • server/src/services/ffmpeg.processor.ts:24-379
  • docker-nginx/bookapi.conf:1-15

详细组件分析

前端组件分析（uniapp + Vue 3 + TypeScript）

  • 应用入口与状态
    • 创建 SSR App、注册 Pinia，初始化用户状态
  • 网络请求封装
    • 统一基地址、Token 注入、重试、缓存、超时、错误处理与登录态失效跳转

  • 页面与组件

    • 页面路由、播放器、骨架屏、下载组件等

      sequenceDiagram
participant U as "用户"
participant P as "前端页面"
participant R as "请求封装"
participant N as "Nginx 反代"
participant S as "Koa 后端"
U->>P : 触发操作
P->>R : request(url, options)
R->>R : 注入 Authorization/缓存/重试
R->>N : HTTP 请求
N->>S : 反向代理转发
S-->>R : 返回 {code,data}
R-->>P : 成功/失败处理与提示
P-->>U : 更新界面

图表来源

  • my-uniapp-vue3/src/utils/request.ts:35-99
  • docker-nginx/bookapi.conf:6-13
  • server/src/app.ts:92-130

章节来源

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

后端组件分析（Koa.js + 模块化路由）

  • 应用入口与中间件
    • 错误处理、Sentry、性能监控、Winston 日志、CORS、安全防护、限流、BodyParser、静态文件挂载
  • 路由模块
    • 认证、TTS、会员、播放器、收藏、偏好、搜索、分类、评论、通知、模板、BGM、音频编辑、书籍生成、视频生成等

  • 配置与模型

    • 端口、JWT、DashScope TTS、模型列表、上传目录等

    • Prisma 模型覆盖用户、书籍、章节、音频、视频、订单、订阅等

      classDiagram
class KoaApp {
+中间件链
+路由注册
+静态文件
}
class AuthController {
+发送验证码
+手机号登录
+获取/更新用户信息
}
class TTSController {
+获取音色/服务商
+异步生成音频
+预览音色
+下载信息/批量下载
}
class MemberController {
+权益信息
+会员状态
+创建订单
+模拟支付
+订单列表
}
class BookGenController {
+批量生成书籍
+取消任务
+查询状态
}
class VideoGenController {
+项目管理
+生成视频
+素材管理
+从书籍生成项目
}
KoaApp --> AuthController : "注册路由"
KoaApp --> TTSController : "注册路由"
KoaApp --> MemberController : "注册路由"
KoaApp --> BookGenController : "注册路由"
KoaApp --> VideoGenController : "注册路由"

图表来源

  • server/src/app.ts:64-130
  • server/src/modules/auth/auth.controller.ts:10-94
  • server/src/modules/tts/tts.controller.ts:12-274
  • server/src/modules/member/member.controller.ts:9-90
  • server/src/modules/book-generator/book-generator.controller.ts:24-199
  • server/src/modules/video-generator/video-generator.controller.ts:28-244

章节来源

  • server/src/app.ts:64-130
  • server/src/config/index.ts:69-117
  • server/prisma/schema.prisma:10-472

音频处理流程（FFmpeg）

  • 支持的功能
    • 下载远程文件、合并音频、音视频合并、获取时长、格式转换、裁剪、音量调整
    • 自动清理临时文件，上传至对象存储

  • 流程示意

    flowchart TD
Start(["进入处理"]) --> CheckURL["校验输入URL/本地路径"]
CheckURL --> Download["下载到本地临时目录"]
Download --> DecideOp{"操作类型？"}
DecideOp --> |合并音频| Merge["构建文件列表并执行合并"]
DecideOp --> |音视频合并| MergeAV["合并音视频(可选BGM混音)"]
DecideOp --> |获取时长| Probe["ffprobe 获取时长"]
DecideOp --> |格式转换| Convert["按目标格式转换"]
DecideOp --> |裁剪| Trim["按时间段裁剪"]
DecideOp --> |音量调整| Volume["按倍数调整音量"]
Merge & MergeAV & Probe & Convert & Trim & Volume --> Upload["上传至对象存储"]
Upload --> Cleanup["清理临时文件"]
Cleanup --> End(["结束"])

图表来源

  • server/src/services/ffmpeg.processor.ts:24-379

章节来源

  • server/src/services/ffmpeg.processor.ts:24-379

微服务化模块划分策略

  • 认证模块：手机号登录、验证码、用户信息维护
  • TTS 模块：音色/服务商查询、异步生成、预览、下载与批量下载
  • 会员模块：权益、状态、订单、模拟支付、订单列表
  • 书籍生成模块：内容生成、音频生成、音频合并、视频生成、视频合并、批量任务与取消
  • 视频生成模块：项目管理、素材管理、从书籍生成项目
  • 其他模块：播放器、收藏、偏好、搜索、分类、评论、通知、模板、BGM、音频编辑、历史、草稿、发布、签到、订阅、支付、反馈等

章节来源

  • server/src/modules/auth/auth.controller.ts:10-94
  • server/src/modules/tts/tts.controller.ts:12-274
  • server/src/modules/member/member.controller.ts:9-90
  • server/src/modules/book-generator/book-generator.controller.ts:24-199
  • server/src/modules/video-generator/video-generator.controller.ts:28-244

部署架构（Docker + Nginx 反向代理）

  • Docker Compose 启动 Nginx，监听 80 端口，将请求代理到 host.docker.internal:3000
  • 后端服务监听 3000 端口，提供健康检查与静态资源服务

  • 建议在生产环境增加 HTTPS、负载均衡与多实例部署

    graph TB
subgraph "容器编排"
D["docker-compose.yml"]
N["Nginx 容器"]
S["后端服务容器"]
end
D --> N
D --> S
N --> S

图表来源

  • docker-nginx/docker-compose.yml:1-12
  • docker-nginx/bookapi.conf:6-13
  • deploy-package/server/app.js:82-97

章节来源

  • docker-nginx/docker-compose.yml:1-12
  • docker-nginx/bookapi.conf:1-15
  • deploy-package/server/app.js:82-97

依赖分析

  • 前端依赖
    • uni-app 生态、Vue 3、Pinia、vconsole、marked、katex 等
  • 后端依赖
    • Koa 生态、@koa/router、@koa/bodyparser、@koa/cors、Prisma、LangChain、Sentry、Bull 队列、Redis、OpenAI、阿里云 OSS、FFmpeg 等

  • 数据模型

    • 用户、书籍、章节、音频、视频、订单、订阅、播放记录、收藏、评论、通知、搜索历史、签到、播放列表、草稿、发布任务、素材、反馈等

      graph LR
FE["前端 uniapp"] --> API["Koa 后端"]
API --> PRISMA["Prisma"]
PRISMA --> MYSQL["MySQL"]
API --> REDIS["Redis"]
API --> OSS["对象存储"]
API --> FFMPEG["FFmpeg"]
API --> LLM["LangChain/LangGraph"]

图表来源

  • server/package.json:11-44
  • server/prisma/schema.prisma:10-472
  • server/src/services/ffmpeg.processor.ts:24-379

章节来源

  • server/package.json:11-44
  • server/prisma/schema.prisma:10-472

性能考虑

  • 前端
    • 使用请求缓存与重试，减少重复请求与网络波动影响
    • 在 H5 环境可按需开启 vConsole 调试
  • 后端
    • 中间件包含性能监控与日志，建议启用限流与安全防护
    • 音频/视频处理为 CPU 密集型，建议配合队列与异步处理
    • 对象存储与本地存储可按需切换，注意带宽与成本
  • 部署
    • Nginx 反代简化部署与域名管理，建议横向扩展与负载均衡

故障排查指南

  • 常见问题定位
    • 健康检查：访问 /health 确认服务可用
    • 日志：查看后端启动日志与错误日志
    • 前端网络：检查请求封装中的错误提示与重试逻辑
  • 常见错误与处理
    • 登录态失效：前端检测到 401 自动清空 token 并跳转登录
    • 请求过于频繁：后端返回 429，前端提示稍后再试
    • 服务器错误：后端返回 5xx，前端提示服务器错误
  • FFmpeg 处理
    • 检查临时目录权限与磁盘空间
    • 确认远程 URL 可访问与超时设置合理

章节来源

  • server/src/app.ts:92-98
  • my-uniapp-vue3/src/utils/request.ts:135-159
  • server/src/services/ffmpeg.processor.ts:346-375

结论

该系统以 uniapp 实现跨端一致性体验，以 Koa.js 提供轻量且模块化的后端服务，以 Prisma + MySQL 保障数据结构清晰与扩展性，以 FFmpeg 与对象存储支撑音频/视频处理与分发。通过 Nginx 反向代理与容器化部署，具备良好的可运维性与扩展性。后续可在生产环境引入负载均衡、CDN、更完善的限流与监控体系，并持续优化音频/视频处理的并发与成本。

附录

  • 快速开始与环境要求
    • Node.js >= 18、MySQL >= 6.0、FFmpeg（用于音频处理）
  • API 示例（节选）
    • 认证：发送验证码、手机号登录、获取用户信息
    • TTS：音色列表、生成音频、预览音色、下载信息与批量下载
    • 会员：权益信息、会员状态、创建订单、模拟支付、订单列表
    • 书籍生成：批量生成、取消任务、查询状态
    • 视频生成：项目管理、生成视频、素材管理、从书籍生成项目

章节来源

  • README.md:56-113
  • server/src/modules/auth/auth.controller.ts:10-94
  • server/src/modules/tts/tts.controller.ts:12-274
  • server/src/modules/member/member.controller.ts:9-90
  • server/src/modules/book-generator/book-generator.controller.ts:24-199
  • server/src/modules/video-generator/video-generator.controller.ts:28-244