# 快速开始

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [DEPLOY.md](file://docs/DEPLOY.md)
- [app-troubleshooting.md](file://docs/app-troubleshooting.md)
- [server/package.json](file://server/package.json)
- [my-uniapp-vue3/package.json](file://my-uniapp-vue3/package.json)
- [server/src/config/index.ts](file://server/src/config/index.ts)
- [server/src/config/models.json](file://server/src/config/models.json)
- [server/src/config/models-validator.ts](file://server/src/config/models-validator.ts)
- [server/src/models/index.ts](file://server/src/models/index.ts)
- [server/src/services/ffmpeg.processor.ts](file://server/src/services/ffmpeg.processor.ts)
- [my-uniapp-vue3/src/utils/config.ts](file://my-uniapp-vue3/src/utils/config.ts)
</cite>

## 目录
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：包含部署、故障排除等运维文档。

```mermaid
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](file://server/src/config/index.ts#L69-L117)
- [server/src/config/models.json:1-186](file://server/src/config/models.json#L1-L186)
- [server/src/models/index.ts:1-15](file://server/src/models/index.ts#L1-L15)
- [server/src/services/ffmpeg.processor.ts:194-378](file://server/src/services/ffmpeg.processor.ts#L194-L378)
- [my-uniapp-vue3/src/utils/config.ts:1-80](file://my-uniapp-vue3/src/utils/config.ts#L1-L80)

**章节来源**
- [README.md:31-52](file://README.md#L31-L52)

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

**章节来源**
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [server/src/models/index.ts:1-15](file://server/src/models/index.ts#L1-L15)
- [server/src/services/ffmpeg.processor.ts:194-378](file://server/src/services/ffmpeg.processor.ts#L194-L378)
- [my-uniapp-vue3/src/utils/config.ts:1-80](file://my-uniapp-vue3/src/utils/config.ts#L1-L80)

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

```mermaid
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](file://server/src/config/index.ts#L73-L93)
- [server/src/models/index.ts:1-15](file://server/src/models/index.ts#L1-L15)
- [server/src/services/ffmpeg.processor.ts:194-378](file://server/src/services/ffmpeg.processor.ts#L194-L378)

## 详细组件分析

### 后端启动流程
- 进入 server 目录，安装依赖后复制并编辑 .env，然后启动开发服务。
- 开发脚本使用 tsx watch 监听 TypeScript 源文件变化，自动重启服务。

```mermaid
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](file://README.md#L62-L75)
- [server/package.json:6-9](file://server/package.json#L6-L9)

**章节来源**
- [README.md:62-75](file://README.md#L62-L75)
- [server/package.json:6-9](file://server/package.json#L6-L9)

### 前端启动流程
- 进入 my-uniapp-vue3 目录，安装依赖后启动 H5 开发服务器。
- 支持多种小程序平台的开发与构建脚本。

```mermaid
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](file://README.md#L77-L90)
- [my-uniapp-vue3/package.json:4-37](file://my-uniapp-vue3/package.json#L4-L37)

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

### 环境变量与配置要点
- 服务端口与环境：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 进行批量可用性验证。

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

**图表来源**
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [server/src/config/models.json:1-186](file://server/src/config/models.json#L1-L186)

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

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

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

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

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

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

```mermaid
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](file://my-uniapp-vue3/src/utils/config.ts#L1-L80)

**章节来源**
- [my-uniapp-vue3/src/utils/config.ts:1-80](file://my-uniapp-vue3/src/utils/config.ts#L1-L80)

## 依赖关系分析
- 后端依赖：Koa、Prisma、LangChain、阿里云 OSS、Redis、FFmpeg（fluent-ffmpeg）、微信支付、Sentry 等。
- 前端依赖：uni-app、Vue 3、Pinia、marked、katex 等。

```mermaid
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](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)

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

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

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

**章节来源**
- [DEPLOY.md:445-558](file://docs/DEPLOY.md#L445-L558)
- [app-troubleshooting.md:1-201](file://docs/app-troubleshooting.md#L1-L201)

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

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

## 附录

### 环境要求与安装
- Node.js 18+
- MongoDB 6.0+（配置中存在 URI，但源码使用 Prisma 连接 MySQL）
- FFmpeg（用于音频处理）

**章节来源**
- [README.md:56-60](file://README.md#L56-L60)
- [DEPLOY.md:15-22](file://docs/DEPLOY.md#L15-L22)

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

**章节来源**
- [README.md:54-90](file://README.md#L54-L90)

### 关键环境变量说明
- 服务端口与环境：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](file://server/src/config/index.ts#L69-L117)
- [DEPLOY.md:118-143](file://docs/DEPLOY.md#L118-L143)

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

**章节来源**
- [server/src/config/models.json:1-186](file://server/src/config/models.json#L1-L186)
- [server/src/config/models-validator.ts:90-128](file://server/src/config/models-validator.ts#L90-L128)