# 日志监控服务

<cite>
**本文引用的文件**
- [server/src/app.ts](file://server/src/app.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/middleware/errorHandler.ts](file://server/src/middleware/errorHandler.ts)
- [server/src/services/requestLogger.ts](file://server/src/services/requestLogger.ts)
- [server/src/services/log.service.ts](file://server/src/services/log.service.ts)
- [server/src/services/log.controller.ts](file://server/src/services/log.controller.ts)
</cite>

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

## 简介
本文件面向AI有声书生成平台的日志监控服务，系统性阐述错误监控（Sentry）、请求日志中间件、日志格式与轮转策略、性能监控与指标采集、以及日志在系统调试、性能分析与安全审计中的关键作用。文档基于仓库中现有的日志与监控实现进行深入分析，并提供可操作的集成与扩展建议。

## 项目结构
日志监控相关能力主要分布在以下模块：
- 应用入口：注册中间件与路由，统一启动流程
- 日志服务：基于Winston的多通道日志输出、HTTP请求日志中间件
- 错误监控：基于Sentry的错误捕获、性能采样与错误过滤
- 请求日志：独立的请求日志中间件与持久化服务
- 日志控制器：提供日志查询、错误分析、统计与清理等API

```mermaid
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](file://server/src/app.ts#L63-L130)
- [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/requestLogger.ts:4-57](file://server/src/services/requestLogger.ts#L4-L57)
- [server/src/services/log.service.ts:42-354](file://server/src/services/log.service.ts#L42-L354)
- [server/src/services/log.controller.ts:1-233](file://server/src/services/log.controller.ts#L1-L233)
- [server/src/middleware/errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)

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

## 核心组件
- Winston日志服务：控制台彩色输出、错误/常规/HTTP三类文件日志、按大小与文件数轮转
- Sentry错误监控：DSN初始化、性能采样、错误过滤、上下文与标签设置、Koa错误中间件
- 请求日志中间件：记录请求/响应元数据、状态码分级、异步持久化至内存与文件
- 日志控制器：提供日志查询、错误分析、统计、清理与自动修复建议接口
- 错误处理中间件：统一错误响应、开发环境返回堆栈、基础业务错误类型

章节来源
- [server/src/services/logger.service.ts:11-114](file://server/src/services/logger.service.ts#L11-L114)
- [server/src/services/sentry.service.ts:7-113](file://server/src/services/sentry.service.ts#L7-L113)
- [server/src/services/requestLogger.ts:4-57](file://server/src/services/requestLogger.ts#L4-L57)
- [server/src/services/log.service.ts:4-354](file://server/src/services/log.service.ts#L4-L354)
- [server/src/services/log.controller.ts:1-233](file://server/src/services/log.controller.ts#L1-L233)
- [server/src/middleware/errorHandler.ts:3-67](file://server/src/middleware/errorHandler.ts#L3-L67)

## 架构总览
整体监控链路由“请求进入 -> 错误/性能中间件 -> 请求日志 -> 日志服务 -> 多通道输出”构成；同时通过Sentry对异常进行集中上报与性能采样。

```mermaid
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](file://server/src/app.ts#L63-L130)
- [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)
- [server/src/services/logger.service.ts:74-102](file://server/src/services/logger.service.ts#L74-L102)
- [server/src/services/requestLogger.ts:4-57](file://server/src/services/requestLogger.ts#L4-L57)
- [server/src/services/log.service.ts:140-171](file://server/src/services/log.service.ts#L140-L171)

## 详细组件分析

### Winston日志服务与HTTP请求日志中间件
- 多通道输出
  - 控制台：开发环境输出彩色日志，生产环境提升至info级别
  - 错误日志文件：仅记录error级别，包含堆栈
  - 常规日志文件：记录info及以上级别，包含堆栈
  - HTTP请求日志文件：记录http级别，包含方法、URL、状态、耗时、IP、UA
- 日志格式：统一时间戳、级别、消息或堆栈、附加元数据JSON化
- HTTP中间件：在next()后计算耗时并写入HTTP日志；异常时写入错误日志并抛出
- 环境变量控制：LOG_LEVEL决定全局级别，NODE_ENV影响控制台级别

```mermaid
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](file://server/src/services/logger.service.ts#L74-L102)

章节来源
- [server/src/services/logger.service.ts:11-114](file://server/src/services/logger.service.ts#L11-L114)

### Sentry错误监控集成
- 初始化：读取SENTRY_DSN，未配置则跳过；设置环境、采样率、性能分析集成、错误过滤
- 错误过滤：忽略特定无关错误（如Redis连接被拒绝）
- 上下文与标签：支持设置用户、标签、严重级别、自定义上下文
- Koa错误中间件：捕获异常并携带method/url/user上下文上报

```mermaid
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](file://server/src/services/sentry.service.ts#L92-L110)
- [server/src/services/sentry.service.ts:7-43](file://server/src/services/sentry.service.ts#L7-L43)

章节来源
- [server/src/services/sentry.service.ts:7-113](file://server/src/services/sentry.service.ts#L7-L113)

### 请求日志中间件与日志服务
- 请求日志中间件：生成请求ID、记录请求头、IP、UA、状态码、响应时间与大小；根据状态码分级
- 日志服务：内存中维护请求日志，限制最大条数；异步落盘至requests.json；提供查询、错误分析、统计、清理、自动修复建议
- 错误模式识别：内置常见错误类型的正则与修复建议，支持自动分析与建议返回

```mermaid
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](file://server/src/services/log.service.ts#L42-L354)
- [server/src/services/requestLogger.ts:4-57](file://server/src/services/requestLogger.ts#L4-L57)

章节来源
- [server/src/services/requestLogger.ts:4-57](file://server/src/services/requestLogger.ts#L4-L57)
- [server/src/services/log.service.ts:42-354](file://server/src/services/log.service.ts#L42-L354)

### 错误处理中间件与自定义错误类型
- 统一错误响应：设置状态码与标准返回结构
- 开发环境：附加堆栈信息
- 自定义错误类：AppError、UnauthorizedError、ForbiddenError、NotFoundError、BadRequestError、QuotaExceededError

```mermaid
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](file://server/src/middleware/errorHandler.ts#L3-L24)

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

### 日志控制器与API
- 查询请求日志：支持按级别、路径、状态、时间范围筛选，分页返回
- 获取错误日志与分析：最近错误、错误聚合分析、自动修复建议
- 统计与清理：总览统计、按小时清理旧日志
- 测试接口：模拟多种错误类型便于联调

章节来源
- [server/src/services/log.controller.ts:1-233](file://server/src/services/log.controller.ts#L1-L233)

## 依赖关系分析
- 应用入口统一注册中间件顺序：错误处理 -> Sentry错误中间件 -> 性能监控 -> Winston日志 -> 安全中间件 -> CORS -> BodyParser -> 静态文件 -> 路由
- 请求日志中间件与日志服务解耦，既可通过Winston输出到文件，也可通过请求日志中间件持久化到内存与文件
- Sentry与Winston并行工作，前者专注异常与性能，后者专注结构化日志与HTTP追踪

```mermaid
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](file://server/src/app.ts#L63-L130)
- [server/src/services/log.controller.ts:1-233](file://server/src/services/log.controller.ts#L1-L233)
- [server/src/services/requestLogger.ts:4-57](file://server/src/services/requestLogger.ts#L4-L57)
- [server/src/services/log.service.ts:42-354](file://server/src/services/log.service.ts#L42-L354)
- [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/app.ts:63-130](file://server/src/app.ts#L63-L130)

## 性能考量
- Winston轮转策略：单文件最大10MB，错误/常规各10个文件，HTTP 5个文件，避免磁盘无限增长
- 请求日志异步落盘：通过延时保存减少IO阻塞
- Sentry采样率：生产环境降低Traces采样，提高性能；开启CPU Profiling采样
- 中间件顺序：将性能监控置于错误捕获之后，确保异常也能被采样

章节来源
- [server/src/services/logger.service.ts:38-64](file://server/src/services/logger.service.ts#L38-L64)
- [server/src/services/log.service.ts:130-138](file://server/src/services/log.service.ts#L130-L138)
- [server/src/services/sentry.service.ts:15-22](file://server/src/services/sentry.service.ts#L15-L22)

## 故障排查指南
- Sentry未生效
  - 检查是否配置SENTRY_DSN；若未配置，初始化会跳过
  - 查看初始化日志输出
- 错误未上报
  - 确认Sentry错误中间件已在应用入口注册
  - 检查错误过滤规则是否误判
- 日志缺失
  - 确认Winston日志目录存在且有写权限
  - 检查LOG_LEVEL与NODE_ENV是否导致日志被抑制
- 请求日志不显示
  - 确认请求日志中间件已注册
  - 检查日志文件是否被清理或轮转覆盖
- 自动修复建议无效
  - 确认错误内容与内置正则匹配
  - 可扩展错误模式与修复建议映射

章节来源
- [server/src/services/sentry.service.ts:7-43](file://server/src/services/sentry.service.ts#L7-L43)
- [server/src/services/logger.service.ts:5-9](file://server/src/services/logger.service.ts#L5-L9)
- [server/src/services/requestLogger.ts:4-57](file://server/src/services/requestLogger.ts#L4-L57)
- [server/src/services/log.service.ts:66-110](file://server/src/services/log.service.ts#L66-L110)

## 结论
该日志监控体系以Winston提供结构化日志与HTTP追踪，以Sentry提供异常与性能采样，辅以独立的请求日志中间件与日志服务，形成“请求可观测、异常可追踪、性能可度量”的闭环。通过清晰的日志级别、标准化格式与轮转策略，结合错误分析与自动修复建议，显著提升系统调试效率与稳定性保障。

## 附录

### 环境变量与配置要点
- LOG_LEVEL：Winston全局日志级别
- NODE_ENV：影响控制台输出级别与Sentry采样率
- SENTRY_DSN：Sentry数据源标识，未配置则跳过初始化

章节来源
- [server/src/services/logger.service.ts:68-72](file://server/src/services/logger.service.ts#L68-L72)
- [server/src/services/sentry.service.ts:7-43](file://server/src/services/sentry.service.ts#L7-L43)

### 实际代码示例（路径指引）
- 初始化Sentry：[server/src/services/sentry.service.ts:7-43](file://server/src/services/sentry.service.ts#L7-L43)
- 设置用户上下文与标签：[server/src/services/sentry.service.ts:75-87](file://server/src/services/sentry.service.ts#L75-L87)
- 捕获异常与消息：[server/src/services/sentry.service.ts:48-70](file://server/src/services/sentry.service.ts#L48-L70)
- Koa错误中间件：[server/src/services/sentry.service.ts:92-110](file://server/src/services/sentry.service.ts#L92-L110)
- Winston日志配置与HTTP中间件：[server/src/services/logger.service.ts:11-114](file://server/src/services/logger.service.ts#L11-L114)
- 请求日志中间件：[server/src/services/requestLogger.ts:4-57](file://server/src/services/requestLogger.ts#L4-L57)
- 日志服务与错误分析：[server/src/services/log.service.ts:42-354](file://server/src/services/log.service.ts#L42-L354)
- 日志控制器API：[server/src/services/log.controller.ts:1-233](file://server/src/services/log.controller.ts#L1-L233)
- 应用入口注册顺序：[server/src/app.ts:63-130](file://server/src/app.ts#L63-L130)