日志监控服务.md 16 KB
日志监控服务
本文引用的文件
- server/src/app.ts
- server/src/services/logger.service.ts
- server/src/services/sentry.service.ts
- server/src/middleware/errorHandler.ts
- server/src/services/requestLogger.ts
- server/src/services/log.service.ts
- server/src/services/log.controller.ts
目录
简介
本文件面向AI有声书生成平台的日志监控服务，系统性阐述错误监控（Sentry）、请求日志中间件、日志格式与轮转策略、性能监控与指标采集、以及日志在系统调试、性能分析与安全审计中的关键作用。文档基于仓库中现有的日志与监控实现进行深入分析，并提供可操作的集成与扩展建议。
项目结构
日志监控相关能力主要分布在以下模块：
- 应用入口：注册中间件与路由，统一启动流程
- 日志服务：基于Winston的多通道日志输出、HTTP请求日志中间件
- 错误监控：基于Sentry的错误捕获、性能采样与错误过滤
- 请求日志：独立的请求日志中间件与持久化服务
日志控制器：提供日志查询、错误分析、统计与清理等API
graph TB subgraph "应用层" APP["应用入口<br/>server/src/app.ts"] end subgraph "日志与监控" WLOG["Winston日志服务<br/>server/src/services/logger.service.ts"] SENTRY["Sentry错误监控<br/>server/src/services/sentry.service.ts"] REQLOG["请求日志中间件<br/>server/src/services/requestLogger.ts"] LOGSVC["日志服务(内存+文件)<br/>server/src/services/log.service.ts"] LOGCTRL["日志控制器<br/>server/src/services/log.controller.ts"] ERRMW["错误处理中间件<br/>server/src/middleware/errorHandler.ts"] end APP --> WLOG APP --> SENTRY APP --> REQLOG APP --> LOGCTRL REQLOG --> LOGSVC APP --> ERRMW
图表来源
- server/src/app.ts:63-130
- server/src/services/logger.service.ts:67-114
- server/src/services/sentry.service.ts:7-43
- server/src/services/requestLogger.ts:4-57
- server/src/services/log.service.ts:42-354
- server/src/services/log.controller.ts:1-233
- server/src/middleware/errorHandler.ts:3-24
章节来源
- server/src/app.ts:63-130
核心组件
- Winston日志服务：控制台彩色输出、错误/常规/HTTP三类文件日志、按大小与文件数轮转
- Sentry错误监控：DSN初始化、性能采样、错误过滤、上下文与标签设置、Koa错误中间件
- 请求日志中间件：记录请求/响应元数据、状态码分级、异步持久化至内存与文件
- 日志控制器：提供日志查询、错误分析、统计、清理与自动修复建议接口
- 错误处理中间件：统一错误响应、开发环境返回堆栈、基础业务错误类型
章节来源
- server/src/services/logger.service.ts:11-114
- server/src/services/sentry.service.ts:7-113
- server/src/services/requestLogger.ts:4-57
- server/src/services/log.service.ts:4-354
- server/src/services/log.controller.ts:1-233
- server/src/middleware/errorHandler.ts:3-67
架构总览
整体监控链路由“请求进入 -> 错误/性能中间件 -> 请求日志 -> 日志服务 -> 多通道输出”构成；同时通过Sentry对异常进行集中上报与性能采样。
sequenceDiagram
participant C as "客户端"
participant A as "应用入口(app.ts)"
participant MW1 as "错误处理中间件"
participant MW2 as "Sentry错误中间件"
participant MW3 as "性能监控中间件"
participant MW4 as "Winston日志中间件"
participant R as "请求日志中间件"
participant L as "日志服务"
participant S as "Sentry"
C->>A : 发起HTTP请求
A->>MW1 : 进入错误处理
A->>MW2 : 进入Sentry错误中间件
A->>MW3 : 进入性能监控
A->>MW4 : 进入Winston日志
A->>R : 进入请求日志中间件
R->>L : 写入请求日志(内存+文件)
MW4-->>C : 返回响应
MW2-->>S : 上报异常(如发生)
MW3-->>A : 采集性能指标
图表来源
- server/src/app.ts:63-130
- server/src/middleware/errorHandler.ts:3-24
- server/src/services/sentry.service.ts:92-110
- server/src/services/logger.service.ts:74-102
- server/src/services/requestLogger.ts:4-57
- server/src/services/log.service.ts:140-171
详细组件分析
Winston日志服务与HTTP请求日志中间件
- 多通道输出
- 控制台：开发环境输出彩色日志，生产环境提升至info级别
- 错误日志文件：仅记录error级别，包含堆栈
- 常规日志文件：记录info及以上级别，包含堆栈
- HTTP请求日志文件：记录http级别，包含方法、URL、状态、耗时、IP、UA
- 日志格式：统一时间戳、级别、消息或堆栈、附加元数据JSON化
- HTTP中间件：在next()后计算耗时并写入HTTP日志；异常时写入错误日志并抛出
环境变量控制：LOG_LEVEL决定全局级别，NODE_ENV影响控制台级别
flowchart TD Start(["进入httpLogger"]) --> CallNext["执行下游中间件(next)"] CallNext --> IsErr{"是否抛出异常?"} IsErr -- 否 --> Calc["计算耗时(ms)"] Calc --> WriteHttp["写入HTTP日志文件"] WriteHttp --> End(["结束"]) IsErr -- 是 --> CalcErr["计算耗时(ms)"] CalcErr --> WriteErr["写入错误日志(含堆栈)"] WriteErr --> Throw["重新抛出异常"] Throw --> End
图表来源
- server/src/services/logger.service.ts:74-102
章节来源
- server/src/services/logger.service.ts:11-114
Sentry错误监控集成
- 初始化：读取SENTRY_DSN，未配置则跳过；设置环境、采样率、性能分析集成、错误过滤
- 错误过滤：忽略特定无关错误（如Redis连接被拒绝）
- 上下文与标签：支持设置用户、标签、严重级别、自定义上下文
Koa错误中间件：捕获异常并携带method/url/user上下文上报
sequenceDiagram participant M as "Sentry错误中间件" participant C as "Koa上下文" participant S as "Sentry SDK" M->>C : 获取method/url/user M->>S : withScope设置标签/用户 M->>S : captureException(异常) M-->>C : 抛出异常(交由后续中间件处理)
图表来源
- server/src/services/sentry.service.ts:92-110
- server/src/services/sentry.service.ts:7-43
章节来源
- server/src/services/sentry.service.ts:7-113
请求日志中间件与日志服务
- 请求日志中间件：生成请求ID、记录请求头、IP、UA、状态码、响应时间与大小；根据状态码分级
- 日志服务：内存中维护请求日志，限制最大条数；异步落盘至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 : map +ip : string +userAgent : string +body? : any } LogService --> RequestLog : "管理"
图表来源
- server/src/services/log.service.ts:42-354
- server/src/services/requestLogger.ts:4-57
章节来源
- server/src/services/requestLogger.ts:4-57
- server/src/services/log.service.ts:42-354
错误处理中间件与自定义错误类型
- 统一错误响应：设置状态码与标准返回结构
- 开发环境：附加堆栈信息
自定义错误类：AppError、UnauthorizedError、ForbiddenError、NotFoundError、BadRequestError、QuotaExceededError
flowchart TD Enter(["进入errorHandler"]) --> TryNext["执行下游(next)"] TryNext --> Catch{"是否抛出异常?"} Catch -- 否 --> End(["结束"]) Catch -- 是 --> BuildResp["构造错误响应(含状态/代码/消息)"] BuildResp --> DevEnv{"开发环境?"} DevEnv -- 是 --> AddStack["附加堆栈"] DevEnv -- 否 --> SkipStack["不附加堆栈"] AddStack --> End SkipStack --> End
图表来源
- server/src/middleware/errorHandler.ts:3-24
章节来源
- server/src/middleware/errorHandler.ts:3-67
日志控制器与API
- 查询请求日志：支持按级别、路径、状态、时间范围筛选，分页返回
- 获取错误日志与分析：最近错误、错误聚合分析、自动修复建议
- 统计与清理：总览统计、按小时清理旧日志
- 测试接口：模拟多种错误类型便于联调
章节来源
- server/src/services/log.controller.ts:1-233
依赖关系分析
- 应用入口统一注册中间件顺序：错误处理 -> Sentry错误中间件 -> 性能监控 -> Winston日志 -> 安全中间件 -> CORS -> BodyParser -> 静态文件 -> 路由
- 请求日志中间件与日志服务解耦，既可通过Winston输出到文件，也可通过请求日志中间件持久化到内存与文件
Sentry与Winston并行工作，前者专注异常与性能，后者专注结构化日志与HTTP追踪
graph LR APP["app.ts"] --> ERR["errorHandler.ts"] APP --> SERR["sentry.service.ts"] APP --> PERF["performance.ts"] APP --> WLOG["logger.service.ts"] APP --> SEC["security.ts"] APP --> CORS["cors"] APP --> BODY["bodyparser"] APP --> STATIC["static"] APP --> ROUTER["log.controller.ts"] ROUTER --> REQLOG["requestLogger.ts"] REQLOG --> LOGSVC["log.service.ts"]
图表来源
- server/src/app.ts:63-130
- server/src/services/log.controller.ts:1-233
- server/src/services/requestLogger.ts:4-57
- server/src/services/log.service.ts:42-354
- server/src/services/logger.service.ts:67-114
- server/src/services/sentry.service.ts:7-43
章节来源
- server/src/app.ts:63-130
性能考量
- Winston轮转策略：单文件最大10MB，错误/常规各10个文件，HTTP 5个文件，避免磁盘无限增长
- 请求日志异步落盘：通过延时保存减少IO阻塞
- Sentry采样率：生产环境降低Traces采样，提高性能；开启CPU Profiling采样
- 中间件顺序：将性能监控置于错误捕获之后，确保异常也能被采样
章节来源
- server/src/services/logger.service.ts:38-64
- server/src/services/log.service.ts:130-138
- server/src/services/sentry.service.ts:15-22
故障排查指南
- Sentry未生效
- 检查是否配置SENTRY_DSN；若未配置，初始化会跳过
- 查看初始化日志输出
- 错误未上报
- 确认Sentry错误中间件已在应用入口注册
- 检查错误过滤规则是否误判
- 日志缺失
- 确认Winston日志目录存在且有写权限
- 检查LOG_LEVEL与NODE_ENV是否导致日志被抑制
- 请求日志不显示
- 确认请求日志中间件已注册
- 检查日志文件是否被清理或轮转覆盖
- 自动修复建议无效
- 确认错误内容与内置正则匹配
- 可扩展错误模式与修复建议映射
章节来源
- server/src/services/sentry.service.ts:7-43
- server/src/services/logger.service.ts:5-9
- server/src/services/requestLogger.ts:4-57
- server/src/services/log.service.ts:66-110
结论
该日志监控体系以Winston提供结构化日志与HTTP追踪，以Sentry提供异常与性能采样，辅以独立的请求日志中间件与日志服务，形成“请求可观测、异常可追踪、性能可度量”的闭环。通过清晰的日志级别、标准化格式与轮转策略，结合错误分析与自动修复建议，显著提升系统调试效率与稳定性保障。
附录
环境变量与配置要点
- LOG_LEVEL：Winston全局日志级别
- NODE_ENV：影响控制台输出级别与Sentry采样率
- SENTRY_DSN：Sentry数据源标识，未配置则跳过初始化
章节来源
- server/src/services/logger.service.ts:68-72
- server/src/services/sentry.service.ts:7-43
实际代码示例（路径指引）
- 初始化Sentry：server/src/services/sentry.service.ts:7-43
- 设置用户上下文与标签：server/src/services/sentry.service.ts:75-87
- 捕获异常与消息：server/src/services/sentry.service.ts:48-70
- Koa错误中间件：server/src/services/sentry.service.ts:92-110
- Winston日志配置与HTTP中间件：server/src/services/logger.service.ts:11-114
- 请求日志中间件：server/src/services/requestLogger.ts:4-57
- 日志服务与错误分析：server/src/services/log.service.ts:42-354
- 日志控制器API：server/src/services/log.controller.ts:1-233
- 应用入口注册顺序：server/src/app.ts:63-130