From 85f1f18adad834aa0210809e83df8edf99a72981 Mon Sep 17 00:00:00 2001
From: KennethCheng <kennethcheng1874@163.com>
Date: Tue, 13 Oct 2026 14:44:49 +0800
Subject: [PATCH] docs:README

---
 README.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 119 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..05ea2f9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,119 @@
+# Airflow Demo
+
+一个用于学习和练习 **Apache Airflow** 的示例代码仓库。仓库通过多个独立的 DAG 示例，演示任务定义、参数配置、分支选择、任务间通信、传感器以及跨 DAG 依赖等常见用法，并包含 Hive 集成示例。
+
+> 本仓库以学习示例为主。运行前请检查代码中使用的 Airflow Operator、Connection ID、文件路径和外部服务配置，并根据自己的环境进行调整。
+
+## 环境参考
+
+当前学习环境可参考以下版本：
+
+- Python 3.6
+- Apache Airflow 2.2.5
+- Apache Hive 2.3.6（仅运行 Hive 示例时需要）
+
+Airflow 不同版本之间的导入路径、Provider 依赖和部分参数可能存在差异。若使用其他版本，请以当前安装版本的文档和实际报错为准。
+
+## 示例目录
+
+| 文件 | 主要内容 |
+| --- | --- |
+| `hello_world.py` | 基础 DAG 与任务定义入门示例 |
+| `hello_world2.py` | 另一种基础工作流与任务编排示例 |
+| `args_example.py` | DAG 和任务的参数配置示例 |
+| `branch_example.py` | 使用分支任务，根据 Python 函数的返回值选择后续执行路径 |
+| `xcom_example.py` | 使用 XCom 在任务之间传递少量数据 |
+| `xcom_example2.py` | XCom 的另一种任务间数据传递场景 |
+| `file_sensor_example.py` | 使用 Sensor 等待文件出现或上游任务达到指定状态 |
+| `dag_dependency1.py` | 跨 DAG 依赖示例的一部分，建议与 `dag_dependency2.py` 配合阅读 |
+| `dag_dependency2.py` | 跨 DAG 依赖、触发或等待相关示例，具体行为以代码配置为准 |
+| `hive_provider.py` | Hive Operator / Provider 集成示例，需要配置对应的 Hive 连接和服务 |
+
+## 如何运行
+
+### 1. 确认 Airflow 环境
+
+先进入已经安装 Airflow 的 Python 虚拟环境，并确认 Airflow 可以正常执行：
+
+```bash
+airflow version
+```
+
+### 2. 克隆仓库
+
+```bash
+git clone https://gitea.kennethcheng.cc/KennethCheng/airflow_demo.git
+cd airflow_demo
+```
+
+### 3. 将示例放入 DAG 目录
+
+查看当前 Airflow 配置的 DAG 目录：
+
+```bash
+airflow config get-value core dags_folder
+```
+
+确认目录无误后，将示例 Python 文件复制到该目录。也可以根据自己的部署方式，将仓库目录配置为 Airflow 能够扫描到的 DAG 目录：
+
+```bash
+DAGS_DIR="$(airflow config get-value core dags_folder)"
+cp ./*.py "$DAGS_DIR"/
+```
+
+请确保 Airflow Scheduler 对这些文件有读取权限。若使用容器或多节点部署，还需要保证相关节点能够访问相同的 DAG 文件及所需资源。
+
+### 4. 检查 DAG 是否加载成功
+
+```bash
+airflow dags list
+```
+
+如果示例未出现在列表中，检查导入错误：
+
+```bash
+airflow dags list-import-errors
+```
+
+也可以打开 Airflow Web UI，查看 DAG 列表、任务依赖图、运行日志和任务状态。具体启动 Scheduler、Web Server 的方式取决于现有 Airflow 部署。
+
+### 5. 运行示例
+
+在 Web UI 中找到对应 DAG 并手动触发，或使用命令行触发：
+
+```bash
+airflow dags trigger <dag_id>
+```
+
+将 `<dag_id>` 替换为代码中实际定义的 DAG ID。**DAG ID 不一定与 Python 文件名相同**；运行前请先查看对应文件中的 `dag_id` 配置。
+
+## 运行前需要注意
+
+### 跨 DAG 依赖
+
+阅读 `dag_dependency1.py` 和 `dag_dependency2.py` 时，注意上游和下游 DAG 的 `dag_id`、调度时间、逻辑日期（Logical Date / Execution Date）以及 Sensor 的等待条件。两个 DAG 的调度方式或逻辑日期不匹配时，下游任务可能一直等待。
+
+### 文件传感器
+
+运行 `file_sensor_example.py` 前，请检查代码中配置的目标文件路径。该路径必须对运行 Sensor 任务的 Airflow 执行环境可见；如果文件由其他主机或容器生成，需要确认目录挂载或共享方式正确。
+
+### XCom
+
+XCom 适合传递任务间需要的小型元数据或计算结果，不建议用来传输大型 DataFrame、文件内容或大批量业务数据。大型数据通常应存储在文件系统、对象存储或数据库中，再通过 XCom 传递其路径或标识。
+
+### Hive 集成
+
+运行 `hive_provider.py` 前，请确认 HiveServer2 / Metastore 等所需服务已启动且网络可达，并在 Airflow 的 **Admin → Connections** 中配置连接。Connection ID、连接参数和代码中的配置必须一致；若缺少相应 Provider 包，请安装与当前 Airflow 版本兼容的依赖。
+
+## 建议学习顺序
+
+1. 从 `hello_world.py`、`hello_world2.py` 熟悉 DAG 和 Operator 的基本结构。
+2. 阅读 `args_example.py`，了解 DAG 与任务的参数配置。
+3. 学习 `xcom_example.py`、`xcom_example2.py`，掌握任务间传递小型数据的方法。
+4. 阅读 `branch_example.py`，理解分支选择与不同任务路径。
+5. 练习 `file_sensor_example.py` 和两份跨 DAG 依赖示例，理解任务等待与工作流协作。
+6. 最后阅读 `hive_provider.py`，尝试将 Airflow 与 Hive 环境连接起来。
+
+## 说明
+
+本仓库用于个人学习和功能演示。用于生产环境前，请根据实际业务补充依赖管理、连接与敏感信息管理、任务超时、重试策略、告警、日志和数据质量校验等配置。