# 调试技巧

<cite>
**本文档引用的文件**
- [README.md](file://README.md)
- [API.md](file://docs/API.md)
- [app-troubleshooting.md](file://docs/app-troubleshooting.md)
- [debug.ts](file://my-uniapp-vue3/src/utils/debug.ts)
- [request.ts](file://my-uniapp-vue3/src/utils/request.ts)
- [logger.service.ts](file://server/src/services/logger.service.ts)
- [errorHandler.ts](file://server/src/middleware/errorHandler.ts)
- [index.ts](file://server/src/services/llm/index.ts)
- [tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [video-generator.service.ts](file://server/src/modules/video-generator/video-generator.service.ts)
- [ffmpeg.processor.ts](file://server/src/services/ffmpeg.processor.ts)
- [langgraph-controller.ts](file://server/src/modules/book-generator/langgraph-controller.ts)
</cite>

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

## 简介
本调试技巧文档面向AI有声书生成平台的前端、后端、数据库、AI服务与媒体处理链路，提供系统化的调试方法论与实操步骤，涵盖：
- 前端调试：Vue DevTools、网络请求、性能分析
- 后端调试：Node.js调试器、日志分析、错误追踪
- 数据库调试：查询优化、索引分析、事务调试
- AI服务调试：LangGraph、LLM调用监控、模型输出分析
- 媒体处理调试：FFmpeg参数、音频格式转换、视频生成
- 第三方服务调试：API调用、SDK问题、服务可用性监控
- 常见问题诊断、性能瓶颈分析与生产问题快速定位

## 项目结构
该平台采用前后端分离架构，前端基于 uniapp + Vue 3 + TypeScript，后端基于 Node.js + Koa，使用 FFmpeg 进行媒体处理，并通过多供应商 TTS 与 LLM 提供 AI 能力。

```mermaid
graph TB
subgraph "前端(uniapp)"
UI["页面与组件<br/>store/页面/工具"]
Utils["工具函数<br/>request.ts/debug.ts"]
end
subgraph "后端(Node.js/Koa)"
API["路由与控制器<br/>langgraph-controller.ts"]
Services["业务服务<br/>tts.service.ts<br/>video-generator.service.ts"]
LLM["LLM适配层<br/>llm/index.ts"]
Media["媒体处理<br/>ffmpeg.processor.ts"]
Logger["日志与错误<br/>logger.service.ts<br/>errorHandler.ts"]
end
subgraph "基础设施"
DB["数据库<br/>Prisma/MongoDB"]
Storage["对象存储/OSS"]
Providers["TTS/LLM提供商"]
end
UI --> Utils
Utils --> API
API --> Services
Services --> LLM
Services --> Media
Services --> DB
Services --> Storage
API --> Logger
LLM --> Providers
```

图表来源
- [README.md:31-52](file://README.md#L31-L52)
- [langgraph-controller.ts:1-800](file://server/src/modules/book-generator/langgraph-controller.ts#L1-L800)
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [video-generator.service.ts:1-556](file://server/src/modules/video-generator/video-generator.service.ts#L1-L556)
- [ffmpeg.processor.ts:1-379](file://server/src/services/ffmpeg.processor.ts#L1-L379)
- [logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)

章节来源
- [README.md:18-30](file://README.md#L18-L30)
- [API.md:1-499](file://docs/API.md#L1-L499)

## 核心组件
- 前端调试工具：全局调试模块 debug.ts，统一输出页面、参数、API请求/响应、错误日志；请求封装 request.ts，内置重试、缓存、超时与错误处理。
- 后端日志与错误：winston 日志器，HTTP 请求日志；统一错误中间件，抛出自定义 AppError 及其子类。
- AI服务：LLM 适配层，支持原始字符串调用、消息格式调用、工具调用与模型自动切换。
- 媒体处理：FFmpeg 处理器，支持远程文件下载、合并、格式转换、裁剪、音量调整与清理。
- 业务服务：TTS 服务（多供应商）、视频生成服务（含章节关联与进度推送）。

章节来源
- [debug.ts:1-305](file://my-uniapp-vue3/src/utils/debug.ts#L1-L305)
- [request.ts:1-207](file://my-uniapp-vue3/src/utils/request.ts#L1-L207)
- [logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [index.ts:1-362](file://server/src/services/llm/index.ts#L1-L362)
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [video-generator.service.ts:1-556](file://server/src/modules/video-generator/video-generator.service.ts#L1-L556)
- [ffmpeg.processor.ts:1-379](file://server/src/services/ffmpeg.processor.ts#L1-L379)

## 架构概览
下图展示从前端到后端、AI与媒体处理的关键交互路径，以及日志与错误处理贯穿全链路。

```mermaid
sequenceDiagram
participant FE as "前端页面"
participant Req as "请求封装<br/>request.ts"
participant Ctrl as "控制器<br/>langgraph-controller.ts"
participant Svc as "业务服务<br/>tts.service.ts / video-generator.service.ts"
participant LLM as "LLM适配<br/>llm/index.ts"
participant Media as "FFmpeg处理器<br/>ffmpeg.processor.ts"
participant Log as "日志中间件<br/>logger.service.ts"
FE->>Req : 发起API请求
Req->>Ctrl : 调用后端路由
Ctrl->>Svc : 触发业务逻辑
Svc->>LLM : LLM调用/工具调用
LLM-->>Svc : 返回文本/工具结果
Svc->>Media : 媒体处理(合并/转换/裁剪)
Media-->>Svc : 返回处理结果
Ctrl-->>Req : 统一响应格式
Req-->>FE : 展示结果/错误
Ctrl->>Log : 记录HTTP请求日志
```

图表来源
- [request.ts:35-168](file://my-uniapp-vue3/src/utils/request.ts#L35-L168)
- [langgraph-controller.ts:383-530](file://server/src/modules/book-generator/langgraph-controller.ts#L383-L530)
- [tts.service.ts:285-542](file://server/src/modules/tts/tts.service.ts#L285-L542)
- [video-generator.service.ts:157-312](file://server/src/modules/video-generator/video-generator.service.ts#L157-L312)
- [index.ts:155-201](file://server/src/services/llm/index.ts#L155-L201)
- [ffmpeg.processor.ts:69-183](file://server/src/services/ffmpeg.processor.ts#L69-L183)
- [logger.service.ts:75-102](file://server/src/services/logger.service.ts#L75-L102)

## 详细组件分析

### 前端调试：Vue DevTools、网络与性能
- 使用全局调试模块：
  - 页面加载与参数：initDebug() 在 onShow 时输出页面路径与参数，便于定位页面切换与参数传递问题。
  - API 请求/响应/错误：request.ts 调用 debugApiRequest/debugApiResponse/debugApiError，统一输出方法、URL、状态、耗时与页面上下文。
  - 全局错误捕获：initGlobalErrorHandler() 捕获未处理 Promise 与运行时错误，结合 uni.onError 输出堆栈信息。
- 性能分析：
  - 在 request.ts 中记录请求开始/结束时间，计算耗时，辅助识别慢接口。
  - 使用浏览器/开发者工具的性能面板观察主线程阻塞、重绘与 GC。
- App 端兼容性：
  - 遵循 app-troubleshooting.md 的条件编译与替代方案，避免直接使用 H5 特有 API。

```mermaid
flowchart TD
Start(["页面初始化"]) --> InitDebug["initDebug()<br/>注册页面/导航拦截器"]
InitDebug --> PageShow["onShow()<br/>输出页面路径与参数"]
PageShow --> Request["发起请求 request()"]
Request --> DebugReq["debugApiRequest()<br/>记录请求"]
Request --> Resp{"响应成功?"}
Resp --> |是| DebugResp["debugApiResponse()<br/>记录状态/耗时/数据"]
Resp --> |否| DebugErr["debugApiError()<br/>记录错误/耗时"]
DebugResp --> End(["完成"])
DebugErr --> End
```

图表来源
- [debug.ts:194-278](file://my-uniapp-vue3/src/utils/debug.ts#L194-L278)
- [request.ts:102-168](file://my-uniapp-vue3/src/utils/request.ts#L102-L168)

章节来源
- [debug.ts:1-305](file://my-uniapp-vue3/src/utils/debug.ts#L1-L305)
- [request.ts:1-207](file://my-uniapp-vue3/src/utils/request.ts#L1-L207)
- [app-troubleshooting.md:1-201](file://docs/app-troubleshooting.md#L1-L201)

### 后端调试：Node.js、日志与错误
- Node.js 调试器：
  - 使用 --inspect/--inspect-brk 启动，配合 VS Code/Chrome DevTools 断点调试。
  - 在关键业务入口（如 langgraph-controller.ts）设置断点，观察上下文、参数与分支逻辑。
- 日志分析：
  - winston 日志器输出到控制台与文件，区分 info/error/http 等级别；httpLogger 记录请求方法、URL、状态、耗时与 UA/IP。
  - 关注 error.log 与 http.log，结合业务日志定位问题根因。
- 错误追踪：
  - errorHandler 中间件统一捕获异常，返回 code/status，并在开发环境输出 stack。
  - 自定义 AppError/UnauthorizedError/ForbiddenError/NotFoundError/BadRequestError/QuotaExceededError，便于前端识别与提示。

```mermaid
sequenceDiagram
participant C as "客户端"
participant M as "中间件<br/>errorHandler.ts"
participant L as "日志<br/>logger.service.ts"
participant S as "业务逻辑"
C->>M : 发起请求
M->>S : 调用业务
S-->>M : 抛出异常
M-->>C : 统一错误响应(code,status)
M->>L : 记录错误日志(stack,meta)
```

图表来源
- [errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)
- [logger.service.ts:75-102](file://server/src/services/logger.service.ts#L75-L102)

章节来源
- [logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)

### 数据库调试：查询优化、索引与事务
- 查询优化：
  - 使用 Prisma/数据库客户端进行 EXPLAIN/EXPLAIN ANALYZE，关注全表扫描、缺失索引与 N+1 查询。
  - 对高频查询字段建立复合索引，如用户ID+状态、书ID+章节号等。
- 索引分析：
  - 通过慢查询日志与性能剖析工具识别低效 SQL，针对性补充索引。
- 事务调试：
  - 对跨表写入（如生成音频后更新章节与记录）使用事务包裹，失败时回滚。
  - 在并发场景下使用悲观锁/乐观锁，避免脏写与丢失更新。

[本节为通用指导，不直接分析具体文件]

### AI服务调试：LangGraph、LLM调用与模型输出
- LangGraph 调试：
  - 在 langgraph-controller.ts 中观察书籍创建流程：预估规模、配额检查、队列/同步模式、状态更新与错误回退。
  - 关键断点：生成前配额检查、队列加入/降级、生成完成/失败状态回写。
- LLM 调用监控：
  - index.ts 提供 callLLM/callLLMWithMessages/callLLMWithTools，均记录请求/响应日志与模型切换。
  - 使用 getToolCapableModel/getNextToolCapableModel 自动切换可用模型，避免单点故障。
- 模型输出分析：
  - 在 LLM 适配层打印消息摘要与响应片段，结合业务校验（如 JSON 解析、关键词匹配）进行降级处理。

```mermaid
sequenceDiagram
participant Ctrl as "控制器<br/>langgraph-controller.ts"
participant LLM as "LLM适配<br/>llm/index.ts"
participant Svc as "业务服务<br/>tts.service.ts"
participant DB as "数据库"
Ctrl->>LLM : callLLMWithMessages(书籍类型/难度推荐)
LLM-->>Ctrl : 返回JSON/文本
Ctrl->>Svc : 触发生成(队列/同步)
Svc->>DB : 更新书籍/章节状态
Svc-->>Ctrl : 返回生成结果
```

图表来源
- [langgraph-controller.ts:383-530](file://server/src/modules/book-generator/langgraph-controller.ts#L383-L530)
- [index.ts:155-201](file://server/src/services/llm/index.ts#L155-L201)
- [tts.service.ts:285-542](file://server/src/modules/tts/tts.service.ts#L285-L542)

章节来源
- [langgraph-controller.ts:1-800](file://server/src/modules/book-generator/langgraph-controller.ts#L1-L800)
- [index.ts:1-362](file://server/src/services/llm/index.ts#L1-L362)

### 媒体处理调试：FFmpeg参数、音频格式与视频生成
- FFmpeg 参数调试：
  - 使用 ffmpeg.processor.ts 的下载、合并、格式转换、裁剪、音量调整等方法，逐步验证命令参数与超时设置。
  - 通过日志输出确认下载完成、合并成功、上传完成与清理临时文件。
- 音频格式转换：
  - convertFormat 支持 mp3/wav/aac，可调整比特率；结合 getDuration 获取时长验证质量。
- 视频生成：
  - video-generator.service.ts 从章节音频与图片生成视频，支持带/不带背景音乐；失败时更新项目状态并推送 WebSocket 事件。

```mermaid
flowchart TD
A["输入URL数组"] --> D["downloadFile()<br/>远程下载到本地"]
D --> L["生成文件列表list.txt"]
L --> M["ffmpeg 合并音频"]
M --> U["上传到存储"]
U --> R["返回最终URL"]
D -.-> C["cleanupTempFiles()<br/>清理临时文件"]
M -.-> C
U -.-> C
```

图表来源
- [ffmpeg.processor.ts:69-122](file://server/src/services/ffmpeg.processor.ts#L69-L122)

章节来源
- [ffmpeg.processor.ts:1-379](file://server/src/services/ffmpeg.processor.ts#L1-L379)
- [video-generator.service.ts:157-312](file://server/src/modules/video-generator/video-generator.service.ts#L157-L312)

### 第三方服务调试：API调用、SDK与可用性监控
- API 调用调试：
  - 使用 request.ts 的统一请求封装，开启 showLoading、配置 retry/cache/timeout，结合 debugApiRequest/debugApiResponse 定位问题。
  - 参考 API.md 的接口规范，核对请求/响应格式与错误码。
- SDK 使用问题：
  - TTS 服务支持阿里云、MiniMax、Mock 多供应商，若出现额度限制或网络异常，自动切换下一个供应商。
- 服务可用性监控：
  - 通过日志与错误中间件记录异常，结合健康检查接口与告警策略，快速发现服务不可用。

章节来源
- [request.ts:1-207](file://my-uniapp-vue3/src/utils/request.ts#L1-L207)
- [API.md:1-499](file://docs/API.md#L1-L499)
- [tts.service.ts:163-190](file://server/src/modules/tts/tts.service.ts#L163-L190)

## 依赖分析
- 前端依赖后端接口与统一响应格式；请求封装依赖调试模块输出日志。
- 后端控制器依赖业务服务；业务服务依赖 LLM 与媒体处理；日志中间件贯穿请求生命周期。
- LLM 适配层依赖配置中心与模型列表，具备自动模型切换能力。
- 媒体处理依赖 FFmpeg 与存储服务，具备远程下载与上传能力。

```mermaid
graph LR
FE["前端<br/>request.ts/debug.ts"] --> API["后端路由<br/>langgraph-controller.ts"]
API --> SVC["业务服务<br/>tts.service.ts<br/>video-generator.service.ts"]
SVC --> LLM["LLM适配<br/>llm/index.ts"]
SVC --> MEDIA["FFmpeg处理器<br/>ffmpeg.processor.ts"]
API --> LOG["日志中间件<br/>logger.service.ts"]
API --> ERR["错误中间件<br/>errorHandler.ts"]
```

图表来源
- [request.ts:35-168](file://my-uniapp-vue3/src/utils/request.ts#L35-L168)
- [langgraph-controller.ts:383-530](file://server/src/modules/book-generator/langgraph-controller.ts#L383-L530)
- [tts.service.ts:285-542](file://server/src/modules/tts/tts.service.ts#L285-L542)
- [video-generator.service.ts:157-312](file://server/src/modules/video-generator/video-generator.service.ts#L157-L312)
- [index.ts:155-201](file://server/src/services/llm/index.ts#L155-L201)
- [ffmpeg.processor.ts:69-183](file://server/src/services/ffmpeg.processor.ts#L69-L183)
- [logger.service.ts:75-102](file://server/src/services/logger.service.ts#L75-L102)
- [errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)

## 性能考虑
- 前端：
  - 合理使用缓存（GET 请求缓存）、减少不必要的重渲染、拆分大组件。
- 后端：
  - 使用连接池、批量写入、异步处理（队列/WebSocket）降低阻塞；对热点接口进行限流与熔断。
- 媒体处理：
  - 控制并发与超时，合理设置 FFmpeg 参数与比特率；及时清理临时文件。
- AI 服务：
  - 优先使用支持工具调用的模型，必要时自动切换；对长文本分段处理，避免超时。

[本节为通用指导，不直接分析具体文件]

## 故障排查指南
- 常见问题诊断：
  - App 白屏/正则报错：marked 包版本问题，降级至旧版本。
  - App 端 window/document/localStorage 兼容性：使用条件编译或替代方案。
  - JSON 循环引用导致崩溃：避免对页面对象直接序列化。
  - CSS gap 不兼容：改用 margin 替代。
  - Android 手机网络请求无反应：检查平台判断与 API 地址拼接。
- 生产问题快速定位：
  - 查看 error.log/http.log，结合业务日志定位异常堆栈与请求上下文。
  - 使用统一错误响应 code/status，前端据此提示与重试。
  - 对 TTS/视频生成等耗时任务，通过状态轮询与 WebSocket 推送实时反馈。

章节来源
- [app-troubleshooting.md:1-201](file://docs/app-troubleshooting.md#L1-L201)
- [logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)

## 结论
通过统一的日志与错误处理、完善的前端调试工具、可切换的 AI 与媒体处理链路，以及针对 App 端的兼容性与性能优化，本平台能够高效定位与解决各类问题。建议在开发与生产环境中持续完善监控与告警，形成闭环的调试与运维体系。

[本节为总结，不直接分析具体文件]

## 附录
- API 接口参考：详见 API.md，涵盖认证、TTS、音频、会员、分享等模块的请求/响应规范与错误码。
- 快速启动与环境：参考 README.md 的技术栈与启动说明，确保 Node.js、数据库与 FFmpeg 环境正确配置。

章节来源
- [API.md:1-499](file://docs/API.md#L1-L499)
- [README.md:54-90](file://README.md#L54-L90)