Главная Обзор Помощь
Вход
caojunfei
/
audio_codebuddy
1
0
Ответвить 0
Файлы Задачи 0 Запросы на слияние 0 Вики
Ветка: master
Ветки Метки
audio_codebuddy
/
.qoder
/
repowiki
/
zh
/
content
/
快速开始.md

快速开始.md 12 KB
Постоянная ссылка История Исходник

快速开始

本文引用的文件

  • README.md
  • DEPLOY.md
  • app-troubleshooting.md
  • server/package.json
  • my-uniapp-vue3/package.json
  • server/src/config/index.ts
  • server/src/config/models.json
  • server/src/config/models-validator.ts
  • server/src/models/index.ts
  • server/src/services/ffmpeg.processor.ts
  • my-uniapp-vue3/src/utils/config.ts

目录

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

简介

本指南面向新加入的开发者，帮助你在约30分钟内完成环境准备、项目克隆、依赖安装与启动，并理解关键配置项与常见问题的排查方法。项目采用前后端分离架构：后端基于 Node.js 18 + Koa 2.x，数据库使用 MongoDB（项目配置中也包含 Prisma MySQL 客户端），前端基于 uniapp + Vue 3 + TypeScript，支持 H5 与微信小程序。

项目结构

  • 后端 server：包含模块化业务逻辑、中间件、配置与服务层，使用 Prisma 管理数据库连接。
  • 前端 my-uniapp-vue3：基于 uniapp 的跨端应用，支持 H5 与微信小程序。

  • 文档 docs：包含部署、故障排除等运维文档。

    graph TB
subgraph "后端"
S_CFG["配置<br/>server/src/config/index.ts"]
S_MOD["模型配置<br/>server/src/config/models.json"]
S_DB["数据库连接<br/>server/src/models/index.ts"]
S_FFMPEG["音频处理<br/>server/src/services/ffmpeg.processor.ts"]
end
subgraph "前端"
F_CFG["API 地址配置<br/>my-uniapp-vue3/src/utils/config.ts"]
end
F_CFG --> S_CFG
S_CFG --> S_DB
S_CFG --> S_FFMPEG
S_MOD --> S_CFG

图表来源

  • server/src/config/index.ts:69-117
  • server/src/config/models.json:1-186
  • server/src/models/index.ts:1-15
  • server/src/services/ffmpeg.processor.ts:194-378
  • my-uniapp-vue3/src/utils/config.ts:1-80

章节来源

  • README.md:31-52

核心组件

  • 后端配置中心：集中管理端口、数据库、JWT、阿里云百炼 TTS、模型列表与默认值。
  • 数据库连接：Prisma 客户端负责连接 MySQL（尽管配置中存在 MongoDB URI，但源码使用 Prisma 连接 MySQL）。
  • 音频处理：基于 FFmpeg 的合并、格式转换、音量调整等能力。
  • 前端 API 地址：根据运行平台自动选择开发/生产 API 地址。

章节来源

  • server/src/config/index.ts:69-117
  • server/src/models/index.ts:1-15
  • server/src/services/ffmpeg.processor.ts:194-378
  • my-uniapp-vue3/src/utils/config.ts:1-80

架构总览

后端通过 Koa 提供 REST API，前端通过 uniapp 在 H5/小程序环境下访问后端接口；音频生成与处理依赖 FFmpeg；配置与模型管理由后端集中维护。

graph TB
FE["前端应用<br/>H5/小程序"] --> BE["后端服务<br/>Koa + Prisma"]
BE --> DB["数据库<br/>MySQL (Prisma)"]
BE --> TTS["TTS 服务<br/>阿里云百炼/其他模型"]
BE --> FS["文件存储<br/>本地/对象存储"]
BE --> FFMPEG["FFmpeg 处理"]

图表来源

  • server/src/config/index.ts:73-93
  • server/src/models/index.ts:1-15
  • server/src/services/ffmpeg.processor.ts:194-378

详细组件分析

后端启动流程

  • 进入 server 目录，安装依赖后复制并编辑 .env，然后启动开发服务。

  • 开发脚本使用 tsx watch 监听 TypeScript 源文件变化，自动重启服务。

    sequenceDiagram
participant Dev as "开发者"
participant Shell as "终端"
participant NPM as "npm 脚本"
participant TSX as "tsx 监听"
participant Koa as "Koa 应用"
Dev->>Shell : 进入 server 目录
Shell->>NPM : npm install
Shell->>Shell : 复制 .env.example 为 .env
Shell->>NPM : npm run dev
NPM->>TSX : 启动监听
TSX->>Koa : 加载入口并启动
Koa-->>Dev : 服务就绪 (端口)

图表来源

  • README.md:62-75
  • server/package.json:6-9

章节来源

  • README.md:62-75
  • server/package.json:6-9

前端启动流程

  • 进入 my-uniapp-vue3 目录，安装依赖后启动 H5 开发服务器。

  • 支持多种小程序平台的开发与构建脚本。

    sequenceDiagram
participant Dev as "开发者"
participant Shell as "终端"
participant Uni as "uni 命令"
participant Browser as "浏览器/H5"
Dev->>Shell : 进入 my-uniapp-vue3
Shell->>Shell : npm install
Shell->>Uni : npm run dev : h5
Uni-->>Browser : 启动 H5 开发服务器

图表来源

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

章节来源

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

环境变量与配置要点

  • 服务端口与环境：PORT、NODE_ENV。
  • 数据库连接：MONGODB_URI（配置中存在，但源码使用 Prisma 连接 MySQL）。
  • JWT：JWT_SECRET、JWT_EXPIRES_IN。
  • 阿里云百炼 TTS：DASHSCOPE_API_KEY、DASHSCOPE_MODEL、DASHSCOPE_VOICE、DASHSCOPE_TTS_MODELS、DASHSCOPE_USE_REALTIME、DASHSCOPE_REALTIME_MODEL。

  • 模型配置：models.json 统一管理供应商、模型列表与默认值；可通过 models-validator.ts 进行批量可用性验证。

    flowchart TD
Start(["读取 .env"]) --> Port["解析端口与环境"]
Port --> DB["数据库连接配置"]
DB --> JWT["JWT 密钥与过期时间"]
JWT --> TTS["阿里云百炼 TTS 参数"]
TTS --> Models["模型配置加载"]
Models --> Done(["应用启动"])

图表来源

  • server/src/config/index.ts:69-117
  • server/src/config/models.json:1-186

章节来源

  • server/src/config/index.ts:69-117
  • server/src/config/models.json:1-186

FFmpeg 音频处理流程

  • 下载远程音频至本地临时目录，生成合并列表，执行合并/格式转换/音量调整等操作，最后上传并清理临时文件。

    flowchart TD
A["输入音频URL列表"] --> B["下载到本地临时目录"]
B --> C["生成合并列表文件"]
C --> D["执行合并/转换/调整"]
D --> E["上传输出文件"]
E --> F["清理临时文件"]
F --> G["返回处理结果"]

图表来源

  • server/src/services/ffmpeg.processor.ts:194-378

章节来源

  • server/src/services/ffmpeg.processor.ts:194-378

前端 API 地址选择逻辑

  • 根据运行平台（H5/小程序/App）与环境变量自动选择 API 基础地址，开发环境默认使用反向代理路径，生产环境使用固定域名。

    flowchart TD
P["检测运行平台"] --> Env{"是否生产环境?"}
Env --> |是| Prod["使用固定域名"]
Env --> |否| H5Check{"是否 H5 且在小程序模拟器?"}
H5Check --> |是| DevWeb["使用 Web 地址"]
H5Check --> |否| DevRel["使用相对路径 (反向代理)"]
Prod --> Out["返回 API 基础地址"]
DevWeb --> Out
DevRel --> Out

图表来源

  • my-uniapp-vue3/src/utils/config.ts:1-80

章节来源

  • my-uniapp-vue3/src/utils/config.ts:1-80

依赖关系分析

  • 后端依赖：Koa、Prisma、LangChain、阿里云 OSS、Redis、FFmpeg（fluent-ffmpeg）、微信支付、Sentry 等。

  • 前端依赖：uni-app、Vue 3、Pinia、marked、katex 等。

    graph LR
S_Pkg["server/package.json"] --> Deps["后端依赖集合"]
F_Pkg["my-uniapp-vue3/package.json"] --> F_Deps["前端依赖集合"]
Deps --> S_FFMPEG["FFmpeg 相关"]
Deps --> S_PRISMA["Prisma/MySQL"]
Deps --> S_LANG["LangChain/OpenAI"]
Deps --> S_OSS["阿里云 OSS"]
Deps --> S_REDIS["Redis"]
Deps --> S_SENTRY["Sentry"]

图表来源

  • server/package.json:11-44
  • my-uniapp-vue3/package.json:39-63

章节来源

  • server/package.json:11-44
  • my-uniapp-vue3/package.json:39-63

性能注意事项

  • 使用 Redis 缓存可提升响应速度（可选）。
  • 合理设置上传文件大小限制与超时时间。
  • 对于大量音频处理任务，建议使用队列与异步处理，避免阻塞主线程。

[本节为通用指导，无需列出具体文件来源]

故障排除指南

  • MongoDB 连接失败：检查服务状态、认证凭据与日志；按需重置用户。
  • FFmpeg 找不到：确认系统已安装并加入 PATH。
  • 端口被占用：查找占用进程并释放，或修改 .env 中的 PORT。
  • 跨域问题：在后端配置允许的源与凭证。
  • 前端 App 白屏：marked 版本过高导致正则不兼容，需降级到旧版本。
  • 平台判断错误：修复前端 config.ts 中平台名大小写不一致的问题。
  • JSON 循环引用：避免对包含循环引用的对象直接序列化。
  • CSS gap 兼容性：App 端不支持 gap，使用 margin 替代。

章节来源

  • DEPLOY.md:445-558
  • app-troubleshooting.md:1-201

结论

按照本指南完成环境准备与启动后，你将拥有可运行的后端服务与前端 H5 页面。后续可根据需要完善 .env 配置、接入真实 TTS 服务与对象存储，并结合文档进行部署与运维。

[本节为总结性内容，无需列出具体文件来源]

附录

环境要求与安装

  • Node.js 18+
  • MongoDB 6.0+（配置中存在 URI，但源码使用 Prisma 连接 MySQL）
  • FFmpeg（用于音频处理）

章节来源

  • README.md:56-60
  • DEPLOY.md:15-22

项目克隆与启动步骤

  • 克隆仓库后，分别进入 server 与 my-uniapp-vue3 目录安装依赖。
  • 后端：复制 .env.example 为 .env，然后 npm run dev。
  • 前端：npm install 后 npm run dev:h5。

章节来源

  • README.md:54-90

关键环境变量说明

  • 服务端口与环境：PORT、NODE_ENV。
  • 数据库：MONGODB_URI（配置中存在，源码使用 Prisma 连接 MySQL）。
  • JWT：JWT_SECRET、JWT_EXPIRES_IN。
  • 阿里云百炼 TTS：DASHSCOPE_API_KEY、DASHSCOPE_MODEL、DASHSCOPE_VOICE、DASHSCOPE_TTS_MODELS、DASHSCOPE_USE_REALTIME、DASHSCOPE_REALTIME_MODEL。
  • 应用 URL：APP_URL。

章节来源

  • server/src/config/index.ts:69-117
  • DEPLOY.md:118-143

模型配置与验证

  • models.json 统一管理供应商与模型列表，默认模型与音色。
  • models-validator.ts 支持批量验证模型可用性并生成报告。

章节来源

  • server/src/config/models.json:1-186
  • server/src/config/models-validator.ts:90-128