audio_codebuddy/.qoder/repowiki/zh/content/系统架构/部署架构/监控与日志.md

监控与日志

本文引用的文件

• server/src/services/sentry.service.ts
• server/dist/services/sentry.service.js
• server/src/services/logger.service.ts
• server/dist/services/logger.service.js
• server/src/middleware/errorHandler.ts
• server/src/app.ts
• server/monitor-book.js
• server/monitor-generation.js
• server/monitor-progress.js
• feature_list_monitor.json

目录

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

简介

本文件面向AI有声书生成平台，系统性说明监控与日志体系的设计与实践，覆盖以下方面：

• Sentry错误监控：初始化、异常捕获、异常分类、Koa中间件集成、采样率与过滤策略
• Winston日志系统：日志级别、格式化输出、文件轮转策略、HTTP请求日志中间件
• 性能监控指标：API响应时间、数据库查询性能、内存使用情况的采集与分析
• 实时监控仪表板：关键指标可视化、趋势分析、异常检测的落地路径
• 日志分析与故障排查：日志聚合、搜索过滤、关联分析的方法论与实操步骤

项目结构

后端采用Koa框架，监控与日志能力通过独立服务模块与中间件注入到应用生命周期中；数据库监控脚本用于观测生成流程状态。

graph TB
subgraph "应用层"
APP["应用入口<br/>server/src/app.ts"]
ROUTER["路由注册<br/>app.ts"]
end
subgraph "监控与日志服务"
SENTRY["Sentry服务<br/>server/src/services/sentry.service.ts"]
WINSTON["Winston日志服务<br/>server/src/services/logger.service.ts"]
end
subgraph "中间件"
ERR["错误处理中间件<br/>server/src/middleware/errorHandler.ts"]
PERF["性能监控中间件<br/>app.ts 引入"]
end
subgraph "数据库监控脚本"
MON1["监控书籍进度<br/>server/monitor-book.js"]
MON2["监控生成流程<br/>server/monitor-generation.js"]
MON3["监控进度概览<br/>server/monitor-progress.js"]
end
APP --> ROUTER
APP --> SENTRY
APP --> WINSTON
APP --> ERR
APP --> PERF
ROUTER --> MON1
ROUTER --> MON2
ROUTER --> MON3

图表来源

• server/src/app.ts:133-194
• server/src/services/sentry.service.ts:1-113
• server/src/services/logger.service.ts:1-114
• server/src/middleware/errorHandler.ts:1-67
• server/monitor-book.js:1-56
• server/monitor-generation.js:1-60
• server/monitor-progress.js:1-39

章节来源

• server/src/app.ts:133-194

核心组件

• Sentry错误监控服务：负责初始化、异常捕获、消息上报、用户与标签上下文设置、Koa错误中间件集成
• Winston日志服务：负责控制台与多文件输出、格式化、轮转策略、HTTP请求日志中间件
• 错误处理中间件：统一错误响应、开发环境堆栈回传、自定义业务错误类型
• 数据库监控脚本：周期性查询书籍状态与章节统计，辅助生成流程可观测性

章节来源

• server/src/services/sentry.service.ts:1-113
• server/dist/services/sentry.service.js:1-142
• server/src/services/logger.service.ts:1-114
• server/dist/services/logger.service.js:1-95
• server/src/middleware/errorHandler.ts:1-67

架构总览

下图展示Sentry与Winston在应用中的集成位置与调用链路。

sequenceDiagram
participant Client as "客户端"
participant Koa as "Koa应用<br/>server/src/app.ts"
participant SentryMW as "Sentry错误中间件"
participant Handler as "业务处理器"
participant Winston as "Winston日志中间件"
participant SentrySvc as "Sentry服务"
Client->>Koa : "HTTP请求"
Koa->>SentryMW : "进入Sentry错误中间件"
Koa->>Winston : "进入Winston日志中间件"
Winston->>Winston : "记录请求开始时间"
Koa->>Handler : "执行业务逻辑"
alt 发生异常
Handler-->>SentryMW : "抛出异常"
SentryMW->>SentrySvc : "captureException(含method/url/user)"
SentryMW-->>Koa : "继续抛出异常"
else 正常返回
Handler-->>Winston : "正常返回"
Winston->>Winston : "计算耗时并记录HTTP日志"
end
Koa-->>Client : "响应"

图表来源

• server/src/app.ts:64-75
• server/src/app.ts:92-97
• server/src/services/sentry.service.ts:92-110
• server/src/services/logger.service.ts:75-102

详细组件分析

Sentry错误监控

• 初始化与采样
  • 从环境变量读取DSN，未配置则跳过初始化并在控制台提示
  • 生产环境采样率为10%，开发环境为100%
  • 启用Node Profiling集成，便于CPU火焰图分析
• 异常捕获与分类
  • 提供捕获异常与消息的便捷函数，并支持设置上下文与严重级别
  • 在Koa中间件中自动附加method、url、用户ID等标签，便于分类与检索

• 错误过滤

  • 内置过滤器可忽略特定无意义的网络连接拒绝错误，降低噪声

    flowchart TD
    Start(["初始化Sentry"]) --> CheckDSN{"是否配置DSN?"}
    CheckDSN --> |否| Skip["跳过初始化并记录提示"]
    CheckDSN --> |是| Init["初始化Sentry<br/>设置采样率/集成/过滤器"]
    Init --> Ready["Sentry就绪"]
    Ready --> OnError["捕获异常"]
    OnError --> Scope["设置上下文/标签/用户"]
    Scope --> Capture["上报Sentry"]
    

图表来源

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

章节来源

• server/src/services/sentry.service.ts:1-113
• server/dist/services/sentry.service.js:1-142

Winston日志系统

• 日志级别与输出
  • 控制台输出级别随NODE_ENV动态调整（生产为info，开发为debug）
  • LOG_LEVEL环境变量可覆盖默认级别
• 文件输出与轮转
  • error.log：仅error级别，最大10MB，最多保留10个文件
  • combined.log：通用日志，最大10MB，最多保留10个文件
  • http.log：HTTP请求日志，最大10MB，最多保留5个文件
• 格式化
  • 统一时间戳格式、包含stack字段、支持结构化元数据打印

• HTTP请求日志中间件

  • 记录method、url、status、duration、ip、userAgent等字段

  • 异常时记录错误信息与堆栈

    flowchart TD
    ReqStart["请求开始"] --> Calc["计算耗时"]
    Calc --> Normal{"正常返回?"}
    Normal --> |是| LogHTTP["写入HTTP日志文件"]
    Normal --> |否| LogErr["写入错误日志文件<br/>包含错误与堆栈"]
    LogHTTP --> Done["结束"]
    LogErr --> Done
    

图表来源

• server/src/services/logger.service.ts:75-102
• server/src/services/logger.service.ts:29-64

章节来源

• server/src/services/logger.service.ts:1-114
• server/dist/services/logger.service.js:1-95

错误处理中间件与自定义错误

• 统一错误响应：设置状态码与标准响应体
• 开发环境：额外返回堆栈信息

• 自定义错误类型：AppError、UnauthorizedError、ForbiddenError、NotFoundError、BadRequestError、QuotaExceededError

  flowchart TD
  Try["执行业务逻辑"] --> Catch{"是否抛错?"}
  Catch --> |否| Next["继续下一个中间件/处理器"]
  Catch --> |是| BuildResp["构造错误响应体<br/>设置状态码/消息"]
  BuildResp --> DevEnv{"是否开发环境?"}
  DevEnv --> |是| AddStack["附加堆栈信息"]
  DevEnv --> |否| SkipStack["不附加堆栈"]
  AddStack --> Return["返回响应"]
  SkipStack --> Return
  

图表来源

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

章节来源

• server/src/middleware/errorHandler.ts:1-67

数据库监控脚本

• monitor-book.js：按3秒间隔轮询指定书籍的章节层级统计，直到完成或失败
• monitor-generation.js：按30秒间隔轮询书籍状态、章节数量与已完成内容数

• monitor-progress.js：按5秒间隔轮询书籍状态与进度

  flowchart TD
  Start(["开始监控"]) --> Loop["循环N次"]
  Loop --> Query["查询书籍状态与章节统计"]
  Query --> Print["打印状态/进度/章节统计"]
  Print --> Check{"状态=completed/failed?"}
  Check --> |是| End["结束并输出最终统计"]
  Check --> |否| Sleep["等待固定间隔"]
  Sleep --> Loop
  

图表来源

• server/monitor-book.js:4-50
• server/monitor-generation.js:4-54
• server/monitor-progress.js:4-33

章节来源

• server/monitor-book.js:1-56
• server/monitor-generation.js:1-60
• server/monitor-progress.js:1-39

依赖关系分析

• 应用入口在启动阶段初始化Sentry，随后连接数据库、测试Redis与存储、初始化WebSocket、启动路由与队列处理器

• 中间件顺序对可观测性至关重要：错误处理中间件应尽早拦截；Sentry中间件负责异常上报；Winston中间件负责日志记录；性能中间件负责指标采集

  graph LR
  Start["应用启动"] --> InitSentry["initSentry()"]
  InitSentry --> ConnectDB["连接数据库"]
  ConnectDB --> TestRedis["测试Redis连接"]
  TestRedis --> TestStorage["测试存储连接"]
  TestStorage --> InitWS["初始化WebSocket"]
  InitWS --> Routes["注册路由"]
  Routes --> Middlewares["中间件链路"]
  Middlewares --> SentryMW["Sentry错误中间件"]
  Middlewares --> WinstonMW["Winston日志中间件"]
  Middlewares --> PerfMW["性能监控中间件"]
  

图表来源

• server/src/app.ts:133-194

章节来源

• server/src/app.ts:133-194

性能考虑

• API响应时间
  • 使用Winston中间件记录每次请求的耗时，结合前端埋点与Sentry事务采样，形成端到端时延画像
• 数据库查询性能
  • 结合Prisma日志与数据库慢查询日志，定位长事务与热点查询
  • 监控脚本可作为轻量级数据库侧观测手段，辅助生成流程稳定性评估
• 内存使用情况
  • 结合Node.js进程指标与容器监控，观察峰值与GC行为
  • 对批量任务（如音频合成）进行分片与限流，避免内存抖动
• 采样与成本平衡
  • Sentry在生产环境采用10%的事务采样，避免高基数追踪带来的成本压力

章节来源

• server/src/services/logger.service.ts:75-102
• server/src/services/sentry.service.ts:15-22
• server/monitor-generation.js:4-54

故障排查指南

• 日志聚合与搜索
  • 使用HTTP日志文件定位请求路径与状态码，结合错误日志快速定位异常堆栈
  • 利用结构化元数据字段进行过滤（如method、url、status、duration）
• 关联分析
  • 将Sentry事件与对应HTTP请求ID关联，结合Winston日志中的时间戳与IP，还原用户行为链路
• 自动化修复与回归
  • 参考功能清单中的“错误自动分析与修复”流程，设计自动化修复接口与状态回写机制
• 常见问题定位
  • Redis连接失败：检查过滤器是否忽略该错误，确认实际连接状态
  • 大文件上传超时：检查bodyparser与koa-body配置及磁盘空间
  • 生成流程卡住：使用监控脚本观察章节状态变化，定位阻塞节点

章节来源

• server/src/services/logger.service.ts:75-102
• server/src/services/sentry.service.ts:24-38
• feature_list_monitor.json:10-44

结论

本监控与日志体系以Sentry与Winston为核心，配合统一错误处理中间件与性能监控中间件，实现了从异常捕获、日志记录到指标采集的全链路可观测性。数据库监控脚本进一步增强了生成流程的可见性。建议后续完善：

• 实时仪表板：基于HTTP日志与Sentry事件构建可视化面板
• 告警规则：针对错误率、P95/P99延迟、数据库慢查询、Redis可用性等建立阈值告警
• 安全与合规：对敏感信息脱敏、限制日志保留周期、审计访问权限

附录

• 环境变量与配置要点
  • SENTRY_DSN：Sentry DSN，未配置时跳过初始化
  • NODE_ENV：影响Sentry采样率与控制台日志级别
  • LOG_LEVEL：覆盖默认日志级别
• 测试与验证
  • 参考功能清单中的后端与前端测试步骤，验证日志中间件、错误日志查询与自动修复接口

章节来源

• server/src/services/sentry.service.ts:8-13
• server/src/services/logger.service.ts:69-72
• feature_list_monitor.json:14-25
• feature_list_monitor.json:30-43