编辑“︁Airflow时区设置”︁（章节）

= Airflow时区设置 =

== 介绍 ==  
Apache Airflow 是一个用于编排复杂工作流的平台，其核心功能之一是调度任务。时区设置是调度任务的关键配置，直接影响任务的执行时间和计划。本文将详细介绍 Airflow 的时区配置原理、最佳实践以及常见问题的解决方法，帮助用户正确配置时区以避免调度错误。

Airflow 默认使用 UTC 时区，但用户可以根据需求修改为本地时区（如 `Asia/Shanghai` 或 `America/New_York`）。时区设置涉及以下核心组件：  
1. **调度器时区**：决定 DAG 的计划执行时间。  
2. **数据库时区**：存储任务执行时间戳的时区。  
3. **Web UI 时区**：显示任务日志和元数据的时区。  

== 配置时区 ==  

=== 修改默认时区 ===  
在 `airflow.cfg` 中设置 `default_timezone` 和 `default_ui_timezone`：  

<syntaxhighlight lang="ini">  
[core]  
default_timezone = Asia/Shanghai  
default_ui_timezone = Asia/Shanghai  
</syntaxhighlight>  

或通过环境变量覆盖：  
<syntaxhighlight lang="bash">  
export AIRFLOW__CORE__DEFAULT_TIMEZONE="Asia/Shanghai"  
export AIRFLOW__CORE__DEFAULT_UI_TIMEZONE="Asia/Shanghai"  
</syntaxhighlight>  

=== 代码中指定时区 ===  
在 DAG 定义中，可通过 `timezone` 参数强制指定时区：  
<syntaxhighlight lang="python">  
from datetime import datetime  
from airflow import DAG  
from pytz import timezone  

local_tz = timezone("Asia/Shanghai")  

dag = DAG(  
    "my_dag",  
    start_date=datetime(2023, 1, 1, tzinfo=local_tz),  
    schedule_interval="0 8 * * *",  # 每天北京时间 8:00  
)  
</syntaxhighlight>  

== 时区转换原理 ==  
Airflow 内部将所有时间戳转换为 UTC 存储。调度器根据以下规则处理时区：  
1. 若 `start_date` 带时区信息，则按该时区计算计划时间。  
2. 若 `start_date` 无时区，则使用 `default_timezone`。  

=== 时间计算示例 ===  
假设时区为 `Asia/Shanghai`（UTC+8），`schedule_interval` 为 `0 8 * * *`：  
* 调度器会在 UTC 时间 `00:00`（即北京时间 `08:00`）触发任务。  

== 常见问题 ==  

=== 问题1：任务未按预期时间触发 ===  
'''原因'''：`start_date` 未指定时区，且 `default_timezone` 配置错误。  
'''解决'''：确保 `start_date` 包含时区信息：  
<syntaxhighlight lang="python">  
start_date=datetime(2023, 1, 1, tzinfo=timezone("Asia/Shanghai"))  
</syntaxhighlight>  

=== 问题2：Web UI 显示时间错误 ===  
'''原因'''：`default_ui_timezone` 未配置或与数据库时区不一致。  
'''解决'''：检查 `airflow.cfg` 并重启 Web 服务器。  

== 实际案例 ==  

=== 案例：跨时区调度 ===  
某公司在北京（UTC+8）和纽约（UTC-5）均有团队，需在两地工作时间触发任务：  
1. 配置 Airflow 时区为 UTC，避免歧义。  
2. 在 DAG 中动态转换时区：  
<syntaxhighlight lang="python">  
new_york_time = timezone("America/New_York").localize(datetime(2023, 1, 1))  
start_date = new_york_time.astimezone(timezone("UTC"))  
</syntaxhighlight>  

== 高级配置 ==  

=== 使用 Pendulum 替代 pytz ===  
Pendulum 提供更友好的时区操作 API：  
<syntaxhighlight lang="python">  
import pendulum  

local_tz = pendulum.timezone("Asia/Shanghai")  
start_date = pendulum.datetime(2023, 1, 1, tz=local_tz)  
</syntaxhighlight>  

=== 动态时区调整 ===  
通过宏 `{{ data_interval_start }}` 在任务运行时获取当前时区时间：  
<syntaxhighlight lang="python">  
def print_time(**context):  
    exec_time = context["data_interval_start"].astimezone(timezone("Asia/Shanghai"))  
    print(f"执行时间（北京时间）: {exec_time}")  
</syntaxhighlight>  

== 总结 ==  
* 始终明确指定 `start_date` 的时区。  
* 确保 `default_timezone` 与业务需求一致。  
* 使用 Pendulum 简化时区操作。  
* 通过日志验证任务触发时间是否符合预期。  

<mermaid>  
graph TD  
    A[配置 airflow.cfg] --> B[设置 default_timezone]  
    A --> C[设置 default_ui_timezone]  
    D[DAG 定义] --> E[指定 start_date 时区]  
    D --> F[使用 schedule_interval 计划]  
    B --> G[调度器按 UTC 计算]  
    C --> H[Web UI 显示本地时间]  
</mermaid>

[[Category:大数据框架]]
[[Category:Airflow]]
[[Category:Airflow调度与触发]]