@umacloud/knowledge 1.0.1

package/data-engineering/02-playbooks/spark-etl-playbook.md

@@ -0,0 +1,496 @@
+---
+id: spark-etl-playbook
+title: Spark ETL开发完整指南
+domain: data-engineering
+category: 02-playbooks
+difficulty: intermediate
+tags: [data-engineering, etl, etl流程, playbook, spark, 参考资料, 学习路径, 性能优化]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# Spark ETL开发完整指南
+
+## 概述
+Apache Spark是一个快速、通用的大数据处理引擎,支持批处理、流处理、SQL查询和机器学习。本指南覆盖Spark ETL(Extract-Transform-Load)的最佳实践。
+
+## 核心概念
+
+### 1. RDD vs DataFrame vs Dataset
+
+**RDD (Resilient Distributed Dataset)**:
+- 底层API
+- 无模式
+- 函数式编程
+
+```python
+from pyspark import SparkContext
+
+sc = SparkContext.getOrCreate()
+
+# 创建RDD
+rdd = sc.parallelize([1, 2, 3, 4, 5])
+
+# 转换
+squared = rdd.map(lambda x: x ** 2)
+filtered = rdd.filter(lambda x: x > 10)
+```
+
+**DataFrame**:
+- 高层API
+- 有模式
+- SQL风格
+
+```python
+from pyspark.sql import SparkSession
+
+spark = SparkSession.builder.appName("ETL").getOrCreate()
+
+# 创建DataFrame
+df = spark.createDataFrame(
+    [(1, "Alice", 30), (2, "Bob", 25)],
+    ["id", "name", "age"]
+)
+
+# SQL查询
+df.createOrReplaceTempView("users")
+result = spark.sql("SELECT * FROM users WHERE age > 25")
+```
+
+**Dataset**:
+- 类型安全的DataFrame
+- Scala/Java优先
+
+### 2. 惰性求值
+Spark延迟执行,直到遇到action操作。
+
+```python
+# Transformation (惰性)
+mapped = df.select("name", "age").filter(df.age > 20)
+
+# Action (触发执行)
+result = mapped.collect()  # 触发计算
+```
+
+### 3. 分区和并行
+
+```python
+# 查看分区数
+print(df.rdd.getNumPartitions)
+
+# 重分区
+repartitioned = df.repartition(10)
+
+# Coalesce (减少分区)
+coalesced = df.coalesce(5)
+```
+
+## ETL流程
+
+### 1. Extract (提取)
+
+#### 从文件系统读取
+
+```python
+# CSV
+df = spark.read.csv("hdfs://path/to/file.csv", header=True, inferSchema=True)
+
+# JSON
+df = spark.read.json("hdfs://path/to/file.json")
+
+# Parquet (推荐)
+df = spark.read.parquet("hdfs://path/to/file.parquet")
+
+# 分区数据
+df = spark.read.parquet("hdfs://path/to/data") \
+    .filter("year=2024") \
+    .filter("month=03")
+```
+
+#### 从数据库读取
+
+```python
+# JDBC
+df = spark.read \
+    .format("jdbc") \
+    .option("url", "jdbc:postgresql://localhost:5432/db") \
+    .option("dbtable", "users") \
+    .option("user", "user") \
+    .option("password", "password") \
+    .load()
+
+# 带推下谓词
+df = spark.read \
+    .format("jdbc") \
+    .option("url", "jdbc:postgresql://localhost:5432/db") \
+    .option("dbtable", "(SELECT * FROM users WHERE active=true) AS users") \
+    .option("user", "user") \
+    .option("password", "password") \
+    .load()
+```
+
+#### 从Kafka读取
+
+```python
+# 流式读取
+df = spark \
+    .readStream \
+    .format("kafka") \
+    .option("kafka.bootstrap.servers", "localhost:9092") \
+    .option("subscribe", "topic1,topic2") \
+    .load()
+
+# 批量读取
+df = spark \
+    .read \
+    .format("kafka") \
+    .option("kafka.bootstrap.servers", "localhost:9092") \
+    .option("subscribe", "topic1") \
+    .option("startingOffsets", "earliest") \
+    .option("endingOffsets", "latest") \
+    .load()
+```
+
+### 2. Transform (转换)
+
+#### 基础转换
+
+```python
+# 选择列
+selected = df.select("name", "age")
+
+# 过滤
+filtered = df.filter(df.age > 25)
+
+# 去重
+distinct = df.dropDuplicates(["user_id"])
+
+# 排序
+sorted_df = df.orderBy(df.age.desc())
+
+# 重命名
+renamed = df.withColumnRenamed("old_name", "new_name")
+
+# 添加列
+with_new = df.withColumn("age_plus_10", df.age + 10)
+```
+
+#### 聚合
+
+```python
+# 分组聚合
+agg_df = df.groupBy("department").agg(
+    {"salary": "avg", "age": "max"}
+)
+
+# 多聚合
+from pyspark.sql.functions import avg, max, count
+
+agg_df = df.groupBy("department").agg(
+    avg("salary").alias("avg_salary"),
+    max("age").alias("max_age"),
+    count("*").alias("count")
+)
+
+# Window函数
+from pyspark.sql.window import Window
+from pyspark.sql.functions import row_number, rank
+
+window_spec = Window.partitionBy("department").orderBy(df.salary.desc())
+
+ranked = df.withColumn("rank", rank().over(window_spec))
+```
+
+#### Join
+
+```python
+# Inner Join
+joined = df1.join(df2, df1.id == df2.user_id, "inner")
+
+# Left Join
+left_joined = df1.join(df2, df1.id == df2.user_id, "left")
+
+# Broadcast Join (小表)
+from pyspark.sql.functions import broadcast
+
+joined = df1.join(broadcast(small_df), df1.id == small_df.id)
+
+# 多列Join
+joined = df1.join(df2, ["id", "date"])
+```
+
+#### UDF (用户定义函数)
+
+```python
+from pyspark.sql.functions import udf
+from pyspark.sql.types import StringType
+
+@udf(returnType=StringType())
+def categorize_age(age):
+    if age < 18:
+        return "minor"
+    elif age < 65:
+        return "adult"
+    else:
+        return "senior"
+
+df = df.withColumn("age_category", categorize_age(df.age))
+
+# Pandas UDF (更快)
+import pandas as pd
+from pyspark.sql.functions import pandas_udf
+
+@pandas_udf("string")
+def categorize_age_udf(age_series: pd.Series) -> pd.Series:
+    return age_series.apply(lambda age: "minor" if age < 18 else "adult")
+```
+
+### 3. Load (加载)
+
+#### 写入文件系统
+
+```python
+# Parquet (推荐)
+df.write.parquet("hdfs://path/to/output", mode="overwrite")
+
+# 分区写入
+df.write.partitionBy("year", "month").parquet("hdfs://path/to/output")
+
+# CSV
+df.write.csv("hdfs://path/to/output.csv", header=True, mode="overwrite")
+
+# JSON
+df.write.json("hdfs://path/to/output.json", mode="overwrite")
+```
+
+#### 写入数据库
+
+```python
+df.write \
+    .format("jdbc") \
+    .option("url", "jdbc:postgresql://localhost:5432/db") \
+    .option("dbtable", "output_table") \
+    .option("user", "user") \
+    .option("password", "password") \
+    .mode("append") \
+    .save()
+```
+
+#### 写入Kafka
+
+```python
+# 流式写入
+query = df \
+    .writeStream \
+    .format("kafka") \
+    .option("kafka.bootstrap.servers", "localhost:9092") \
+    .option("topic", "output_topic") \
+    .option("checkpointLocation", "/path/to/checkpoint") \
+    .start()
+
+# 批量写入
+df \
+    .selectExpr("CAST(key AS STRING)", "CAST(value AS STRING)") \
+    .write \
+    .format("kafka") \
+    .option("kafka.bootstrap.servers", "localhost:9092") \
+    .option("topic", "output_topic") \
+    .save()
+```
+
+## 性能优化
+
+### 1. 缓存
+
+```python
+# 缓存DataFrame
+df.cache()
+
+# 持久化到磁盘
+from pyspark import StorageLevel
+
+df.persist(StorageLevel.MEMORY_AND_DISK)
+
+# 解除缓存
+df.unpersist()
+```
+
+### 2. 分区优化
+
+```python
+# 查看分区数
+print(df.rdd.getNumPartitions())
+
+# 增加分区
+repartitioned = df.repartition(100, "user_id")
+
+# 减少分区
+coalesced = df.coalesce(10)
+
+# 自定义分区
+from pyspark.sql.functions import spark_partition_id
+
+df.withColumn("partition_id", spark_partition_id())
+```
+
+### 3. 广播变量
+
+```python
+# 广播小数据集
+broadcast_var = spark.sparkContext.broadcast({"key": "value"})
+
+# 使用
+def my_udf(value):
+    return broadcast_var.value.get(value)
+
+# 清理
+broadcast_var.unpersist()
+```
+
+### 4. 累加器
+
+```python
+# 创建累加器
+acc = spark.sparkContext.accumulator(0)
+
+def add_to_acc(value):
+    acc.add(value)
+
+# 使用
+df.foreach(lambda row: add_to_acc(row["amount"]))
+
+print(acc.value)
+```
+
+## 监控和调优
+
+### 1. Spark UI
+
+访问 `http://localhost:4040` 查看:
+- Jobs
+- Stages
+- Storage
+- Environment
+- Executors
+
+### 2. 执行计划
+
+```python
+# 查看逻辑计划
+df.explain(True)
+
+# 查看物理计划
+df.explain()
+```
+
+### 3. 内存调优
+
+```python
+# spark-submit参数
+--executor-memory 8G \
+--executor-cores 4 \
+--driver-memory 4G \
+--conf spark.sql.shuffle.partitions=200
+```
+
+## 最佳实践
+
+### ✅ DO
+
+1. **使用Parquet格式**
+```python
+# ✅ 列式存储,性能好
+df.write.parquet("output")
+```
+
+2. **合理分区**
+```python
+# ✅ 按常用查询字段分区
+df.write.partitionBy("date", "hour").parquet("output")
+```
+
+3. **使用广播Join**
+```python
+# ✅ 小表广播
+joined = large_df.join(broadcast(small_df), "id")
+```
+
+4. **缓存重用数据**
+```python
+# ✅ 多次使用的数据
+df.cache()
+df.count()
+df.show()
+```
+
+### ❌ DON'T
+
+1. **不要使用collect()获取大数据**
+```python
+# ❌ 内存溢出
+data = df.collect()
+
+# ✅ 使用limit
+data = df.limit(1000).collect()
+```
+
+2. **不要过度分区**
+```python
+# ❌ 太多小分区
+df.repartition(1000)
+
+# ✅ 合理分区数
+df.repartition(200)
+```
+
+3. **不要使用row count做检查**
+```python
+# ❌ 触发完整计算
+if df.count() > 0:
+    df.show()
+
+# ✅ 使用take
+if df.head(1):
+    df.show()
+```
+
+## 学习路径
+
+### 初级 (1-2周)
+1. Spark架构和RDD基础
+2. DataFrame和SQL
+3. 基础ETL操作
+
+### 中级 (2-3周)
+1. 聚合和Window函数
+2. UDF和性能优化
+3. 流处理(Structured Streaming)
+
+### 高级 (2-4周)
+1. 自定义数据源
+2. 集群调优
+3. 生产部署
+
+### 专家级 (持续)
+1. 性能调优和故障排查
+2. 多租户资源管理
+3. 实时Lambda架构
+
+## 参考资料
+
+### 官方文档
+- [Spark官方文档](https://spark.apache.org/docs/latest/)
+- [PySpark文档](https://spark.apache.org/docs/latest/api/python/)
+
+### 教程
+- [Spark编程指南](https://spark.apache.org/docs/latest/rdd-programming-guide.html)
+- [Spark SQL指南](https://spark.apache.org/docs/latest/sql-programming-guide.html)
+
+---
+
+**知识ID**: `spark-etl-playbook`  
+**领域**: data-engineering  
+**类型**: playbooks  
+**难度**: intermediate  
+**质量分**: 90  
+**维护者**: data-team@umadev.com  
+**最后更新**: 2026-03-28

package/data-engineering/03-checklists/pipeline-launch-checklist.md

@@ -0,0 +1,194 @@
+---
+id: pipeline-launch-checklist
+title: 数据管道上线检查清单
+domain: data-engineering
+category: 03-checklists
+difficulty: intermediate
+tags: [agent, alerting, checklist, data-engineering, launch, pipeline, quality, 上线前最终确认]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 数据管道上线检查清单
+
+## 概述
+
+本清单用于数据管道（Data Pipeline）从开发环境迁移到生产环境前的系统化审查。覆盖数据质量、可靠性、监控、安全、性能和运维六大维度。适用于批处理管道（Spark / Airflow）和流处理管道（Kafka / Flink / Spark Streaming）。
+
+所有 MUST 级别项未通过则阻止上线。
+
+---
+
+## 1. 数据质量（Data Quality）
+
+### MUST
+
+- [ ] 输入数据 Schema 校验已实现（字段名、类型、非空约束）
+- [ ] 输出数据 Schema 与下游消费者契约一致
+- [ ] 空值处理策略已定义（丢弃 / 默认值填充 / 标记异常）
+- [ ] 重复数据检测与去重逻辑已实现
+- [ ] 数据类型转换有异常处理（如字符串转日期失败不导致管道崩溃）
+- [ ] 数据量级校验：输出行数与输入行数的比例在合理范围内
+- [ ] 关键业务字段的值域校验（如金额 > 0，日期在合理范围内）
+
+### SHOULD
+
+- [ ] 数据质量指标暴露到监控系统（空值率、去重率、异常率）
+- [ ] 数据血缘（Data Lineage）已记录：每个字段的来源和转换逻辑
+- [ ] 数据新鲜度检查：数据时间戳不超过预期延迟
+- [ ] 数据分布异常检测（统计分布与历史基线对比）
+- [ ] 数据质量看板可视化（Grafana / DataDog / Great Expectations）
+- [ ] 使用 Great Expectations / Deequ / Soda 等工具自动化质量检查
+
+## 2. 可靠性（Reliability）
+
+### MUST
+
+- [ ] 幂等性保证：管道重复执行不产生重复数据
+- [ ] 失败重试机制已配置（重试次数、间隔、退避策略）
+- [ ] 死信队列（DLQ）已配置：无法处理的消息不丢弃，进入 DLQ
+- [ ] 检查点 / 偏移量管理已实现（Kafka offset / Flink checkpoint / Spark checkpoint）
+- [ ] 管道从失败点恢复的能力已验证（不需要从头重跑）
+- [ ] 上游数据源不可用时的降级策略已定义（等待 / 跳过 / 使用缓存数据）
+- [ ] 数据写入使用事务或原子操作（避免部分写入导致不一致）
+
+### SHOULD
+
+- [ ] Exactly-once 语义已实现（或 at-least-once + 幂等去重）
+- [ ] 背压（Backpressure）处理机制已实现
+- [ ] 管道支持优雅停机（处理完当前批次后再停止）
+- [ ] 上下游 Schema 变更的兼容性策略（Schema Evolution）
+- [ ] 灾备切换方案已验证（主集群故障时切到备用集群）
+- [ ] 数据回填（Backfill）脚本已准备并测试
+
+## 3. 监控与告警（Monitoring & Alerting）
+
+### MUST
+
+- [ ] 管道运行状态监控（运行中 / 成功 / 失败 / 延迟）
+- [ ] 处理延迟监控：端到端延迟超过 SLA 触发告警
+- [ ] 数据积压监控：未处理消息数 / Kafka Consumer Lag 告警
+- [ ] 错误率监控：处理失败比例 > 1% 触发告警
+- [ ] 管道进程存活监控（进程崩溃 / OOM 即时告警）
+- [ ] 输出数据量监控：输出为 0 行或骤降 > 50% 触发告警
+- [ ] 资源使用监控：CPU / 内存 / 磁盘超过阈值告警
+
+### SHOULD
+
+- [ ] Grafana / Datadog 仪表板已创建，包含：
+  - 处理吞吐量（records/sec）
+  - 端到端延迟（P50 / P95 / P99）
+  - Consumer Lag 趋势
+  - 错误率趋势
+  - 资源使用趋势
+- [ ] 告警分级：P1（管道停止/数据丢失）、P2（延迟超标）、P3（资源告警）
+- [ ] 告警收敛：同一问题不重复告警（设置静默窗口）
+- [ ] 每日自动生成管道运行报告（成功率、延迟、数据量）
+- [ ] SLA 仪表板：展示各管道的 SLA 达成率
+
+## 4. 安全（Security）
+
+### MUST
+
+- [ ] 敏感数据已加密传输（Kafka SSL / HTTPS / TLS）
+- [ ] 敏感数据已加密存储或脱敏（PII 字段：姓名、手机号、身份证号）
+- [ ] 数据访问权限控制（Kafka ACL / HDFS 权限 / 数据库权限）
+- [ ] 密码/密钥通过 Secret Manager 管理（不硬编码在代码或配置中）
+- [ ] 管道运行账户使用最小权限原则
+- [ ] 数据保留策略已定义（过期数据自动清理）
+
+### SHOULD
+
+- [ ] 数据分级标注（公开 / 内部 / 机密 / 绝密）
+- [ ] 敏感数据访问有审计日志
+- [ ] GDPR / 个人信息保护法合规审查已完成
+- [ ] 跨区域数据传输合规审查（如有跨境场景）
+- [ ] 定期安全扫描：依赖漏洞检查
+- [ ] 数据删除请求处理流程已定义（Right to be Forgotten）
+
+## 5. 性能（Performance）
+
+### MUST
+
+- [ ] 吞吐量满足业务需求（处理速度 ≥ 数据产生速度）
+- [ ] 端到端延迟满足 SLA（批处理 < N 小时，流处理 < N 秒）
+- [ ] 压力测试已完成：2 倍峰值流量下管道仍可正常处理
+- [ ] 资源分配已优化（不过度分配浪费成本，不欠分配导致瓶颈）
+- [ ] 大数据量场景已验证（数据量翻倍时性能劣化在可接受范围）
+
+### SHOULD
+
+- [ ] 分区策略已优化（Kafka partition 数量合理，Spark partition 大小 128-256MB）
+- [ ] 序列化格式已选定并验证（Avro / Protobuf / Parquet > JSON / CSV）
+- [ ] 数据压缩已启用（Snappy / LZ4 / Zstd）
+- [ ] 小文件合并策略已实现（避免 HDFS 小文件问题）
+- [ ] 数据倾斜检测和处理（Spark: salting / repartition）
+- [ ] 冷启动性能已验证（管道重启后处理积压数据的时间可接受）
+
+## 6. 运维（Operations）
+
+### MUST
+
+- [ ] 管道部署使用 CI/CD 自动化（不手动部署）
+- [ ] 配置与代码分离（使用配置文件 / 环境变量）
+- [ ] 管道版本与代码版本可追溯（Git tag / 镜像版本）
+- [ ] 回滚方案已定义并验证
+- [ ] 运行手册（Runbook）已编写，包含常见故障处理步骤
+- [ ] On-call 轮值已安排
+
+### SHOULD
+
+- [ ] 管道支持参数化运行（日期范围、数据源、输出目标可配置）
+- [ ] 日志级别可动态调整（不需重启即可切换 DEBUG/INFO）
+- [ ] 管道依赖关系可视化（DAG 图）
+- [ ] 容量规划文档已编写（数据增长预估 + 资源扩容方案）
+- [ ] 成本监控：每条管道的计算成本可追踪
+- [ ] 定期回顾：每月审查管道运行质量和成本
+
+---
+
+## 批处理管道补充检查
+
+- [ ] 调度配置正确（Airflow DAG / Cron / 云调度器）
+- [ ] 任务依赖关系正确（上游任务失败时下游不启动）
+- [ ] SLA 超时设置：任务超过预期时间触发告警
+- [ ] 历史数据回填方案已测试
+- [ ] 并行度设置合理（不超过集群资源上限）
+
+## 流处理管道补充检查
+
+- [ ] Consumer Group 配置正确
+- [ ] Checkpoint 间隔设置合理（太频繁影响性能，太稀疏恢复慢）
+- [ ] Watermark 策略已定义（处理乱序事件）
+- [ ] 窗口函数配置正确（窗口大小、滑动间隔、允许延迟）
+- [ ] State 大小监控（避免 State 无限增长导致 OOM）
+
+---
+
+## 上线前最终确认
+
+| 序号 | 检查项 | 状态 |
+|------|--------|------|
+| 1 | 所有 MUST 级别检查项通过 | [ ] |
+| 2 | 端到端测试在 staging 环境通过 | [ ] |
+| 3 | 数据质量校验通过 | [ ] |
+| 4 | 监控仪表板和告警已配置 | [ ] |
+| 5 | Runbook 已编写并由团队审阅 | [ ] |
+| 6 | 回滚方案已验证 | [ ] |
+| 7 | 下游消费者已通知并确认兼容 | [ ] |
+
+---
+
+## Agent Checklist
+
+以下为 AI Agent 在数据管道上线审查时必须逐项验证的硬约束：
+
+- [ ] 确认管道 Schema 校验逻辑存在（输入 + 输出）
+- [ ] 确认幂等性：手动触发管道两次，输出数据不重复
+- [ ] 确认失败恢复：模拟中途失败后重启，数据完整且不重复
+- [ ] 确认监控告警：管道停止后 < 5 分钟收到告警
+- [ ] 确认密码/密钥不在代码或配置文件中明文出现
+- [ ] 确认吞吐量测试结果满足 SLA
+- [ ] 确认 Consumer Lag / 处理延迟指标可在监控系统中查看
+- [ ] 确认回滚方案文档存在且步骤清晰
+- [ ] 确认数据保留策略已配置（过期数据自动清理）
+- [ ] 生成上线检查报告并附在发布 ticket 中