audio_codebuddy/.qoder/repowiki/zh/content/后端架构/错误处理与日志.md

错误处理与日志

本文引用的文件

• server/src/app.ts
• server/src/middleware/errorHandler.ts
• server/src/middleware/errorHandler.js
• server/src/services/logger.service.ts
• server/src/services/sentry.service.ts
• server/src/services/requestLogger.ts
• server/src/services/log.service.ts
• server/src/services/log.controller.ts
• server/src/middleware/performance.ts
• server/src/config/index.ts

目录

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

简介

本文件面向AI有声书生成平台的错误处理与日志系统，系统性梳理全局错误处理机制、日志架构与配置、Sentry错误监控集成、请求日志与性能监控、审计日志实现以及最佳实践与故障排查。目标是帮助开发者快速理解并高效维护生产环境下的可观测性与稳定性。

项目结构

围绕错误处理与日志的关键模块分布如下：

• 应用入口与中间件装配：应用启动时注册全局错误处理、Sentry错误处理、性能监控、HTTP日志、安全中间件等。
• 错误处理：统一错误捕获与响应格式化，提供多种业务错误类型。
• 日志系统：基于Winston的多通道日志输出，包含控制台、错误文件、合并文件、HTTP请求日志，并提供请求级日志与分析能力。
• Sentry：错误监控与聚合，支持采样、过滤、上下文与标签设置。
• 性能监控：内置请求计数、平均耗时、慢请求阈值、错误率统计与指标路由。

• 审计与分析：请求日志持久化、错误模式识别、自动修复建议、统计数据与清理策略。

  graph TB
  A["应用入口<br/>server/src/app.ts"] --> B["全局错误处理<br/>errorHandler.ts/.js"]
  A --> C["Sentry错误处理中间件<br/>sentry.service.ts"]
  A --> D["性能监控中间件<br/>performance.ts"]
  A --> E["Winston HTTP日志中间件<br/>logger.service.ts"]
  A --> F["请求日志中间件<br/>requestLogger.ts"]
  F --> G["请求日志服务<br/>log.service.ts"]
  G --> H["请求日志控制器<br/>log.controller.ts"]
  B --> I["统一错误响应格式"]
  C --> J["Sentry错误上报"]
  D --> K["性能指标统计"]
  E --> L["文件/控制台日志输出"]
  

图表来源

• server/src/app.ts:64-67
• server/src/middleware/errorHandler.ts:3-24
• server/src/services/sentry.service.ts:92-110
• server/src/middleware/performance.ts:29-76
• server/src/services/logger.service.ts:75-102
• server/src/services/requestLogger.ts:5-54
• server/src/services/log.service.ts:42-354
• server/src/services/log.controller.ts:1-233

章节来源

• server/src/app.ts:64-67

核心组件

• 全局错误处理中间件：捕获未处理异常，标准化响应体，开发环境附加堆栈信息。
• 自定义错误类型：AppError及子类（未授权、禁止、未找到、请求错误、配额超限）。
• Winston日志系统：控制台彩色输出、错误/常规/HTTP三类文件日志、轮转与格式化。
• Sentry错误监控：初始化、过滤、上下文、标签、Koa中间件集成。
• 请求日志中间件：记录请求/响应元数据、状态码分级、持久化与分析。
• 性能监控中间件：全局与端点级指标、慢请求告警、错误率计算。
• 日志服务与控制器：内存中维护请求日志、错误模式识别、自动修复建议、统计数据、清理策略。

章节来源

• server/src/middleware/errorHandler.ts:27-67
• server/src/middleware/errorHandler.js:56-87
• server/src/services/logger.service.ts:11-72
• server/src/services/sentry.service.ts:7-43
• server/src/services/requestLogger.ts:5-54
• server/src/middleware/performance.ts:29-109
• server/src/services/log.service.ts:42-354
• server/src/services/log.controller.ts:1-233

架构总览

下图展示错误与日志在请求生命周期中的流转与落盘：

sequenceDiagram
participant Client as "客户端"
participant App as "Koa应用<br/>app.ts"
participant ReqLog as "请求日志中间件<br/>requestLogger.ts"
participant Perf as "性能监控<br/>performance.ts"
participant HttpLog as "HTTP日志中间件<br/>logger.service.ts"
participant ErrMW as "全局错误处理<br/>errorHandler.ts"
participant SentryMW as "Sentry错误处理<br/>sentry.service.ts"
participant LogSvc as "日志服务<br/>log.service.ts"
Client->>App : 发起HTTP请求
App->>ReqLog : 进入请求日志中间件
ReqLog->>Perf : 进入性能监控
Perf->>HttpLog : 进入HTTP日志
HttpLog->>SentryMW : 进入Sentry错误处理
SentryMW->>ErrMW : 进入全局错误处理
ErrMW-->>Client : 返回标准化错误响应
ReqLog->>LogSvc : 记录请求日志(含错误)
HttpLog-->>Client : 写入HTTP日志文件

图表来源

• server/src/app.ts:64-67
• server/src/services/requestLogger.ts:5-54
• server/src/middleware/performance.ts:29-76
• server/src/services/logger.service.ts:75-102
• server/src/middleware/errorHandler.ts:3-24
• server/src/services/sentry.service.ts:92-110
• server/src/services/log.service.ts:140-171

详细组件分析

全局错误处理机制

• 设计要点
  • 在Koa管道最前端注册，确保所有异常被捕获。
  • 将错误映射为标准响应体，包含业务码、消息与空数据域；开发环境追加堆栈。
  • 提供自定义错误基类与领域错误类型，便于上层抛出与识别。
• 错误分类与传播
  • 自定义错误类型覆盖未授权、禁止、未找到、请求错误、配额超限等。
  • 通过ctx.status与ctx.body统一输出，保证前后端一致的错误契约。

• 响应格式化策略

  • 固定字段：code、message、data；开发环境附加stack。

  • 未捕获异常默认500，业务错误按错误类型映射对应状态码与业务码。

    flowchart TD
    Start(["进入全局错误处理"]) --> TryNext["调用下游中间件/路由"]
    TryNext --> CatchErr{"是否抛出异常?"}
    CatchErr --> |否| End(["结束"])
    CatchErr --> |是| Normalize["标准化错误对象"]
    Normalize --> SetStatus["设置状态码"]
    SetStatus --> BuildResp["构建响应体<br/>code/message/data(+stack)"]
    BuildResp --> End
    

图表来源

• server/src/middleware/errorHandler.ts:3-24
• server/src/middleware/errorHandler.js:56-87

章节来源

• server/src/middleware/errorHandler.ts:27-67
• server/src/middleware/errorHandler.js:88-148

日志系统架构与配置

• 日志级别与格式
  • Winston配置：控制台彩色输出、时间戳、简单格式；错误/常规/HTTP三类文件日志。
  • HTTP日志独立通道，记录请求方法、URL、状态、耗时、IP、UA等。
• 日志轮转机制
  • 错误/常规日志：单文件最大10MB，最多保留10个文件。
  • HTTP日志：单文件最大10MB，最多保留5个文件。

• 目录与级别

  • 日志目录自动创建；生产环境控制台级别提升至info，可通过LOG_LEVEL调整。

    flowchart TD
    Init["初始化Winston"] --> Console["控制台传输<br/>Console(level='info'|'debug')"]
    Init --> ErrorFile["错误文件传输<br/>error.log(10MB*10)"]
    Init --> Combined["常规文件传输<br/>combined.log(10MB*10)"]
    Init --> HttpFile["HTTP文件传输<br/>http.log(10MB*5)"]
    Console --> Logger["创建logger实例"]
    ErrorFile --> Logger
    Combined --> Logger
    HttpFile --> Logger
    

图表来源

• server/src/services/logger.service.ts:11-72

章节来源

• server/src/services/logger.service.ts:11-72

Sentry错误监控集成

• 初始化与采样
  • 通过环境变量配置DSN；生产环境trace采样率较低，开发环境较高；开启性能剖析。
• 过滤策略
  • 对特定无关错误（如Redis连接拒绝）进行过滤，避免噪声。
• 上下文与标签
  • 支持设置用户、标签、上下文，便于问题定位。

• Koa中间件集成

  • 在Sentry错误处理中间件中注入请求方法、URL、用户信息，统一上报。

    sequenceDiagram
    participant App as "应用启动<br/>app.ts"
    participant Sentry as "Sentry初始化<br/>sentry.service.ts"
    participant MW as "Sentry错误处理中间件<br/>sentry.service.ts"
    participant Route as "业务路由"
    App->>Sentry : initSentry()
    Sentry-->>App : 初始化完成
    App->>MW : 注册中间件
    MW->>Route : 处理请求
    Route-->>MW : 抛出异常
    MW->>Sentry : captureException(带上下文)
    Sentry-->>MW : 上报完成
    MW-->>Route : 重新抛出异常
    

图表来源

• server/src/app.ts:135-136
• server/src/services/sentry.service.ts:7-43
• server/src/services/sentry.service.ts:92-110

章节来源

• server/src/services/sentry.service.ts:7-43
• server/src/services/sentry.service.ts:92-110

请求日志与审计

• 记录内容
  • 请求ID、方法、路径、查询字符串、头部、IP、UA；响应状态、耗时、响应大小；错误信息与堆栈。
• 状态码分级
  • 5xx：ERROR；4xx：WARN；2xx/3xx：INFO。
• 持久化与分析
  • 内存中维护请求日志，异步写入requests.json；提供过滤、统计、错误分析、自动修复建议、清理策略。

• 审计能力

  • 提供日志列表、最近错误、错误分析、统计数据、清理接口；支持按路径、状态、时间范围筛选。

    classDiagram
    class LogService {
    +logs : RequestLog[]
    +logRequest(log)
    +getLogs(filter)
    +getErrorLogs()
    +getRecentErrors(count)
    +analyzeErrors()
    +autoAnalyzeError(log)
    +clearLogs(olderThanHours?)
    +getStats()
    }
    class RequestLog {
    +requestId : string
    +timestamp : Date
    +method : string
    +path : string
    +query : string
    +status : number
    +responseTime : number
    +responseSize : number
    +level : LogLevel
    +error? : string
    +stack? : string
    +headers : Record
    +ip : string
    +userAgent : string
    +body? : any
    }
    LogService --> RequestLog : "管理"
    

图表来源

• server/src/services/log.service.ts:42-354

章节来源

• server/src/services/requestLogger.ts:5-54
• server/src/services/log.service.ts:42-354
• server/src/services/log.controller.ts:1-233

性能监控与指标

• 指标维度
  • 全局：总请求数、平均响应时间、慢请求数、错误总数。
  • 端点级：请求数、平均/最大耗时、错误数。
• 慢请求阈值
  • 默认1秒，超过阈值在控制台告警。

• 指标路由

  • 提供/getMetrics接口，返回当前指标与错误率百分比。

    flowchart TD
    PMStart["进入性能监控"] --> Measure["记录开始时间"]
    Measure --> Next["调用下游"]
    Next --> Done{"是否异常?"}
    Done --> |否| Update["更新全局与端点指标"]
    Update --> Slow{"是否慢请求?"}
    Slow --> |是| Warn["控制台告警"]
    Slow --> |否| Resp["设置X-Response-Time"]
    Done --> |是| ErrUpdate["错误计数+1"]
    ErrUpdate --> Throw["重新抛出错误"]
    Resp --> PMEnd["结束"]
    Warn --> PMEnd
    Throw --> PMEnd
    

图表来源

• server/src/middleware/performance.ts:29-109

章节来源

• server/src/middleware/performance.ts:29-109

错误分类与传播流程

• 错误类型
  • AppError及其子类：未授权、禁止、未找到、请求错误、配额超限。

• 传播路径

  • 业务层抛出自定义错误 → 全局错误处理中间件标准化响应 → Sentry中间件上报（如启用） → HTTP日志记录 → 请求日志持久化。

    sequenceDiagram
    participant Biz as "业务层"
    participant ErrMW as "全局错误处理"
    participant SentryMW as "Sentry中间件"
    participant HttpLog as "HTTP日志"
    participant ReqLog as "请求日志"
    Biz->>Biz : 抛出AppError/子类
    Biz->>ErrMW : 未捕获异常
    ErrMW-->>Biz : 标准化响应(code,message,data)
    ErrMW->>SentryMW : 上报异常(可选)
    ErrMW->>HttpLog : 记录HTTP日志
    ErrMW->>ReqLog : 记录请求日志
    

图表来源

• server/src/middleware/errorHandler.ts:27-67
• server/src/services/sentry.service.ts:92-110
• server/src/services/logger.service.ts:75-102
• server/src/services/requestLogger.ts:5-54

章节来源

• server/src/middleware/errorHandler.ts:27-67
• server/src/services/sentry.service.ts:92-110
• server/src/services/logger.service.ts:75-102
• server/src/services/requestLogger.ts:5-54

依赖关系分析

• 组件耦合
  • app.ts集中装配各中间件，形成清晰的请求管线。
  • requestLogger依赖log.service进行持久化与分析；log.controller提供管理接口。
  • performance与logger/sentry相互独立，分别负责指标与观测。

• 外部依赖

  • Winston用于结构化日志；Sentry用于错误监控与聚合；Koa中间件生态。

    graph LR
    App["app.ts"] --> EH["errorHandler.ts"]
    App --> SMW["sentry.service.ts"]
    App --> PM["performance.ts"]
    App --> HL["logger.service.ts"]
    App --> RL["requestLogger.ts"]
    RL --> LS["log.service.ts"]
    LS --> LC["log.controller.ts"]
    

图表来源

• server/src/app.ts:64-67
• server/src/services/requestLogger.ts:5-54
• server/src/services/log.service.ts:42-354
• server/src/services/log.controller.ts:1-233

章节来源

• server/src/app.ts:64-67

性能考量

• 日志写入
  • 请求日志采用setTimeout异步落盘，避免阻塞主请求链路。
• 文件轮转
  • 合理的单文件大小与文件数量限制，平衡磁盘占用与历史保留。
• 指标计算
  • 平均值与端点级统计采用在线递推公式，内存占用低、实时性强。
• 采样与过滤
  • Sentry在生产环境降低trace采样率，减少开销；对无关错误进行过滤。

章节来源

• server/src/services/log.service.ts:130-154
• server/src/services/logger.service.ts:38-64
• server/src/middleware/performance.ts:49-75
• server/src/services/sentry.service.ts:18-38

故障排查指南

• 常见问题定位
  • 查看HTTP日志文件（error.log/combined.log/http.log）定位异常请求与堆栈。
  • 使用请求日志接口筛选路径、状态、时间范围，结合错误分析接口识别重复错误模式。
• 自动修复建议
  • 使用“自动分析”接口输入错误描述，获取预设的修复建议；必要时调用“执行自动修复”接口进行模拟修复。
• 清理与归档
  • 使用删除接口按小时清理旧日志，释放磁盘空间；定期归档重要日志文件。
• 性能问题
  • 通过/getMetrics查看慢请求与错误率；关注控制台慢请求告警；结合端点级指标定位热点接口。
• Sentry集成
  • 确认SENRAY_DSN配置；检查过滤规则是否误伤；在Sentry面板查看聚合与告警。

章节来源

• server/src/services/log.controller.ts:88-202
• server/src/middleware/performance.ts:99-109
• server/src/services/sentry.service.ts:7-43

结论

该系统以Koa中间件为核心，结合Winston、Sentry与自研日志服务，实现了从异常捕获、标准化响应、结构化日志、性能监控到自动修复建议的全链路可观测体系。通过明确的错误分类、严格的日志轮转与采样策略、以及可扩展的错误模式识别，平台能够在复杂场景下保持高稳定性与可维护性。

附录

配置示例与环境变量

• 日志级别
  • LOG_LEVEL：默认debug，生产环境建议info。
• Sentry
  • SENTRY_DSN：必填；NODE_ENV决定环境标签与采样率。
• 应用端口与模型
  • PORT/NODE_ENV：应用端口与运行环境；模型切换逻辑由配置模块提供辅助函数。

章节来源

• server/src/services/logger.service.ts:69
• server/src/services/sentry.service.ts:8-18
• server/src/config/index.ts:69-117