# 监控与日志

<cite>
**本文引用的文件**
- [server/src/services/sentry.service.ts](file://server/src/services/sentry.service.ts)
- [server/dist/services/sentry.service.js](file://server/dist/services/sentry.service.js)
- [server/src/services/logger.service.ts](file://server/src/services/logger.service.ts)
- [server/dist/services/logger.service.js](file://server/dist/services/logger.service.js)
- [server/src/middleware/errorHandler.ts](file://server/src/middleware/errorHandler.ts)
- [server/src/app.ts](file://server/src/app.ts)
- [server/monitor-book.js](file://server/monitor-book.js)
- [server/monitor-generation.js](file://server/monitor-generation.js)
- [server/monitor-progress.js](file://server/monitor-progress.js)
- [feature_list_monitor.json](file://feature_list_monitor.json)
</cite>

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

## 简介
本文件面向AI有声书生成平台，系统性说明监控与日志体系的设计与实践，覆盖以下方面：
- Sentry错误监控：初始化、异常捕获、异常分类、Koa中间件集成、采样率与过滤策略
- Winston日志系统：日志级别、格式化输出、文件轮转策略、HTTP请求日志中间件
- 性能监控指标：API响应时间、数据库查询性能、内存使用情况的采集与分析
- 实时监控仪表板：关键指标可视化、趋势分析、异常检测的落地路径
- 日志分析与故障排查：日志聚合、搜索过滤、关联分析的方法论与实操步骤

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

```mermaid
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](file://server/src/app.ts#L133-L194)
- [server/src/services/sentry.service.ts:1-113](file://server/src/services/sentry.service.ts#L1-L113)
- [server/src/services/logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [server/src/middleware/errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [server/monitor-book.js:1-56](file://server/monitor-book.js#L1-L56)
- [server/monitor-generation.js:1-60](file://server/monitor-generation.js#L1-L60)
- [server/monitor-progress.js:1-39](file://server/monitor-progress.js#L1-L39)

**章节来源**
- [server/src/app.ts:133-194](file://server/src/app.ts#L133-L194)

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

**章节来源**
- [server/src/services/sentry.service.ts:1-113](file://server/src/services/sentry.service.ts#L1-L113)
- [server/dist/services/sentry.service.js:1-142](file://server/dist/services/sentry.service.js#L1-L142)
- [server/src/services/logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [server/dist/services/logger.service.js:1-95](file://server/dist/services/logger.service.js#L1-L95)
- [server/src/middleware/errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)

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

```mermaid
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](file://server/src/app.ts#L64-L75)
- [server/src/app.ts:92-97](file://server/src/app.ts#L92-L97)
- [server/src/services/sentry.service.ts:92-110](file://server/src/services/sentry.service.ts#L92-L110)
- [server/src/services/logger.service.ts:75-102](file://server/src/services/logger.service.ts#L75-L102)

## 详细组件分析

### Sentry错误监控
- 初始化与采样
  - 从环境变量读取DSN，未配置则跳过初始化并在控制台提示
  - 生产环境采样率为10%，开发环境为100%
  - 启用Node Profiling集成，便于CPU火焰图分析
- 异常捕获与分类
  - 提供捕获异常与消息的便捷函数，并支持设置上下文与严重级别
  - 在Koa中间件中自动附加method、url、用户ID等标签，便于分类与检索
- 错误过滤
  - 内置过滤器可忽略特定无意义的网络连接拒绝错误，降低噪声

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

**章节来源**
- [server/src/services/sentry.service.ts:1-113](file://server/src/services/sentry.service.ts#L1-L113)
- [server/dist/services/sentry.service.js:1-142](file://server/dist/services/sentry.service.js#L1-L142)

### 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等字段
  - 异常时记录错误信息与堆栈

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

**图表来源**
- [server/src/services/logger.service.ts:75-102](file://server/src/services/logger.service.ts#L75-L102)
- [server/src/services/logger.service.ts:29-64](file://server/src/services/logger.service.ts#L29-L64)

**章节来源**
- [server/src/services/logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [server/dist/services/logger.service.js:1-95](file://server/dist/services/logger.service.js#L1-L95)

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

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

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

### 数据库监控脚本
- monitor-book.js：按3秒间隔轮询指定书籍的章节层级统计，直到完成或失败
- monitor-generation.js：按30秒间隔轮询书籍状态、章节数量与已完成内容数
- monitor-progress.js：按5秒间隔轮询书籍状态与进度

```mermaid
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](file://server/monitor-book.js#L4-L50)
- [server/monitor-generation.js:4-54](file://server/monitor-generation.js#L4-L54)
- [server/monitor-progress.js:4-33](file://server/monitor-progress.js#L4-L33)

**章节来源**
- [server/monitor-book.js:1-56](file://server/monitor-book.js#L1-L56)
- [server/monitor-generation.js:1-60](file://server/monitor-generation.js#L1-L60)
- [server/monitor-progress.js:1-39](file://server/monitor-progress.js#L1-L39)

## 依赖关系分析
- 应用入口在启动阶段初始化Sentry，随后连接数据库、测试Redis与存储、初始化WebSocket、启动路由与队列处理器
- 中间件顺序对可观测性至关重要：错误处理中间件应尽早拦截；Sentry中间件负责异常上报；Winston中间件负责日志记录；性能中间件负责指标采集

```mermaid
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](file://server/src/app.ts#L133-L194)

**章节来源**
- [server/src/app.ts:133-194](file://server/src/app.ts#L133-L194)

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

**章节来源**
- [server/src/services/logger.service.ts:75-102](file://server/src/services/logger.service.ts#L75-L102)
- [server/src/services/sentry.service.ts:15-22](file://server/src/services/sentry.service.ts#L15-L22)
- [server/monitor-generation.js:4-54](file://server/monitor-generation.js#L4-L54)

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

**章节来源**
- [server/src/services/logger.service.ts:75-102](file://server/src/services/logger.service.ts#L75-L102)
- [server/src/services/sentry.service.ts:24-38](file://server/src/services/sentry.service.ts#L24-L38)
- [feature_list_monitor.json:10-44](file://feature_list_monitor.json#L10-L44)

## 结论
本监控与日志体系以Sentry与Winston为核心，配合统一错误处理中间件与性能监控中间件，实现了从异常捕获、日志记录到指标采集的全链路可观测性。数据库监控脚本进一步增强了生成流程的可见性。建议后续完善：
- 实时仪表板：基于HTTP日志与Sentry事件构建可视化面板
- 告警规则：针对错误率、P95/P99延迟、数据库慢查询、Redis可用性等建立阈值告警
- 安全与合规：对敏感信息脱敏、限制日志保留周期、审计访问权限

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

**章节来源**
- [server/src/services/sentry.service.ts:8-13](file://server/src/services/sentry.service.ts#L8-L13)
- [server/src/services/logger.service.ts:69-72](file://server/src/services/logger.service.ts#L69-L72)
- [feature_list_monitor.json:14-25](file://feature_list_monitor.json#L14-L25)
- [feature_list_monitor.json:30-43](file://feature_list_monitor.json#L30-L43)