# 后端服务排查

<cite>
**本文引用的文件**
- [server/src/app.ts](file://server/src/app.ts)
- [server/src/middleware/errorHandler.ts](file://server/src/middleware/errorHandler.ts)
- [server/src/services/redis.service.ts](file://server/src/services/redis.service.ts)
- [server/src/services/queue.service.ts](file://server/src/services/queue.service.ts)
- [server/src/middleware/cache.ts](file://server/src/middleware/cache.ts)
- [server/src/modules/book-generator/book-queue.processor.ts](file://server/src/modules/book-generator/book-queue.processor.ts)
- [server/src/middleware/performance.ts](file://server/src/middleware/performance.ts)
- [server/src/services/logger.service.ts](file://server/src/services/logger.service.ts)
- [server/src/services/sentry.service.ts](file://server/src/services/sentry.service.ts)
- [server/src/config/index.ts](file://server/src/config/index.ts)
- [server/src/modules/tts/tts.controller.ts](file://server/src/modules/tts/tts.controller.ts)
- [server/src/modules/auth/auth.controller.ts](file://server/src/modules/auth/auth.controller.ts)
- [server/src/services/memory-queue.ts](file://server/src/services/memory-queue.ts)
- [server/src/models/index.ts](file://server/src/models/index.ts)
</cite>

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

## 简介
本文件面向AI有声书生成平台的后端服务运维与开发人员，聚焦Node.js/Koa.js服务在生产环境中的常见故障场景与排查路径，覆盖API接口异常、数据库连接问题、队列服务故障、Redis缓存异常、中间件错误处理、内存泄漏检测、异步任务处理问题、第三方服务集成故障以及系统资源监控等主题。文档提供日志分析方法、错误码含义解释、性能监控指标与根因分析流程，并给出可视化图示帮助快速定位问题。

## 项目结构
后端采用Koa应用入口集中初始化，路由按模块拆分，服务层（队列、缓存、日志、Sentry）独立封装，业务控制器与领域服务解耦，整体呈现“路由-控制器-服务-基础设施”的分层架构。

```mermaid
graph TB
A["Koa 应用<br/>server/src/app.ts"] --> B["路由注册<br/>各模块控制器"]
A --> C["中间件链路<br/>错误处理/安全/性能/缓存"]
A --> D["服务层<br/>Redis/队列/日志/Sentry/存储"]
B --> E["业务控制器<br/>如 tts.controller.ts / auth.controller.ts"]
D --> F["队列服务<br/>queue.service.ts"]
D --> G["Redis 服务<br/>redis.service.ts"]
D --> H["日志服务<br/>logger.service.ts"]
D --> I["Sentry 监控<br/>sentry.service.ts"]
D --> J["内存队列回退<br/>memory-queue.ts"]
A --> K["数据库连接<br/>models/index.ts"]
```

图表来源
- [server/src/app.ts:57-130](file://server/src/app.ts#L57-L130)
- [server/src/modules/tts/tts.controller.ts:1-274](file://server/src/modules/tts/tts.controller.ts#L1-L274)
- [server/src/modules/auth/auth.controller.ts:1-94](file://server/src/modules/auth/auth.controller.ts#L1-L94)
- [server/src/services/queue.service.ts:48-342](file://server/src/services/queue.service.ts#L48-L342)
- [server/src/services/redis.service.ts:3-271](file://server/src/services/redis.service.ts#L3-L271)
- [server/src/services/logger.service.ts:67-114](file://server/src/services/logger.service.ts#L67-L114)
- [server/src/services/sentry.service.ts:7-43](file://server/src/services/sentry.service.ts#L7-L43)
- [server/src/services/memory-queue.ts:17-119](file://server/src/services/memory-queue.ts#L17-L119)
- [server/src/models/index.ts:1-15](file://server/src/models/index.ts#L1-L15)

章节来源
- [server/src/app.ts:57-130](file://server/src/app.ts#L57-L130)

## 核心组件
- 应用入口与中间件栈：统一初始化Sentry、数据库、Redis、存储、WebSocket；注册错误处理、性能监控、HTTP日志、安全防护、CORS、BodyParser、静态文件挂载与路由。
- 队列服务：基于Bull的Redis队列，支持任务排队、并发控制、状态查询、进度回调；Redis不可用时回退至内存队列。
- Redis服务：提供键值、Hash、JSON读写、过期、存在性检查、PING连通性测试与断开；具备重连策略与事件监听。
- 缓存中间件：基于Redis的HTTP响应缓存与清理，支持自定义键生成器与前缀。
- 性能监控中间件：统计总请求数、平均响应时间、慢请求、错误率与端点级指标，并提供指标路由。
- 日志服务：Winston多通道输出，分别记录控制台、错误文件、综合日志、HTTP请求日志。
- Sentry服务：初始化SDK、错误过滤、上下文设置、Koa错误捕获中间件。
- 数据库连接：Prisma客户端连接封装。
- 业务控制器：TTS、认证等模块的API接口，包含参数校验、配额检查、异步任务触发与状态查询。

章节来源
- [server/src/app.ts:63-130](file://server/src/app.ts#L63-L130)
- [server/src/services/queue.service.ts:48-342](file://server/src/services/queue.service.ts#L48-L342)
- [server/src/services/redis.service.ts:3-271](file://server/src/services/redis.service.ts#L3-L271)
- [server/src/middleware/cache.ts:13-98](file://server/src/middleware/cache.ts#L13-L98)
- [server/src/middleware/performance.ts:29-110](file://server/src/middleware/performance.ts#L29-L110)
- [server/src/services/logger.service.ts:67-114](file://server/src/services/logger.service.ts#L67-L114)
- [server/src/services/sentry.service.ts:7-43](file://server/src/services/sentry.service.ts#L7-L43)
- [server/src/models/index.ts:1-15](file://server/src/models/index.ts#L1-L15)
- [server/src/modules/tts/tts.controller.ts:12-274](file://server/src/modules/tts/tts.controller.ts#L12-L274)
- [server/src/modules/auth/auth.controller.ts:10-94](file://server/src/modules/auth/auth.controller.ts#L10-L94)

## 架构总览
下图展示服务启动、中间件执行、路由处理、队列与缓存交互的关键流程。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Koa as "Koa 应用<br/>app.ts"
participant MW as "中间件栈<br/>error/performance/cache"
participant Router as "路由<br/>controllers"
participant Svc as "服务层<br/>Redis/Queue/Logger/Sentry"
participant DB as "数据库<br/>Prisma"
Client->>Koa : HTTP 请求
Koa->>MW : 错误处理/性能/日志/安全/CORS
MW-->>Koa : 通过
Koa->>Router : 路由匹配
Router->>Svc : 业务调用缓存/队列/存储
Router->>DB : 数据库操作
DB-->>Router : 结果
Router-->>Client : 响应
Koa->>Svc : 性能指标/日志/Sentry上报
```

图表来源
- [server/src/app.ts:63-130](file://server/src/app.ts#L63-L130)
- [server/src/middleware/errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)
- [server/src/middleware/performance.ts:29-76](file://server/src/middleware/performance.ts#L29-L76)
- [server/src/middleware/cache.ts:13-48](file://server/src/middleware/cache.ts#L13-L48)
- [server/src/modules/tts/tts.controller.ts:52-127](file://server/src/modules/tts/tts.controller.ts#L52-L127)
- [server/src/models/index.ts:5-13](file://server/src/models/index.ts#L5-L13)

## 详细组件分析

### 组件A：错误处理与自定义错误类
- 设计要点
  - 统一错误捕获与响应格式，支持状态码与业务码分离。
  - 提供AppError及子类（未授权、禁止、未找到、请求错误、配额超限）便于语义化抛错。
  - 开发环境返回堆栈，生产环境隐藏细节。
- 排查要点
  - 检查控制器是否正确抛出自定义错误类。
  - 查看错误响应体中的code/status字段，结合日志定位具体模块。
  - 关注Sentry错误上报是否生效（需配置DSN）。

```mermaid
classDiagram
class AppError {
+number code
+number status
+constructor(message, code, status)
}
class UnauthorizedError
class ForbiddenError
class NotFoundError
class BadRequestError
class QuotaExceededError
AppError <|-- UnauthorizedError
AppError <|-- ForbiddenError
AppError <|-- NotFoundError
AppError <|-- BadRequestError
AppError <|-- QuotaExceededError
```

图表来源
- [server/src/middleware/errorHandler.ts:27-67](file://server/src/middleware/errorHandler.ts#L27-L67)

章节来源
- [server/src/middleware/errorHandler.ts:3-67](file://server/src/middleware/errorHandler.ts#L3-L67)

### 组件B：Redis缓存服务
- 设计要点
  - 连接重试策略、事件监听（connect/error/close）、可用性标记。
  - 提供get/set/getJSON/setJSON/del/delPattern/hset/hget/hgetall/incr/expire/exists等常用操作。
  - 提供testConnection与disconnect。
- 排查要点
  - 启动日志确认Redis连通性；若不可用，缓存中间件会跳过缓存。
  - 检查键空间是否存在、过期策略是否合理、批量删除是否命中模式。
  - 观察错误日志中的[Redis]前缀定位失败点。

```mermaid
flowchart TD
Start(["进入缓存操作"]) --> CheckAvail["检查Redis可用性"]
CheckAvail --> |不可用| SkipCache["跳过缓存，直接请求"]
CheckAvail --> |可用| GenKey["生成缓存键"]
GenKey --> GetOp["执行GET/HGET/HGETALL"]
GetOp --> Hit{"命中？"}
Hit --> |是| ReturnCache["返回缓存数据"]
Hit --> |否| ExecNext["执行下游请求"]
ExecNext --> Save{"状态=200且有body？"}
Save --> |是| SetOp["SET/SETEX/SETJSON/HSET"]
Save --> |否| End(["结束"])
SetOp --> End
SkipCache --> End
```

图表来源
- [server/src/services/redis.service.ts:43-255](file://server/src/services/redis.service.ts#L43-L255)
- [server/src/middleware/cache.ts:13-48](file://server/src/middleware/cache.ts#L13-L48)

章节来源
- [server/src/services/redis.service.ts:3-271](file://server/src/services/redis.service.ts#L3-L271)
- [server/src/middleware/cache.ts:13-98](file://server/src/middleware/cache.ts#L13-L98)

### 组件C：队列服务与书籍生成处理器
- 设计要点
  - QueueService基于Bull，支持多种队列类型与任务状态；默认移除完成/失败任务以控制Redis占用。
  - Redis不可用时回退至MemoryQueue，维持基本并发与处理能力。
  - 书籍生成处理器支持Redis或内存两种模式，最大并发3；启动时恢复中断任务。
- 排查要点
  - 检查Redis连通性与队列事件（completed/failed/error）日志。
  - 使用getTaskStatus查询任务状态与失败原因；关注stalledInterval与maxStalledCount。
  - 若出现大量failed，结合Sentry与日志定位具体业务节点。

```mermaid
sequenceDiagram
participant Ctrl as "控制器"
participant QS as "QueueService"
participant RQ as "Redis 队列(Bull)"
participant MQ as "内存队列"
participant Proc as "书籍生成处理器"
participant Store as "书籍状态存储"
Ctrl->>QS : addBookGenerationTask(data)
alt Redis可用
QS->>RQ : add(data)
RQ-->>QS : jobId
RQ->>Proc : process(job)
Proc->>Store : 更新genStage/progress
Proc-->>RQ : 完成/失败
else Redis不可用
QS->>MQ : add(data)
MQ->>Proc : process(job)
Proc-->>MQ : 完成/失败
end
```

图表来源
- [server/src/services/queue.service.ts:72-160](file://server/src/services/queue.service.ts#L72-L160)
- [server/src/services/memory-queue.ts:26-99](file://server/src/services/memory-queue.ts#L26-L99)
- [server/src/modules/book-generator/book-queue.processor.ts:48-83](file://server/src/modules/book-generator/book-queue.processor.ts#L48-L83)

章节来源
- [server/src/services/queue.service.ts:48-342](file://server/src/services/queue.service.ts#L48-L342)
- [server/src/services/memory-queue.ts:17-119](file://server/src/services/memory-queue.ts#L17-L119)
- [server/src/modules/book-generator/book-queue.processor.ts:16-83](file://server/src/modules/book-generator/book-queue.processor.ts#L16-L83)

### 组件D：性能监控与指标路由
- 设计要点
  - 记录总请求数、平均响应时间、慢请求阈值（1秒）、端点级统计与错误率。
  - 提供/X-Response-Time响应头与/health与/api/metrics路由。
- 排查要点
  - 通过/api/metrics查看全局指标与端点错误率，识别异常波动。
  - 慢请求告警（>1s）提示可能的数据库慢查询、第三方调用阻塞或CPU瓶颈。

```mermaid
flowchart TD
Req["请求进入"] --> StartT["记录开始时间"]
StartT --> Next["执行下游处理"]
Next --> Done{"完成/异常？"}
Done --> |正常| Calc["计算耗时并更新指标"]
Done --> |异常| IncErr["错误计数+1"]
Calc --> SetHdr["设置X-Response-Time头"]
SetHdr --> End["返回响应"]
IncErr --> Throw["抛出异常"]
```

图表来源
- [server/src/middleware/performance.ts:29-76](file://server/src/middleware/performance.ts#L29-L76)
- [server/src/app.ts:92-97](file://server/src/app.ts#L92-L97)

章节来源
- [server/src/middleware/performance.ts:19-110](file://server/src/middleware/performance.ts#L19-L110)
- [server/src/app.ts:92-97](file://server/src/app.ts#L92-L97)

### 组件E：日志与Sentry监控
- 设计要点
  - Winston多通道：Console、错误文件、综合日志、HTTP请求日志；HTTP中间件统一记录请求/错误。
  - Sentry初始化、错误过滤（如Redis连接拒绝）、Koa中间件捕获上下文（方法、URL、用户）。
- 排查要点
  - 生产环境关注error.log与http.log；开发环境可查看控制台彩色输出。
  - 在Sentry中按方法/URL/用户维度聚合错误，结合堆栈定位根因。

章节来源
- [server/src/services/logger.service.ts:67-114](file://server/src/services/logger.service.ts#L67-L114)
- [server/src/services/sentry.service.ts:7-113](file://server/src/services/sentry.service.ts#L7-L113)
- [server/src/app.ts:133-192](file://server/src/app.ts#L133-L192)

### 组件F：数据库连接与模型
- 设计要点
  - Prisma客户端连接封装，统一$connect/$disconnect。
  - TTS控制器提供/test-db接口验证连接状态。
- 排查要点
  - 启动日志确认MySQL连接成功；/test-db返回连接状态与表计数。
  - 数据库异常通常表现为连接超时、事务冲突或索引缺失。

章节来源
- [server/src/models/index.ts:1-15](file://server/src/models/index.ts#L1-L15)
- [server/src/modules/tts/tts.controller.ts:34-50](file://server/src/modules/tts/tts.controller.ts#L34-L50)

### 组件G：业务控制器（TTS与认证）
- 设计要点
  - TTS：音色列表、提供商列表、异步生成、状态查询、预览、批量下载；内置参数校验与配额检查。
  - 认证：发送验证码、手机号登录、用户信息查询与更新。
- 排查要点
  - 参数校验失败会抛出BadRequestError；未找到资源抛出NotFoundError。
  - TTS生成后按字数消耗配额，异常时记录告警。

章节来源
- [server/src/modules/tts/tts.controller.ts:12-274](file://server/src/modules/tts/tts.controller.ts#L12-L274)
- [server/src/modules/auth/auth.controller.ts:10-94](file://server/src/modules/auth/auth.controller.ts#L10-L94)

## 依赖关系分析
- 组件耦合
  - app.ts集中引入并装配中间件、路由与服务，耦合度低，便于扩展。
  - QueueService对RedisService强依赖，MemoryQueue作为降级方案，降低单点风险。
  - 控制器仅依赖服务接口，避免直接依赖底层实现。
- 外部依赖
  - Redis/Bull用于队列；Winston用于日志；Sentry用于错误监控；Prisma用于数据库访问。
- 循环依赖
  - 未见明显循环依赖；模块间通过导出单例服务进行协作。

```mermaid
graph LR
App["app.ts"] --> EH["errorHandler.ts"]
App --> PM["performance.ts"]
App --> CL["cache.ts"]
App --> RS["redis.service.ts"]
App --> QS["queue.service.ts"]
App --> LS["logger.service.ts"]
App --> SS["sentry.service.ts"]
App --> MD["models/index.ts"]
TTS["tts.controller.ts"] --> QS
TTS --> RS
TTS --> MD
AUTH["auth.controller.ts"] --> MD
```

图表来源
- [server/src/app.ts:63-130](file://server/src/app.ts#L63-L130)
- [server/src/services/queue.service.ts:18-20](file://server/src/services/queue.service.ts#L18-L20)
- [server/src/services/redis.service.ts:1-2](file://server/src/services/redis.service.ts#L1-L2)
- [server/src/modules/tts/tts.controller.ts:1-5](file://server/src/modules/tts/tts.controller.ts#L1-L5)
- [server/src/modules/auth/auth.controller.ts:1-6](file://server/src/modules/auth/auth.controller.ts#L1-L6)

章节来源
- [server/src/app.ts:63-130](file://server/src/app.ts#L63-L130)

## 性能考量
- 慢请求识别：超过1秒的请求计入慢请求并告警。
- 队列并发：书籍生成最大并发3，避免资源争抢；可根据Redis性能调整。
- 缓存命中：合理TTL与键前缀提升命中率，减少数据库压力。
- 日志级别：生产环境降低控制台冗余，重点保留HTTP与错误日志。
- 监控采样：Sentry在生产环境按比例采样，必要时提高采样率定位问题。

[本节为通用指导，无需列出章节来源]

## 故障排查指南

### 1) API接口异常
- 现象
  - 响应体包含code/status/message/data，业务错误与系统错误区分明确。
- 排查步骤
  - 查看控制器是否抛出自定义错误类；核对状态码与业务码。
  - 检查Sentry错误面板，按URL/方法/用户聚合定位。
  - 开启开发环境堆栈辅助定位。
- 常见错误码
  - 400：请求参数错误（如文本为空、音色缺失）。
  - 401：未授权访问。
  - 403：禁止访问。
  - 404：资源不存在（如书籍/音频）。
  - 429：使用次数/配额已达上限。
  - 500：服务器内部错误。

章节来源
- [server/src/middleware/errorHandler.ts:3-67](file://server/src/middleware/errorHandler.ts#L3-L67)
- [server/src/modules/tts/tts.controller.ts:70-96](file://server/src/modules/tts/tts.controller.ts#L70-L96)
- [server/src/modules/tts/tts.controller.ts:130-143](file://server/src/modules/tts/tts.controller.ts#L130-L143)

### 2) 数据库连接问题
- 现象
  - 启动日志显示MySQL连接状态；/test-db返回连接状态与表计数。
- 排查步骤
  - 确认数据库服务可达、凭据正确、网络策略放行。
  - 查看Prisma连接异常堆栈；检查慢查询与连接池配置。
  - 使用/test-db接口快速验证连通性。

章节来源
- [server/src/models/index.ts:5-13](file://server/src/models/index.ts#L5-L13)
- [server/src/modules/tts/tts.controller.ts:34-50](file://server/src/modules/tts/tts.controller.ts#L34-L50)

### 3) 队列服务故障
- 现象
  - 队列不可用时回退至内存队列；任务状态查询失败或无进度。
- 排查步骤
  - 检查Redis连通性与事件日志；关注completed/failed/error。
  - 使用getTaskStatus查询状态与失败原因；核对stalled配置。
  - 服务器重启后自动恢复中断任务，观察日志确认恢复数量。
- 降级策略
  - Redis不可用时自动切换MemoryQueue，维持基本并发。

章节来源
- [server/src/services/queue.service.ts:53-122](file://server/src/services/queue.service.ts#L53-L122)
- [server/src/services/memory-queue.ts:54-99](file://server/src/services/memory-queue.ts#L54-L99)
- [server/src/modules/book-generator/book-queue.processor.ts:88-124](file://server/src/modules/book-generator/book-queue.processor.ts#L88-L124)

### 4) Redis缓存异常
- 现象
  - 缓存中间件跳过缓存；键不存在或过期；批量删除未命中。
- 排查步骤
  - 使用testConnection确认连通性；检查重连策略与事件日志。
  - 核对键前缀与生成规则；确认TTL与过期策略。
  - 使用delPattern清理相关键空间；观察批量删除日志。

章节来源
- [server/src/services/redis.service.ts:246-255](file://server/src/services/redis.service.ts#L246-L255)
- [server/src/middleware/cache.ts:13-48](file://server/src/middleware/cache.ts#L13-L48)

### 5) 中间件错误处理
- 现象
  - 统一错误响应；开发环境返回堆栈；生产环境隐藏细节。
- 排查步骤
  - 确认errorHandler位于中间件栈首位；检查自定义错误类使用是否规范。
  - 关注Sentry中间件是否正确捕获上下文。

章节来源
- [server/src/middleware/errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)
- [server/src/services/sentry.service.ts:92-110](file://server/src/services/sentry.service.ts#L92-L110)

### 6) 内存泄漏检测
- 建议措施
  - 使用Node.js内置heap snapshot与heap profiler；关注定时器、事件监听器与闭包持有。
  - 监控进程内存与堆外内存；对长连接（WebSocket）与大对象序列化保持警惕。
  - 通过性能中间件识别慢请求，间接定位潜在泄漏点。

[本节为通用指导，无需列出章节来源]

### 7) 异步任务处理问题
- 现象
  - 任务长时间处于waiting/active；失败后未恢复；进度回调未触发。
- 排查步骤
  - 检查队列并发与Redis可用性；核对任务超时配置。
  - 观察书籍生成处理器日志；确认状态更新与失败回写。
  - 使用getTaskStatus与onProgress定位问题。

章节来源
- [server/src/services/queue.service.ts:197-237](file://server/src/services/queue.service.ts#L197-L237)
- [server/src/modules/book-generator/book-queue.processor.ts:16-43](file://server/src/modules/book-generator/book-queue.processor.ts#L16-L43)

### 8) 第三方服务集成故障
- 现象
  - TTS提供商调用失败、限流、余额不足、模型不支持等。
- 排查步骤
  - 检查模型配置与自动切换逻辑；根据shouldSwitchModel判定是否需要切换。
  - 关注/DASHSCOPE相关配置项与实时模式开关。
  - 通过Sentry与日志聚合错误，定位具体供应商与接口。

章节来源
- [server/src/config/index.ts:46-67](file://server/src/config/index.ts#L46-L67)
- [server/src/config/index.ts:83-93](file://server/src/config/index.ts#L83-L93)

### 9) 系统资源监控
- 指标建议
  - CPU使用率、内存占用、GC暂停时间、打开文件描述符数。
  - 队列等待/活跃任务数、Redis内存使用、HTTP请求数与错误率。
- 工具建议
  - Node.js Profiler与火焰图；Prometheus/Grafana（可选）；容器监控（如Docker stats）。

[本节为通用指导，无需列出章节来源]

## 结论
本排查文档围绕Koa应用的中间件、服务与业务控制器，构建了从启动到运行的全链路故障排查路径。通过统一的错误处理、性能监控、日志与Sentry监控、Redis与队列的可观测性，以及针对TTS与书籍生成的专项流程，可快速定位并解决生产环境中的常见问题。建议在变更发布前进行端到端回归测试，并持续完善监控与告警体系。

[本节为总结性内容，无需列出章节来源]

## 附录

### A. 常用健康与指标接口
- 健康检查：GET /health
- 性能指标：GET /api/metrics

章节来源
- [server/src/app.ts:92-97](file://server/src/app.ts#L92-L97)

### B. 启动流程与优雅关闭
- 启动顺序：Sentry初始化 → 数据库连接 → Redis/存储连通性测试 → 订阅套餐初始化 → WebSocket → 启动HTTP服务 → 初始化书籍生成队列 → 恢复中断任务。
- 优雅关闭：接收SIGTERM/SIGINT，关闭队列与Redis连接后退出。

章节来源
- [server/src/app.ts:133-192](file://server/src/app.ts#L133-L192)