# 告警引擎设计文档

## 一、设计原则

### 1.1 核心原则

- **快**：错误发生后 1 分钟内触发告警
- **准**：减少误报，告警要有价值
- **全**：支持多种告警规则和通知渠道
- **轻**：不依赖复杂组件，轻量实现

### 1.2 告警目标

- 错误突增：及时发现线上故障
- 新错误出现：第一时间感知新问题
- 错误率超标：质量红线监控
- 性能劣化：用户体验下降预警

---

## 二、告警规则类型

### 2.1 规则分类

| 类型 | 说明 | 实时性 | 复杂度 |
|------|------|--------|--------|
| **阈值告警** | 指标超过固定阈值 | 高 | 低 |
| **突增告警** | 同比/环比增长超过阈值 | 中 | 中 |
| **新错误告警** | 出现新的错误指纹 | 高 | 低 |
| **错误率告警** | 错误率超过阈值 | 中 | 中 |
| **质量分告警** | 性能/质量综合评分下降 | 低 | 高 |

### 2.2 内置规则模板

#### 1. 错误数量突增

```yaml
name: 错误数量突增
type: spike
metric: error_count
window: 5m           # 检测窗口
compare: 1h_ago      # 对比：1小时前
threshold: 200%      # 增长 200% 触发
min_count: 10        # 最少 10 条才检测（避免噪音）
level: warning
```

#### 2. 新错误出现

```yaml
name: 新错误出现
type: new_error
metric: error_fingerprint
window: 24h          # 过去 24 小时没出现过
level: info
```

#### 3. JS 错误率过高

```yaml
name: JS 错误率过高
type: threshold
metric: error_rate   # 错误数 / PV
window: 5m
threshold: 5%        # 错误率超过 5%
level: critical
```

#### 4. 页面性能劣化

```yaml
name: LCP 性能劣化
type: threshold
metric: lcp_p95
window: 15m
threshold: 4000      # P95 LCP > 4s
level: warning
```

#### 5. 接口错误率过高

```yaml
name: 接口错误率过高
type: threshold
metric: api_error_rate
window: 5m
threshold: 10%
level: critical
```

---

## 三、告警引擎架构

### 3.1 整体架构

```
┌──────────────────────────────────────────────────────┐
│                     事件流                            │
│  错误事件 ──→ 实时检测 ──→ 触发规则 ──→ 告警通知      │
│                (快路径)                               │
└──────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│                     定时任务                          │
│  Loki/MySQL ──→ 指标计算 ──→ 规则匹配 ──→ 告警通知   │
│                (慢路径)                               │
└──────────────────────────────────────────────────────┘
```

### 3.2 双路径设计

#### 快路径：实时检测（秒级）

用于：新错误出现、错误数突增（粗粒度）

```
事件入队
    ↓
实时规则引擎
    ├─ 检查是否是新指纹（内存 BloomFilter）
    ├─ 检查 1 分钟错误数是否突增
    └─ 触发 → 入告警队列
    ↓
告警收敛 + 去重
    ↓
通知
```

#### 慢路径：定时检测（分钟级）

用于：复杂计算、分位数、错误率

```
定时任务（每 5 分钟）
    ↓
从 Loki/MySQL 拉取指标
    ↓
计算同比、环比、分位数
    ↓
匹配告警规则
    ↓
触发 → 入告警队列
    ↓
告警收敛 + 去重
    ↓
通知
```

---

## 四、告警规则引擎

### 4.1 规则数据结构

```sql
CREATE TABLE alert_rules (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  project_id VARCHAR(64) NOT NULL,
  name VARCHAR(128) NOT NULL,
  description TEXT,
  
  -- 规则类型
  type VARCHAR(32) NOT NULL,  -- threshold / spike / new_error / error_rate
  
  -- 规则配置（JSON）
  config JSON NOT NULL,
  /*
  {
    "metric": "error_count",
    "window": "5m",
    "threshold": 100,
    "compare": "1h_ago",
    "operator": ">"
  }
  */
  
  -- 告警级别
  level VARCHAR(32) NOT NULL,  -- info / warning / critical
  
  -- 通知渠道
  channels JSON NOT NULL,
  /*
  [
    { "type": "webhook", "url": "https://..." },
    { "type": "email", "to": ["a@b.com"] }
  ]
  */
  
  -- 收敛配置
  group_by VARCHAR(64),        -- 按指纹/项目/页面分组
  interval INT DEFAULT 300,    -- 同组告警间隔（秒）
  max_count INT DEFAULT 10,    -- 每小时最多告警次数
  
  -- 状态
  enabled TINYINT DEFAULT 1,
  created_at DATETIME,
  updated_at DATETIME,
  
  INDEX idx_project (project_id)
);
```

### 4.2 规则匹配流程

```
新指标数据到达
    ↓
加载项目的所有启用规则
    ↓
逐条匹配
    ├─ 类型匹配？
    ├─ 条件满足？
    └─ 未被静默？
    ↓
触发告警
    ↓
告警去重 + 收敛
    ↓
发送通知
```

### 4.3 内置规则表达式

支持简单的表达式语法：

```
# 阈值比较
error_count > 100
error_rate > 0.05
lcp_p95 >= 4000

# 同比环比
error_count / error_count_1h_ago > 2
error_count > error_count_1d_ago * 1.5
```

---

## 五、告警收敛与降噪

### 5.1 降噪策略

| 策略 | 说明 | 效果 |
|------|------|------|
| **同指纹去重** | 同一错误 5 分钟内只告警 1 次 | 减少 80% 重复告警 |
| **分组收敛** | 按项目/级别聚合，合并发送 | 减少通知数量 |
| **频率限制** | 每项目每小时最多 N 条 | 防止告警风暴 |
| **静默期** | 已知问题可设置静默 | 忽略已知问题 |
| **最小阈值** | 数量太少不告警 | 避免噪音 |

### 5.2 告警去重键

```
去重键 = project_id + rule_id + fingerprint + 时间窗口
```

同一去重键在 `interval` 时间内只发 1 次告警。

### 5.3 告警升级

- 持续时间超过 30 分钟 → 级别升级（warning → critical）
- 影响用户数超过阈值 → 级别升级
- 持续超过 2 小时 → 通知更多人

---

## 六、通知渠道

### 6.1 支持的渠道

| 渠道 | 说明 | 适用场景 |
|------|------|----------|
| **Webhook** | 通用 HTTP 回调 | 飞书、钉钉、企业微信、Slack |
| **邮件** | SMTP 发送 | 正式通知、归档 |
| **Server酱** | 微信推送 | 个人项目 |
| **飞书机器人** | 专用适配 | 飞书团队 |
| **钉钉机器人** | 专用适配 | 钉钉团队 |

### 6.2 Webhook 格式

```json
{
  "alert_id": "alert_abc123",
  "rule_id": 123,
  "rule_name": "错误数量突增",
  "level": "critical",
  "project_id": "1001",
  "project_name": "前端项目",
  
  "metric": "error_count",
  "value": 250,
  "threshold": 100,
  "window": "5m",
  
  "description": "5 分钟内错误数达到 250，超过阈值 100，增长 150%",
  
  "details": {
    "error_type": "TypeError",
    "top_errors": [
      { "fingerprint": "a1b2c3", "message": "...", "count": 100 },
      { "fingerprint": "d4e5f6", "message": "...", "count": 50 }
    ]
  },
  
  "link": "https://log.example.com/manage/#/errors?project=1001",
  "timestamp": "2024-01-01T00:00:00Z"
}
```

### 6.3 飞书 / 钉钉适配

提供现成的模板，直接粘贴 Webhook URL 即可使用：

- 飞书：使用富文本卡片，支持点击跳转
- 钉钉：使用 Markdown 格式，支持 @人

---

## 七、告警事件存储

### 7.1 告警历史表

```sql
CREATE TABLE alert_events (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  project_id VARCHAR(64) NOT NULL,
  rule_id BIGINT NOT NULL,
  rule_name VARCHAR(128),
  level VARCHAR(32),
  
  -- 告警数据
  metric VARCHAR(64),
  value DOUBLE,
  threshold DOUBLE,
  description TEXT,
  details JSON,
  
  -- 状态
  status VARCHAR(32) DEFAULT 'firing',  -- firing / resolved / acknowledged
  
  -- 时间
  started_at DATETIME,
  resolved_at DATETIME NULL,
  duration INT,  -- 持续时间（秒）
  
  created_at DATETIME,
  updated_at DATETIME,
  
  INDEX idx_project_time (project_id, started_at),
  INDEX idx_status (status)
);
```

### 7.2 状态流转

```
firing ──→ acknowledged ──→ resolved
  │                           ↑
  └───────────────────────────┘
        自动恢复（指标降下来）
```

---

## 八、实现方案

### 8.1 轻量实现（v1）

**技术栈**：Node.js + 内存定时器 + MySQL

```
API Server 进程内
    ├─ 事件消费时同步检测（快路径）
    │   ├─ 新错误检测（BloomFilter）
    │   └─ 简单计数（1min 滑动窗口）
    │
    └─ 定时任务（慢路径）
        └─ 每 5 分钟跑一次复杂规则
```

**优点**：无额外组件，部署简单
**缺点**：单进程，无法水平扩展

### 8.2 独立服务（v2）

**技术栈**：独立的 Alert Worker 进程 + Redis

```
API Server → Redis Stream → Alert Worker
                          → 规则匹配
                          → 告警收敛
                          → 通知发送
```

**优点**：可独立扩展，不影响接入性能
**缺点**：多一个组件

---

## 九、静默与抑制

### 9.1 静默规则

用户可以设置静默期，暂时忽略某些告警：

```yaml
- project_id: 1001
  fingerprint: a1b2c3d4
  reason: "已知问题，下个版本修复"
  start_time: 2024-01-01 00:00:00
  end_time: 2024-01-03 00:00:00
  created_by: user1
```

### 9.2 抑制规则

高优先级告警抑制低优先级：

- critical 级别的错误告警触发后，同指纹的 warning 级告警被抑制
- 项目级别的大故障告警触发后，该项目的其他告警被抑制

---

## 十、与现有系统集成

### 10.1 当前状态

- 有 Loki 存原始数据 → 可用于慢路径查询
- 有 MySQL（待加聚合层）→ 可存规则和告警历史
- 有管理后台 → 可加告警管理页面

### 10.2 落地步骤

**v1（最小可用）**：
1. 新增 alert_rules 和 alert_events 表
2. 实现新错误检测（快路径，内存 BloomFilter）
3. 实现 Webhook 通知
4. 管理后台加告警规则配置页面

**v2（增强）**：
1. 实现定时规则引擎（慢路径）
2. 增加突增检测、错误率检测
3. 支持飞书/钉钉专用模板
4. 告警收敛和静默功能

**v3（完善）**：
1. 独立 Alert Worker 服务
2. Redis 队列 + 分布式锁
3. 更复杂的规则表达式
4. 告警抑制和升级