# 监控告警

<cite>
**本文引用的文件**
- [server/src/app.ts](file://server/src/app.ts)
- [server/src/middleware/performance.ts](file://server/src/middleware/performance.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/logger.service.ts](file://server/src/services/logger.service.ts)
- [server/src/services/log.service.ts](file://server/src/services/log.service.ts)
- [server/src/services/queue.service.ts](file://server/src/services/queue.service.ts)
- [server/src/config/index.ts](file://server/src/config/index.ts)
- [server/src/modules/subscription/subscription.controller.ts](file://server/src/modules/subscription/subscription.controller.ts)
- [.codebuddy/rules/harness.mdc](file://.codebuddy/rules/harness.mdc)
</cite>

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

## 简介
本文件面向AI有声书生成平台的运维与开发团队，提供一套完整的监控告警方案。内容覆盖系统监控指标定义、性能监控配置、业务监控设置；涵盖Sentry错误监控集成、日志收集分析与APM性能监控；解释告警规则配置、通知渠道设置与告警升级策略；并提供关键指标仪表板设计、自定义监控图表与趋势分析思路，以及系统健康检查、容量规划与性能瓶颈识别方法，帮助实现数据驱动的运维决策。

## 项目结构
围绕监控与告警的关键模块分布如下：
- 应用入口与中间件：应用启动、路由注册、全局中间件（性能、安全、限流、Sentry、HTTP日志等）
- 错误与异常：统一错误处理中间件与自定义错误类型
- 错误监控：Sentry初始化、错误捕获、上下文与标签设置
- 日志体系：Winston HTTP日志、请求日志服务与错误模式分析
- 性能监控：内置性能中间件与指标导出路由
- 队列与任务：任务队列、状态统计与进度回调
- 配置中心：模型与服务配置、默认模型切换策略
- 业务监控：订阅与配额接口（可用于业务指标采集）

```mermaid
graph TB
A["应用入口<br/>server/src/app.ts"] --> B["性能监控中间件<br/>server/src/middleware/performance.ts"]
A --> C["Sentry错误监控<br/>server/src/services/sentry.service.ts"]
A --> D["错误处理中间件<br/>server/src/middleware/errorHandler.ts"]
A --> E["Winston HTTP日志<br/>server/src/services/logger.service.ts"]
A --> F["请求日志服务<br/>server/src/services/log.service.ts"]
A --> G["队列服务<br/>server/src/services/queue.service.ts"]
A --> H["配置中心<br/>server/src/config/index.ts"]
A --> I["订阅/配额接口<br/>server/src/modules/subscription/subscription.controller.ts"]
```

**图示来源**
- [server/src/app.ts:1-194](file://server/src/app.ts#L1-L194)
- [server/src/middleware/performance.ts:1-109](file://server/src/middleware/performance.ts#L1-L109)
- [server/src/services/sentry.service.ts:1-113](file://server/src/services/sentry.service.ts#L1-L113)
- [server/src/middleware/errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [server/src/services/logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [server/src/services/log.service.ts:1-354](file://server/src/services/log.service.ts#L1-L354)
- [server/src/services/queue.service.ts:1-347](file://server/src/services/queue.service.ts#L1-L347)
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [server/src/modules/subscription/subscription.controller.ts:47-99](file://server/src/modules/subscription/subscription.controller.ts#L47-L99)

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

## 核心组件
- 应用入口与中间件链：负责注册全局中间件、静态资源、路由与健康检查端点，并在启动时进行外部依赖连通性检测与优雅关闭处理。
- 性能监控中间件：统计总请求数、平均响应时间、慢请求、端点级指标与错误率，并提供指标导出路由。
- Sentry错误监控：初始化SDK、按环境采样、过滤无关错误、捕获异常与消息、设置用户与标签、并作为Koa中间件统一上报。
- 错误处理中间件：统一捕获异常，构造标准化错误响应，并在开发环境输出堆栈。
- 日志体系：Winston控制台与文件输出、HTTP请求日志、请求日志服务（内存+持久化）、错误模式识别与修复建议。
- 队列服务：基于Redis/Bull的任务队列，提供任务添加、状态查询、进度更新、统计与降级回退至内存队列。
- 配置中心：集中管理模型配置、默认模型、启用模型、模型切换策略（如限流/配额/服务不可用等）。
- 业务监控：订阅/配额接口可用于统计用户使用情况、Token消耗与限额校验，支撑业务指标采集。

**章节来源**
- [server/src/app.ts:63-130](file://server/src/app.ts#L63-L130)
- [server/src/middleware/performance.ts:1-109](file://server/src/middleware/performance.ts#L1-L109)
- [server/src/services/sentry.service.ts:1-113](file://server/src/services/sentry.service.ts#L1-L113)
- [server/src/middleware/errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [server/src/services/logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [server/src/services/log.service.ts:1-354](file://server/src/services/log.service.ts#L1-L354)
- [server/src/services/queue.service.ts:1-347](file://server/src/services/queue.service.ts#L1-L347)
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [server/src/modules/subscription/subscription.controller.ts:47-99](file://server/src/modules/subscription/subscription.controller.ts#L47-L99)

## 架构总览
下图展示监控与告警在系统中的位置与交互：

```mermaid
graph TB
subgraph "客户端"
U["用户/前端/第三方"]
end
subgraph "服务端"
R["Koa路由与控制器"]
PM["性能监控中间件"]
EH["错误处理中间件"]
SL["Sentry错误监控"]
WL["Winston日志"]
LS["请求日志服务"]
QS["队列服务"]
CFG["配置中心"]
end
subgraph "外部依赖"
RD["Redis"]
DB["数据库"]
ST["对象存储/本地存储"]
end
U --> R
R --> PM
R --> EH
EH --> SL
R --> WL
WL --> LS
R --> QS
R --> CFG
QS --> RD
R --> DB
R --> ST
```

**图示来源**
- [server/src/app.ts:63-130](file://server/src/app.ts#L63-L130)
- [server/src/middleware/performance.ts:1-109](file://server/src/middleware/performance.ts#L1-L109)
- [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/services/log.service.ts:1-354](file://server/src/services/log.service.ts#L1-L354)
- [server/src/services/queue.service.ts:1-347](file://server/src/services/queue.service.ts#L1-L347)
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)

## 详细组件分析

### 性能监控中间件
- 指标维度
  - 全局：总请求数、平均响应时间、慢请求数、错误数、错误率
  - 端点级：端点调用次数、平均耗时、最大耗时、错误数
- 实现要点
  - 在每个请求前后计算耗时并更新指标
  - 超阈值（默认1秒）记录慢请求日志
  - 通过响应头返回本次响应时间
  - 提供指标导出路由，便于外部监控系统抓取
- 可观测性价值
  - 识别慢端点与异常波动
  - 评估整体吞吐与延迟表现
  - 为容量规划与限流策略提供依据

```mermaid
flowchart TD
Start(["进入中间件"]) --> Mark["记录开始时间"]
Mark --> Next["执行下游中间件/控制器"]
Next --> Done{"是否抛错？"}
Done --> |否| Calc["计算耗时并更新指标"]
Done --> |是| Err["统计错误并抛出"]
Calc --> Slow{"是否慢请求？"}
Slow --> |是| Warn["记录慢请求日志"]
Slow --> |否| Resp["设置响应头并返回"]
Warn --> Resp
Err --> End(["结束"])
Resp --> End
```

**图示来源**
- [server/src/middleware/performance.ts:29-76](file://server/src/middleware/performance.ts#L29-L76)

**章节来源**
- [server/src/middleware/performance.ts:1-109](file://server/src/middleware/performance.ts#L1-L109)
- [server/src/app.ts:96-97](file://server/src/app.ts#L96-L97)

### Sentry错误监控集成
- 初始化与采样
  - 读取DSN与环境变量，生产环境降低追踪采样率，开启CPU性能分析
  - 提供错误过滤策略（如忽略特定连接拒绝错误）
- 上下文与标签
  - 设置用户ID、URL、方法等标签，便于聚合与检索
  - 支持捕获异常与消息，并可附加上下文元数据
- 与Koa集成
  - 作为中间件统一捕获未处理异常并上报

```mermaid
sequenceDiagram
participant C as "客户端"
participant K as "Koa应用"
participant EH as "错误处理中间件"
participant S as "Sentry"
C->>K : 发起请求
K->>EH : 进入错误处理
EH-->>K : 执行业务逻辑
K-->>EH : 抛出异常
EH->>S : captureException(带标签/用户)
S-->>EH : 上报完成
EH-->>C : 返回错误响应
```

**图示来源**
- [server/src/services/sentry.service.ts:92-110](file://server/src/services/sentry.service.ts#L92-L110)
- [server/src/middleware/errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)

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

### 日志收集与分析
- Winston日志
  - 控制台彩色输出、错误文件与常规文件滚动、HTTP请求日志文件
  - 支持按级别输出与结构化元数据
- 请求日志服务
  - 内存中维护请求日志，限制最大条数并异步落盘
  - 提供过滤、统计、错误模式分析与自动修复建议
  - 统计错误数、告警数、平均响应时间与Top路径

```mermaid
flowchart TD
A["接收请求日志"] --> B["写入内存日志"]
B --> C{"超过最大条数？"}
C --> |是| D["截断旧日志"]
C --> |否| E["保持"]
D --> F["异步落盘"]
E --> F
F --> G["控制台输出"]
G --> H["错误模式匹配与建议"]
```

**图示来源**
- [server/src/services/log.service.ts:140-171](file://server/src/services/log.service.ts#L140-L171)
- [server/src/services/log.service.ts:217-271](file://server/src/services/log.service.ts#L217-L271)

**章节来源**
- [server/src/services/logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [server/src/services/log.service.ts:1-354](file://server/src/services/log.service.ts#L1-L354)

### 队列与任务监控
- 队列能力
  - 基于Redis/Bull的任务队列，支持任务添加、状态查询、进度更新、统计与暂停/恢复
  - 当Redis不可用时自动降级至内存队列，保证基本可用
- 监控点
  - 各队列等待/活跃/完成/失败/延迟任务数
  - 任务超时与失败原因
  - 进度回调与实时状态更新

```mermaid
classDiagram
class QueueService {
+addTask(queueType, data, options) Promise<string|null>
+getTaskStatus(queueType, jobId) Promise<status>
+updateProgress(queueType, jobId, progress, data) Promise<void>
+getQueueStats(queueType) Promise<counts>
+pauseQueue(queueType) Promise<void>
+resumeQueue(queueType) Promise<void>
+closeAll() Promise<void>
}
class RedisService {
+isAvailable() boolean
}
QueueService --> RedisService : "依赖"
```

**图示来源**
- [server/src/services/queue.service.ts:48-347](file://server/src/services/queue.service.ts#L48-L347)

**章节来源**
- [server/src/services/queue.service.ts:1-347](file://server/src/services/queue.service.ts#L1-L347)

### 配置中心与模型切换
- 配置管理
  - 统一加载模型供应商、默认模型、启用模型列表
  - 提供按类型筛选模型与获取下一个可用模型的能力
- 模型切换策略
  - 根据错误关键字判断是否需要切换（如限流、配额、服务不可用、4xx/5xx等）
  - 用于在多模型场景下的自动容灾与降级

**章节来源**
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)

### 业务监控（订阅与配额）
- 接口能力
  - 用户Token余额查询、使用记录分页查询、配额检查与兼容旧接口
- 监控价值
  - 作为业务指标采集入口，结合日志与Sentry事件，形成用户行为与消费趋势画像
  - 支撑容量规划与付费转化分析

**章节来源**
- [server/src/modules/subscription/subscription.controller.ts:47-99](file://server/src/modules/subscription/subscription.controller.ts#L47-L99)

## 依赖关系分析
- 组件耦合
  - 应用入口对中间件与服务的依赖清晰，中间件链顺序影响可观测性数据质量
  - 性能中间件与Sentry中间件需位于错误处理之前以确保异常被正确捕获与上报
- 外部依赖
  - Redis用于队列持久化，不可用时触发降级
  - 数据库与对象存储/本地存储在启动阶段进行连通性检测
- 潜在风险
  - 队列不可用时，任务可能丢失或阻塞
  - 日志文件滚动与磁盘空间占用需监控
  - Sentry采样率与过滤策略需定期评估

```mermaid
graph LR
APP["应用入口"] --> PM["性能中间件"]
APP --> EH["错误处理中间件"]
EH --> SEN["Sentry"]
APP --> LOG["Winston日志"]
LOG --> LGS["请求日志服务"]
APP --> Q["队列服务"]
Q --> RDS["Redis"]
APP --> CFG["配置中心"]
```

**图示来源**
- [server/src/app.ts:63-130](file://server/src/app.ts#L63-L130)
- [server/src/services/queue.service.ts:53-59](file://server/src/services/queue.service.ts#L53-L59)
- [server/src/services/logger.service.ts:18-65](file://server/src/services/logger.service.ts#L18-L65)
- [server/src/services/log.service.ts:42-63](file://server/src/services/log.service.ts#L42-L63)

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

## 性能考量
- 指标采集
  - 性能中间件提供端点级与全局指标，建议结合Prometheus/Grafana进行长期趋势分析
  - 队列统计可反映任务积压与处理能力
- 资源与容量
  - Redis可用性直接影响队列可靠性，建议部署哨兵/集群并监控连接池
  - 对象存储/本地存储的IO与带宽需纳入容量规划
- 瓶颈识别
  - 结合慢请求日志与Sentry错误事件，定位热点端点与异常模式
  - 通过日志服务的Top路径与错误分析，识别高频失败路径

[本节为通用指导，无需具体文件引用]

## 故障排查指南
- 健康检查
  - 通过健康检查端点快速判断服务可用性
- 错误处理
  - 统一错误响应与堆栈输出，便于快速定位问题
- 日志定位
  - 使用Winston文件与请求日志服务，结合错误模式匹配与修复建议
- 队列问题
  - 检查队列状态与统计，必要时暂停/恢复或清空队列
- Sentry事件
  - 通过标签与用户上下文快速关联问题与用户

**章节来源**
- [server/src/app.ts:91-94](file://server/src/app.ts#L91-L94)
- [server/src/middleware/errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)
- [server/src/services/log.service.ts:217-297](file://server/src/services/log.service.ts#L217-L297)
- [server/src/services/queue.service.ts:290-330](file://server/src/services/queue.service.ts#L290-L330)
- [server/src/services/sentry.service.ts:75-87](file://server/src/services/sentry.service.ts#L75-L87)

## 结论
本方案以“可观测性即基础设施”为核心理念，通过性能中间件、Sentry错误监控、Winston日志与请求日志服务、队列统计与配置中心，构建了覆盖系统、性能与业务的监控体系。建议在此基础上完善告警规则、通知渠道与升级策略，并持续迭代指标与仪表板，以支撑数据驱动的运维与产品决策。

[本节为总结，无需具体文件引用]

## 附录

### 告警规则与通知策略建议
- 规则维度
  - 错误率：全局错误率、端点错误率
  - 延迟与慢请求：平均响应时间、慢请求占比
  - 队列积压：等待/失败任务数、长时间未完成任务
  - 资源健康：Redis可用性、存储IO、数据库连接数
  - 业务指标：Token消耗、配额使用、用户活跃度
- 通知渠道
  - 邮件、即时通讯群组、电话（严重级别）
- 升级策略
  - 一级告警：10分钟未处置自动升级
  - 二级告警：30分钟未处置自动升级
  - 三级告警：1小时未处置自动升级

[本节为通用指导，无需具体文件引用]

### 关键指标仪表板设计
- 面板建议
  - 全局概览：请求总量、错误率、慢请求、平均响应时间
  - 端点热力：Top N慢端点、错误分布
  - 队列看板：各队列任务状态、处理速率
  - 业务看板：用户配额使用、Token消耗趋势
- 图表类型
  - 折线图（趋势）、柱状图（分布）、热力图（端点）

[本节为通用指导，无需具体文件引用]

### 系统健康检查与部署验证
- 健康检查端点：/health
- 部署验证流程参考：启动服务后验证健康与静态资源可用性

**章节来源**
- [server/src/app.ts:91-94](file://server/src/app.ts#L91-L94)
- [.codebuddy/rules/harness.mdc:100-148](file://.codebuddy/rules/harness.mdc#L100-L148)