audio_codebuddy/.qoder/repowiki/zh/content/部署运维/监控告警.md

监控告警

本文引用的文件

• server/src/app.ts
• server/src/middleware/performance.ts
• server/src/services/sentry.service.ts
• server/src/middleware/errorHandler.ts
• server/src/services/logger.service.ts
• server/src/services/log.service.ts
• server/src/services/queue.service.ts
• server/src/config/index.ts
• server/src/modules/subscription/subscription.controller.ts
• .codebuddy/rules/harness.mdc

目录

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

简介

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

项目结构

围绕监控与告警的关键模块分布如下：

• 应用入口与中间件：应用启动、路由注册、全局中间件（性能、安全、限流、Sentry、HTTP日志等）
• 错误与异常：统一错误处理中间件与自定义错误类型
• 错误监控：Sentry初始化、错误捕获、上下文与标签设置
• 日志体系：Winston HTTP日志、请求日志服务与错误模式分析
• 性能监控：内置性能中间件与指标导出路由
• 队列与任务：任务队列、状态统计与进度回调
• 配置中心：模型与服务配置、默认模型切换策略

• 业务监控：订阅与配额接口（可用于业务指标采集）

  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
• server/src/middleware/performance.ts:1-109
• server/src/services/sentry.service.ts:1-113
• server/src/middleware/errorHandler.ts:1-67
• server/src/services/logger.service.ts:1-114
• server/src/services/log.service.ts:1-354
• server/src/services/queue.service.ts:1-347
• server/src/config/index.ts:1-117
• server/src/modules/subscription/subscription.controller.ts:47-99

章节来源

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

核心组件

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

章节来源

• server/src/app.ts:63-130
• server/src/middleware/performance.ts:1-109
• server/src/services/sentry.service.ts:1-113
• server/src/middleware/errorHandler.ts:1-67
• server/src/services/logger.service.ts:1-114
• server/src/services/log.service.ts:1-354
• server/src/services/queue.service.ts:1-347
• server/src/config/index.ts:1-117
• server/src/modules/subscription/subscription.controller.ts:47-99

架构总览

下图展示监控与告警在系统中的位置与交互：

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
• server/src/middleware/performance.ts:1-109
• server/src/services/sentry.service.ts:1-113
• server/src/services/logger.service.ts:1-114
• server/src/services/log.service.ts:1-354
• server/src/services/queue.service.ts:1-347
• server/src/config/index.ts:1-117

详细组件分析

性能监控中间件

• 指标维度
  • 全局：总请求数、平均响应时间、慢请求数、错误数、错误率
  • 端点级：端点调用次数、平均耗时、最大耗时、错误数
• 实现要点
  • 在每个请求前后计算耗时并更新指标
  • 超阈值（默认1秒）记录慢请求日志
  • 通过响应头返回本次响应时间
  • 提供指标导出路由，便于外部监控系统抓取

• 可观测性价值

  • 识别慢端点与异常波动
  • 评估整体吞吐与延迟表现

  • 为容量规划与限流策略提供依据

    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

章节来源

• server/src/middleware/performance.ts:1-109
• server/src/app.ts:96-97

Sentry错误监控集成

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

• 与Koa集成

  • 作为中间件统一捕获未处理异常并上报

    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
• server/src/middleware/errorHandler.ts:3-24

章节来源

• server/src/services/sentry.service.ts:1-113
• server/src/middleware/errorHandler.ts:1-67

日志收集与分析

• Winston日志
  • 控制台彩色输出、错误文件与常规文件滚动、HTTP请求日志文件
  • 支持按级别输出与结构化元数据

• 请求日志服务

  • 内存中维护请求日志，限制最大条数并异步落盘
  • 提供过滤、统计、错误模式分析与自动修复建议

  • 统计错误数、告警数、平均响应时间与Top路径

    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
• server/src/services/log.service.ts:217-271

章节来源

• server/src/services/logger.service.ts:1-114
• server/src/services/log.service.ts:1-354

队列与任务监控

• 队列能力
  • 基于Redis/Bull的任务队列，支持任务添加、状态查询、进度更新、统计与暂停/恢复
  • 当Redis不可用时自动降级至内存队列，保证基本可用

• 监控点

  • 各队列等待/活跃/完成/失败/延迟任务数
  • 任务超时与失败原因

  • 进度回调与实时状态更新

    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

章节来源

• server/src/services/queue.service.ts:1-347

配置中心与模型切换

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

章节来源

• server/src/config/index.ts:1-117

业务监控（订阅与配额）

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

章节来源

• server/src/modules/subscription/subscription.controller.ts:47-99

依赖关系分析

• 组件耦合
  • 应用入口对中间件与服务的依赖清晰，中间件链顺序影响可观测性数据质量
  • 性能中间件与Sentry中间件需位于错误处理之前以确保异常被正确捕获与上报
• 外部依赖
  • Redis用于队列持久化，不可用时触发降级
  • 数据库与对象存储/本地存储在启动阶段进行连通性检测

• 潜在风险

  • 队列不可用时，任务可能丢失或阻塞
  • 日志文件滚动与磁盘空间占用需监控

  • Sentry采样率与过滤策略需定期评估

    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
• server/src/services/queue.service.ts:53-59
• server/src/services/logger.service.ts:18-65
• server/src/services/log.service.ts:42-63

章节来源

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

性能考量

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

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

故障排查指南

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

章节来源

• server/src/app.ts:91-94
• server/src/middleware/errorHandler.ts:3-24
• server/src/services/log.service.ts:217-297
• server/src/services/queue.service.ts:290-330
• server/src/services/sentry.service.ts:75-87

结论

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

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

附录

告警规则与通知策略建议

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

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

关键指标仪表板设计

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

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

系统健康检查与部署验证

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

章节来源

• server/src/app.ts:91-94
• .codebuddy/rules/harness.mdc:100-148