audio_codebuddy/.qoder/repowiki/zh/content/开发指南/调试技巧.md

调试技巧

本文档引用的文件

• README.md
• API.md
• app-troubleshooting.md
• debug.ts
• request.ts
• logger.service.ts
• errorHandler.ts
• index.ts
• tts.service.ts
• video-generator.service.ts
• ffmpeg.processor.ts
• langgraph-controller.ts

目录

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 能力。

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
• langgraph-controller.ts:1-800
• tts.service.ts:1-715
• video-generator.service.ts:1-556
• ffmpeg.processor.ts:1-379
• logger.service.ts:1-114
• errorHandler.ts:1-67

章节来源

• README.md:18-30
• API.md:1-499

核心组件

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

章节来源

• debug.ts:1-305
• request.ts:1-207
• logger.service.ts:1-114
• errorHandler.ts:1-67
• index.ts:1-362
• tts.service.ts:1-715
• video-generator.service.ts:1-556
• ffmpeg.processor.ts:1-379

架构概览

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

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
• langgraph-controller.ts:383-530
• tts.service.ts:285-542
• video-generator.service.ts:157-312
• index.ts:155-201
• ffmpeg.processor.ts:69-183
• logger.service.ts:75-102

详细组件分析

前端调试：Vue DevTools、网络与性能

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

• App 端兼容性：

  • 遵循 app-troubleshooting.md 的条件编译与替代方案，避免直接使用 H5 特有 API。

    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
• request.ts:102-168

章节来源

• debug.ts:1-305
• request.ts:1-207
• app-troubleshooting.md:1-201

后端调试：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，便于前端识别与提示。

    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
• logger.service.ts:75-102

章节来源

• logger.service.ts:1-114
• errorHandler.ts:1-67

数据库调试：查询优化、索引与事务

• 查询优化：
  • 使用 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 解析、关键词匹配）进行降级处理。

    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
• index.ts:155-201
• tts.service.ts:285-542

章节来源

• langgraph-controller.ts:1-800
• index.ts:1-362

媒体处理调试：FFmpeg参数、音频格式与视频生成

• FFmpeg 参数调试：
  • 使用 ffmpeg.processor.ts 的下载、合并、格式转换、裁剪、音量调整等方法，逐步验证命令参数与超时设置。
  • 通过日志输出确认下载完成、合并成功、上传完成与清理临时文件。
• 音频格式转换：
  • convertFormat 支持 mp3/wav/aac，可调整比特率；结合 getDuration 获取时长验证质量。

• 视频生成：

  • video-generator.service.ts 从章节音频与图片生成视频，支持带/不带背景音乐；失败时更新项目状态并推送 WebSocket 事件。

    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

章节来源

• ffmpeg.processor.ts:1-379
• video-generator.service.ts:157-312

第三方服务调试：API调用、SDK与可用性监控

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

章节来源

• request.ts:1-207
• API.md:1-499
• tts.service.ts:163-190

依赖分析

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

• 媒体处理依赖 FFmpeg 与存储服务，具备远程下载与上传能力。

  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
• langgraph-controller.ts:383-530
• tts.service.ts:285-542
• video-generator.service.ts:157-312
• index.ts:155-201
• ffmpeg.processor.ts:69-183
• logger.service.ts:75-102
• errorHandler.ts:3-24

性能考虑

• 前端：
  • 合理使用缓存（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
• logger.service.ts:1-114
• errorHandler.ts:1-67

结论

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

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

附录

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

章节来源

• API.md:1-499
• README.md:54-90