@umacloud/knowledge 1.0.1

package/data-engineering/05-cases/case-real-time-pipeline.md

@@ -0,0 +1,355 @@
+---
+id: case-real-time-pipeline
+title: 实时数据管道案例：Kafka + Flink 构建实时数据处理系统
+domain: data-engineering
+category: 05-cases
+difficulty: intermediate
+tags: [agent, case, checklist, data-engineering, pipeline, real, time, 业务背景]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 实时数据管道案例：Kafka + Flink 构建实时数据处理系统
+
+## 概述
+
+本案例记录一个电商平台构建实时数据处理系统的完整过程。系统目标是将用户行为数据（浏览、点击、加购、下单）从产生到可查询的延迟从 T+1（次日批处理）缩短到 < 30 秒。日均处理事件 2 亿条，峰值 QPS 50,000。团队 6 人（2 数据工程师 + 2 后端 + 1 SRE + 1 数据分析师），建设周期 10 周。
+
+技术栈：Kafka 3.5 + Flink 1.17 + PostgreSQL + Redis + ClickHouse
+
+---
+
+## 业务背景
+
+### 原有架构（批处理）
+
+```
+用户行为 → MySQL binlog → 每日凌晨 Spark 批处理 → Hive → 报表（T+1）
+```
+
+痛点：
+1. 运营团队需要实时看到活动效果，T+1 延迟不可接受
+2. 推荐系统依赖用户最新行为，批处理数据太旧
+3. 风控系统需要秒级识别异常行为
+4. 凌晨批处理窗口已满负荷，无法扩展
+
+### 目标架构（实时 + 批处理 Lambda）
+
+```
+用户行为 → Kafka → Flink 实时处理 → ClickHouse（实时查询）
+                                   → Redis（实时推荐特征）
+                                   → PostgreSQL（告警/风控）
+           同时 → S3 归档 → Spark 批处理（T+1 修正层）
+```
+
+---
+
+## 第一阶段：Kafka 集群搭建与数据接入（第 1-3 周）
+
+### Kafka 集群规划
+
+| 参数 | 配置 | 说明 |
+|------|------|------|
+| Broker 数量 | 5 | 3 个不够峰值，5 个留有余量 |
+| 副本因子 | 3 | 任意 1 个 Broker 宕机不丢数据 |
+| 分区数 | 30 | 按峰值 QPS / 单分区吞吐量计算 |
+| 保留时间 | 7 天 | 满足回填和故障恢复需求 |
+| 压缩 | LZ4 | 吞吐优先，压缩比适中 |
+| 消息格式 | Avro + Schema Registry | 强 Schema 保证数据质量 |
+
+### Topic 设计
+
+```
+user-events           # 原始用户行为事件（浏览/点击/加购/下单）
+user-events-enriched  # 富化后事件（关联用户画像和商品信息）
+user-events-dlq       # 死信队列（处理失败的消息）
+aggregated-metrics    # 聚合后的实时指标
+alert-events          # 风控告警事件
+```
+
+### 数据接入方案
+
+```
+1. 前端埋点 → API Gateway → 事件收集服务 → Kafka
+   - 使用批量发送（batch.size=16384, linger.ms=10）
+   - acks=1（权衡延迟和可靠性）
+   - 关键事件（下单/支付）acks=all
+
+2. 事件格式（Avro Schema）
+   {
+     "event_id": "uuid",
+     "user_id": "long",
+     "event_type": "enum(view, click, add_cart, order, pay)",
+     "item_id": "long",
+     "timestamp": "long (epoch ms)",
+     "properties": "map<string, string>",
+     "session_id": "string",
+     "device": "string",
+     "ip": "string"
+   }
+
+3. Schema Evolution 策略
+   - 使用 BACKWARD 兼容模式
+   - 新字段必须有默认值
+   - 不允许删除字段或修改类型
+```
+
+### 数据验证
+
+- 发送端：Schema 校验 + 必填字段检查
+- 消费端：二次校验 + 异常数据进 DLQ
+- 端到端：从前端发送到 Kafka 可消费 < 500ms
+
+---
+
+## 第二阶段：Flink 实时处理引擎（第 4-7 周）
+
+### Flink 集群配置
+
+| 参数 | 配置 |
+|------|------|
+| JobManager | 2（HA 模式，ZooKeeper 选主） |
+| TaskManager | 8（每个 4 CPU, 8GB 内存） |
+| 并行度 | 30（与 Kafka 分区数一致） |
+| Checkpoint 间隔 | 60 秒 |
+| Checkpoint 存储 | S3 |
+| State Backend | RocksDB（大状态支持） |
+| 重启策略 | 固定延迟重启，最多 3 次，间隔 30 秒 |
+
+### 处理流程
+
+```
+Kafka Source (user-events)
+  │
+  ├→ [1] 数据清洗
+  │     - Schema 校验
+  │     - 时间戳合法性（不超过未来 5 分钟，不早于 7 天前）
+  │     - 必填字段非空
+  │     - 异常数据 → DLQ
+  │
+  ├→ [2] 数据富化（Async I/O）
+  │     - 关联 Redis 中的用户画像（年龄段、等级、地区）
+  │     - 关联 Redis 中的商品信息（类目、价格、品牌）
+  │     - 使用 AsyncDataStream，并发 100，超时 5s
+  │     - 缓存命中率 > 95%，未命中回查数据库
+  │
+  ├→ [3] 实时聚合（窗口计算）
+  │     - 滚动窗口（1 分钟）：PV/UV/GMV 按分钟聚合
+  │     - 滑动窗口（5 分钟滑动 1 分钟）：实时趋势
+  │     - 会话窗口（30 分钟间隔）：用户会话分析
+  │     - Watermark：允许 30 秒延迟，超时数据进侧输出
+  │
+  ├→ [4] 实时风控
+  │     - 同一用户 1 分钟内下单 > 5 次 → 告警
+  │     - 同一 IP 1 分钟内请求 > 1000 次 → 告警
+  │     - 异常金额检测（偏离用户历史均值 3 个标准差）
+  │     - 使用 Flink CEP（Complex Event Processing）模式匹配
+  │
+  └→ [5] 多 Sink 输出
+        - ClickHouse：富化后的明细数据 + 聚合数据
+        - Redis：用户实时特征（最近浏览、加购列表）
+        - PostgreSQL：风控告警记录
+        - Kafka (aggregated-metrics)：下游消费
+```
+
+### 关键代码模式
+
+```
+// Watermark 策略
+WatermarkStrategy
+  .forBoundedOutOfOrderness(Duration.ofSeconds(30))
+  .withTimestampAssigner((event, timestamp) -> event.getTimestamp())
+  .withIdleness(Duration.ofMinutes(1))  // 处理空闲分区
+
+// Async I/O 富化
+AsyncDataStream.unorderedWait(
+    cleanedStream,
+    new UserProfileAsyncFunction(),  // Redis 查询
+    5, TimeUnit.SECONDS,             // 超时
+    100                              // 并发容量
+)
+
+// 窗口聚合
+enrichedStream
+    .keyBy(event -> event.getItemId())
+    .window(TumblingEventTimeWindows.of(Time.minutes(1)))
+    .allowedLateness(Time.seconds(30))
+    .sideOutputLateData(lateOutputTag)
+    .aggregate(new MetricsAggregateFunction(), new MetricsWindowFunction())
+```
+
+### 状态管理
+
+- 风控状态（用户行为计数器）：TTL 设为 1 小时，自动清理
+- 窗口状态：随窗口关闭自动清理
+- 异步查询缓存：使用 MapState，TTL 5 分钟
+- State 大小监控：每个 TaskManager 的 RocksDB 使用量 < 4GB
+
+---
+
+## 第三阶段：存储层与查询层（第 7-8 周）
+
+### ClickHouse 配置
+
+```sql
+-- 明细表（按天分区，按用户 ID 排序）
+CREATE TABLE user_events_detail (
+    event_id UUID,
+    user_id UInt64,
+    event_type Enum8('view'=1, 'click'=2, 'add_cart'=3, 'order'=4, 'pay'=5),
+    item_id UInt64,
+    item_category String,
+    event_time DateTime,
+    properties Map(String, String)
+) ENGINE = MergeTree()
+PARTITION BY toYYYYMMDD(event_time)
+ORDER BY (user_id, event_time)
+TTL event_time + INTERVAL 90 DAY;
+
+-- 聚合表（预聚合，加速查询）
+CREATE TABLE metrics_1min (
+    time_bucket DateTime,
+    item_id UInt64,
+    pv UInt64,
+    uv AggregateFunction(uniq, UInt64),
+    gmv Decimal(18,2)
+) ENGINE = AggregatingMergeTree()
+PARTITION BY toYYYYMMDD(time_bucket)
+ORDER BY (time_bucket, item_id);
+```
+
+### Redis 实时特征
+
+```
+Key 设计：
+  user:{uid}:recent_views    → List (最近 50 个浏览商品 ID)
+  user:{uid}:cart             → Set (当前购物车商品 ID)
+  user:{uid}:session_events   → Counter (会话内事件计数)
+  item:{item_id}:realtime_pv  → Counter (实时 PV，1 分钟过期)
+
+TTL 策略：
+  recent_views: 24 小时
+  cart: 7 天
+  session_events: 30 分钟
+  realtime_pv: 1 分钟
+```
+
+---
+
+## 第四阶段：监控与运维（第 9 周）
+
+### 监控指标
+
+```
+管道级别：
+  - 端到端延迟（从事件产生到可查询）：P50 < 10s, P99 < 30s
+  - 处理吞吐量：records/sec（正常 2500，峰值 50000）
+  - 错误率：< 0.01%
+  - Kafka Consumer Lag：< 10000 条
+
+Flink 级别：
+  - Checkpoint 耗时：< 30 秒
+  - Checkpoint 失败率：< 1%
+  - Backpressure 比例：< 10%
+  - GC 暂停时间：< 500ms
+
+存储级别：
+  - ClickHouse 写入延迟：< 1 秒
+  - Redis 命令延迟：P99 < 5ms
+  - ClickHouse 磁盘使用趋势
+```
+
+### 告警规则
+
+| 告警 | 条件 | 级别 |
+|------|------|------|
+| 管道停止 | Flink Job 状态非 RUNNING | P1 |
+| 数据积压 | Consumer Lag > 100000 | P1 |
+| 端到端延迟 | P99 > 60s | P2 |
+| Checkpoint 失败 | 连续 3 次失败 | P2 |
+| 错误率异常 | > 0.1% | P2 |
+| 资源告警 | CPU > 80% 持续 10 分钟 | P3 |
+
+### Runbook 摘要
+
+| 故障场景 | 处理步骤 |
+|---------|---------|
+| Flink Job 崩溃 | 1. 检查异常日志 2. 从最近 Checkpoint 恢复 3. 若无法恢复则从 Kafka 回溯 |
+| Kafka Broker 宕机 | 1. 确认副本可用 2. 等待自动 Leader 选举 3. 检查数据完整性 |
+| ClickHouse 写入失败 | 1. 检查磁盘空间 2. 检查 MergeTree 合并状态 3. 数据暂存 Kafka 等恢复后补写 |
+| Consumer Lag 持续增长 | 1. 检查是否有 Backpressure 2. 增加并行度 3. 检查下游 Sink 是否阻塞 |
+
+---
+
+## 第五阶段：上线与优化（第 10 周）
+
+### 灰度上线步骤
+
+```
+Day 1: 部署管道，仅处理 10% 流量（Kafka 按 partition 分流）
+  - 验证数据正确性：与批处理结果对比
+  - 验证延迟：端到端 < 30s
+
+Day 3: 扩展到 50% 流量
+  - 观察资源使用
+  - 验证 ClickHouse 查询性能
+
+Day 5: 100% 流量
+  - 全量运行
+  - 关闭旧的批处理报表链路（保留批处理修正层）
+```
+
+### 上线后性能优化
+
+| 问题 | 根因 | 优化 | 效果 |
+|------|------|------|------|
+| 热点分区积压 | 头部用户事件集中在少数 partition | 使用 user_id 哈希分区替代轮询 | Lag 从 50000 降至 2000 |
+| Checkpoint 超时 | State 过大（8GB） | 启用增量 Checkpoint + TTL 清理过期状态 | 从 45s 降至 12s |
+| ClickHouse 写入慢 | 小批量频繁写入 | Flink Sink 攒批 5 秒或 10000 条写入一次 | 写入延迟从 3s 降至 0.5s |
+| GC 暂停 | 对象创建过多 | 使用对象池 + 减少 String 拼接 | GC 暂停从 800ms 降至 200ms |
+
+---
+
+## 最终成果
+
+| 指标 | 旧架构（批处理） | 新架构（实时） |
+|------|-----------------|---------------|
+| 数据延迟 | T+1（12-18 小时） | < 15 秒（P99 < 30s） |
+| 日处理量 | 2 亿条 | 2 亿条（持平） |
+| 峰值吞吐 | N/A（批量） | 50,000 events/sec |
+| 风控响应 | 次日发现 | 秒级告警 |
+| 推荐新鲜度 | 昨日行为 | 最近 30 秒行为 |
+| 运营数据 | 次日报表 | 实时仪表板 |
+
+### 业务影响
+
+- 推荐点击率提升 18%（实时特征 vs 昨日特征）
+- 风控拦截率提升 35%（秒级 vs 次日）
+- 运营活动调整响应时间从 "次日" 缩短到 "分钟级"
+- 大促期间实时 GMV 看板支撑运营决策
+
+---
+
+## 经验总结
+
+1. **先跑通再优化** - 第一版不追求极致性能，先确保数据正确
+2. **Schema 管理是基础** - Avro + Schema Registry 避免了大量数据质量问题
+3. **State 管理是核心难点** - 必须设置 TTL，否则 State 无限增长导致 OOM
+4. **批处理不要废弃** - Lambda 架构的批处理层作为实时层的修正层仍有价值
+5. **监控先于功能** - 没有监控的实时管道等于定时炸弹
+
+---
+
+## Agent Checklist
+
+以下为 AI Agent 在构建实时数据管道时必须遵循的硬约束：
+
+- [ ] 确认 Kafka Topic 的副本因子 ≥ 3
+- [ ] 确认消息格式使用 Schema（Avro/Protobuf），不使用纯 JSON
+- [ ] 确认 Flink Checkpoint 已启用且存储在持久化存储
+- [ ] 确认 State TTL 已设置，防止无限增长
+- [ ] 确认 Watermark 策略已定义，包含允许延迟时间
+- [ ] 确认 DLQ（死信队列）已配置
+- [ ] 确认端到端延迟监控和告警已配置
+- [ ] 确认 Consumer Lag 监控和告警已配置
+- [ ] 确认灰度上线方案已定义（不允许一次性全量切换）
+- [ ] 生成管道上线报告包含：架构图、性能基线、监控配置、Runbook