后端服务排查.md 23 KB
后端服务排查
本文引用的文件
- server/src/app.ts
- server/src/middleware/errorHandler.ts
- server/src/services/redis.service.ts
- server/src/services/queue.service.ts
- server/src/middleware/cache.ts
- server/src/modules/book-generator/book-queue.processor.ts
- server/src/middleware/performance.ts
- server/src/services/logger.service.ts
- server/src/services/sentry.service.ts
- server/src/config/index.ts
- server/src/modules/tts/tts.controller.ts
- server/src/modules/auth/auth.controller.ts
- server/src/services/memory-queue.ts
- server/src/models/index.ts
目录
简介
本文件面向AI有声书生成平台的后端服务运维与开发人员，聚焦Node.js/Koa.js服务在生产环境中的常见故障场景与排查路径，覆盖API接口异常、数据库连接问题、队列服务故障、Redis缓存异常、中间件错误处理、内存泄漏检测、异步任务处理问题、第三方服务集成故障以及系统资源监控等主题。文档提供日志分析方法、错误码含义解释、性能监控指标与根因分析流程，并给出可视化图示帮助快速定位问题。
项目结构
后端采用Koa应用入口集中初始化，路由按模块拆分，服务层（队列、缓存、日志、Sentry）独立封装，业务控制器与领域服务解耦，整体呈现“路由-控制器-服务-基础设施”的分层架构。
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
- server/src/modules/tts/tts.controller.ts:1-274
- server/src/modules/auth/auth.controller.ts:1-94
- server/src/services/queue.service.ts:48-342
- server/src/services/redis.service.ts:3-271
- server/src/services/logger.service.ts:67-114
- server/src/services/sentry.service.ts:7-43
- server/src/services/memory-queue.ts:17-119
- server/src/models/index.ts:1-15
章节来源
- server/src/app.ts:57-130
核心组件
- 应用入口与中间件栈：统一初始化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
- server/src/services/queue.service.ts:48-342
- server/src/services/redis.service.ts:3-271
- server/src/middleware/cache.ts:13-98
- server/src/middleware/performance.ts:29-110
- server/src/services/logger.service.ts:67-114
- server/src/services/sentry.service.ts:7-43
- server/src/models/index.ts:1-15
- server/src/modules/tts/tts.controller.ts:12-274
- server/src/modules/auth/auth.controller.ts:10-94
架构总览
下图展示服务启动、中间件执行、路由处理、队列与缓存交互的关键流程。
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
- server/src/middleware/errorHandler.ts:3-24
- server/src/middleware/performance.ts:29-76
- server/src/middleware/cache.ts:13-48
- server/src/modules/tts/tts.controller.ts:52-127
- server/src/models/index.ts:5-13
详细组件分析
组件A：错误处理与自定义错误类
- 设计要点
- 统一错误捕获与响应格式，支持状态码与业务码分离。
- 提供AppError及子类（未授权、禁止、未找到、请求错误、配额超限）便于语义化抛错。
- 开发环境返回堆栈，生产环境隐藏细节。
排查要点
- 检查控制器是否正确抛出自定义错误类。
- 查看错误响应体中的code/status字段，结合日志定位具体模块。
关注Sentry错误上报是否生效（需配置DSN）。
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
章节来源
- server/src/middleware/errorHandler.ts:3-67
组件B：Redis缓存服务
- 设计要点
- 连接重试策略、事件监听（connect/error/close）、可用性标记。
- 提供get/set/getJSON/setJSON/del/delPattern/hset/hget/hgetall/incr/expire/exists等常用操作。
- 提供testConnection与disconnect。
排查要点
- 启动日志确认Redis连通性；若不可用，缓存中间件会跳过缓存。
- 检查键空间是否存在、过期策略是否合理、批量删除是否命中模式。
观察错误日志中的[Redis]前缀定位失败点。
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
- server/src/middleware/cache.ts:13-48
章节来源
- server/src/services/redis.service.ts:3-271
- server/src/middleware/cache.ts:13-98
组件C：队列服务与书籍生成处理器
- 设计要点
- QueueService基于Bull，支持多种队列类型与任务状态；默认移除完成/失败任务以控制Redis占用。
- Redis不可用时回退至MemoryQueue，维持基本并发与处理能力。
- 书籍生成处理器支持Redis或内存两种模式，最大并发3；启动时恢复中断任务。
排查要点
- 检查Redis连通性与队列事件（completed/failed/error）日志。
- 使用getTaskStatus查询任务状态与失败原因；关注stalledInterval与maxStalledCount。
若出现大量failed，结合Sentry与日志定位具体业务节点。
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
- server/src/services/memory-queue.ts:26-99
- server/src/modules/book-generator/book-queue.processor.ts:48-83
章节来源
- server/src/services/queue.service.ts:48-342
- server/src/services/memory-queue.ts:17-119
- server/src/modules/book-generator/book-queue.processor.ts:16-83
组件D：性能监控与指标路由
- 设计要点
- 记录总请求数、平均响应时间、慢请求阈值（1秒）、端点级统计与错误率。
- 提供/X-Response-Time响应头与/health与/api/metrics路由。
排查要点
- 通过/api/metrics查看全局指标与端点错误率，识别异常波动。
慢请求告警（>1s）提示可能的数据库慢查询、第三方调用阻塞或CPU瓶颈。
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
- server/src/app.ts:92-97
章节来源
- server/src/middleware/performance.ts:19-110
- server/src/app.ts:92-97
组件E：日志与Sentry监控
- 设计要点
- Winston多通道：Console、错误文件、综合日志、HTTP请求日志；HTTP中间件统一记录请求/错误。
- Sentry初始化、错误过滤（如Redis连接拒绝）、Koa中间件捕获上下文（方法、URL、用户）。
- 排查要点
- 生产环境关注error.log与http.log；开发环境可查看控制台彩色输出。
- 在Sentry中按方法/URL/用户维度聚合错误，结合堆栈定位根因。
章节来源
- server/src/services/logger.service.ts:67-114
- server/src/services/sentry.service.ts:7-113
- server/src/app.ts:133-192
组件F：数据库连接与模型
- 设计要点
- Prisma客户端连接封装，统一$connect/$disconnect。
- TTS控制器提供/test-db接口验证连接状态。
- 排查要点
- 启动日志确认MySQL连接成功；/test-db返回连接状态与表计数。
- 数据库异常通常表现为连接超时、事务冲突或索引缺失。
章节来源
- server/src/models/index.ts:1-15
- server/src/modules/tts/tts.controller.ts:34-50
组件G：业务控制器（TTS与认证）
- 设计要点
- TTS：音色列表、提供商列表、异步生成、状态查询、预览、批量下载；内置参数校验与配额检查。
- 认证：发送验证码、手机号登录、用户信息查询与更新。
- 排查要点
- 参数校验失败会抛出BadRequestError；未找到资源抛出NotFoundError。
- TTS生成后按字数消耗配额，异常时记录告警。
章节来源
- server/src/modules/tts/tts.controller.ts:12-274
- server/src/modules/auth/auth.controller.ts:10-94
依赖关系分析
- 组件耦合
- app.ts集中引入并装配中间件、路由与服务，耦合度低，便于扩展。
- QueueService对RedisService强依赖，MemoryQueue作为降级方案，降低单点风险。
- 控制器仅依赖服务接口，避免直接依赖底层实现。
- 外部依赖
- Redis/Bull用于队列；Winston用于日志；Sentry用于错误监控；Prisma用于数据库访问。
循环依赖
未见明显循环依赖；模块间通过导出单例服务进行协作。
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
- server/src/services/queue.service.ts:18-20
- server/src/services/redis.service.ts:1-2
- server/src/modules/tts/tts.controller.ts:1-5
- server/src/modules/auth/auth.controller.ts:1-6
章节来源
- server/src/app.ts:63-130
性能考量
- 慢请求识别：超过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
- server/src/modules/tts/tts.controller.ts:70-96
- server/src/modules/tts/tts.controller.ts:130-143
2) 数据库连接问题
- 现象
- 启动日志显示MySQL连接状态；/test-db返回连接状态与表计数。
- 排查步骤
- 确认数据库服务可达、凭据正确、网络策略放行。
- 查看Prisma连接异常堆栈；检查慢查询与连接池配置。
- 使用/test-db接口快速验证连通性。
章节来源
- server/src/models/index.ts:5-13
- server/src/modules/tts/tts.controller.ts:34-50
3) 队列服务故障
- 现象
- 队列不可用时回退至内存队列；任务状态查询失败或无进度。
- 排查步骤
- 检查Redis连通性与事件日志；关注completed/failed/error。
- 使用getTaskStatus查询状态与失败原因；核对stalled配置。
- 服务器重启后自动恢复中断任务，观察日志确认恢复数量。
- 降级策略
- Redis不可用时自动切换MemoryQueue，维持基本并发。
章节来源
- server/src/services/queue.service.ts:53-122
- server/src/services/memory-queue.ts:54-99
- server/src/modules/book-generator/book-queue.processor.ts:88-124
4) Redis缓存异常
- 现象
- 缓存中间件跳过缓存；键不存在或过期；批量删除未命中。
- 排查步骤
- 使用testConnection确认连通性；检查重连策略与事件日志。
- 核对键前缀与生成规则；确认TTL与过期策略。
- 使用delPattern清理相关键空间；观察批量删除日志。
章节来源
- server/src/services/redis.service.ts:246-255
- server/src/middleware/cache.ts:13-48
5) 中间件错误处理
- 现象
- 统一错误响应；开发环境返回堆栈；生产环境隐藏细节。
- 排查步骤
- 确认errorHandler位于中间件栈首位；检查自定义错误类使用是否规范。
- 关注Sentry中间件是否正确捕获上下文。
章节来源
- server/src/middleware/errorHandler.ts:3-24
- server/src/services/sentry.service.ts:92-110
6) 内存泄漏检测
- 建议措施
- 使用Node.js内置heap snapshot与heap profiler；关注定时器、事件监听器与闭包持有。
- 监控进程内存与堆外内存；对长连接（WebSocket）与大对象序列化保持警惕。
- 通过性能中间件识别慢请求，间接定位潜在泄漏点。
[本节为通用指导，无需列出章节来源]
7) 异步任务处理问题
- 现象
- 任务长时间处于waiting/active；失败后未恢复；进度回调未触发。
- 排查步骤
- 检查队列并发与Redis可用性；核对任务超时配置。
- 观察书籍生成处理器日志；确认状态更新与失败回写。
- 使用getTaskStatus与onProgress定位问题。
章节来源
- server/src/services/queue.service.ts:197-237
- server/src/modules/book-generator/book-queue.processor.ts:16-43
8) 第三方服务集成故障
- 现象
- TTS提供商调用失败、限流、余额不足、模型不支持等。
- 排查步骤
- 检查模型配置与自动切换逻辑；根据shouldSwitchModel判定是否需要切换。
- 关注/DASHSCOPE相关配置项与实时模式开关。
- 通过Sentry与日志聚合错误，定位具体供应商与接口。
章节来源
- server/src/config/index.ts:46-67
- server/src/config/index.ts:83-93
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
B. 启动流程与优雅关闭
- 启动顺序：Sentry初始化 → 数据库连接 → Redis/存储连通性测试 → 订阅套餐初始化 → WebSocket → 启动HTTP服务 → 初始化书籍生成队列 → 恢复中断任务。
- 优雅关闭：接收SIGTERM/SIGINT，关闭队列与Redis连接后退出。
章节来源
- server/src/app.ts:133-192