{
"canonical_name": "apache/airflow",
"compilation_id": "pack_cdc292bbb7344110b578a02b2ba52c0a",
"created_at": "2026-05-15T12:40:25.534244+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install apache-airflow` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install apache-airflow",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_5d56f7c6c45b4f5fb4a0cec12f84ab59"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_539dc6d821ffb0b2cb2eb9c1a6d6c916",
"canonical_name": "apache/airflow",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/apache/airflow",
"slug": "airflow",
"source_packet_id": "phit_9794b724102d4e4a983c048690ad5474",
"source_validation_id": "dval_8d9084c3d733430f996064066351670c"
},
"merchandising": {
"best_for": "需要流程自动化能力，并使用 local_cli的用户",
"github_forks": 17049,
"github_stars": 45394,
"one_liner_en": "Apache Airflow - A platform to programmatically author, schedule, and monitor workflows",
"one_liner_zh": "Apache Airflow - A platform to programmatically author, schedule, and monitor workflows",
"primary_category": {
"category_id": "workflow-automation",
"confidence": "high",
"name_en": "Workflow Automation",
"name_zh": "流程自动化",
"reason": "curated popular coverage category matched project identity"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "airflow",
"title_zh": "airflow 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_9794b724102d4e4a983c048690ad5474",
"page_model": {
"artifacts": {
"artifact_slug": "airflow",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install apache-airflow",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/apache/airflow#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"流程自动化",
"断点恢复流程",
"评测体系"
],
"eyebrow": "流程自动化",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要流程自动化能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Apache Airflow - A platform to programmatically author, schedule, and monitor workflows"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`ExternalTaskSensor` can succeed early for task groups with NULL task states",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_3c746f7ce44f43f1a5a81840f4ee741a | https://github.com/apache/airflow/issues/66877 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：`ExternalTaskSensor` can succeed early for task groups with NULL task states",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:33884891 | https://github.com/apache/airflow | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:33884891 | https://github.com/apache/airflow | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:33884891 | https://github.com/apache/airflow | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:33884891 | https://github.com/apache/airflow | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:33884891 | https://github.com/apache/airflow | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.1.6",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_c94c5b79bb91454c9e0ad22b4a36dc11 | https://github.com/apache/airflow/releases/tag/3.1.6 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Apache Airflow 3.1.6",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.1.7",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_80a5614167b44ecca96422caa56afca4 | https://github.com/apache/airflow/releases/tag/3.1.7 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Apache Airflow 3.1.7",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.1.8",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_3437fcfc89ff40a0ba17b7e5a5d8aa2c | https://github.com/apache/airflow/releases/tag/3.1.8 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Apache Airflow 3.1.8",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.2.0",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_d18a498a98ed48f0bb3f813aaa554aea | https://github.com/apache/airflow/releases/tag/3.2.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Apache Airflow 3.2.0",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.2.1",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_41889eab2c0240bbb0bd010262d41346 | https://github.com/apache/airflow/releases/tag/3.2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Apache Airflow 3.2.1",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow Ctl (airflowctl) 0.1.2",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_df5b495084624a899a4674d4b0193ec7 | https://github.com/apache/airflow/releases/tag/airflow-ctl/0.1.2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Apache Airflow Ctl (airflowctl) 0.1.2",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow Helm Chart 1.19.0",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_0f5ecc599d634c1daa9ee6c9f2434849 | https://github.com/apache/airflow/releases/tag/helm-chart/1.19.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Apache Airflow Helm Chart 1.19.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow Helm Chart 1.20.0",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_c13fe02283094cffa9e186716cc8dcf5 | https://github.com/apache/airflow/releases/tag/helm-chart/1.20.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Apache Airflow Helm Chart 1.20.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow Helm Chart 1.21.0",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_d29213d0ae2441e8907f407d8dc9b861 | https://github.com/apache/airflow/releases/tag/helm-chart/1.21.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Apache Airflow Helm Chart 1.21.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：airflow-ctl/0.1.3",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_9096523c7ba541c6ac1b6b926d6f6bc0 | https://github.com/apache/airflow/releases/tag/airflow-ctl/0.1.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：airflow-ctl/0.1.3",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 19 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：`ExternalTaskSensor` can succeed early for task groups with NULL task states。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 4369,
"forks": 17049,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 45394
},
"source_url": "https://github.com/apache/airflow",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Apache Airflow - A platform to programmatically author, schedule, and monitor workflows",
"title": "airflow 能力包",
"trial_prompt": "# airflow - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 airflow 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的流程自动化任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-introduction：Project Introduction。围绕“Project Introduction”模拟一次用户任务，不展示安装或运行结果。\n2. core-concepts：Core Concepts。围绕“Core Concepts”模拟一次用户任务，不展示安装或运行结果。\n3. architecture-overview：Architecture Overview。围绕“Architecture Overview”模拟一次用户任务，不展示安装或运行结果。\n4. scheduler-executor：Scheduler and Executor Architecture。围绕“Scheduler and Executor Architecture”模拟一次用户任务，不展示安装或运行结果。\n5. rest-api：REST API。围绕“REST API”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-introduction\n输入：用户提供的“Project Introduction”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. core-concepts\n输入：用户提供的“Core Concepts”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture-overview\n输入：用户提供的“Architecture Overview”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. scheduler-executor\n输入：用户提供的“Scheduler and Executor Architecture”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. rest-api\n输入：用户提供的“REST API”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-introduction：Step 1 必须围绕“Project Introduction”形成一个小中间产物，并等待用户确认。\n- Step 2 / core-concepts：Step 2 必须围绕“Core Concepts”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture-overview：Step 3 必须围绕“Architecture Overview”形成一个小中间产物，并等待用户确认。\n- Step 4 / scheduler-executor：Step 4 必须围绕“Scheduler and Executor Architecture”形成一个小中间产物，并等待用户确认。\n- Step 5 / rest-api：Step 5 必须围绕“REST API”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/apache/airflow\n- https://github.com/apache/airflow#readme\n- .github/skills/aip-user-stories/SKILL.md\n- .github/skills/airflow-translations/SKILL.md\n- .github/skills/maintainer-review/SKILL.md\n- .github/skills/pr-stats/SKILL.md\n- .github/skills/pr-triage/SKILL.md\n- .github/skills/prepare-providers-documentation/SKILL.md\n- README.md\n- INSTALLING.md\n- PROVIDERS.rst\n- airflow-core/src/airflow/version.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 airflow 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: `ExternalTaskSensor` can succeed early for task groups with NULL task st（https://github.com/apache/airflow/issues/66877）；github/github_issue: edge3: upgrade from 1.x silently leaves schema stale — `BaseDBManager.up（https://github.com/apache/airflow/issues/66524）；github/github_release: Apache Airflow Helm Chart 1.21.0（https://github.com/apache/airflow/releases/tag/helm-chart/1.21.0）；github/github_release: Apache Airflow 3.2.1（https://github.com/apache/airflow/releases/tag/3.2.1）；github/github_release: Apache Airflow 3.2.0（https://github.com/apache/airflow/releases/tag/3.2.0）；github/github_release: Apache Airflow Helm Chart 1.20.0（https://github.com/apache/airflow/releases/tag/helm-chart/1.20.0）；github/github_release: airflow-ctl/0.1.3（https://github.com/apache/airflow/releases/tag/airflow-ctl/0.1.3）；github/github_release: Apache Airflow 3.1.8（https://github.com/apache/airflow/releases/tag/3.1.8）；github/github_release: Apache Airflow Ctl (airflowctl) 0.1.2（https://github.com/apache/airflow/releases/tag/airflow-ctl/0.1.2）；github/github_release: Apache Airflow Helm Chart 1.19.0（https://github.com/apache/airflow/releases/tag/helm-chart/1.19.0）；github/github_release: Apache Airflow 3.1.7（https://github.com/apache/airflow/releases/tag/3.1.7）；github/github_release: Apache Airflow 3.1.6（https://github.com/apache/airflow/releases/tag/3.1.6）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "`ExternalTaskSensor` can succeed early for task groups with NULL task st",
"url": "https://github.com/apache/airflow/issues/66877"
},
{
"kind": "github_issue",
"source": "github",
"title": "edge3: upgrade from 1.x silently leaves schema stale — `BaseDBManager.up",
"url": "https://github.com/apache/airflow/issues/66524"
},
{
"kind": "github_release",
"source": "github",
"title": "Apache Airflow Helm Chart 1.21.0",
"url": "https://github.com/apache/airflow/releases/tag/helm-chart/1.21.0"
},
{
"kind": "github_release",
"source": "github",
"title": "Apache Airflow 3.2.1",
"url": "https://github.com/apache/airflow/releases/tag/3.2.1"
},
{
"kind": "github_release",
"source": "github",
"title": "Apache Airflow 3.2.0",
"url": "https://github.com/apache/airflow/releases/tag/3.2.0"
},
{
"kind": "github_release",
"source": "github",
"title": "Apache Airflow Helm Chart 1.20.0",
"url": "https://github.com/apache/airflow/releases/tag/helm-chart/1.20.0"
},
{
"kind": "github_release",
"source": "github",
"title": "airflow-ctl/0.1.3",
"url": "https://github.com/apache/airflow/releases/tag/airflow-ctl/0.1.3"
},
{
"kind": "github_release",
"source": "github",
"title": "Apache Airflow 3.1.8",
"url": "https://github.com/apache/airflow/releases/tag/3.1.8"
},
{
"kind": "github_release",
"source": "github",
"title": "Apache Airflow Ctl (airflowctl) 0.1.2",
"url": "https://github.com/apache/airflow/releases/tag/airflow-ctl/0.1.2"
},
{
"kind": "github_release",
"source": "github",
"title": "Apache Airflow Helm Chart 1.19.0",
"url": "https://github.com/apache/airflow/releases/tag/helm-chart/1.19.0"
},
{
"kind": "github_release",
"source": "github",
"title": "Apache Airflow 3.1.7",
"url": "https://github.com/apache/airflow/releases/tag/3.1.7"
},
{
"kind": "github_release",
"source": "github",
"title": "Apache Airflow 3.1.6",
"url": "https://github.com/apache/airflow/releases/tag/3.1.6"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "流程自动化",
"desc": "Apache Airflow - A platform to programmatically author, schedule, and monitor workflows",
"effort": "安装已验证",
"forks": 17049,
"icon": "bolt",
"name": "airflow 能力包",
"risk": "可发布",
"slug": "airflow",
"stars": 45394,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"流程自动化",
"断点恢复流程",
"评测体系"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/apache/airflow 项目说明书\n\n生成时间：2026-05-15 12:21:31 UTC\n\n## 目录\n\n- [Project Introduction](#project-introduction)\n- [Core Concepts](#core-concepts)\n- [Architecture Overview](#architecture-overview)\n- [Scheduler and Executor Architecture](#scheduler-executor)\n- [REST API](#rest-api)\n- [User Interface](#user-interface)\n- [Data Flow and State Management](#data-flow-xcom)\n- [Connections and Variables](#connections-variables)\n- [Docker and Helm Deployment](#docker-helm)\n- [Kubernetes Deployment](#kubernetes-deployment)\n\n\n\n## Project Introduction\n\n### 相关页面\n\n相关主题：[Architecture Overview](#architecture-overview), [Core Concepts](#core-concepts)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/apache/airflow/blob/main/README.md)\n- [INSTALLING.md](https://github.com/apache/airflow/blob/main/INSTALLING.md)\n- [PROVIDERS.rst](https://github.com/apache/airflow/blob/main/PROVIDERS.rst)\n- [airflow-core/src/airflow/version.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/version.py)\n- [airflow-core/src/airflow/utils/db.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/utils/db.py)\n- [airflow-core/src/airflow/_vendor/README.md](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/_vendor/README.md)\n\n\n# Project Introduction\n\nApache Airflow is an open-source platform designed for **orchestrating, scheduling, and monitoring** complex workflows. Originally developed at Airbnb, it has become the industry standard for data pipeline orchestration, enabling users to define, schedule, and execute workflows as Directed Acyclic Graphs (DAGs).\n\n资料来源：[README.md](https://github.com/apache/airflow/blob/main/README.md)\n\n## Overview\n\nApache Airflow provides a comprehensive solution for workflow management with the following key characteristics:\n\n| Aspect | Description |\n|--------|-------------|\n| **Type** | Open-source workflow orchestration platform |\n| **Language** | Python |\n| **License** | Apache License 2.0 |\n| **Primary Use** | Data pipelines, ETL processes, ML workflows |\n| **Architecture** | Distributed, scalable, extensible |\n\n资料来源：[README.md](https://github.com/apache/airflow/blob/main/README.md)\n\n## Core Architecture\n\nAirflow follows a distributed architecture with several key components working together to manage workflow execution.\n\n```mermaid\ngraph TD\n subgraph Client[\"Client Layer\"]\n WebServer[\"Web Server\"]\n CLI[\"Command Line Interface\"]\n API[\"REST API\"]\n end\n \n subgraph Scheduler[\"Core Components\"]\n Scheduler[\"Scheduler\"]\n Executor[\"Executor\"]\n Database[\"Metadata Database\"]\n end\n \n subgraph Workers[\"Worker Layer\"]\n Workers[\"Workers\"]\n Tasks[\"Task Instances\"]\n end\n \n subgraph External[\"External Systems\"]\n Triggerer[\"Triggerer\"]\n Logger[\"Logging\"]\n end\n \n WebServer --> Database\n CLI --> Database\n API --> Database\n Scheduler --> Database\n Scheduler --> Executor\n Executor --> Workers\n Workers --> Database\n Triggerer --> Database\n \n style Database fill:#f9f,stroke:#333,stroke-width:2px\n```\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n\n## DAG-Based Workflow Model\n\nAt the heart of Airflow is the **DAG (Directed Acyclic Graph)** concept. A DAG represents a collection of tasks with defined dependencies, arranged in a way that reflects the logical flow of work.\n\n### Key DAG Properties\n\n| Property | Description |\n|----------|-------------|\n| **Directed** | Tasks have explicit dependencies (upstream/downstream relationships) |\n| **Acyclic** | No circular dependencies; workflows flow in one direction |\n| **Graph** | Complex dependency structures are supported |\n\n### Default Connections\n\nAirflow ships with pre-configured connection definitions for common integrations:\n\n| Connection ID | Type | Default Configuration |\n|---------------|------|----------------------|\n| `facebook_default` | facebook_social | Facebook Ad account credentials |\n| `fs_default` | fs | Filesystem path `/` |\n| `ftp_default` | ftp | localhost:21, SSH key auth |\n| `google_cloud_default` | google_cloud_platform | Default GCP schema |\n| `hive_cli_default` | hive_cli | localhost:10000, Beeline mode |\n| `hiveserver2_default` | hiveserver2 | localhost:10000 |\n| `http_default` | http | https://www.httpbin.org/ |\n| `gremlin_default` | gremlin | gremlin:8182 |\n\n资料来源：[airflow-core/src/airflow/utils/db.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/utils/db.py)\n\n## Providers Ecosystem\n\nApache Airflow's functionality is extended through **Providers** — packages that integrate Airflow with external services and systems.\n\n```mermaid\ngraph LR\n Airflow[\"Apache Airflow Core\"] --> Providers[\"Providers\"]\n Providers --> Google[\"Google Cloud Provider\"]\n Providers --> AWS[\"Amazon Provider\"]\n Providers --> Azure[\"Microsoft Azure Provider\"]\n Providers --> Edge3[\"Edge3 Provider\"]\n Providers --> Others[\"Other Providers\"]\n```\n\n### Provider Management\n\nProviders can be discovered and managed through the Airflow CLI:\n\n```bash\nairflow providers [list|get|widgets|sensors|hooks|executors]\n```\n\n### Key Provider Features\n\n| Feature | Description |\n|---------|-------------|\n| **Hooks** | Interfaces to external systems for connection management |\n| **Operators** | Pre-built task templates for common operations |\n| **Sensors** | Tasks that wait for external conditions |\n| **Transfers** | Tasks for moving data between systems |\n\n资料来源：[PROVIDERS.rst](https://github.com/apache/airflow/blob/main/PROVIDERS.rst)\n\n## Version Information\n\nThe Airflow version is managed centrally and can be accessed programmatically:\n\n```python\n# airflow-core/src/airflow/version.py\nversion = \"2.11.0\"\n```\n\n资料来源：[airflow-core/src/airflow/version.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/version.py)\n\n## Installation Methods\n\nAirflow supports multiple installation approaches to suit different environments and use cases.\n\n| Method | Use Case | Command/Config |\n|--------|----------|----------------|\n| **PyPI** | Standard installation | `pip install apache-airflow` |\n| **Sources** | Development/contribution | Clone repository and install |\n| **Providers from sources** | Testing provider changes | Breeze commands |\n| **Constraints** | Reproducible builds | Use constraints files |\n\n资料来源：[INSTALLING.md](https://github.com/apache/airflow/blob/main/INSTALLING.md)\n\n### Installing Specific Versions\n\nThe `--use-airflow-version` option provides flexibility for version installation:\n\n| Version Specifier | Behavior |\n|-------------------|----------|\n| `none` | Skip Airflow installation |\n| `wheel` | Install from local `dist/` folder |\n| `sdist` | Install from source distribution |\n| `owner/repo:branch` | Install from GitHub repository |\n| `PR_NUMBER` | Install from a Pull Request |\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/common_options.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/common_options.py)\n\n## Vendored Dependencies\n\nAirflow maintains a `_vendor` package for dependencies that need special handling:\n\n```mermaid\ngraph TD\n Vendor[\"_vendor Package\"] --> License[\"Move to licenses/ folder\"]\n Vendor --> Remove[\"Remove README/supporting files\"]\n Vendor --> Requirements[\"Add to pyproject.toml\"]\n Vendor --> Fixes[\"Re-apply historical fixes\"]\n```\n\n### Vendoring Process\n\n1. Update `vendor.md` with library, version, and SHA256 hash\n2. Remove old files and directories\n3. Move LICENSE files to `licenses/` folder\n4. Add requirements to `pyproject.toml` with appropriate comments\n5. Re-apply any necessary cherry-picked fixes\n\n资料来源：[airflow-core/src/airflow/_vendor/README.md](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/_vendor/README.md)\n\n## Development Environment (Breeze)\n\nThe **Breeze** tool is Airflow's primary development environment, providing consistent tooling for testing, building, and development.\n\n### Key Breeze Commands\n\n| Command | Purpose |\n|---------|---------|\n| `breeze sbom update-sbom-information` | Update SBOM information |\n| `breeze workflow run-publish` | Run documentation workflow |\n| `breeze build` | Build Airflow images |\n\n### Breeze Configuration Options\n\n| Option | Description |\n|--------|-------------|\n| `--airflow-version` | Specify Airflow version |\n| `--debian-version` | Select base Debian version |\n| `--docker-cache` | Configure build caching |\n| `--mount-sources` | Control source mounting strategy |\n| `--allow-pre-releases` | Enable pre-release installations |\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/sbom_commands.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/sbom_commands.py)\n\n## CLI Commands Structure\n\nAirflow provides a comprehensive command-line interface organized into logical groups:\n\n```mermaid\ngraph TD\n CLI[\"airflow CLI\"] --> Groups\n Groups --> Config[\"config - View configuration\"]\n Groups --> Info[\"info - Show system info\"]\n Groups --> Plugins[\"plugins - Dump plugin info\"]\n Groups --> Connections[\"connections - Manage connections\"]\n Groups --> Providers[\"providers - Display providers\"]\n Groups --> DAGs[\"dags - Manage DAGs\"]\n Groups --> db_manager[\"db-manager - Database management\"]\n Groups --> rotate_fernet[\"rotate-fernet-key - Rotate keys\"]\n```\n\n### Core CLI Commands\n\n| Command | Function | Purpose |\n|---------|----------|---------|\n| `airflow config` | View configuration | Display current Airflow settings |\n| `airflow info` | System information | Show environment details |\n| `airflow plugins` | Plugin dump | Display loaded plugins |\n| `airflow connections` | Connection management | CRUD operations for connections |\n| `airflow providers` | Provider display | List installed providers |\n| `airflow db-manager` | Database management | External DB manager operations |\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n\n## Dependencies and Requirements\n\n### Generated Dependency Files\n\nThe repository maintains several auto-generated dependency files:\n\n| File | Purpose | Generation Command |\n|------|---------|-------------------|\n| `devel_deps.txt` | Development dependencies | `./dev/get_devel_deps.sh` |\n| `dep_tree.txt` | Full dependency tree | `uv tree --no-dedupe` |\n| `dependency_depth.json` | Dependency depth analysis | Generated by Breeze |\n\n### PyPI README Generation\n\nThe `PYPI_README.md` is automatically generated from the main README using pre-commit hooks defined in `.pre-commit-config.yaml`, ensuring consistency between project documentation and PyPI listings.\n\n资料来源：[generated/README.md](https://github.com/apache/airflow/blob/main/generated/README.md)\n\n## Summary\n\nApache Airflow is a robust, extensible workflow orchestration platform that provides:\n\n- **DAG-based workflow definition** for complex pipeline management\n- **Extensible architecture** through providers and plugins\n- **Multiple deployment options** from development to production\n- **Comprehensive CLI and UI** for monitoring and management\n- **Strong ecosystem** of integrations with major cloud providers and services\n\nThe platform's design prioritizes **dynamic pipeline generation**, **extensible operator library**, and **robust scheduling capabilities**, making it the go-to choice for data engineering teams worldwide.\n\n---\n\n\n\n## Core Concepts\n\n### 相关页面\n\n相关主题：[Scheduler and Executor Architecture](#scheduler-executor), [Data Flow and State Management](#data-flow-xcom)\n\n\nRelated Source Files\n\nThe following source files are used to generate this documentation:\n\n- [airflow-core/src/airflow/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n- [airflow-core/src/airflow/cli/commands/config_command.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/commands/config_command.py)\n- [airflow-core/src/airflow/utils/db.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/utils/db.py)\n- [providers/google/src/airflow/providers/google/cloud/hooks/cloud_composer.py](https://github.com/apache/airflow/blob/main/providers/google/src/airflow/providers/google/cloud/hooks/cloud_composer.py)\n- [generated/README.md](https://github.com/apache/airflow/blob/main/generated/README.md)\n\n\n# Core Concepts\n\nApache Airflow is an open-source workflow orchestration platform designed to programmatically author, schedule, and monitor complex data pipelines. The platform provides a robust framework for defining workflows as Directed Acyclic Graphs (DAGs), enabling organizations to automate and manage data processing workflows at scale.\n\n## DAG (Directed Acyclic Graph)\n\nThe DAG is the fundamental building block of Airflow. It represents a collection of tasks with defined dependencies, organized in a way that reflects the logical flow of work through the system.\n\n### DAG Structure\n\nA DAG defines the overall structure of a workflow:\n\n- **Nodes**: Represent individual tasks or operations\n- **Edges**: Define dependencies between tasks (task A must complete before task B can start)\n- **No Cycles**: The graph must flow in one direction without circular dependencies\n\n### DAG Commands\n\nAirflow provides comprehensive CLI commands for managing DAGs through the `dag_cli_commands` configuration.\n\n| Command | Purpose |\n|---------|---------|\n| `dags list` | List all DAGs in the environment |\n| `dags details` | Get detailed information about a specific DAG |\n| `dags list-runs` | List all runs for a specific DAG |\n| `dags list-import-errors` | Show DAGs with import errors |\n| `dags report` | Display DagBag loading report |\n| `dags pause` | Pause a DAG from scheduling |\n| `dags unpause` | Resume DAG scheduling |\n| `dags backfill` | Run subsections of a DAG for a date range |\n| `dags test` | Test a DAG execution |\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n### DAG Execution Parameters\n\nWhen creating a backfill operation, the following parameters can be configured:\n\n| Parameter | Description |\n|-----------|-------------|\n| `dag_id` | The identifier of the DAG to backfill |\n| `from_date` | Start date for the backfill range |\n| `to_date` | End date for the backfill range |\n| `run_conf` | Configuration to pass to the DAG run |\n| `run_backwards` | Execute DAG runs in reverse chronological order |\n| `max_active_runs` | Maximum number of concurrent active DAG runs |\n| `reprocess_behavior` | How to handle already-processed runs |\n| `run_on_latest_version` | Whether to use the latest DAG version |\n| `dry_run` | Execute without making changes |\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n## Tasks and Task Instances\n\n### Task Instance States\n\nA task instance represents a specific execution of a task within a DAG run. Each task instance progresses through various states during its lifecycle.\n\n```mermaid\ngraph TD\n A[None] --> B[Scheduled]\n B --> C[Queued]\n C --> D[Running]\n D --> E{Success/Failed/Skipped}\n E --> F[Success]\n E --> G[Failed]\n E --> H[Skipped]\n D --> I[Upstream Failed]\n F --> J[Complete]\n G --> J\n H --> J\n I --> J\n```\n\n### Task Instance Management\n\nThe Airflow UI provides functionality for clearing task instances, allowing operators to re-execute tasks that may have failed or need to be reprocessed. The `ClearTaskInstanceConfirmationDialog` component handles the confirmation workflow for this operation.\n\nKey attributes displayed when clearing a task instance:\n\n- Current state of the task\n- Start date (shown as relative time)\n- User who executed the task (or \"unknown user\" if unavailable)\n\n## DAG Runs\n\nA DAG Run represents an individual execution of an entire DAG at a specific point in time. Each DAG run has:\n\n- **Run ID**: Unique identifier for the run\n- **State**: Current state (running, success, failed)\n- **Execution Date**: The logical date/time the DAG was scheduled to run\n- **Start/End Date**: Actual execution timestamps\n- **Configuration**: Run-specific configuration parameters\n\n### Listing DAG Runs\n\nThe `list-runs` command supports filtering by:\n\n- **State**: Filter runs by their state (running, success, failed)\n- **No Backfill**: Exclude backfill runs from results\n- **Start Date**: Filter runs executed after a specific date\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n## Variables\n\nAirflow Variables provide a mechanism for storing and retrieving arbitrary content or settings as simple key-value pairs. Variables are encrypted when the `fernet_key` is configured.\n\n### Variable Commands\n\n| Command | Purpose |\n|---------|---------|\n| `variables list` | List all variables |\n| `variables get` | Get a specific variable value |\n| `variables set` | Set a variable value |\n| `variables delete` | Delete a variable |\n| `variables export` | Export all variables to stdout |\n| `variables import` | Import variables from a file |\n\n### Variable Options\n\n| Option | Description |\n|--------|-------------|\n| `VAR` | Variable key name |\n| `VAR_VALUE` | Value to set |\n| `VAR_DESCRIPTION` | Optional description |\n| `SERIALIZE_JSON` | Serialize value as JSON |\n| `DESERIALIZE_JSON` | Deserialize JSON value |\n| `DEFAULT` | Default value if variable doesn't exist |\n| `VAR_IMPORT` | Path to import file |\n| `VAR_ACTION_ON_EXISTING_KEY` | Action for existing keys |\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n## Connections\n\nAirflow Connections store credentials and configuration information needed to connect to external systems. Default connections are automatically created during initialization.\n\n### Default Connection Types\n\nThe `db.py` utility creates several default connections:\n\n| Connection ID | Type | Purpose |\n|---------------|------|---------|\n| `facebook_social` | facebook_social | Facebook social authentication |\n| `fs_default` | fs | File system operations |\n| `ftp_default` | ftp | FTP server access |\n| `google_cloud_default` | google_cloud_platform | GCP default credentials |\n| `gremlin_default` | gremlin | Gremlin graph database |\n| `hive_cli_default` | hive_cli | Hive command-line interface |\n| `hiveserver2_default` | hiveserver2 | HiveServer2 JDBC connections |\n| `http_default` | http | Generic HTTP endpoints |\n| `iceberg_default` | iceberg | Apache Iceberg catalog |\n\nSource: [airflow-core/src/airflow/utils/db.py](airflow-core/src/airflow/utils/db.py)\n\n### Connection CLI Commands\n\n| Command | Purpose |\n|---------|---------|\n| `connections list` | List all connections |\n| `connections add` | Add a new connection |\n| `connections delete` | Delete a connection |\n| `connections get` | Get connection details |\n| `connections edit` | Edit an existing connection |\n\n## Assets\n\nAssets represent data sources or destinations in Airflow. They can be associated with DAGs to create data-aware scheduling.\n\n### Asset Commands\n\n| Command | Purpose |\n|---------|---------|\n| `assets list` | List all assets |\n| `assets details` | Show asset details |\n| `assets materialze` | Materialize an asset |\n\n### Asset Details Parameters\n\n| Parameter | Description |\n|-----------|-------------|\n| `ASSET_ALIAS` | Alias name for the asset |\n| `ASSET_NAME` | Name of the asset |\n| `ASSET_URI` | URI identifying the asset |\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n## Configuration Changes in Airflow 3.0\n\nAirflow 3.0 introduces several configuration changes that affect default behavior.\n\n### Default Behavior Changes\n\n| Configuration | Old Default | New Default |\n|---------------|-------------|-------------|\n| `catchup_by_default` | `True` | `False` |\n| `create_cron_data_intervals` | `True` | `False` |\n| `create_delta_data_intervals` | `True` | `False` |\n\nSource: [airflow-core/src/airflow/cli/commands/config_command.py](airflow-core/src/airflow/cli/commands/config_command.py)\n\n### Configuration Renames\n\nSeveral scheduler configurations have been renamed:\n\n| Old Name | New Name |\n|----------|----------|\n| `scheduler.processor_poll_interval` | `scheduler.scheduler_idle_sleep_time` |\n| `scheduler.deactivate_stale_dags_interval` | `scheduler.parsing_cleanup_interval` |\n| `scheduler.statsd_on` | `metrics.statsd_on` |\n| `scheduler.max_threads` | `dag_processor.parsing_processes` |\n\nSource: [airflow-core/src/airflow/cli/commands/config_command.py](airflow-core/src/airflow/cli/commands/config_command.py)\n\n### Catchup Behavior Change\n\nIn Airflow 3.0, DAGs without explicit `catchup` parameter definition will not catch up by default. This represents a change from Airflow 2.x behavior. Organizations relying on catchup behavior should set `catchup = True` in their DAG definitions or configure:\n\n```ini\n[scheduler]\ncatchup_by_default = True\n```\n\n## Providers\n\nAirflow Providers extend the core functionality by integrating with external services and systems.\n\n### Provider Information Commands\n\n| Command | Purpose |\n|---------|---------|\n| `providers list` | List all installed providers |\n| `providers details` | Show provider details |\n| `providers hooks` | List registered provider hooks |\n| `providers triggers` | List registered provider triggers |\n| `providers executors` | Get information about executors |\n| `providers secrets` | Get information about secrets backends |\n| `providers connections` | Get connection information |\n| `providers notifications` | Get notification information |\n| `providers extra-links` | List extra links from providers |\n| `providers widgets` | List connection form widgets |\n| `providers behaviors` | Get connection types with custom behaviors |\n| `providers logging` | Get task logging handlers |\n| `providers auth-managers` | Get auth managers information |\n| `providers configs` | Get provider configuration |\n| `providers lazy-loaded` | Check lazy loading status |\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n## Dependency Management\n\n### Dependency Tree\n\nAirflow's dependency tree defines the module structure and relationships between packages. This information is generated and maintained in the repository for dependency analysis.\n\n| File | Purpose |\n|------|---------|\n| `dep_tree.txt` | Complete dependency tree of Airflow |\n| `dependency_depth.json` | Dependency depth analysis |\n\nGenerated using:\n```bash\nuv tree --no-dedupe > /opt/airflow/generated/dep_tree.txt\n```\n\nSource: [generated/README.md](generated/README.md)\n\n## Workflow Architecture\n\n```mermaid\ngraph TD\n subgraph \"Authoring\"\n A[Define DAG] --> B[Define Tasks]\n B --> C[Set Dependencies]\n end\n \n subgraph \"Scheduling\"\n D[Scheduler] --> E{Parse DAGs}\n E --> F[DAG Run Created]\n F --> G[Task Instances Queued]\n end\n \n subgraph \"Execution\"\n G --> H[Executor]\n H --> I[Worker]\n I --> J[Task Execution]\n end\n \n subgraph \"Monitoring\"\n J --> K[Update State]\n K --> L[UI/Webserver]\n L --> M[Logs & Metrics]\n end\n \n G -->|Async Operations| N[Async Commands]\n N --> O[Cloud Composer Environments]\n```\n\n## Security Features\n\n### Fernet Key Rotation\n\nAirflow supports rotating Fernet encryption keys to maintain security of stored credentials and variables:\n\n```bash\nairflow rotate-fernet-key\n```\n\nThis command rotates all encrypted connection credentials and variables.\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n### Configuration Reference\n\nFor secure connections, refer to the official documentation:\nhttps://airflow.apache.org/docs/apache-airflow/stable/howto/secure-connections.html\n\n## Additional CLI Commands\n\n### Info Command\n\nProvides system and environment information:\n\n```bash\nairflow info [--anonymize] [--file-io] [--output OUTPUT] [--verbose]\n```\n\n### Standalone Mode\n\nRuns a complete Airflow instance for testing or development:\n\n```bash\nairflow standalone\n```\n\n### Cheat Sheet\n\nDisplays a quick reference for common Airflow commands:\n\n```bash\nairflow cheat-sheet [--verbose]\n```\n\n### Plugins Command\n\nDump information about loaded plugins:\n\n```bash\nairflow plugins [--output OUTPUT] [--verbose]\n```\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n## Teams (RBAC)\n\nAirflow supports team-based access control with the following operations:\n\n### Team Commands\n\n| Command | Purpose |\n|---------|---------|\n| `teams create` | Create a new team |\n| `teams delete` | Delete a team |\n\n### Team Creation Requirements\n\n- Team names must be 3-50 characters long\n- Only alphanumeric characters, hyphens, and underscores are allowed\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n---\n\n\n\n## Architecture Overview\n\n### 相关页面\n\n相关主题：[Scheduler and Executor Architecture](#scheduler-executor), [REST API](#rest-api)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [airflow-core/docs/img/diagram_basic_airflow_architecture.py](https://github.com/apache/airflow/blob/main/airflow-core/docs/img/diagram_basic_airflow_architecture.py)\n- [airflow-core/docs/img/diagram_distributed_airflow_architecture.py](https://github.com/apache/airflow/blob/main/airflow-core/docs/img/diagram_distributed_airflow_architecture.py)\n- [airflow-core/docs/img/diagram_auth_manager_airflow_architecture.py](https://github.com/apache/airflow/blob/main/airflow-core/docs/img/diagram_auth_manager_airflow_architecture.py)\n- [airflow-core/src/airflow/dag_processing/manager.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/dag_processing/manager.py)\n- [airflow-core/docs/core-concepts/overview.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/core-concepts/overview.rst)\n\n\n# Architecture Overview\n\nApache Airflow is an open-source workflow orchestration platform designed to programmatically author, schedule, and monitor complex data pipelines. The architecture is built around a distributed, scalable design that separates concerns between scheduling, execution, and monitoring.\n\n## Core Architectural Components\n\nAirflow's architecture consists of several key components that work together to manage workflow execution across distributed environments.\n\n### Component Overview\n\n| Component | Purpose | Key Files |\n|-----------|---------|-----------|\n| **Scheduler** | Triggers scheduled tasks and submits tasks to executors | `airflow-core/src/airflow/dag_processing/manager.py` |\n| **Executor** | Executes tasks distributed across workers | Configured via `airflow.cfg` |\n| **Web Server** | Provides UI for monitoring and management | `airflow/ui/` |\n| **Database** | Stores DAGs, connections, variables, and execution history | Configured via `airflow.cfg` |\n| **DAG Processor** | Parses and processes DAG files | `airflow-core/src/airflow/dag_processing/manager.py` |\n\n资料来源：[airflow-core/docs/core-concepts/overview.rst]()\n\n## Basic Architecture\n\nThe basic Airflow architecture runs all components on a single machine, suitable for development, testing, and small-scale deployments.\n\n```mermaid\ngraph TB\n subgraph \"Airflow Core\"\n WS[Web Server] <--> DB[(Metadata Database)]\n SCH[Scheduler] <--> DB\n SCH <--> EX[Executor]\n EX <--> DB\n DP[DAG Processor] <--> DB\n end\n \n subgraph \"DAG Storage\"\n DAG[DAG Files] --> DP\n end\n \n WS -->|UI Access| Users\n SCH -->|Schedule| DAG\n```\n\nThis single-node deployment includes all core components running together, with the scheduler handling task scheduling and the web server providing the user interface.\n\n资料来源：[airflow-core/docs/img/diagram_basic_airflow_architecture.py]()\n\n## Distributed Architecture\n\nFor production environments, Airflow supports a distributed architecture where components can scale independently.\n\n```mermaid\ngraph TB\n subgraph \"Web Tier\"\n WS1[Web Server 1]\n WS2[Web Server 2]\n LB[Load Balancer]\n end\n \n subgraph \"Scheduler Tier\"\n SCH1[Scheduler 1]\n SCH2[Scheduler 2]\n end\n \n subgraph \"Worker Tier\"\n W1[Worker 1]\n W2[Worker 2]\n W3[Worker N]\n end\n \n subgraph \"Metadata\"\n DB[(PostgreSQL/MySQL)]\n REDIS[(Redis/Message Broker)]\n end\n \n LB --> WS1\n LB --> WS2\n WS1 <--> DB\n WS2 <--> DB\n SCH1 <--> DB\n SCH2 <--> DB\n SCH1 --> REDIS\n SCH2 --> REDIS\n REDIS --> W1\n REDIS --> W2\n REDIS --> W3\n```\n\n### Scalability Features\n\nThe distributed architecture provides:\n\n- **Horizontal Scaling**: Multiple schedulers and web servers can run in parallel\n- **Worker Flexibility**: Workers can be added or removed based on workload\n- **High Availability**: No single point of failure for critical components\n- **Isolation**: DAG processing is separated from execution\n\n资料来源：[airflow-core/docs/img/diagram_distributed_airflow_architecture.py]()\n\n## DAG Processing Architecture\n\nThe DAG Processor is responsible for reading, parsing, and validating DAG files before the Scheduler can schedule their tasks.\n\n### Processing Pipeline\n\n```mermaid\ngraph LR\n A[DAG Files] -->|Read| B[DAG Processor]\n B -->|Parse| C[DAG Bag]\n C -->|Validate| D[Valid DAGs]\n D -->|Sync| E[(Metadata DB)]\n B -->|Log| F[Processor Logs]\n```\n\n### Key Processing Manager\n\nThe `DagFileProcessorManager` handles:\n\n1. **File Discovery**: Scanning DAG directories for Python files\n2. **Parsing**: Converting Python DAG definitions into Airflow DAG objects\n3. **Serialization**: Storing parsed DAGs in the database\n4. **Callback Handling**: Processing DAG-level callbacks\n\n```python\n# Simplified from airflow-core/src/airflow/dag_processing/manager.py\nclass DagFileProcessorManager:\n def process_file(self, filepath):\n \"\"\"Process a single DAG file and return list of DAGs.\"\"\"\n dagbag = DagBag(dag_folder=filepath)\n for dag in dagbag.dags.values():\n dag.sync_to_db()\n return dagbag.dags\n```\n\n资料来源：[airflow-core/src/airflow/dag_processing/manager.py]()\n\n## Authentication and Authorization Architecture\n\nAirflow supports pluggable authentication through the Auth Manager interface, allowing integration with various authentication backends.\n\n```mermaid\ngraph TB\n U[User] -->|Auth Request| AM[Auth Manager]\n AM -->|User Lookup| DB[(Metadata DB)]\n AM -->|Backend Check| BE[External Backend OIDC/SAML/LDAP]\n BE -->|Validation| AM\n AM -->|Permissions| PERMS[Permission Set]\n PERMS -->|Grant Access| RES[Resources]\n```\n\n### Auth Manager Components\n\n| Component | Responsibility |\n|-----------|----------------|\n| `AuthManager` | Core interface for authentication |\n| `FastAPIAuthManager` | Default implementation for Airflow 3.0+ |\n| `Backends` | External identity providers |\n\nThe auth manager architecture enables:\n\n- Integration with enterprise identity providers\n- Role-based access control (RBAC)\n- Fine-grained permissions on DAGs and tasks\n\n资料来源：[airflow-core/docs/img/diagram_auth_manager_airflow_architecture.py]()\n\n## Configuration Management\n\nAirflow 3.0 introduced significant configuration changes from Airflow 2.x:\n\n### Configuration Changes Summary\n\n| Old Parameter | New Parameter | Section |\n|---------------|---------------|---------|\n| `processor_poll_interval` | `scheduler_idle_sleep_time` | scheduler |\n| `deactivate_stale_dags_interval` | `parsing_cleanup_interval` | scheduler |\n| `statsd_on` | `statsd_on` | metrics |\n| `max_threads` | `parsing_processes` | dag_processor |\n| `create_cron_data_intervals` | unchanged | scheduler |\n| `create_delta_data_intervals` | unchanged | scheduler |\n\n### Default Behavior Changes\n\nIn Airflow 3.0, the default for `catchup_by_default` is `False`, meaning DAGs without explicit catchup configuration will not backfill past runs.\n\n资料来源：[airflow-core/src/airflow/cli/commands/config_command.py]()\n\n## Executor Architecture\n\nAirflow supports multiple executor types for different deployment scenarios:\n\n| Executor | Use Case | Scalability |\n|----------|----------|-------------|\n| **LocalExecutor** | Single machine, development | Limited |\n| **SequentialExecutor** | Debugging, minimal resources | None |\n| **CeleryExecutor** | Production, distributed | High |\n| **KubernetesExecutor** | Containerized environments | Very High |\n| **RayExecutor** | Ray cluster integration | High |\n\n### Executor Selection\n\nExecutors are configured in `airflow.cfg`:\n\n```ini\n[core]\nexecutor = KubernetesExecutor\n```\n\n资料来源：[airflow-core/docs/core-concepts/overview.rst]()\n\n## CLI and Command Architecture\n\nThe Airflow CLI provides a comprehensive command-line interface for managing Airflow components:\n\n### Command Structure\n\n```\nairflow\n├── config # View configuration\n├── connections # Manage connections\n├── dags # DAG management\n├── db-manager # Database management\n├── info # System information\n├── plugins # Plugin dump\n├── providers # Provider information\n├── rotate-fernet-key # Credential rotation\n├── standalone # All-in-one mode\n└── version # Version display\n```\n\n### Key CLI Commands\n\n| Command | Purpose |\n|---------|---------|\n| `airflow dags backfill` | Run historical DAG executions |\n| `airflow dags list-runs` | List DAG run instances |\n| `airflow connections list` | Show configured connections |\n| `airflow providers list` | Display loaded providers |\n| `airflow rotate-fernet-key` | Rotate encryption keys |\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py]()\n\n## Provider Architecture\n\nProviders extend Airflow's capabilities by integrating with external systems:\n\n### Provider Categories\n\n- **Cloud Providers**: Google Cloud, AWS, Azure\n- **Service Integrations**: HTTP, SSH, GraphQL\n- **Database Connectors**: PostgreSQL, MySQL, Snowflake\n- **Data Processing**: Spark, Databricks, dbt\n\n### Provider Communication\n\n```mermaid\ngraph LR\n A[Airflow Task] -->|Hook| B[Provider Hook]\n B -->|API| C[External Service]\n C -->|Response| B\n B -->|Result| A\n```\n\nProviders are discovered and managed through the `airflow providers` CLI commands.\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py]()\n\n## Installation Modes\n\n### Docker Installation\n\nAirflow provides official Docker images with multiple variants:\n\n| Image Type | Description | Size |\n|------------|-------------|------|\n| `apache/airflow:latest` | Latest stable, default Python | ~1GB |\n| `apache/airflow:3.x.x` | Versioned release | ~1GB |\n| `apache/airflow:slim-latest` | Minimal installation | ~500MB |\n\n### Installation Methods\n\n```bash\n# Basic installation\npip install 'apache-airflow==3.2.0' \\\n --constraint \"https://raw.githubusercontent.com/apache/airflow/constraints-3.2.0/constraints-3.10.txt\"\n\n# With extras\npip install 'apache-airflow[postgres,google]==3.2.0' \\\n --constraint \"https://raw.githubusercontent.com/apache/airflow/constraints-3.2.0/constraints-3.10.txt\"\n```\n\n资料来源：[docker-stack-docs/README.md]()\n资料来源：[generated/PYPI_README.md]()\n\n## Default Connections\n\nAirflow ships with pre-configured default connections for common integrations:\n\n| Connection ID | Type | Purpose |\n|---------------|------|---------|\n| `google_cloud_default` | google_cloud_platform | GCP resources |\n| `fs_default` | fs | File system access |\n| `http_default` | http | HTTP endpoints |\n| `ftp_default` | ftp | FTP/SFTP transfers |\n| `hive_cli_default` | hive_cli | Hive CLI connections |\n| `hiveserver2_default` | hiveserver2 | HiveServer2 connections |\n\n资料来源：[airflow-core/src/airflow/utils/db.py]()\n\n## Development and Testing Architecture\n\nThe Breeze development environment provides an integrated development setup:\n\n### Breeze Features\n\n- Pre-configured Docker-based development environment\n- Multiple Python version support\n- Integration testing framework\n- Static code analysis tools\n- Documentation building capabilities\n\n### Development Commands\n\n```bash\n# Start development shell\nbreeze shell\n\n# Run tests\nbreeze test\n\n# Build documentation\nbreeze build-docs\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/developer_commands.py]()\n\n## Shared Distribution Architecture\n\nAirflow supports shared code distributions for cross-project functionality:\n\n### Configuration\n\n```toml\n[tool.airflow]\nshared_distributions = [\n \"apache-airflow-shared-timezones\",\n]\n```\n\nShared distributions are:\n\n1. Defined in `pyproject.toml` under `tool.airflow`\n2. Symlinked via `_shared` folder\n3. Automatically synchronized by pre-commit hooks\n\n资料来源：[shared/README.md]()\n\n## MyPy Type Checking Integration\n\nAirflow provides custom MyPy plugins for enhanced type checking:\n\n### Available Plugins\n\n| Plugin | Purpose |\n|--------|---------|\n| `airflow_mypy.plugins.decorators` | Type checking for Airflow decorators |\n| `airflow_mypy.plugins.outputs` | Type inference for XCom arguments |\n\n### Configuration\n\n```ini\n[mypy]\nplugins = airflow_mypy.plugins.decorators, airflow_mypy.plugins.outputs\n```\n\nOr in `pyproject.toml`:\n\n```toml\n[tool.mypy]\nplugins = [\"airflow_mypy.plugins.decorators\", \"airflow_mypy.plugins.outputs\"]\n```\n\n资料来源：[dev/mypy/README.md]()\n\n## Build and Release Architecture\n\n### SBOM (Software Bill of Materials)\n\nAirflow generates SBOMs for security and compliance tracking:\n\n- Dependency tree generation via `uv tree`\n- Dependency depth analysis\n- Version-specific SBOM files\n\n### Documentation Build\n\nThe documentation system includes:\n\n- Sphinx-based documentation generation\n- Pagefind search integration\n- Multi-version documentation support\n- Third-party inventory tracking\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/sbom_commands.py]()\n资料来源：[devel-common/src/sphinx_exts/pagefind_search/README.md]()\n\n## Summary\n\nApache Airflow's architecture is designed for scalability, reliability, and extensibility:\n\n- **Modular Design**: Components can be scaled independently\n- **Pluggable Executors**: Support for various execution backends\n- **Extensible Providers**: Integration with external systems\n- **Production-Ready**: High availability and monitoring capabilities\n- **Developer-Friendly**: Comprehensive tooling and documentation\n\nThe architecture supports deployments from single-machine development environments to large-scale, distributed production systems handling thousands of workflows.\n\n---\n\n\n\n## Scheduler and Executor Architecture\n\n### 相关页面\n\n相关主题：[Architecture Overview](#architecture-overview), [Kubernetes Deployment](#kubernetes-deployment)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [airflow-core/src/airflow/jobs/scheduler_job_runner.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/jobs/scheduler_job_runner.py)\n- [airflow-core/src/airflow/executors/base_executor.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/executors/base_executor.py)\n- [airflow-core/src/airflow/executors/local_executor.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/executors/local_executor.py)\n- [airflow-core/src/airflow/executors/executor_loader.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/executors/executor_loader.py)\n- [airflow-core/src/airflow/dag_processing/collection.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/dag_processing/collection.py)\n- [airflow-core/src/airflow/timetables/base.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/timetables/base.py)\n- [airflow-core/docs/administration-and-deployment/scheduler.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/administration-and-deployment/scheduler.rst)\n\n\n# Scheduler and Executor Architecture\n\nApache Airflow's scheduling and execution system is a distributed architecture that coordinates the parsing of Directed Acyclic Graphs (DAGs), scheduling of task instances, and execution of tasks across worker nodes. This document provides a comprehensive overview of how the Scheduler and Executors interact to process and execute workflows.\n\n## Overview\n\nThe Scheduler and Executor architecture in Apache Airflow consists of several interconnected components that work together to transform DAG definitions into executed tasks. The system separates concerns between **scheduling decisions** (when to run tasks based on dependencies and timetable data) and **execution** (how and where tasks actually run).\n\n```mermaid\ngraph TD\n A[DAG Files] --> B[DAG Processor]\n B --> C[DAG Parsing]\n C --> D[Serialized DAGs]\n D --> E[Metadata Database]\n E --> F[Scheduler]\n F --> G[Executor]\n G --> H[Workers]\n H --> I[Task Execution]\n I --> E\n```\n\n## Scheduler Architecture\n\n### Scheduler Process\n\nThe Scheduler is a long-running daemon process that continuously monitors DAGs and schedules task instances for execution. It is configured through CLI commands defined in the system.\n\n**CLI Configuration:**\n\nThe scheduler command is defined in `cli_config.py` and accepts multiple configuration parameters for controlling its behavior.\n\n| Parameter | Purpose | Default |\n|-----------|---------|---------|\n| `--num-runs` | Number of scheduler runs before exiting | -1 (infinite) |\n| `--only-idle` | Only schedule DAGs with idle tasks | False |\n| `--pid` | PID file location | None |\n| `--daemon` | Run as daemon process | False |\n| `--stdout` | stdout log file | None |\n| `--stderr` | stderr log file | None |\n| `--log-file` | Log file path | None |\n| `--skip-serve-logs` | Skip serving logs | False |\n| `--dev` | Development mode | False |\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n\n### Job Lifecycle\n\nThe Scheduler creates and manages Jobs that represent its operational cycles. Each scheduler run follows a specific lifecycle that involves database interactions.\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI Component\n participant JobRunner as JobRunner\n participant DB as Database\n participant TaskRunner as TaskRunner\n\n activate CLI\n CLI->>JobRunner: Create Job\n activate JobRunner\n JobRunner->>DB: Create Job Record\n activate DB\n DB-->>JobRunner: Job Created\n JobRunner->>DB: Create Session\n DB->>JobRunner: Session\n deactivate DB\n JobRunner->>CLI: Job Created\n deactivate JobRunner\n CLI->>JobRunner: Execute Job\n activate JobRunner\n par\n JobRunner->>DB: Schedule Tasks\n activate DB\n DB-->>JobRunner: Scheduled Tasks\n deactivate DB\n and\n JobRunner->>JobRunner: Process DAG Files\n end\n JobRunner->>DB: Perform Heartbeat\n activate DB\n DB->>JobRunner: Heartbeat Response\n JobRunner->>JobRunner: Heartbeat Callback\n DB-->>JobRunner: Close Session\n deactivate DB\n JobRunner->>CLI: Job Completed\n deactivate JobRunner\n deactivate CLI\n```\n\n资料来源：[airflow-core/src/airflow/jobs/JOB_LIFECYCLE.md](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/jobs/JOB_LIFECYCLE.md)\n\n### Scheduler Responsibilities\n\nThe Scheduler performs the following key operations:\n\n1. **DAG Parsing**: Reads DAG files and parses them into Python objects\n2. **Task Scheduling**: Determines which tasks are ready to execute based on dependencies\n3. **DagRun Creation**: Creates DagRun records for scheduled DAG runs\n4. **TaskInstance Creation**: Creates TaskInstance records for tasks to be executed\n5. **Heartbeating**: Maintains its presence and reports health to the database\n\n## Executor Architecture\n\nExecutors are responsible for the actual execution of tasks. Airflow supports multiple executor types, each with different deployment characteristics.\n\n### Executor Types\n\n| Executor | Description | Use Case |\n|----------|-------------|----------|\n| SequentialExecutor | Executes tasks sequentially in the same process | Development/Debugging |\n| LocalExecutor | Executes tasks in parallel processes on a single machine | Single-node deployments |\n| CeleryExecutor | Distributes tasks across multiple machines using Celery | Distributed production deployments |\n| KubernetesExecutor | Creates pods per task in Kubernetes | Kubernetes-native deployments |\n| LocalKubernetesExecutor | Hybrid of Local and Kubernetes executors | Testing/minimal Kubernetes |\n\n### Executor Loader\n\nThe `ExecutorLoader` class is responsible for loading and configuring executors based on Airflow configuration. It supports both simple executor names and complex module paths with optional aliases.\n\n```mermaid\ngraph TD\n A[Executor Config] --> B{ExecutorLoader}\n B --> C{Check Format}\n C -->|Simple Name| D[Load Core Executor]\n C -->|Team:Executor| E[Parse Team Config]\n E --> F[Alias:Module/Name]\n F --> G[Resolve Module Path]\n D --> H[Return ExecutorName]\n G --> H\n```\n\n**Executor Configuration Parsing:**\n\nThe loader parses executor configurations in multiple formats:\n\n- **Simple name**: `SequentialExecutor`, `LocalExecutor`\n- **Module path**: `airflow.executors.local_executor.LocalExecutor`\n- **With alias**: `MyAlias:LocalExecutor`\n- **Team-based**: `team_name:executor_name` or `team_name:alias:executor_name`\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/executors/executor_loader.py)\n\n### Base Executor Interface\n\nAll executors inherit from `BaseExecutor` which defines the standard interface:\n\n| Method | Purpose |\n|--------|---------|\n| `execute_async()` | Execute a single task |\n| `sync()` | Sync state with metadata database |\n| `end()` | Cleanup executor resources |\n| `terminate()` | Force terminate all running tasks |\n| `try_adopt_task_instances()` | Adopt orphaned task instances |\n| `render_slots()` | Render available executor slots |\n\n### Local Executor\n\nThe Local Executor executes tasks in parallel worker processes on a single machine, providing a balance between simplicity and parallelism.\n\n**Key Features:**\n- Configurable parallelism (number of parallel workers)\n- Supports task-level parallelism within a single node\n- Inherits configuration from core executor registry\n- Can be configured with aliases for multi-team deployments\n\n```python\n# Example: Loading LocalExecutor with team configuration\nexecutor_names_per_team.append(\n ExecutorName(\n alias=None, \n module_path=cls.executors[module_or_name], \n team_name=team_name\n )\n)\n```\n\n资料来源：[airflow-core/src/airflow/executors/local_executor.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/executors/local_executor.py)\n\n## Task Scheduling Flow\n\nThe complete task scheduling flow involves multiple stages from DAG definition to task execution:\n\n```mermaid\ngraph LR\n A[DAG File] --> B[DAG Processor]\n B --> C[Parse DAG]\n C --> D[Serialize DAG]\n D --> E[Store in DB]\n E --> F[Scheduler]\n F --> G[Evaluate Timetable]\n G --> H{Check Dependencies}\n H -->|Met| I[Create TaskInstance]\n H -->|Not Met| J[Skip]\n I --> K[Queue Task]\n K --> L[Executor]\n L --> M[Worker]\n M --> N[Execute Task]\n N --> O[Update State]\n O --> P[Record XCom]\n```\n\n### DAG Processing\n\nThe DAG collection module handles parsing and synchronization of DAGs:\n\n| Component | Responsibility |\n|-----------|----------------|\n| `DagBag` | Collection of parsed DAGs from file system |\n| `DagFileProcessor` | Parses individual DAG files |\n| `DagFileProcessorAgent` | Manages multiple DAG processors |\n| `SerializedDagModel` | Database representation of serialized DAGs |\n\n资料来源：[airflow-core/src/airflow/dag_processing/collection.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/dag_processing/collection.py)\n\n### Timetables\n\nTimetables determine when DAGs should be triggered. They provide schedule information and calculate logical dates for DAG runs.\n\n**Key Timetable Methods:**\n\n| Method | Purpose |\n|--------|---------|\n| `describe()` | Human-readable schedule description |\n| `infer_data_interval()` | Infer run boundaries from logical date |\n| `get_next_runtime()` | Calculate next scheduled run time |\n| `validate()` | Validate timetable configuration |\n\n资料来源：[airflow-core/src/airflow/timetables/base.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/timetables/base.py)\n\n## Task State Management\n\nTask instances maintain state throughout their lifecycle. The `TaskState` class provides methods for managing task state via supervisor communications.\n\n```mermaid\ngraph TD\n A[Task Starts] --> B[Scheduled]\n B --> C[Queued]\n C --> D[Started]\n D --> E{Ran Successfully?}\n E -->|Yes| F[Success]\n E -->|No| G{Retryable?}\n G -->|Yes| H[Up for Retry]\n H --> C\n G -->|No| I[Failed]\n F --> J[Emit XCom]\n I --> J\n```\n\n### TaskState API\n\nThe TaskState class provides key-value storage for task state information:\n\n| Method | Description |\n|--------|-------------|\n| `get(key)` | Retrieve task state value by key |\n| `set(key, value)` | Store task state value |\n| `delete(key)` | Delete a specific key |\n| `clear(all_map_indices)` | Clear all keys or map-index specific keys |\n\n资料来源：[task-sdk/src/airflow/sdk/execution_time/context.py](https://github.com/apache/airflow/blob/main/task-sdk/src/airflow/sdk/execution_time/context.py)\n\n## DAG Runs and Task Instances\n\n### DagRun States\n\n| State | Description |\n|-------|-------------|\n| `queued` | Initial state when DAG run is created |\n| `running` | DAG run is currently executing |\n| `success` | All tasks in the DAG completed successfully |\n| `failed` | DAG run failed due to task or system failure |\n\n### Run Types\n\n| Type | Trigger Mechanism |\n|------|-------------------|\n| `scheduled` | Triggered automatically by timetable |\n| `manual` | Triggered by user action via CLI or UI |\n| `dataset` | Triggered by dataset dependency |\n| `backfill` | Triggered by explicit backfill command |\n\n资料来源：[airflow-core/src/airflow/ui/src/pages/DagRuns.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/DagRuns.tsx)\n\n## CLI Commands for Scheduler and Executor\n\n### Scheduler Commands\n\n```bash\n# Start the scheduler\nairflow scheduler\n\n# Start with specific number of runs\nairflow scheduler --num-runs 10\n\n# Run in daemon mode\nairflow scheduler --daemon --log-file /path/to/scheduler.log\n\n# Development mode\nairflow scheduler --dev\n```\n\n### DAG Processing Commands\n\n```bash\n# Trigger DAG run\nairflow dags trigger \n\n# Test task\nairflow tasks test \n\n# Clear task instances\nairflow tasks clear \n\n# Render task template\nairflow tasks render \n```\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n\n## Configuration\n\n### Executor Configuration\n\nExecutors are configured in `airflow.cfg` or through environment variables:\n\n```ini\n[core]\nexecutor = LocalExecutor\n\n[celery]\ncelery_executor_config = ...\n```\n\n### Scheduler Configuration\n\n| Configuration | Description | Default |\n|---------------|--------------|---------|\n| `scheduler_num_runs` | Number of scheduler runs | -1 (infinite) |\n| `scheduler_idle_sleep_time` | Seconds between scheduler loops | 1 |\n| `num_runs` | Alternative parameter for number of runs | -1 |\n| `only_idle` | Only schedule idle DAGs | False |\n\n## Signal Handling\n\nThe scheduler supports the following signals for operational control:\n\n| Signal | Action |\n|--------|--------|\n| `SIGUSR2` | Dump a snapshot of task state being tracked by the executor |\n\nExample usage:\n```bash\npkill -f -USR2 \"airflow scheduler\"\n```\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n\n## Related Components\n\n### Triggerer\n\nThe Triggerer is a separate daemon that manages lightweight asynchronous triggers for tasks that need to wait for external conditions:\n\n```bash\nairflow triggerer --capacity 1000 --queues queue1,queue2\n```\n\n| Parameter | Purpose |\n|-----------|---------|\n| `--capacity` | Maximum concurrent triggers |\n| `--queues` | Queues to consume from |\n| `--pid` | PID file location |\n| `--daemon` | Run as daemon |\n\n### DAG Processor\n\nThe DAG Processor parses and validates DAG files before they are scheduled:\n\n```bash\nairflow dag-processor --bundle-name --num-runs 5\n```\n\n## Summary\n\nThe Scheduler and Executor Architecture in Apache Airflow provides a robust, scalable system for orchestrating complex workflows. Key architectural principles include:\n\n1. **Separation of Concerns**: Scheduler handles scheduling decisions; Executors handle task execution\n2. **Pluggable Executors**: Multiple executor types support different deployment scenarios\n3. **Database-Driven State**: All state is persisted in the metadata database for durability\n4. **Continuous Loop**: Scheduler runs continuously, periodically evaluating DAGs and scheduling tasks\n5. **Team-Based Execution**: Modern Airflow supports team-based executor configuration with aliases\n\n---\n\n\n\n## REST API\n\n### 相关页面\n\n相关主题：[User Interface](#user-interface), [Architecture Overview](#architecture-overview)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [airflow-core/src/airflow/api_fastapi/core_api/app.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/app.py)\n- [airflow-core/src/airflow/api_fastapi/core_api/routes/ui/dag_runs.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/routes/ui/dag_runs.py)\n- [airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py)\n- [airflow-core/src/airflow/api_fastapi/auth/managers/simple/simple_auth_manager.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/auth/managers/simple/simple_auth_manager.py)\n- [airflow-core/src/airflow/api_fastapi/execution_api/app.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/execution_api/app.py)\n- [airflow-core/docs/stable-rest-api-ref.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/stable-rest-api-ref.rst)\n\n\n# REST API\n\nApache Airflow provides a comprehensive REST API for programmatic interaction with the workflow automation platform. The API is built using FastAPI and enables external systems and applications to manage DAGs, trigger executions, monitor workflows, and interact with task instances.\n\n## Architecture Overview\n\nApache Airflow's REST API is architected as a multi-layer FastAPI application that separates concerns between the core API and the execution API.\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n A[External Clients]\n B[CLI Tools]\n C[UI Dashboard]\n end\n \n subgraph \"REST API Layer\"\n D[Core API /api/v1]\n E[Execution API /execution]\n end\n \n subgraph \"Service Layer\"\n F[DAG Management Service]\n G[Task Execution Service]\n H[Configuration Service]\n end\n \n subgraph \"Data Layer\"\n I[Airflow Database]\n J[Metadata DB]\n end\n \n A --> D\n B --> D\n C --> D\n C --> E\n D --> F\n D --> H\n E --> G\n F --> I\n G --> I\n H --> J\n```\n\n### Core API (`/api/v1`)\n\nThe Core API provides the primary interface for DAG management, monitoring, and administrative operations. It handles:\n\n- DAG run creation and management\n- Task instance operations\n- Connection and variable management\n- User and permission management\n- Plugin and provider information\n\n资料来源：[airflow-core/src/airflow/api_fastapi/core_api/app.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/app.py)\n\n### Execution API (`/execution`)\n\nThe Execution API is designed for lightweight, high-performance task execution operations. It provides endpoints for:\n\n- Task state updates\n- XCom value operations\n- Task heartbeat signals\n- Execution context retrieval\n\n资料来源：[airflow-core/src/airflow/api_fastapi/execution_api/app.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/execution_api/app.py)\n\n## Authentication and Authorization\n\nAirflow's REST API supports multiple authentication mechanisms through a pluggable auth manager architecture.\n\n### Authentication Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant API as REST API\n participant Auth as Auth Manager\n participant DB as Database\n \n Client->>API: Request with credentials\n API->>Auth: Validate credentials\n Auth->>DB: Check user/permissions\n DB-->>Auth: User info + permissions\n Auth-->>API: Auth result\n alt Authentication Success\n API-->>Client: 200 + Response data\n else Authentication Failure\n API-->>Client: 401/403 + Error\n end\n```\n\n### Simple Auth Manager\n\nFor development and testing environments, Airflow provides a Simple Auth Manager that supports basic authentication mechanisms.\n\n资料来源：[airflow-core/src/airflow/api_fastapi/auth/managers/simple/simple_auth_manager.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/auth/managers/simple/simple_auth_manager.py)\n\n### Access Control\n\nThe REST API implements granular access control through DAG-level permissions:\n\n| Permission | Description |\n|------------|-------------|\n| `GET` | Read access to DAG information |\n| `POST` | Create/modify DAG resources |\n| `DELETE` | Remove DAG resources |\n| `EDIT` | Modify DAG configuration |\n\nAccess control is enforced through dependency injection on route handlers:\n\n```python\ndependencies=[\n Depends(requires_access_dag(\"GET\")),\n Depends(requires_access_dag(\"GET\", DagAccessEntity.DEPENDENCIES)),\n Depends(requires_access_dag(\"GET\", DagAccessEntity.TASK_INSTANCE)),\n]\n```\n\n资料来源：[airflow-core/src/airflow/api_fastapi/core_api/routes/ui/structure.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/routes/ui/structure.py)\n\n## DAG Runs API\n\nDAG Runs represent individual executions of a Directed Acyclic Graph (DAG). The DAG Runs API provides comprehensive endpoints for managing workflow executions.\n\n### DAG Run Data Model\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `dag_id` | string | Unique identifier for the DAG |\n| `run_id` | string | Unique identifier for this execution |\n| `state` | enum | Current state (queued, running, success, failed) |\n| `conf` | object | Configuration passed to the DAG |\n| `logical_date` | datetime | Scheduled execution time |\n| `start_date` | datetime | Actual execution start time |\n| `end_date` | datetime | Execution completion time |\n| `external_trigger` | boolean | Whether triggered externally |\n\n资料来源：[airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py)\n\n### Key Endpoints\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/dags/{dag_id}/dagRuns` | GET | List DAG runs with filtering |\n| `/dags/{dag_id}/dagRuns` | POST | Trigger a new DAG run |\n| `/dags/{dag_id}/dagRuns/{run_id}` | GET | Get specific DAG run details |\n| `/dags/{dag_id}/dagRuns/{run_id}` | DELETE | Delete a DAG run |\n| `/dags/{dag_id}/dagRuns/{run_id}/clear` | POST | Clear task instances |\n| `/dags/{dag_id}/dagRuns/{run_id}/confirm` | POST | Confirm a DAG run |\n| `/dags/{dag_id}/dagRuns/{run_id}/update` | PATCH | Update DAG run state |\n\n资料来源：[airflow-core/src/airflow/api_fastapi/core_api/routes/ui/dag_runs.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/routes/ui/dag_runs.py)\n\n### Query Parameters\n\nThe DAG Runs list endpoint supports extensive filtering:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `limit` | integer | Maximum number of results (default: 100) |\n| `offset` | integer | Pagination offset |\n| `order_by` | string | Sort field |\n| `state` | enum | Filter by state |\n| `dag_run_id` | string | Filter by run ID |\n| `logical_date` | datetime | Filter by logical date |\n| `start_date` | datetime | Filter by start date |\n| `end_date` | datetime | Filter by end date |\n| `include_upstream` | boolean | Include upstream dependencies |\n| `include_downstream` | boolean | Include downstream tasks |\n| `depth` | integer | Tree depth limit |\n| `root` | string | Root node filter |\n| `external_dependencies` | boolean | Include external dependencies |\n\n## API Structure and Organization\n\n### Route Organization\n\nThe REST API routes are organized by functional area within the FastAPI application structure:\n\n```mermaid\ngraph LR\n subgraph \"/api/v1\"\n A[UI Routes]\n B[DAG Routes]\n C[Task Routes]\n D[Connection Routes]\n E[Variable Routes]\n F[Plugin Routes]\n end\n \n subgraph \"/execution\"\n G[Task Execution]\n H[XCom Operations]\n end\n```\n\n### Response Models\n\nAll API endpoints return structured responses using Pydantic models. Responses include:\n\n- **Data**: The requested resource or operation result\n- **Meta**: Pagination information and metadata\n- **Links**: HATEOAS-style navigation links\n\n### Error Handling\n\nThe API implements consistent error handling with structured error responses:\n\n| Status Code | Category |\n|-------------|----------|\n| 400 | Bad Request - Invalid parameters |\n| 401 | Unauthorized - Authentication required |\n| 403 | Forbidden - Insufficient permissions |\n| 404 | Not Found - Resource doesn't exist |\n| 409 | Conflict - State conflict |\n| 500 | Internal Server Error |\n\n## Security Considerations\n\n### Session Management\n\nThe REST API integrates with Airflow's session management system. When authentication is enabled:\n\n1. Clients must authenticate to receive a session cookie\n2. Subsequent requests include the session cookie\n3. Sessions expire based on configuration settings\n\n### Role-Based Access Control (RBAC)\n\nThe API supports RBAC through integration with the auth manager:\n\n- **Admin**: Full access to all resources\n- **Op**: Access to DAG operations\n- **User**: Read access to DAGs, limited write access\n- **Viewer**: Read-only access\n\n## Configuration\n\n### Enabling the REST API\n\nThe REST API is enabled by default when Airflow is configured with a supported auth manager. Key configuration options:\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `auth_manager` | simple | Authentication backend |\n| `api_url` | - | Base URL for API endpoints |\n| `secret_key` | - | Session encryption key |\n\n### CORS Configuration\n\nCross-Origin Resource Sharing (CORS) can be configured to allow web clients to access the API:\n\n| Setting | Description |\n|---------|-------------|\n| `access_control_allow_origins` | Allowed origins |\n| `access_control_allow_methods` | Allowed HTTP methods |\n| `access_control_allow_headers` | Allowed headers |\n\n## API Versioning\n\nApache Airflow maintains API stability through versioning:\n\n- **Current Version**: `/api/v1`\n- **Version Prefix**: All endpoints are prefixed with the version\n- **Stability Guarantee**: Within a major version, breaking changes are avoided\n\n资料来源：[airflow-core/docs/stable-rest-api-ref.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/stable-rest-api-ref.rst)\n\n## Usage Examples\n\n### Triggering a DAG Run\n\n```bash\ncurl -X POST \"http://airflow-server:8080/api/v1/dags/my_dag/dagRuns\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\n \"dag_run_id\": \"manual_run_001\",\n \"logical_date\": \"2024-01-15T10:00:00Z\",\n \"conf\": {\"key\": \"value\"}\n }'\n```\n\n### Listing DAG Runs\n\n```bash\ncurl \"http://airflow-server:8080/api/v1/dags/my_dag/dagRuns?state=running&limit=10\" \\\n -H \"Authorization: Bearer \"\n```\n\n## See Also\n\n- [CLI Commands](cli-commands) - Alternative command-line interface\n- [Authentication](authentication) - Auth manager configuration\n- [DAG Runs](dag-runs) - DAG execution management\n- [Task Instances](task-instances) - Task operation API\n\n---\n\n\n\n## User Interface\n\n### 相关页面\n\n相关主题：[REST API](#rest-api), [Core Concepts](#core-concepts)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [airflow-core/src/airflow/ui/src/layouts/Details/Grid/Grid.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/layouts/Details/Grid/Grid.tsx)\n- [airflow-core/src/airflow/ui/src/layouts/Details/Graph/Graph.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/layouts/Details/Graph/Graph.tsx)\n- [airflow-core/src/airflow/ui/src/pages/Dashboard/Dashboard.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/Dashboard/Dashboard.tsx)\n- [airflow-core/src/airflow/ui/src/router.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/router.tsx)\n- [airflow-core/src/airflow/ui/package.json](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/package.json)\n- [airflow-core/docs/ui.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/ui.rst)\n- [airflow-core/src/airflow/ui/src/pages/DagRuns.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/DagRuns.tsx)\n- [airflow-core/src/airflow/ui/src/pages/Dag/Overview/Overview.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/Dag/Overview/Overview.tsx)\n- [airflow-core/src/airflow/ui/src/components/Clear/TaskInstance/ClearTaskInstanceConfirmationDialog.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/Clear/TaskInstance/ClearTaskInstanceConfirmationDialog.tsx)\n- [airflow-core/src/airflow/ui/src/pages/Connections/EditConnectionButton.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/Connections/EditConnectionButton.tsx)\n- [providers/edge3/src/airflow/providers/edge3/plugins/www/src/pages/WorkerPage.tsx](https://github.com/apache/airflow/blob/main/providers/edge3/src/airflow/providers/edge3/plugins/www/src/pages/WorkerPage.tsx)\n\n\n# User Interface\n\n## Overview\n\nApache Airflow's User Interface (UI) is a modern web-based frontend built with React and TypeScript that provides comprehensive workflow management, monitoring, and operational capabilities. The UI serves as the primary visual interface for data engineers and operators to interact with DAGs, task instances, DAG runs, connections, and various Airflow components.\n\nThe UI framework is organized under `airflow-core/src/airflow/ui/` and leverages contemporary React patterns including component composition, lazy loading, and type-safe TypeScript implementations. 资料来源：[airflow-core/docs/ui.rst:1-50]()\n\n## Architecture Overview\n\n### Technology Stack\n\n| Component | Technology | Purpose |\n|-----------|------------|---------|\n| Framework | React 18+ | UI component library |\n| Language | TypeScript | Type safety and better DX |\n| State Management | TanStack Query / React Query | Server state management |\n| Routing | React Router v7 | Client-side routing |\n| Styling | Chakra UI | Component library and styling |\n| Build Tool | Vite | Fast development and building |\n| Icons | Lucide React | Consistent iconography |\n\n资料来源：[airflow-core/src/airflow/ui/package.json:1-30]()\n\n### Directory Structure\n\n```\nairflow/\n├── ui/\n│ ├── src/\n│ │ ├── layouts/ # Page layout components\n│ │ │ └── Details/ # Detail view layouts\n│ │ │ ├── Grid/ # Grid view for DAGs\n│ │ │ └── Graph/ # Graph view for DAGs\n│ │ ├── pages/ # Page components\n│ │ │ ├── Dashboard/ # Dashboard pages\n│ │ │ ├── Dag/ # DAG detail pages\n│ │ │ ├── Run/ # Run detail pages\n│ │ │ └── Connections/ # Connection management\n│ │ ├── components/ # Reusable UI components\n│ │ │ ├── Clear/ # Clear action components\n│ │ │ └── TriggerDag/ # DAG triggering components\n│ │ └── router.tsx # Application routing configuration\n│ └── package.json\n└── providers/\n └── edge3/ # Edge provider with custom UI\n └── plugins/www/src/\n ├── pages/ # Edge-specific pages\n └── components/ # Edge-specific components\n```\n\n## Routing System\n\nThe UI uses React Router v7 for client-side navigation. Routes are defined in `router.tsx` and organized into two main categories: main application routes and detail views.\n\n```mermaid\ngraph TD\n A[\"/\"] --> B[\"Dashboard\"]\n A --> C[\"DAGs List\"]\n A --> D[\"DAG Detail\"]\n D --> D1[\"Grid View\"]\n D --> D2[\"Graph View\"]\n D --> D3[\"Overview\"]\n A --> E[\"DAG Runs\"]\n A --> F[\"Connections\"]\n A --> G[\"Providers\"]\n \n style A fill:#e1f5fe\n style D1 fill:#fff3e0\n style D2 fill:#e8f5e9\n style D3 fill:#f3e5f5\n```\n\n### Core Route Definitions\n\nThe router configuration maps URL paths to page components and handles lazy loading for improved performance:\n\n```typescript\n// Simplified route structure from router.tsx\nroutes = [\n { path: \"/\", component: Dashboard },\n { path: \"/dags\", component: DagList },\n { path: \"/dags/:dagId\", component: DagDetail },\n { path: \"/dags/:dagId/runs\", component: DagRuns },\n { path: \"/runs/:dagRunId\", component: RunDetail },\n { path: \"/connections\", component: Connections },\n]\n```\n\n## Page Components\n\n### Dashboard\n\nThe Dashboard (`Dashboard.tsx`) serves as the landing page, providing an overview of the Airflow environment. It typically includes:\n\n- DAG statistics and health metrics\n- Recent DAG runs\n- Failed or stuck tasks requiring attention\n- Quick access to frequently used DAGs\n\n资料来源：[airflow-core/src/airflow/ui/src/pages/Dashboard/Dashboard.tsx:1-50]()\n\n### DAG Detail Views\n\nDAG detail pages provide comprehensive views of individual DAGs with multiple visualization modes:\n\n#### Grid View\n\nThe Grid view (`Grid.tsx`) displays DAG tasks in a tabular format, allowing users to:\n\n- View task states across multiple DAG runs\n- Navigate through historical runs\n- Identify failed or running tasks quickly\n\n```mermaid\ngraph LR\n subgraph \"Grid View Structure\"\n H[\"Header: DAG Info\"]\n T[\"Task Grid Table\"]\n F[\"Filter/Sort Controls\"]\n end\n \n T --> T1[\"Task Columns\"]\n T --> T2[\"Run Rows\"]\n T1 --> Cell[\"State Cell\"]\n```\n\n资料来源：[airflow-core/src/airflow/ui/src/layouts/Details/Grid/Grid.tsx:1-80]()\n\n#### Graph View\n\nThe Graph view (`Graph.tsx`) renders the DAG structure visually as a directed acyclic graph, showing:\n\n- Task dependencies and relationships\n- Task execution states with color coding\n- Interactive node selection and navigation\n\n资料来源：[airflow-core/src/airflow/ui/src/layouts/Details/Graph/Graph.tsx:1-80]()\n\n#### Overview Page\n\nThe Overview page (`Overview.tsx`) provides a comprehensive dashboard for a specific DAG:\n\n```typescript\ninterface OverviewComponents {\n dagStats: DagStats; // DAG statistics\n failedRuns: FailedRuns; // Failed run alerts\n durationChart: DurationChart; // Duration visualization\n assetEvents: AssetEvents; // Asset event tracking\n dagDeadlines: DagDeadlines; // Deadline management\n failedLogs: FailedLogs; // Failed task logs\n}\n```\n\n资料来源：[airflow-core/src/airflow/ui/src/pages/Dag/Overview/Overview.tsx:1-100]()\n\n### DAG Runs Page\n\nThe DAG Runs page (`DagRuns.tsx`) displays a table of all DAG runs with the following columns:\n\n| Column | Description | Features |\n|--------|-------------|----------|\n| DAG Run ID | Unique identifier | Link to run detail |\n| State | Current state | Colored badge |\n| Run Type | Scheduled, manual, etc. | Icon + text |\n| Run After | Scheduled execution time | Time component |\n| Triggering User | User who triggered | Username display |\n| Start Date | Execution start time | Timestamp |\n| End Date | Execution end time | Timestamp |\n| Duration | Total execution time | Calculated field |\n| DAG Versions | Version tracking | Version badges |\n\n资料来源：[airflow-core/src/airflow/ui/src/pages/DagRuns.tsx:1-100]()\n\n## Dialog Components\n\nDialogs are used throughout the UI for focused interactions, confirmations, and detailed forms.\n\n### Confirmation Dialogs\n\nThe `ClearTaskInstanceConfirmationDialog.tsx` demonstrates the dialog pattern used for critical operations:\n\n```tsx\n\n \n \n \n \n {translate(\"dags:runAndTaskActions.confirmationDialog.title\")}\n \n \n \n {/* Confirmation details */}\n \n \n \n \n \n\n```\n\nKey characteristics:\n- **lazyMount**: Content renders only when opened\n- **unmountOnExit**: Complete cleanup when closed\n- **backdrop**: Modal overlay for focus\n- **size variants**: sm, md, lg, xl for different content types\n\n资料来源：[airflow-core/src/airflow/ui/src/components/Clear/TaskInstance/ClearTaskInstanceConfirmationDialog.tsx:1-60]()\n\n### Edit Dialogs\n\nThe `EditConnectionButton.tsx` demonstrates dialog usage for editing forms:\n\n```tsx\n\n \n \n {translate(\"connections.edit\")}\n \n \n \n \n \n\n```\n\n资料来源：[airflow-core/src/airflow/ui/src/pages/Connections/EditConnectionButton.tsx:1-50]()\n\n## Component Library\n\n### Clear Actions\n\nThe UI provides comprehensive task and group clearing functionality:\n\n```mermaid\ngraph TD\n A[\"Clear Action Trigger\"] --> B{\"Single vs Group\"}\n B -->|Single| C[\"ClearTaskInstanceDialog\"]\n B -->|Group| D[\"ClearGroupTaskInstanceDialog\"]\n \n C --> E[\"Confirmation Dialog\"]\n D --> F[\"Options Selection\"]\n F --> F1[\"Past Tasks\"]\n F --> F2[\"Future Tasks\"]\n F --> F3[\"Upstream\"]\n F --> F4[\"Downstream\"]\n F --> F5[\"Only Failed\"]\n \n E --> G[\"Action Accordion\"]\n F --> G\n G --> H[\"API Execution\"]\n```\n\nComponents in `airflow-core/src/airflow/ui/src/components/Clear/TaskInstance/`:\n\n- `ClearTaskInstanceDialog.tsx` - Single task clearing\n- `ClearTaskInstanceConfirmationDialog.tsx` - Confirmation UI\n- `ClearGroupTaskInstanceDialog.tsx` - Bulk task clearing\n\n### Trigger DAG Components\n\nThe `TriggerDAGAdvancedOptions.tsx` provides advanced options when triggering DAGs:\n\n| Option | Purpose |\n|--------|---------|\n| dagRunId | Custom run identifier |\n| partitionKey | Partition-based execution |\n| note | Execution notes/documentation |\n\n```tsx\n (\n \n \n {translate(\"runId\")}\n \n \n \n {translate(\"components:triggerDag.runIdHelp\")}\n \n \n )}\n/>\n```\n\n资料来源：[airflow-core/src/airflow/ui/src/components/TriggerDag/TriggerDAGAdvancedOptions.tsx:1-80]()\n\n## Edge Provider UI\n\nThe Edge provider (`providers/edge3/`) extends the base UI with worker-specific pages and components.\n\n### Worker Management Page\n\nThe `WorkerPage.tsx` provides a table-based interface for managing edge workers:\n\n```mermaid\ngraph LR\n subgraph \"Worker Page Structure\"\n T[\"Worker Table\"]\n H[\"Header Actions\"]\n F[\"Filter Controls\"]\n end\n \n T --> C1[\"Worker Name\"]\n T --> C2[\"Queues\"]\n T --> C3[\"Active Jobs\"]\n T --> C4[\"System Info\"]\n T --> C5[\"Operations\"]\n```\n\nWorker operations include:\n- **Delete**: Available for offline, unknown, or offline maintenance states\n- **Shutdown**: Available for idle, running, maintenance states\n- **Enter Maintenance**: Set worker to maintenance mode with comment\n- **Exit Maintenance**: Remove worker from maintenance mode\n\n资料来源：[providers/edge3/src/airflow/providers/edge3/plugins/www/src/pages/WorkerPage.tsx:1-100]()\n\n### Worker Operation Dialogs\n\nBulk operations are supported via `BulkWorkerOperations.tsx`:\n\n```tsx\n\n \n \n \n \n \n \n Delete {deleteWorkers.length} selected worker(s)\n \n \n \n \n {deleteWorkers.map((worker) => (\n {worker.worker_name}\n ))}\n \n \n \n \n \n \n \n \n\n```\n\n## Internationalization\n\nThe UI uses i18n (internationalization) patterns for all user-facing text:\n\n```typescript\n// Translation usage example\ntranslate(\"dagRun.runAfter\") // Column headers\ntranslate(\"dags:runAndTaskActions.confirmationDialog.title\")\ntranslate(\"common:modal.confirm\")\ntranslate(\"taskInstance\", { count: affectedTasks.total_entries })\n```\n\nTranslation keys are organized by:\n- **common**: Shared UI elements\n- **components**: Component-specific strings\n- **dags**: DAG-related UI strings\n- **dagRun**: DAG run specific strings\n\n## State Management and Data Fetching\n\nThe UI uses TanStack Query (React Query) for server state management:\n\n```typescript\n// Typical data fetching pattern\nconst { data, isLoading, error } = useQuery({\n queryKey: ['dagRuns', dagId, page],\n queryFn: () => fetchDagRuns(dagId, page),\n});\n```\n\nKey patterns:\n- **Optimistic updates**: Immediate UI feedback during mutations\n- **Lazy loading**: Components render only when needed\n- **Error boundaries**: Graceful error handling with `ErrorAlert` components\n- **Loading states**: Skeleton loaders for better UX\n\n## Pagination\n\nPaginated lists are implemented consistently throughout the UI:\n\n```tsx\n setPage(event.page)}\n page={page}\n pageSize={PAGE_LIMIT}\n>\n \n \n \n \n \n\n```\n\nStandard pagination constants:\n- **PAGE_LIMIT**: Default items per page (typically 25-50)\n- **total_entries**: Total count from API response\n\n## Summary\n\nApache Airflow's User Interface is a comprehensive React-based frontend that provides:\n\n1. **Multi-view DAG Visualization**: Grid, Graph, and Overview views for different use cases\n2. **Comprehensive Task Management**: Clear, trigger, and manage task instances\n3. **Connection Management**: Visual interface for managing Airflow connections\n4. **Edge Worker Control**: Dedicated UI for edge worker deployment management\n5. **Consistent Component Patterns**: Reusable dialogs, tables, and forms\n6. **Internationalization**: Full i18n support for global deployments\n7. **Type Safety**: Full TypeScript coverage for reliable development\n\nThe UI architecture emphasizes modularity, lazy loading, and consistent patterns to ensure maintainability and performance across large-scale Airflow deployments.\n\n---\n\n\n\n## Data Flow and State Management\n\n### 相关页面\n\n相关主题：[Core Concepts](#core-concepts), [Connections and Variables](#connections-variables)\n\n\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [airflow-core/src/airflow/models/xcom.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/xcom.py)\n- [airflow-core/src/airflow/models/xcom_arg.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/xcom_arg.py)\n- [airflow-core/src/airflow/models/asset.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/asset.py)\n- [airflow-core/src/airflow/models/asset_state.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/asset_state.py)\n- [airflow-core/src/airflow/models/task_state.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/task_state.py)\n- [airflow-core/src/airflow/serialization/definitions/xcom_arg.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/serialization/definitions/xcom_arg.py)\n- [airflow-core/docs/core-concepts/xcoms.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/core-concepts/xcoms.rst)\n\n\n# Data Flow and State Management\n\n## Overview\n\nData Flow and State Management in Apache Airflow encompasses the mechanisms by which tasks communicate, share state, and coordinate execution across a Directed Acyclic Graph (DAG). Airflow provides several interconnected systems to manage how data moves between tasks, how task states are tracked, and how assets trigger workflow execution.\n\nThe core components involved in data flow include XCom (Cross-Communication), Assets, and Task State management. These systems work together to enable complex workflows where tasks can pass data, react to external events, and maintain execution context throughout the DAG lifecycle.\n\n## XCom (Cross-Communication)\n\n### Purpose and Role\n\nXCom is Airflow's primary mechanism for inter-task communication. It allows tasks to push and pull values that can be used by downstream tasks in the same DAG. XComs are stored in the Airflow metadata database and can contain any serializable Python object.\n\n### XCom Data Model\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `key` | String | Identifier for the XCom value |\n| `value` | Any | The actual data being passed |\n| `task_id` | String | Task that produced the XCom |\n| `dag_id` | String | DAG containing the task |\n| `run_id` | String | DAG run identifier |\n| `map_index` | Integer | Index for mapped tasks (-1 for non-mapped) |\n| `timestamp` | DateTime | When the XCom was created |\n| `connection_id` | String | Optional connection for large data |\n\n### XCom API Operations\n\n#### Push (Sending XCom Values)\n\nTasks can push XCom values using the `xcom_push()` method:\n\n```python\ntask_instance.xcom_push(key=\"result\", value={\"data\": \"example\"})\n```\n\nOr implicitly by returning a value from a task:\n\n```python\n@task\ndef process_data():\n return {\"processed\": True, \"count\": 42}\n```\n\n#### Pull (Receiving XCom Values)\n\nDownstream tasks can retrieve XCom values using `xcom_pull()`:\n\n```python\nupstream_result = ti.xcom_pull(task_ids=[\"process_data\"], key=\"result\")\n```\n\n### XComArg\n\n`XComArg` provides a more declarative way to reference XCom values, enabling type-safe access to task outputs:\n\n```python\nfrom airflow.models.xcom_arg import XComArg\n\nprocessed_data = XComArg(task_id=\"process_data\")\nresult = processed_data(map_indexes=[0])\n```\n\nXComArg supports the following parameters:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `task_id` | String | Source task identifier |\n| `dag_id` | String | Optional DAG identifier |\n| `map_index` | Integer/List | Specific map index or indices |\n| `key` | String | XCom key to retrieve |\n\n## Asset Management\n\n### Asset Model\n\nAssets represent data sources or sinks that Airflows can monitor. They enable event-driven scheduling where DAGs can be triggered when underlying data changes.\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `name` | String | Human-readable asset name |\n| `uri` | String | Unique identifier (URN, path, etc.) |\n| `group` | String | Logical grouping of assets |\n| `extra` | Dict | Additional metadata |\n| `created_at` | DateTime | Creation timestamp |\n| `updated_at` | DateTime | Last modification timestamp |\n\n### Asset States\n\nAsset states track the lifecycle and availability of assets:\n\n```python\nclass AssetState:\n \"\"\"Represents the state of an asset in the system.\"\"\"\n \n IDLE = \"idle\"\n SCHEDULED = \"scheduled\"\n RUNNING = \"running\"\n SUCCESS = \"success\"\n FAILED = \"failed\"\n```\n\n#### State Transitions\n\n```mermaid\ngraph TD\n A[IDLE] -->|Asset referenced| B[SCHEDULED]\n B -->|Scheduler picks up| C[RUNNING]\n C -->|Success| D[SUCCESS]\n C -->|Failure| E[FAILED]\n D -->|Next schedule| B\n E -->|Retry| B\n```\n\n## Task State Management\n\n### Task States\n\nTask instances progress through a defined set of states:\n\n| State | Description |\n|-------|-------------|\n| `none` | Task has not been triggered |\n| `queued` | Task is queued for execution |\n| `running` | Task is currently executing |\n| `success` | Task completed successfully |\n| `failed` | Task failed during execution |\n| `upstream_failed` | Upstream task dependency failed |\n| `skipped` | Task was skipped due to branching |\n| `up_for_retry` | Task failed but will be retried |\n| `up_for_reschedule` | Task is waiting for reschedule |\n\n### TaskState Model\n\n```python\nclass TaskState:\n \"\"\"Tracks the current state and context of a task instance.\"\"\"\n \n task_id: str\n dag_id: str\n run_id: str\n state: TaskInstanceState\n try_number: int\n max_tries: int\n start_date: Optional[datetime]\n end_date: Optional[datetime]\n duration: Optional[float]\n```\n\n### State Persistence\n\nTask states are persisted to the metadata database, enabling:\n\n- Recovery from scheduler restarts\n- Historical execution tracking\n- DAG run state reconstruction\n- SLA monitoring and alerting\n\n## Data Flow Architecture\n\n### Task Execution Flow\n\n```mermaid\ngraph TD\n A[DAG Trigger] --> B[Scheduler]\n B --> C{Dependency Check}\n C -->|All met| D[Queue Task]\n C -->|Not met| E[Wait]\n D --> F[Executor]\n F --> G[Worker]\n G --> H[Execute Task]\n H --> I{Push XCom}\n I -->|Yes| J[Store in DB]\n J --> K[Task Complete]\n I -->|No| K\n K --> L[Update TaskState]\n L --> M[Check Downstream]\n M --> C\n```\n\n### XCom Storage Flow\n\n```mermaid\ngraph LR\n A[Task Instance] -->|xcom_push| B[XCom Table]\n C[Task Instance] -->|xcom_pull| B\n B -->|query| D[Metadata DB]\n D -->|result| C\n```\n\n## Serialization and Deserialization\n\n### XComArg Serialization\n\nWhen DAGs are serialized (for example, for the webserver or worker), XComArg references must be properly handled:\n\n```python\nclass XComArgBase:\n \"\"\"Base class for serializable XCom arguments.\"\"\"\n \n def serialize(self) -> dict:\n \"\"\"Convert XComArg to dictionary format.\"\"\"\n return {\n \"task_id\": self.task_id,\n \"dag_id\": self.dag_id,\n \"key\": self.key,\n \"map_index\": self.map_index,\n }\n \n @staticmethod\n def deserialize(data: dict) -> \"XComArgBase\":\n \"\"\"Reconstruct XComArg from dictionary.\"\"\"\n return XComArg(**data)\n```\n\n## Best Practices\n\n### Data Flow Design\n\n1. **Minimize XCom payload size** - Large XCom values impact database performance\n2. **Use Assets for external data** - Let the scheduler handle dependency tracking\n3. **Prefer pull over push patterns** - Downstream tasks should pull required data\n4. **Clear XCom when unnecessary** - Use `xcom_clear()` to prevent accumulation\n\n### State Management\n\n1. **Monitor task durations** - Track state transitions for performance analysis\n2. **Configure appropriate retries** - Set `retries` and `retry_delay` based on task reliability\n3. **Use SLA alerts** - Configure `sla` parameter for critical task deadlines\n4. **Clean up failed states** - Implement proper error handling and state recovery\n\n## Configuration Options\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `xcom_pickle_tasks_on_error` | False | Serialize task data to XCom on error |\n| `max_xcom_size` | 1048576 | Maximum XCom value size in bytes |\n| `xcom_backend` | airflow.models.xcom.BaseXCom | Custom XCom backend class |\n| `enable_asset_uri_validation` | True | Validate asset URIs on creation |\n\n## Related Documentation\n\n- [XCom Documentation](airflow-core/docs/core-concepts/xcoms.rst)\n- [Assets Guide](https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/asset-management.html)\n- [Task Lifecycle](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/tasks.html#task-instances)\n\n---\n\n\n\n## Connections and Variables\n\n### 相关页面\n\n相关主题：[Data Flow and State Management](#data-flow-xcom), [Docker and Helm Deployment](#docker-helm)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [airflow-core/src/airflow/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n- [airflow-core/src/airflow/utils/db.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/utils/db.py)\n- [providers/google/src/airflow/providers/google/cloud/hooks/cloud_composer.py](https://github.com/apache/airflow/blob/main/providers/google/src/airflow/providers/google/cloud/hooks/cloud_composer.py)\n- [dev/breeze/src/airflow_breeze/params/build_prod_params.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/params/build_prod_params.py)\n- [generated/README.md](https://github.com/apache/airflow/blob/main/generated/README.md)\n- [dev/breeze/src/airflow_breeze/commands/sbom_commands.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/sbom_commands.py)\n\n\n# Connections and Variables\n\n## Overview\n\nConnections and Variables are two fundamental abstractions in Apache Airflow for managing configuration and external system integrations. They enable DAGs to store, retrieve, and utilize configuration data and credentials without hardcoding sensitive information.\n\n**Connections** provide a secure way to store and manage credentials for external systems such as databases, APIs, cloud services, and file systems. They centralize authentication configuration in one place, making it easy to manage, update, and audit access to external resources.\n\n**Variables** provide a simple key-value store for storing arbitrary configuration data that can be accessed across DAGs and tasks. They are useful for storing environment-specific settings, feature flags, and general configuration values.\n\nBoth features support multiple backend storage mechanisms and can be managed through the Airflow UI, CLI, or programmatically via the API.\n\n## Connections\n\n### Purpose and Scope\n\nConnections in Airflow encapsulate all the information needed to connect to an external system. Each connection includes:\n\n- A unique connection identifier (conn_id)\n- Connection type (conn_type) specifying the external system category\n- Host, port, login, and password fields\n- Schema and extra parameters for additional configuration\n\nConnections are stored in the Airflow metadata database by default but can also be backed by secrets backends such as HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, or Google Cloud Secret Manager.\n\n### Connection Types\n\nAirflow supports numerous connection types through provider packages. The core supported types include:\n\n| Connection Type | Description | Default Port |\n|-----------------|-------------|-------------|\n| `facebook_social` | Facebook OAuth/social authentication | N/A |\n| `fs` | Filesystem connection | N/A |\n| `ftp` | FTP/SFTP server | 21 |\n| `google_cloud_platform` | Google Cloud Platform services | N/A |\n| `gremlin` | Apache TinkerPop Gremlin server | 8182 |\n| `hive_cli` | Hive command-line interface | 10000 |\n| `hiveserver2` | HiveServer2 JDBC interface | 10000 |\n| `http` | HTTP/HTTPS endpoints | 443 |\n| `iceberg` | Apache Iceberg catalog | N/A |\n\n资料来源：[airflow-core/src/airflow/utils/db.py:200-260]()\n\n### Connection Management via CLI\n\nThe Airflow CLI provides comprehensive commands for managing connections:\n\n```bash\n# List all connections\nairflow connections list\n\n# Get a specific connection\nairflow connections get \n\n# Add a new connection\nairflow connections add --conn-type http --host https://api.example.com\n\n# Delete a connection\nairflow connections delete \n\n# Export all connections\nairflow connections export /tmp/connections.json\n\n# Import connections from file\nairflow connections import /tmp/connections.json\n\n# Test a connection\nairflow connections test \n```\n\nThe connection commands are defined in the CLI configuration with lazy-loaded implementations:\n\n```python\nCONNECTIONS_COMMANDS = (\n ActionCommand(name=\"get\", func=lazy_load_command(\"airflow.cli.commands.connection_command.connections_get\"), ...),\n ActionCommand(name=\"list\", func=lazy_load_command(\"airflow.cli.commands.connection_command.connections_list\"), ...),\n ActionCommand(name=\"add\", func=lazy_load_command(\"airflow.cli.commands.connection_command.connections_add\"), ...),\n ActionCommand(name=\"delete\", func=lazy_load_command(\"airflow.cli.commands.connection_command.connections_delete\"), ...),\n ActionCommand(name=\"export\", func=lazy_load_command(\"airflow.cli.commands.connection_command.connections_export\"), ...),\n ActionCommand(name=\"import\", func=lazy_load_command(\"airflow.cli.commands.connection_command.connections_import\"), ...),\n ActionCommand(name=\"test\", func=lazy_load_command(\"airflow.cli.commands.connection_command.connections_test\"), ...),\n)\n```\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:1-50]()\n\n### Connection Storage Architecture\n\n```mermaid\ngraph TD\n A[Airflow CLI/UI/API] --> B[Connection CRUD Operations]\n B --> C{Secrets Backend}\n C -->|None/Default| D[Airflow Metadata Database]\n C -->|HashiCorp Vault| E[Vault Secrets]\n C -->|AWS| F[AWS Secrets Manager]\n C -->|Azure| G[Azure Key Vault]\n C -->|GCP| H[GCP Secret Manager]\n D --> I[connection Table]\n E --> J[Vault Path]\n F --> K[AWS Secrets]\n G --> L[Azure Keys]\n H --> M[GCP Secrets]\n```\n\n### Using Connections in DAGs\n\nConnections are accessed in DAGs through the `BaseHook` class:\n\n```python\nfrom airflow.hooks.base import BaseHook\n\ndef get_external_api_data():\n conn = BaseHook.get_connection(\"my_external_api\")\n api_key = conn.password\n base_url = conn.host\n \n # Use credentials to make API calls\n ...\n```\n\nConnections with custom configurations can utilize the `extra` field for JSON-encoded parameters:\n\n```python\nConnection(\n conn_id=\"ftp_default\",\n conn_type=\"ftp\",\n host=\"localhost\",\n port=21,\n login=\"airflow\",\n password=\"airflow\",\n extra='{\"key_file\": \"~/.ssh/id_rsa\", \"no_host_key_check\": true}'\n)\n```\n\n资料来源：[airflow-core/src/airflow/utils/db.py:230-240]()\n\n## Variables\n\n### Purpose and Scope\n\nVariables provide a simple key-value storage mechanism for storing configuration data that can be shared across DAGs and tasks. They support string values with optional JSON serialization for complex data structures.\n\nKey characteristics of Variables:\n\n- Key-value pairs stored in the Airflow metadata database\n- Optional JSON serialization for non-string values\n- Support for environment-specific configuration\n- Accessible from all DAGs and tasks\n- Can be exported/imported in bulk\n\n### Variable Management via CLI\n\nThe Airflow CLI provides comprehensive commands for managing variables:\n\n```bash\n# List all variables\nairflow variables list\n\n# Get a specific variable\nairflow variables get \n\n# Set a variable\nairflow variables set \n\n# Set a variable with JSON serialization\nairflow variables set config_json '{\"setting\": true}' --serialize-json\n\n# Delete a variable\nairflow variables delete \n\n# Export all variables\nairflow variables export /tmp/variables.json\n\n# Import variables from file\nairflow variables import /tmp/variables.json\n```\n\nThe variable commands are defined with support for serialization options:\n\n```python\nVARIABLES_COMMANDS = (\n ActionCommand(name=\"list\", func=lazy_load_command(\"airflow.cli.commands.variable_command.variables_list\"), ...),\n ActionCommand(name=\"get\", func=lazy_load_command(\"airflow.cli.commands.variable_command.variables_get\"), \n args=(ARG_VAR, ARG_DESERIALIZE_JSON, ARG_DEFAULT, ARG_VERBOSE)),\n ActionCommand(name=\"set\", func=lazy_load_command(\"airflow.cli.commands.variable_command.variables_set\"),\n args=(ARG_VAR, ARG_VAR_VALUE, ARG_VAR_DESCRIPTION, ARG_SERIALIZE_JSON, ARG_VERBOSE)),\n ActionCommand(name=\"delete\", func=lazy_load_command(\"airflow.cli.commands.variable_command.variables_delete\"), ...),\n ActionCommand(name=\"export\", func=lazy_load_command(\"airflow.cli.commands.variable_command.variables_export\"), ...),\n ActionCommand(name=\"import\", func=lazy_load_command(\"airflow.cli.commands.variable_command.variables_import\"), ...),\n)\n```\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:50-80]()\n\n### Variable Storage Architecture\n\n```mermaid\ngraph TD\n A[DAG/Task Code] --> B[Variable API]\n B --> C[Secrets Backend]\n C -->|Default| D[Metadata Database]\n C -->|Backend| E[External Secrets]\n D --> F[variable Table]\n E --> F\n B --> G[JSON Deserializer]\n G --> H[Python Objects]\n F --> I[Key-Value Store]\n```\n\n### Using Variables in DAGs\n\nVariables can be accessed using the `Variable` class:\n\n```python\nfrom airflow.models import Variable\n\n# Get a simple string variable\napi_endpoint = Variable.get(\"api_endpoint\")\n\n# Get with default value\ntimeout = Variable.get(\"timeout\", default_var=30)\n\n# Get and deserialize JSON\nconfig = Variable.get(\"my_config\", deserialize_json=True)\n\n# Set a variable\nVariable.set(\"my_key\", \"my_value\")\nVariable.set(\"config\", {\"setting\": True}, serialize_json=True)\n```\n\n## Secrets Backend Integration\n\nBoth Connections and Variables can be backed by external secrets backends for enhanced security. This allows storing sensitive data in enterprise-grade secret management systems while maintaining the same Airflow API interface.\n\n### Available Secrets Backends\n\n| Backend | Package | Description |\n|---------|---------|-------------|\n| HashiCorp Vault | `airflow.providers.hashicorp` | HashiCorp Vault KV secrets engine |\n| AWS Secrets Manager | `airflow.providers.amazon` | AWS Secrets Manager and SSM Parameter Store |\n| Azure Key Vault | `airflow.providers.microsoft.azure` | Azure Key Vault secrets |\n| GCP Secret Manager | `airflow.providers.google` | Google Cloud Secret Manager |\n| Environment Variables | Built-in | Read from OS environment variables |\n| Local Files | Built-in | Read from JSON/YAML files |\n\n### Configuring Secrets Backends\n\nThe secrets backend is configured via the `[secrets]` section in `airflow.cfg`:\n\n```ini\n[secrets]\nbackend = airflow.providers.google.cloud.secrets.secret_manager.CloudSecretManagerBackend\nbackend_kwargs = {\"project_id\": \"my-project\", \"connections_prefix\": \"airflow-connections\"}\n```\n\n## Best Practices\n\n### Security Considerations\n\n1. **Never hardcode credentials** - Always use Connections or Variables for sensitive data\n2. **Use secrets backends** - For production environments, use enterprise secret management systems\n3. **Enable encryption** - Ensure the Airflow metadata database is encrypted at rest\n4. **Rotate credentials** - Regularly rotate passwords and API keys stored in connections\n5. **Audit access** - Monitor and log access to sensitive connections and variables\n\n### Performance Considerations\n\n1. **Avoid frequent variable reads** - Cache variable values when used repeatedly in a task\n2. **Use connection pooling** - Many hooks automatically pool connections; configure appropriately\n3. **Limit extra field size** - Keep connection `extra` JSON data minimal for performance\n\n### Operational Considerations\n\n1. **Use meaningful conn_ids** - Follow naming conventions like `{env}_{system}_{purpose}`\n2. **Document connections** - Use the description field to document connection purpose and owners\n3. **Export for disaster recovery** - Regularly export connections and variables for backup\n\n```bash\n# Backup connections and variables\nairflow connections export /opt/airflow/backups/connections_$(date +%Y%m%d).json\nairflow variables export /opt/airflow/backups/variables_$(date +%Y%m%d).json\n```\n\n## CLI Command Reference\n\n### Connection Commands\n\n| Command | Description |\n|---------|-------------|\n| `airflow connections list` | List all connections |\n| `airflow connections get ` | Get connection details |\n| `airflow connections add [options]` | Create a connection |\n| `airflow connections delete ` | Delete a connection |\n| `airflow connections export ` | Export connections to file |\n| `airflow connections import ` | Import connections from file |\n| `airflow connections test ` | Test connection availability |\n| `airflow connections create-default-connections` | Initialize provider default connections |\n\n### Variable Commands\n\n| Command | Description |\n|---------|-------------|\n| `airflow variables list` | List all variables |\n| `airflow variables get ` | Get variable value |\n| `airflow variables set ` | Set variable value |\n| `airflow variables delete ` | Delete a variable |\n| `airflow variables export ` | Export variables to file |\n| `airflow variables import ` | Import variables from file |\n\n## See Also\n\n- [Airflow Connections Documentation](https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/connections.html)\n- [Airflow Variables Documentation](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/variables.html)\n- [Secrets Backend Configuration](https://airflow.apache.org/docs/apache-airflow/stable/security/secrets/secrets-backend/index.html)\n- [Google Cloud Composer Hook](https://github.com/apache/airflow/blob/main/providers/google/src/airflow/providers/google/cloud/hooks/cloud_composer.py) - Example of connection usage in provider hooks\n\n---\n\n\n\n## Docker and Helm Deployment\n\n### 相关页面\n\n相关主题：[Kubernetes Deployment](#kubernetes-deployment), [Architecture Overview](#architecture-overview)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [dev/breeze/src/airflow_breeze/commands/release_management_commands.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/release_management_commands.py)\n- [docker-stack-docs/README.md](https://github.com/apache/airflow/blob/main/docker-stack-docs/README.md)\n- [generated/PYPI_README.md](https://github.com/apache/airflow/blob/main/generated/PYPI_README.md)\n- [dev/breeze/src/airflow_breeze/commands/sbom_commands.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/sbom_commands.py)\n- [dev/breeze/src/airflow_breeze/global_constants.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/global_constants.py)\n\n\n# Docker and Helm Deployment\n\nApache Airflow provides comprehensive support for containerized and Kubernetes-based deployments through Docker images and Helm charts. This documentation covers the deployment mechanisms, configuration options, and best practices for running Airflow in these environments.\n\n## Overview\n\nApache Airflow can be deployed using two primary methods:\n\n| Deployment Method | Use Case | Primary Files |\n|------------------|----------|---------------|\n| **Docker** | Local development, single-node deployments, CI/CD pipelines | `Dockerfile`, `Dockerfile.ci` |\n| **Helm Chart** | Production Kubernetes deployments, distributed systems | `chart/Chart.yaml`, `chart/values.yaml` |\n\n资料来源：[docker-stack-docs/README.md](https://github.com/apache/airflow/blob/main/docker-stack-docs/README.md)\n\n## Docker Image Architecture\n\nApache Airflow ships with two main Docker images optimized for different use cases.\n\n### Production Image (`Dockerfile`)\n\nThe production Docker image is built using multi-stage builds and includes all necessary components for running Airflow in production environments. The image uses `python:{DEFAULT_PYTHON_MAJOR_MINOR_VERSION}-slim-{ALLOWED_DEBIAN_VERSIONS[0]}` as its base.\n\nKey characteristics of the production image:\n\n- **Base OS**: Debian slim variant for minimal footprint\n- **Package Manager**: Uses `uv` (Ultraviolet) for faster pip installations\n- **Architecture**: Multi-stage build for optimized image size\n- **User Space**: Runs as non-root user for security\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/release_management_commands.py:55-62](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/release_management_commands.py)\n\n### CI Image (`Dockerfile.ci`)\n\nThe CI image is designed for continuous integration workflows and includes additional tooling for testing and development.\n\n```dockerfile\n# syntax=docker/dockerfile:1.4\nFROM python:{DEFAULT_PYTHON_MAJOR_MINOR_VERSION}-slim-{ALLOWED_DEBIAN_VERSIONS[0]}\nRUN apt-get update && apt-get install -y --no-install-recommends libatomic1 git curl\nRUN pip install uv=={UV_VERSION}\nRUN --mount=type=cache,id=cache-airflow-build-dockerfile-installation,target=/root/.cache/ \\\n uv pip install --system ignore pip=={AIRFLOW_PIP_VERSION} hatch=={HATCH_VERSION} \\\n pyyaml=={PYYAML_VERSION} gitpython=={GITPYTHON_VERSION} rich=={RICH_VERSION} \\\n prek=={PREK_VERSION}\nCOPY . /opt/airflow\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/release_management_commands.py:56-65](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/release_management_commands.py)\n\n### Version Constants\n\nThe build process uses the following pinned version constants:\n\n| Constant | Version | Purpose |\n|----------|---------|---------|\n| `AIRFLOW_PIP_VERSION` | `26.1.1` | pip package manager |\n| `AIRFLOW_UV_VERSION` | `0.11.11` | Fast Python package installer |\n| `GITPYTHON_VERSION` | `3.1.50` | Git operations in Python |\n| `RICH_VERSION` | `15.0.0` | Rich terminal output |\n| `HATCH_VERSION` | `1.16.5` | Python packaging |\n| `PYYAML_VERSION` | `6.0.3` | YAML parsing |\n| `PREK_VERSION` | `0.3.13` | Pre-commit hooks |\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/release_management_commands.py:70-76](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/release_management_commands.py)\n\n## Helm Chart Deployment\n\nThe Apache Airflow Helm chart provides a production-ready deployment mechanism for Kubernetes clusters.\n\n### Chart Metadata\n\n| Property | Value |\n|----------|-------|\n| Chart Name | `airflow` |\n| Repository | Apache Airflow Official |\n| Kubernetes Support | v1.30+, v1.31+, v1.32+, v1.33+ |\n\nSupported Kubernetes versions are determined by the major cloud providers (EKS, AKS, GKE) support windows.\n\n资料来源：[dev/breeze/src/airflow_breeze/global_constants.py:48-54](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/global_constants.py)\n\n### Core Components\n\nThe Helm chart deploys the following core Airflow components:\n\n```mermaid\ngraph TD\n A[Helm Chart] --> B[Webserver]\n A --> C[Scheduler]\n A --> D[Triggerer]\n A --> E[Worker]\n A --> F[Flower]\n A --> G[StatsD]\n A --> H[Redis]\n A --> I[PostgreSQL/MySQL]\n \n B -->|Read/Write| I\n C -->|Queue Jobs| H\n D -->|Async Tasks| H\n E -->|Process Tasks| H\n```\n\n### Scheduler Deployment\n\nThe scheduler is deployed as a Kubernetes Deployment with the following characteristics:\n\n- **Replicas**: Configurable via `replicas` parameter\n- **Resources**: Configurable CPU and memory limits\n- **Health Checks**: Liveness and readiness probes\n- **Persistence**: Optional volume mounts for DAGs and logs\n\n资料来源：[chart/templates/scheduler/scheduler-deployment.yaml](https://github.com/apache/airflow/blob/main/chart/templates/scheduler/scheduler-deployment.yaml)\n\n### Worker Deployment\n\nWorkers process tasks from the message queue and are deployed as:\n\n- **Deployment Type**: StatefulSet or Deployment based on configuration\n- **Scaling**: Horizontal Pod Autoscaler (HPA) support\n- **Queue Configuration**: Multiple queues supported\n- **Resource Management**: Configurable resource requests and limits\n\n资料来源：[chart/templates/workers/worker-deployment.yaml](https://github.com/apache/airflow/blob/main/chart/templates/workers/worker-deployment.yaml)\n\n## Installation Methods\n\n### Installing from PyPI\n\nWhile it is possible to install Airflow using tools like Poetry or pip-tools, only `pip` installation is currently officially supported.\n\n> **Note**: Installing via Poetry or pip-tools is not currently supported.\n\nFor repeatable installation, Airflow maintains \"known-to-be-working\" constraint files in the orphan `constraints-main` and `constraints-2-0` branches. These constraint files are maintained per major/minor Python version.\n\n资料来源：[generated/PYPI_README.md](https://github.com/apache/airflow/blob/main/generated/PYPI_README.md)\n\n### Installing Providers from Sources\n\nProviders can be installed from source with SHA512 verification:\n\n```bash\nshasum -a 512 {{ package_name }}-{{ package_version }}.tar.gz | diff - {{ package_name }}-{{ package_version }}.tar.gz.sha512\n```\n\nThis ensures the integrity of the downloaded package against the provided checksum.\n\n资料来源：[devel-common/src/sphinx_exts/includes/installing-providers-from-sources.rst](https://github.com/apache/airflow/blob/main/devel-common/src/sphinx_exts/includes/installing-providers-from-sources.rst)\n\n## Helm Chart Package Preparation\n\nThe release management tooling includes commands for preparing Helm chart packages:\n\n```mermaid\ngraph LR\n A[Chart Source] --> B[helm package]\n B --> C[Deterministic Repack]\n C --> D[PGP Signature]\n D --> E[Distribution Archive]\n```\n\n### Package Signing\n\nHelm chart packages can be signed using GPG for verification:\n\n```bash\nhelm gpg sign -u \n```\n\nThe signing process generates a provenance file (`.tgz.prov`) that can be used to verify the package integrity.\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/release_management_commands.py:400-420](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/release_management_commands.py)\n\n## Software Bill of Materials (SBOM)\n\nThe Airflow project generates and maintains SBOM information for security and compliance purposes.\n\n### SBOM Commands\n\nThe `breeze` CLI provides commands for managing SBOM information:\n\n```bash\nbreeze sbom update-sbom-information [OPTIONS]\n```\n\n#### Command Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `--airflow-site-archive-path` | Path | Directory for airflow-site-archive |\n| `--airflow-root-path` | Path | Root of the airflow repository |\n| `--airflow-version` | String | Version of airflow to update SBOM |\n| `--airflow-constraints-reference` | String | Constraints reference for SBOM generation |\n\nThese files are placed in `airflow-site-archive/docs-archive/` or `generated/_build/docs/apache-airflow/stable/` depending on the configuration.\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/sbom_commands.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/sbom_commands.py)\n\n### SBOM File Generation\n\nSBOM files are generated based on:\n\n- `provider.yaml` files\n- Airflow constraints\n- Provider tags and releases\n\nThe SBOM information is automatically regenerated using the `breeze release-management generate-providers-metadata` command.\n\n资料来源：[generated/README.md](https://github.com/apache/airflow/blob/main/generated/README.md)\n\n## Docker Compose Deployment\n\nFor development and testing purposes, Airflow can be deployed using Docker Compose.\n\n### Prerequisites\n\n- Docker Engine\n- Docker Compose v2+\n- SQLite database (automatically created if `AIRFLOW_HOME` is not set)\n\n### Basic Usage\n\nFor example commands that start Airflow, refer to the [Executing commands](https://airflow.apache.org/docs/docker-stack/entrypoint.html#entrypoint-commands) documentation.\n\n资料来源：[docker-stack-docs/README.md](https://github.com/apache/airflow/blob/main/docker-stack-docs/README.md)\n\n## Deployment Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n A[Airflow CLI] --> B[REST API]\n C[Web UI] --> B\n end\n \n subgraph \"Core Services\"\n D[Scheduler] --> E[(Metadata DB)]\n F[Triggerer] --> E\n G[Webserver] --> E\n end\n \n subgraph \"Task Execution\"\n H[Workers] --> I[Message Queue]\n D --> I\n F --> I\n end\n \n subgraph \"Storage\"\n J[DAGs Repository]\n K[Logs Storage]\n L[Plugins]\n end\n \n H --> K\n G --> K\n D --> J\n```\n\n## Default Connections\n\nThe Airflow deployment includes pre-configured connection templates for common services:\n\n| Connection ID | Type | Default Settings |\n|---------------|------|-------------------|\n| `google_cloud_default` | Google Cloud Platform | Schema: default |\n| `http_default` | HTTP | Host: https://www.httpbin.org/ |\n| `ftp_default` | FTP | localhost:21 |\n| `hive_cli_default` | Hive CLI | localhost:10000 |\n| `hiveserver2_default` | HiveServer2 | localhost:10000 |\n| `fs_default` | File System | Path: / |\n| `gremlin_default` | Gremlin | Host: gremlin:8182 |\n| `iceberg_default` | Iceberg | HTTPS endpoint |\n\n资料来源：[airflow-core/src/airflow/utils/db.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/utils/db.py)\n\n## Verification and Security\n\n### Package Verification\n\nPyPI releases can be verified by downloading the package, signature, and SHA sum files:\n\n```bash\n#!/bin/bash\nPACKAGE_VERSION={{ package_version }}\nPACKAGE_NAME={{ package_name }}\nprovider_download_dir=$(mktemp -d)\npip download --no-deps \"${PACKAGE_NAME}==${PACKAGE_VERSION}\" --dest \"${provider_download_dir}\"\ncurl \"{{ base_url }}/{{ package_name_underscores }}-{{ package_version }}-py3-none-any.whl.asc\" \\\n -L -o \"${provider_download_dir}/{{ package_name_underscores }}-{{ package_version }}-py3-none-any.whl.asc\"\ncurl \"{{ base_url }}/{{ package_name_underscores }}-{{ package_version }}-py3-none-any.whl.sha512\" \\\n -L -o \"${provider_download_dir}/{{ package_name_underscores }}-{{ package_version }}-py3-none-any.whl.sha512\"\necho \"Please verify files downloaded to ${provider_download_dir}\"\nls -\n```\n\n资料来源：[devel-common/src/sphinx_exts/includes/installing-providers-from-sources.rst](https://github.com/apache/airflow/blob/main/devel-common/src/sphinx_exts/includes/installing-providers-from-sources.rst)\n\n## Related Documentation\n\n- [Docker Stack Documentation](https://airflow.apache.org/docs/docker-stack/)\n- [Helm Chart Documentation](https://airflow.apache.org/docs/helm-chart/)\n- [Docker Compose Guide](https://airflow.apache.org/docs/apache-airflow/stable/howto/docker-compose/index.html)\n- [Executing Commands in Docker](https://airflow.apache.org/docs/docker-stack/entrypoint.html)\n\n---\n\n\n\n## Kubernetes Deployment\n\n### 相关页面\n\n相关主题：[Docker and Helm Deployment](#docker-helm), [Scheduler and Executor Architecture](#scheduler-executor)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/executors/kubernetes_executor.py](https://github.com/apache/airflow/blob/main/providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/executors/kubernetes_executor.py)\n- [providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/operators/pod.py](https://github.com/apache/airflow/blob/main/providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/operators/pod.py)\n- [providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/kube_config.py](https://github.com/apache/airflow/blob/main/providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/kube_config.py)\n- [providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/pod_generator.py](https://github.com/apache/airflow/blob/main/providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/pod_generator.py)\n- [chart/templates/triggerer/triggerer-deployment.yaml](https://github.com/apache/airflow/blob/main/chart/templates/triggerer/triggerer-deployment.yaml)\n- [airflow-core/docs/administration-and-deployment/kubernetes.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/administration-and-deployment/kubernetes.rst)\n- [dev/breeze/src/airflow_breeze/commands/kubernetes_commands.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/kubernetes_commands.py)\n\n\n# Kubernetes Deployment\n\nApache Airflow provides comprehensive Kubernetes support through the CNCF Kubernetes provider package. This integration enables Airflow to run tasks as Kubernetes Pods, providing dynamic resource allocation, isolation, and scalability for workflow execution.\n\n## Architecture Overview\n\nAirflow's Kubernetes deployment consists of multiple components that work together to provide a flexible, scalable execution environment.\n\n### Kubernetes Executor Architecture\n\nThe Kubernetes Executor is one of Airflow's core executors that launches a new Pod for each task instance. Unlike the Celery Executor which reuses workers, the Kubernetes Executor creates isolated Pods for each task execution.\n\n```mermaid\ngraph TD\n A[Airflow Scheduler] -->|submits task| B[Kubernetes Executor]\n B -->|creates| C[Task Pod]\n B -->|watches| C\n C -->|completes| D[Pod Status Update]\n D -->|pods cleaned up| E[Resource Cleanup]\n \n F[Kubernetes API Server] -->|manages| C\n G[Worker Nodes] -->|hosts| C\n```\n\n### Core Components\n\n| Component | File Path | Purpose |\n|-----------|-----------|---------|\n| KubernetesExecutor | `providers/cncf/kubernetes/.../executors/kubernetes_executor.py` | Main executor implementation |\n| KubernetesPodOperator | `providers/cncf/kubernetes/.../operators/pod.py` | Operator for running pods |\n| KubeConfig | `providers/cncf/kubernetes/.../kube_config.py` | Configuration management |\n| PodGenerator | `providers/cncf/kubernetes/.../pod_generator.py` | Pod specification builder |\n\n## Configuration\n\n### Kubernetes Executor Configuration\n\nThe Kubernetes Executor requires configuration in the `airflow.cfg` file under the `[kubernetes]` section.\n\n```ini\n[core]\nexecutor = airflow.providers.cncf.kubernetes.executors.kubernetes_executor.KubernetesExecutor\n\n[kubernetes]\nnamespace = default\npod_template_file = /path/to/pod_template.yaml\nworker_container_repository = apache/airflow\nworker_container_tag = latest\n```\n\n### Key Configuration Parameters\n\n| Parameter | Description | Default |\n|-----------|-------------|---------|\n| `namespace` | Kubernetes namespace for task pods | `default` |\n| `pod_template_file` | Path to pod template yaml | - |\n| `worker_container_repository` | Docker image repository | `apache/airflow` |\n| `worker_container_tag` | Docker image tag | `latest` |\n| `delete_worker_pods` | Delete pods after task completion | `True` |\n| `delete_worker_pods_on_failure` | Delete pods on task failure | `False` |\n| `worker_pods_creation_batch_size` | Batch size for pod creation | `2` |\n\n资料来源：[providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/kube_config.py]()\n\n## Pod Generation\n\nThe `PodGenerator` class is responsible for constructing Kubernetes Pod specifications from Airflow task definitions.\n\n### Pod Template System\n\nAirflow supports custom pod templates that define the base pod specification. These templates use Jinja2 templating to allow dynamic value injection.\n\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n name: airflow-worker-pod\nspec:\n containers:\n - name: base\n image: \"{{ container_image }}\"\n env:\n - name: AIRFLOW__CORE__EXECUTOR\n value: LocalExecutor\n```\n\n资料来源：[providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/pod_generator.py]()\n\n### Dynamic Pod Configuration\n\nThe KubernetesPodOperator allows dynamic configuration of pod specifications at runtime:\n\n```python\nfrom airflow.providers.cncf.kubernetes.operators.pod import KubernetesPodOperator\n\nrun_pod = KubernetesPodOperator(\n task_id=\"run_kubernetes_pod\",\n name=\"my-task-pod\",\n namespace=\"default\",\n image=\"python:3.9-slim\",\n cmds=[\"python\", \"-c\", \"print('Hello from Kubernetes')\"],\n labels={\"app\": \"airflow\", \"environment\": \"production\"},\n volumes=[config_volume],\n volume_mounts=[config_volume_mount],\n get_logs=True,\n is_delete_operator_pod=True,\n)\n```\n\n## Airflow Components on Kubernetes\n\n### Triggerer Deployment\n\nThe Airflow Triggerer runs as a Kubernetes Deployment to manage triggering logic in a distributed environment.\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: airflow-triggerer\n namespace: airflow\nspec:\n replicas: 2\n selector:\n matchLabels:\n component: triggerer\n tier: airflow\n template:\n metadata:\n labels:\n component: triggerer\n tier: airflow\n spec:\n serviceAccountName: airflow-triggerer\n containers:\n - name: triggerer\n image: {{ .Values.images.triggerer }}\n args: [\"triggerer\"]\n ports:\n - name: logs\n containerPort: 8793\n```\n\n资料来源：[chart/templates/triggerer/triggerer-deployment.yaml]()\n\n### Component Services\n\n| Component | Kubernetes Object | Purpose |\n|-----------|-------------------|---------|\n| Scheduler | Deployment | DAG parsing and task scheduling |\n| Webserver | Deployment | Airflow UI serving |\n| Triggerer | Deployment | Deferred task handling |\n| Worker | Deployment/DaemonSet | Task execution |\n| Flower | Deployment | Celery monitoring (optional) |\n| Database | StatefulSet | Metadata storage |\n| Redis | StatefulSet | Message broker |\n\n## Local Development with Skaffold\n\nAirflow provides development workflows using Skaffold for hot-reloading code changes into running Kubernetes pods.\n\n### Skaffold Dev Loop\n\n```bash\nbreeze k8s dev\n```\n\nThis command runs the Skaffold dev loop to sync DAGs and airflow-core sources to running pods including scheduler, triggerer, dag-processor, and API Server with hot-reload support.\n\n```python\n@pulumi_benchmark.group.command(\n name=\"dev\",\n help=(\n \"Run skaffold dev loop to sync dags and airflow-core sources to running pods \"\n \"(scheduler/triggerer/dag-processor/API Server hot-reload; UI auto-refresh not supported yet).\"\n ),\n)\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/kubernetes_commands.py]()\n\n## KubernetesPodOperator\n\nThe KubernetesPodOperator allows users to define and execute arbitrary Kubernetes Pods as Airflow tasks.\n\n### Operator Features\n\n| Feature | Description |\n|---------|-------------|\n| Full Pod Spec | Define complete pod specifications |\n| Volume Management | Support for ConfigMaps, Secrets, PVCs |\n| Image Pull | Private registry authentication |\n| Resource Limits | CPU and memory constraints |\n| Node Selection | Pod affinity and node selectors |\n| Sidecars | Support for sidecar containers |\n\n### Basic Usage\n\n```python\nfrom airflow.providers.cncf.kubernetes.operators.pod import KubernetesPodOperator\n\nwith dag:\n k = KubernetesPodOperator(\n task_id=\"demo_pod\",\n name=\"demo-pod\",\n image=\"python:3.9\",\n cmds=[\"python\", \"-c\", \"print('Hello World')\"],\n namespace=\"default\",\n is_delete_operator_pod=True,\n get_logs=True,\n )\n```\n\n资料来源：[providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/operators/pod.py]()\n\n## Executor Implementation\n\n### Task Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Scheduler\n participant K8sExecutor\n participant KubeAPI\n participant Pod\n \n Scheduler->>K8sExecutor: Queue task for execution\n K8sExecutor->>KubeAPI: Create Pod\n KubeAPI->>Pod: Launch pod\n Pod->>Pod: Execute task\n Pod->>KubeAPI: Report completion\n KubeAPI->>K8sExecutor: Pod completed\n K8sExecutor->>Scheduler: Task result\n```\n\n### Executor Configuration\n\n```python\nclass KubernetesExecutor:\n \"\"\"Kubernetes executor implementation.\"\"\"\n \n def __init__(self):\n self.kube_config = KubeConfig()\n self.manager = PodLauncher(\n kube_config=self.kube_config,\n in_cluster=self.kube_config.get(\"in_cluster\", False),\n )\n```\n\n资料来源：[providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/executors/kubernetes_executor.py]()\n\n## Security Considerations\n\n### Service Account Configuration\n\nRunning Airflow on Kubernetes requires proper service account configuration with appropriate RBAC permissions.\n\n```yaml\napiVersion: v1\nkind: ServiceAccount\nmetadata:\n name: airflow-executor\n namespace: airflow\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: Role\nmetadata:\n name: airflow-executor\nrules:\n - apiGroups: [\"\"]\n resources: [\"pods\"]\n verbs: [\"create\", \"delete\", \"get\", \"list\", \"patch\", \"watch\"]\n - apiGroups: [\"\"]\n resources: [\"pods/log\"]\n verbs: [\"get\"]\n```\n\n### Security Context\n\nPods can be configured with security contexts for enhanced isolation:\n\n```python\nKubernetesPodOperator(\n task_id=\"secure_pod\",\n security_context={\n \"runAsUser\": 1000,\n \"fsGroup\": 2000,\n \"capabilities\": {\"drop\": [\"ALL\"]},\n },\n container_security_context={\n \"readOnlyRootFilesystem\": True,\n \"runAsNonRoot\": True,\n },\n)\n```\n\n## Resource Management\n\n### Pod Resources\n\nTasks can define resource requests and limits:\n\n```python\nKubernetesPodOperator(\n task_id=\"resource_limited_task\",\n container_resources={\n \"request_memory\": \"128Mi\",\n \"request_cpu\": 0.5,\n \"limit_memory\": \"256Mi\",\n \"limit_cpu\": 1,\n },\n)\n```\n\n### Node Affinity and Tolerations\n\n```python\nKubernetesPodOperator(\n task_id=\"specific_node_task\",\n node_selector={\n \"disktype\": \"ssd\",\n \"kubernetes.io/arch\": \"amd64\",\n },\n tolerations=[\n {\n \"key\": \"dedicated\",\n \"operator\": \"Equal\",\n \"value\": \"airflow\",\n \"effect\": \"NoSchedule\",\n }\n ],\n)\n```\n\n## Monitoring and Logging\n\n### Log Aggregation\n\nThe KubernetesPodOperator supports automatic log retrieval from pods:\n\n```python\nKubernetesPodOperator(\n task_id=\"task_with_logs\",\n get_logs=True,\n log_events_on_failure=True,\n)\n```\n\n### Pod Monitoring\n\nPod status can be monitored through the Kubernetes API:\n\n```python\nfrom airflow.providers.cncf.kubernetes.utils import delete_from_dict, create_from_dict\n\n# Watch pod status\nwatcher = PodWatcher(kube_config)\nfor event in watcher.poll_for_pod_completion(task_instance):\n if event[\"type\"] == \"DELETED\":\n break\n```\n\n## Best Practices\n\n### 1. Use Pod Templates\n\nDefine reusable pod templates to ensure consistency across tasks:\n\n```yaml\n# pod_template.yaml\napiVersion: v1\nkind: Pod\nspec:\n securityContext:\n runAsUser: 1000\n fsGroup: 2000\n containers:\n - name: base\n resources:\n requests:\n memory: \"128Mi\"\n cpu: 0.25\n limits:\n memory: \"256Mi\"\n cpu: 0.5\n```\n\n### 2. Implement Graceful Cleanup\n\nConfigure pod deletion policies to manage resource cleanup:\n\n```python\nKubernetesPodOperator(\n task_id=\"cleanup_example\",\n is_delete_operator_pod=True,\n on_finish_callback=cleanup_handler,\n)\n```\n\n### 3. Set Appropriate Timeouts\n\nAlways define task timeouts to prevent orphaned pods:\n\n```python\nKubernetesPodOperator(\n task_id=\"timeout_task\",\n execution_timeout=timedelta(minutes=30),\n task_concurrency=10,\n)\n```\n\n## Helm Chart Deployment\n\nThe official Airflow Helm chart provides production-ready Kubernetes deployment configurations.\n\n### Minimal Installation\n\n```bash\nhelm install airflow apache-airflow/airflow \\\n --namespace airflow \\\n --create-namespace \\\n --set executor=CeleryExecutor \\\n --set webserver.service.type=LoadBalancer\n```\n\n### Production Installation\n\n```bash\nhelm install airflow apache-airflow/airflow \\\n --namespace airflow \\\n --values production-values.yaml\n```\n\nThe Helm chart supports extensive customization through values files, including:\n- Multi-tier architecture configuration\n- Ingress setup for webserver access\n- External database and message broker\n- Persistent volume claims for DAG storage\n- Resource limits per component\n- Security contexts and pod policies\n\n## References\n\nFor further information, refer to the official documentation at `airflow-core/docs/administration-and-deployment/kubernetes.rst` and the Kubernetes provider source code in `providers/cncf/kubernetes/`.\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：apache/airflow\n\n摘要：发现 19 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：`ExternalTaskSensor` can succeed early for task groups with NULL task states。\n\n## 1. 安装坑 · 来源证据：`ExternalTaskSensor` can succeed early for task groups with NULL task states\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`ExternalTaskSensor` can succeed early for task groups with NULL task states\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c746f7ce44f43f1a5a81840f4ee741a | https://github.com/apache/airflow/issues/66877 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:33884891 | https://github.com/apache/airflow | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:33884891 | https://github.com/apache/airflow | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:33884891 | https://github.com/apache/airflow | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:33884891 | https://github.com/apache/airflow | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:33884891 | https://github.com/apache/airflow | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 来源证据：Apache Airflow 3.1.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.1.6\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c94c5b79bb91454c9e0ad22b4a36dc11 | https://github.com/apache/airflow/releases/tag/3.1.6 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 8. 安全/权限坑 · 来源证据：Apache Airflow 3.1.7\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.1.7\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_80a5614167b44ecca96422caa56afca4 | https://github.com/apache/airflow/releases/tag/3.1.7 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 9. 安全/权限坑 · 来源证据：Apache Airflow 3.1.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.1.8\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3437fcfc89ff40a0ba17b7e5a5d8aa2c | https://github.com/apache/airflow/releases/tag/3.1.8 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 安全/权限坑 · 来源证据：Apache Airflow 3.2.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.2.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d18a498a98ed48f0bb3f813aaa554aea | https://github.com/apache/airflow/releases/tag/3.2.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 11. 安全/权限坑 · 来源证据：Apache Airflow 3.2.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.2.1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_41889eab2c0240bbb0bd010262d41346 | https://github.com/apache/airflow/releases/tag/3.2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：Apache Airflow Ctl (airflowctl) 0.1.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow Ctl (airflowctl) 0.1.2\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_df5b495084624a899a4674d4b0193ec7 | https://github.com/apache/airflow/releases/tag/airflow-ctl/0.1.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：Apache Airflow Helm Chart 1.19.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow Helm Chart 1.19.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0f5ecc599d634c1daa9ee6c9f2434849 | https://github.com/apache/airflow/releases/tag/helm-chart/1.19.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：Apache Airflow Helm Chart 1.20.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow Helm Chart 1.20.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c13fe02283094cffa9e186716cc8dcf5 | https://github.com/apache/airflow/releases/tag/helm-chart/1.20.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：Apache Airflow Helm Chart 1.21.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow Helm Chart 1.21.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d29213d0ae2441e8907f407d8dc9b861 | https://github.com/apache/airflow/releases/tag/helm-chart/1.21.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：airflow-ctl/0.1.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：airflow-ctl/0.1.3\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9096523c7ba541c6ac1b6b926d6f6bc0 | https://github.com/apache/airflow/releases/tag/airflow-ctl/0.1.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：edge3: upgrade from 1.x silently leaves schema stale — `BaseDBManager.upgradedb` stamps `alembic_version_edge3` to head…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：edge3: upgrade from 1.x silently leaves schema stale — `BaseDBManager.upgradedb` stamps `alembic_version_edge3` to head without running migrations\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2bc80550929a49ddbce05c557bb225e0 | https://github.com/apache/airflow/issues/66524 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:33884891 | https://github.com/apache/airflow | issue_or_pr_quality=unknown\n\n## 19. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:33884891 | https://github.com/apache/airflow | release_recency=unknown\n\n\n",
"markdown_key": "airflow",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:33884891",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/apache/airflow"
},
{
"evidence_id": "art_228f488f292b41bba44bc96c8f1b02e3",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/apache/airflow#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "airflow 说明书",
"toc": [
"https://github.com/apache/airflow 项目说明书",
"目录",
"Project Introduction",
"Overview",
"Core Architecture",
"DAG-Based Workflow Model",
"Providers Ecosystem",
"Version Information",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "2e886a4dac7e35c453767e4ef7b8e05fc6adb964",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"Dockerfile",
"README.md",
"uv.lock",
"docs/README.md",
"docs/images/documentation_architecture.py"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# simple-auth-manager-ui - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 simple-auth-manager-ui 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.github/skills/aip-user-stories/SKILL.md`, `.github/skills/airflow-translations/SKILL.md`, `.github/skills/maintainer-review/SKILL.md`, `.github/skills/pr-stats/SKILL.md` 等 Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.github/skills/aip-user-stories/SKILL.md`, `.github/skills/airflow-translations/SKILL.md`, `.github/skills/maintainer-review/SKILL.md`, `.github/skills/pr-stats/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `pip install 'apache-airflow==3.2.0' \\` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `pip install 'apache-airflow[postgres,google]==3.2.0' \\` 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：仅建议沙盒试装\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：仅建议沙盒试装\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.github/skills/aip-user-stories/SKILL.md`, `.github/skills/airflow-translations/SKILL.md`, `.github/skills/maintainer-review/SKILL.md`, `.github/skills/pr-stats/SKILL.md` 等 Claim：`clm_0003` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.github/skills/aip-user-stories/SKILL.md`, `.github/skills/airflow-translations/SKILL.md`, `.github/skills/maintainer-review/SKILL.md`, `.github/skills/pr-stats/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.github/skills/aip-user-stories/SKILL.md`, `.github/skills/airflow-translations/SKILL.md`, `.github/skills/maintainer-review/SKILL.md`, `.github/skills/pr-stats/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.github/skills/aip-user-stories/SKILL.md`, `.github/skills/airflow-translations/SKILL.md`, `.github/skills/maintainer-review/SKILL.md`, `.github/skills/pr-stats/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0006` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0007` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.github/skills/aip-user-stories/SKILL.md`, `.github/skills/airflow-translations/SKILL.md`, `.github/skills/maintainer-review/SKILL.md`, `.github/skills/pr-stats/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：11907\n- 重要文件覆盖：40/11907\n- 证据索引条目：80\n- 角色 / Skill 条目：6\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 simple-auth-manager-ui 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 simple-auth-manager-ui 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 simple-auth-manager-ui 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 6 个角色 / Skill / 项目文档条目。\n\n- **aip-user-stories**（skill）：Generate verified recipe playbooks from AIPs with PR implementations post mode , or speculative user stories from AIPs without implementations pre mode . Use when the user provides an AIP URL or AIP content, optionally with PR URLs and file paths. 激活提示：当用户任务与“aip-user-stories”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.github/skills/aip-user-stories/SKILL.md`\n- **airflow-translations**（skill）： 激活提示：当用户任务与“airflow-translations”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.github/skills/airflow-translations/SKILL.md`\n- **maintainer-review**（skill）： 激活提示：当用户任务与“maintainer-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.github/skills/maintainer-review/SKILL.md`\n- **pr-stats**（skill）： 激活提示：当用户任务与“pr-stats”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.github/skills/pr-stats/SKILL.md`\n- **pr-triage**（skill）： 激活提示：当用户任务与“pr-triage”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.github/skills/pr-triage/SKILL.md`\n- **prepare-providers-documentation**（skill）： 激活提示：当用户任务与“prepare-providers-documentation”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.github/skills/prepare-providers-documentation/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Documentation configuration**（documentation）： Database\n CLI --> Database\n API --> Database\n Scheduler --> Database\n Scheduler --> Executor\n Executor --> Workers\n Workers --> Database\n Triggerer --> Database\n \n style Database fill:#f9f,stroke:#333,stroke-width:2px\n```\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n\n## DAG-Based Workflow Model\n\nAt the heart of Airflow is the **DAG (Directed Acyclic Graph)** concept. A DAG represents a collection of tasks with defined dependencies, arranged in a way that reflects the logical flow of work.\n\n### Key DAG Properties\n\n| Property | Description |\n|----------|-------------|\n| **Directed** | Tasks have explicit dependencies (upstream/downstream relationships) |\n| **Acyclic** | No circular dependencies; workflows flow in one direction |\n| **Graph** | Complex dependency structures are supported |\n\n### Default Connections\n\nAirflow ships with pre-configured connection definitions for common integrations:\n\n| Connection ID | Type | Default Configuration |\n|---------------|------|----------------------|\n| `facebook_default` | facebook_social | Facebook Ad account credentials |\n| `fs_default` | fs | Filesystem path `/` |\n| `ftp_default` | ftp | localhost:21, SSH key auth |\n| `google_cloud_default` | google_cloud_platform | Default GCP schema |\n| `hive_cli_default` | hive_cli | localhost:10000, Beeline mode |\n| `hiveserver2_default` | hiveserver2 | localhost:10000 |\n| `http_default` | http | https://www.httpbin.org/ |\n| `gremlin_default` | gremlin | gremlin:8182 |\n\n资料来源：[airflow-core/src/airflow/utils/db.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/utils/db.py)\n\n## Providers Ecosystem\n\nApache Airflow's functionality is extended through **Providers** — packages that integrate Airflow with external services and systems.\n\n```mermaid\ngraph LR\n Airflow[\"Apache Airflow Core\"] --> Providers[\"Providers\"]\n Providers --> Google[\"Google Cloud Provider\"]\n Providers --> AWS[\"Amazon Provider\"]\n Providers --> Azure[\"Microsoft Azure Provider\"]\n Providers --> Edge3[\"Edge3 Provider\"]\n Providers --> Others[\"Other Providers\"]\n```\n\n### Provider Management\n\nProviders can be discovered and managed through the Airflow CLI:\n\n```bash\nairflow providers [list|get|widgets|sensors|hooks|executors]\n```\n\n### Key Provider Features\n\n| Feature | Description |\n|---------|-------------|\n| **Hooks** | Interfaces to external systems for connection management |\n| **Operators** | Pre-built task templates for common operations |\n| **Sensors** | Tasks that wait for external conditions |\n| **Transfers** | Tasks for moving data between systems |\n\n资料来源：[PROVIDERS.rst](https://github.com/apache/airflow/blob/main/PROVIDERS.rst)\n\n## Version Information\n\nThe Airflow version is managed centrally and can be accessed programmatically:\n\n```python\n# airflow-core/src/airflow/version.py\nversion = \"2.11.0\"\n```\n\n资料来源：[airflow-core/src/airflow/version.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/version.py)\n\n## Installation Methods\n\nAirflow supports multiple installation approaches to suit different environments and use cases.\n\n| Method | Use Case | Command/Config |\n|--------|----------|----------------|\n| **PyPI** | Standard installation | `pip install apache-airflow` |\n| **Sources** | Development/contribution | Clone repository and install |\n| **Providers from sources** | Testing provider changes | Breeze commands |\n| **Constraints** | Reproducible builds | Use constraints files |\n\n资料来源：[INSTALLING.md](https://github.com/apache/airflow/blob/main/INSTALLING.md)\n\n### Installing Specific Versions\n\nThe `--use-airflow-version` option provides flexibility for version installation:\n\n| Version Specifier | Behavior |\n|-------------------|----------|\n| `none` | Skip Airflow installation |\n| `wheel` | Install from local `dist/` folder |\n| `sdist` | Install from source distribution |\n| `owner/repo:branch` | Install from GitHub repository |\n| `PR_NUMBER` | Install from a Pull Request |\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/common_options.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/common_options.py)\n\n## Vendored Dependencies\n\nAirflow maintains a `_vendor` package for dependencies that need special handling:\n\n```mermaid\ngraph TD\n Vendor[\"_vendor Package\"] --> License[\"Move to licenses/ folder\"]\n Vendor --> Remove[\"Remove README/supporting files\"]\n Vendor --> Requirements[\"Add to pyproject.toml\"]\n Vendor --> Fixes[\"Re-apply historical fixes\"]\n```\n\n### Vendoring Process\n\n1. Update `vendor.md` with library, version, and SHA256 hash\n2. Remove old files and directories\n3. Move LICENSE files to `licenses/` folder\n4. Add requirements to `pyproject.toml` with appropriate comments\n5. Re-apply any necessary cherry-picked fixes\n\n资料来源：[airflow-core/src/airflow/_vendor/README.md](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/_vendor/README.md)\n\n## Development Environment (Breeze)\n\nThe **Breeze** tool is Airflow's primary development environment, providing consistent tooling for testing, building, and development.\n\n### Key Breeze Commands\n\n| Command | Purpose |\n|---------|---------|\n| `breeze sbom update-sbom-information` | Update SBOM information |\n| `breeze workflow run-publish` | Run documentation workflow |\n| `breeze build` | Build Airflow images |\n\n### Breeze Configuration Options\n\n| Option | Description |\n|--------|-------------|\n| `--airflow-version` | Specify Airflow version |\n| `--debian-version` | Select base Debian version |\n| `--docker-cache` | Configure build caching |\n| `--mount-sources` | Control source mounting strategy |\n| `--allow-pre-releases` | Enable pre-release installations |\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/sbom_commands.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/sbom_commands.py)\n\n## CLI Commands Structure\n\nAirflow provides a comprehensive command-line interface organized into logical groups:\n\n```mermaid\ngraph TD\n CLI[\"airflow CLI\"] --> Groups\n Groups --> Config[\"config - View configuration\"]\n Groups --> Info[\"info - Show system info\"]\n Groups --> Plugins[\"plugins - Dump plugin info\"]\n Groups --> Connections[\"connections - Manage connections\"]\n Groups --> Providers[\"providers - Display providers\"]\n Groups --> DAGs[\"dags - Manage DAGs\"]\n Groups --> db_manager[\"db-manager - Database management\"]\n Groups --> rotate_fernet[\"rotate-fernet-key - Rotate keys\"]\n```\n\n### Core CLI Commands\n\n| Command | Function | Purpose |\n|---------|----------|---------|\n| `airflow config` | View configuration | Display current Airflow settings |\n| `airflow info` | System information | Show environment details |\n| `airflow plugins` | Plugin dump | Display loaded plugins |\n| `airflow connections` | Connection management | CRUD operations for connections |\n| `airflow providers` | Provider display | List installed providers |\n| `airflow db-manager` | Database management | External DB manager operations |\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n\n## Dependencies and Requirements\n\n### Generated Dependency Files\n\nThe repository maintains several auto-generated dependency files:\n\n| File | Purpose | Generation Command |\n|------|---------|-------------------|\n| `devel_deps.txt` | Development dependencies | `./dev/get_devel_deps.sh` |\n| `dep_tree.txt` | Full dependency tree | `uv tree --no-dedupe` |\n| `dependency_depth.json` | Dependency depth analysis | Generated by Breeze |\n\n### PyPI README Generation\n\nThe `PYPI_README.md` is automatically generated from the main README using pre-commit hooks defined in `.pre-commit-config.yaml`, ensuring consistency between project documentation and PyPI listings.\n\n资料来源：[generated/README.md](https://github.com/apache/airflow/blob/main/generated/README.md)\n\n## Summary\n\nApache Airflow is a robust, extensible workflow orchestration platform that provides:\n\n- **DAG-based workflow definition** for complex pipeline management\n- **Extensible architecture** through providers and plugins\n- **Multiple deployment options** from development to production\n- **Comprehensive CLI and UI** for monitoring and management\n- **Strong ecosystem** of integrations with major cloud providers and services\n\nThe platform's design prioritizes **dynamic pipeline generation**, **extensible operator library**, and **robust scheduling capabilities**, making it the go-to choice for data engineering teams worldwide.\n\n---\n\n\n\n## Core Concepts\n\n### 相关页面\n\n相关主题：[Scheduler and Executor Architecture](#scheduler-executor), [Data Flow and State Management](#data-flow-xcom)\n\n\nRelated Source Files\n\nThe following source files are used to generate this documentation:\n\n- [airflow-core/src/airflow/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n- [airflow-core/src/airflow/cli/commands/config_command.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/commands/config_command.py)\n- [airflow-core/src/airflow/utils/db.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/utils/db.py)\n- [providers/google/src/airflow/providers/google/cloud/hooks/cloud_composer.py](https://github.com/apache/airflow/blob/main/providers/google/src/airflow/providers/google/cloud/hooks/cloud_composer.py)\n- [generated/README.md](https://github.com/apache/airflow/blob/main/generated/README.md)\n\n\n# Core Concepts\n\nApache Airflow is an open-source workflow orchestration platform designed to programmatically author, schedule, and monitor complex data pipelines. The platform provides a robust framework for defining workflows as Directed Acyclic Graphs (DAGs), enabling organizations to automate and manage data processing workflows at scale.\n\n## DAG (Directed Acyclic Graph)\n\nThe DAG is the fundamental building block of Airflow. It represents a collection of tasks with defined dependencies, organized in a way that reflects the logical flow of work through the system.\n\n### DAG Structure\n\nA DAG defines the overall structure of a workflow:\n\n- **Nodes**: Represent individual tasks or operations\n- **Edges**: Define dependencies between tasks (task A must complete before task B can start)\n- **No Cycles**: The graph must flow in one direction without circular dependencies\n\n### DAG Commands\n\nAirflow provides comprehensive CLI commands for managing DAGs through the `dag_cli_commands` configuration.\n\n| Command | Purpose |\n|---------|---------|\n| `dags list` | List all DAGs in the environment |\n| `dags details` | Get detailed information about a specific DAG |\n| `dags list-runs` | List all runs for a specific DAG |\n| `dags list-import-errors` | Show DAGs with import errors |\n| `dags report` | Display DagBag loading report |\n| `dags pause` | Pause a DAG from scheduling |\n| `dags unpause` | Resume DAG scheduling |\n| `dags backfill` | Run subsections of a DAG for a date range |\n| `dags test` | Test a DAG execution |\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n### DAG Execution Parameters\n\nWhen creating a backfill operation, the following parameters can be configured:\n\n| Parameter | Description |\n|-----------|-------------|\n| `dag_id` | The identifier of the DAG to backfill |\n| `from_date` | Start date for the backfill range |\n| `to_date` | End date for the backfill range |\n| `run_conf` | Configuration to pass to the DAG run |\n| `run_backwards` | Execute DAG runs in reverse chronological order |\n| `max_active_runs` | Maximum number of concurrent active DAG runs |\n| `reprocess_behavior` | How to handle already-processed runs |\n| `run_on_latest_version` | Whether to use the latest DAG version |\n| `dry_run` | Execute without making changes |\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n## Tasks and Task Instances\n\n### Task Instance States\n\nA task instance represents a specific execution of a task within a DAG run. Each task instance progresses through various states during its lifecycle.\n\n```mermaid\ngraph TD\n A[None] --> B[Scheduled]\n B --> C[Queued]\n C --> D[Running]\n D --> E{Success/Failed/Skipped}\n E --> F[Success]\n E --> G[Failed]\n E --> H[Skipped]\n D --> I[Upstream Failed]\n F --> J[Complete]\n G --> J\n H --> J\n I --> J\n```\n\n### Task Instance Management\n\nThe Airflow UI provides functionality for clearing task instances, allowing operators to re-execute tasks that may have failed or need to be reprocessed. The `ClearTaskInstanceConfirmationDialog` component handles the confirmation workflow for this operation.\n\nKey attributes displayed when clearing a task instance:\n\n- Current state of the task\n- Start date (shown as relative time)\n- User who executed the task (or \"unknown user\" if unavailable)\n\n## DAG Runs\n\nA DAG Run represents an individual execution of an entire DAG at a specific point in time. Each DAG run has:\n\n- **Run ID**: Unique identifier for the run\n- **State**: Current state (running, success, failed)\n- **Execution Date**: The logical date/time the DAG was scheduled to run\n- **Start/End Date**: Actual execution timestamps\n- **Configuration**: Run-specific configuration parameters\n\n### Listing DAG Runs\n\nThe `list-runs` command supports filtering by:\n\n- **State**: Filter runs by their state (running, success, failed)\n- **No Backfill**: Exclude backfill runs from results\n- **Start Date**: Filter runs executed after a specific date\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n## Variables\n\nAirflow Variables provide a mechanism for storing and retrieving arbitrary content or settings as simple key-value pairs. Variables are encrypted when the `fernet_key` is configured.\n\n### Variable Commands\n\n| Command | Purpose |\n|---------|---------|\n| `variables list` | List all variables |\n| `variables get` | Get a specific variable value |\n| `variables set` | Set a variable value |\n| `variables delete` | Delete a variable |\n| `variables export` | Export all variables to stdout |\n| `variables import` | Import variables from a file |\n\n### Variable Options\n\n| Option | Description |\n|--------|-------------|\n| `VAR` | Variable key name |\n| `VAR_VALUE` | Value to set |\n| `VAR_DESCRIPTION` | Optional description |\n| `SERIALIZE_JSON` | Serialize value as JSON |\n| `DESERIALIZE_JSON` | Deserialize JSON value |\n| `DEFAULT` | Default value if variable doesn't exist |\n| `VAR_IMPORT` | Path to import file |\n| `VAR_ACTION_ON_EXISTING_KEY` | Action for existing keys |\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n## Connections\n\nAirflow Connections store credentials and configuration information needed to connect to external systems. Default connections are automatically created during initialization.\n\n### Default Connection Types\n\nThe `db.py` utility creates several default connections:\n\n| Connection ID | Type | Purpose |\n|---------------|------|---------|\n| `facebook_social` | facebook_social | Facebook social authentication |\n| `fs_default` | fs | File system operations |\n| `ftp_default` | ftp | FTP server access |\n| `google_cloud_default` | google_cloud_platform | GCP default credentials |\n| `gremlin_default` | gremlin | Gremlin graph database |\n| `hive_cli_default` | hive_cli | Hive command-line interface |\n| `hiveserver2_default` | hiveserver2 | HiveServer2 JDBC connections |\n| `http_default` | http | Generic HTTP endpoints |\n| `iceberg_default` | iceberg | Apache Iceberg catalog |\n\nSource: [airflow-core/src/airflow/utils/db.py](airflow-core/src/airflow/utils/db.py)\n\n### Connection CLI Commands\n\n| Command | Purpose |\n|---------|---------|\n| `connections list` | List all connections |\n| `connections add` | Add a new connection |\n| `connections delete` | Delete a connection |\n| `connections get` | Get connection details |\n| `connections edit` | Edit an existing connection |\n\n## Assets\n\nAssets represent data sources or destinations in Airflow. They can be associated with DAGs to create data-aware scheduling.\n\n### Asset Commands\n\n| Command | Purpose |\n|---------|---------|\n| `assets list` | List all assets |\n| `assets details` | Show asset details |\n| `assets materialze` | Materialize an asset |\n\n### Asset Details Parameters\n\n| Parameter | Description |\n|-----------|-------------|\n| `ASSET_ALIAS` | Alias name for the asset |\n| `ASSET_NAME` | Name of the asset |\n| `ASSET_URI` | URI identifying the asset |\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n## Configuration Changes in Airflow 3.0\n\nAirflow 3.0 introduces several configuration changes that affect default behavior.\n\n### Default Behavior Changes\n\n| Configuration | Old Default | New Default |\n|---------------|-------------|-------------|\n| `catchup_by_default` | `True` | `False` |\n| `create_cron_data_intervals` | `True` | `False` |\n| `create_delta_data_intervals` | `True` | `False` |\n\nSource: [airflow-core/src/airflow/cli/commands/config_command.py](airflow-core/src/airflow/cli/commands/config_command.py)\n\n### Configuration Renames\n\nSeveral scheduler configurations have been renamed:\n\n| Old Name | New Name |\n|----------|----------|\n| `scheduler.processor_poll_interval` | `scheduler.scheduler_idle_sleep_time` |\n| `scheduler.deactivate_stale_dags_interval` | `scheduler.parsing_cleanup_interval` |\n| `scheduler.statsd_on` | `metrics.statsd_on` |\n| `scheduler.max_threads` | `dag_processor.parsing_processes` |\n\nSource: [airflow-core/src/airflow/cli/commands/config_command.py](airflow-core/src/airflow/cli/commands/config_command.py)\n\n### Catchup Behavior Change\n\nIn Airflow 3.0, DAGs without explicit `catchup` parameter definition will not catch up by default. This represents a change from Airflow 2.x behavior. Organizations relying on catchup behavior should set `catchup = True` in their DAG definitions or configure:\n\n```ini\n[scheduler]\ncatchup_by_default = True\n```\n\n## Providers\n\nAirflow Providers extend the core functionality by integrating with external services and systems.\n\n### Provider Information Commands\n\n| Command | Purpose |\n|---------|---------|\n| `providers list` | List all installed providers |\n| `providers details` | Show provider details |\n| `providers hooks` | List registered provider hooks |\n| `providers triggers` | List registered provider triggers |\n| `providers executors` | Get information about executors |\n| `providers secrets` | Get information about secrets backends |\n| `providers connections` | Get connection information |\n| `providers notifications` | Get notification information |\n| `providers extra-links` | List extra links from providers |\n| `providers widgets` | List connection form widgets |\n| `providers behaviors` | Get connection types with custom behaviors |\n| `providers logging` | Get task logging handlers |\n| `providers auth-managers` | Get auth managers information |\n| `providers configs` | Get provider configuration |\n| `providers lazy-loaded` | Check lazy loading status |\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n## Dependency Management\n\n### Dependency Tree\n\nAirflow's dependency tree defines the module structure and relationships between packages. This information is generated and maintained in the repository for dependency analysis.\n\n| File | Purpose |\n|------|---------|\n| `dep_tree.txt` | Complete dependency tree of Airflow |\n| `dependency_depth.json` | Dependency depth analysis |\n\nGenerated using:\n```bash\nuv tree --no-dedupe > /opt/airflow/generated/dep_tree.txt\n```\n\nSource: [generated/README.md](generated/README.md)\n\n## Workflow Architecture\n\n```mermaid\ngraph TD\n subgraph \"Authoring\"\n A[Define DAG] --> B[Define Tasks]\n B --> C[Set Dependencies]\n end\n \n subgraph \"Scheduling\"\n D[Scheduler] --> E{Parse DAGs}\n E --> F[DAG Run Created]\n F --> G[Task Instances Queued]\n end\n \n subgraph \"Execution\"\n G --> H[Executor]\n H --> I[Worker]\n I --> J[Task Execution]\n end\n \n subgraph \"Monitoring\"\n J --> K[Update State]\n K --> L[UI/Webserver]\n L --> M[Logs & Metrics]\n end\n \n G -->|Async Operations| N[Async Commands]\n N --> O[Cloud Composer Environments]\n```\n\n## Security Features\n\n### Fernet Key Rotation\n\nAirflow supports rotating Fernet encryption keys to maintain security of stored credentials and variables:\n\n```bash\nairflow rotate-fernet-key\n```\n\nThis command rotates all encrypted connection credentials and variables.\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n### Configuration Reference\n\nFor secure connections, refer to the official documentation:\nhttps://airflow.apache.org/docs/apache-airflow/stable/howto/secure-connections.html\n\n## Additional CLI Commands\n\n### Info Command\n\nProvides system and environment information:\n\n```bash\nairflow info [--anonymize] [--file-io] [--output OUTPUT] [--verbose]\n```\n\n### Standalone Mode\n\nRuns a complete Airflow instance for testing or development:\n\n```bash\nairflow standalone\n```\n\n### Cheat Sheet\n\nDisplays a quick reference for common Airflow commands:\n\n```bash\nairflow cheat-sheet [--verbose]\n```\n\n### Plugins Command\n\nDump information about loaded plugins:\n\n```bash\nairflow plugins [--output OUTPUT] [--verbose]\n```\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n## Teams (RBAC)\n\nAirflow supports team-based access control with the following operations:\n\n### Team Commands\n\n| Command | Purpose |\n|---------|---------|\n| `teams create` | Create a new team |\n| `teams delete` | Delete a team |\n\n### Team Creation Requirements\n\n- Team names must be 3-50 characters long\n- Only alphanumeric characters, hyphens, and underscores are allowed\n\nSource: [airflow-core/src/airflow/cli/cli_config.py](airflow-core/src/airflow/cli/cli_config.py)\n\n---\n\n\n\n## Architecture Overview\n\n### 相关页面\n\n相关主题：[Scheduler and Executor Architecture](#scheduler-executor), [REST API](#rest-api)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [airflow-core/docs/img/diagram_basic_airflow_architecture.py](https://github.com/apache/airflow/blob/main/airflow-core/docs/img/diagram_basic_airflow_architecture.py)\n- [airflow-core/docs/img/diagram_distributed_airflow_architecture.py](https://github.com/apache/airflow/blob/main/airflow-core/docs/img/diagram_distributed_airflow_architecture.py)\n- [airflow-core/docs/img/diagram_auth_manager_airflow_architecture.py](https://github.com/apache/airflow/blob/main/airflow-core/docs/img/diagram_auth_manager_airflow_architecture.py)\n- [airflow-core/src/airflow/dag_processing/manager.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/dag_processing/manager.py)\n- [airflow-core/docs/core-concepts/overview.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/core-concepts/overview.rst)\n\n\n# Architecture Overview\n\nApache Airflow is an open-source workflow orchestration platform designed to programmatically author, schedule, and monitor complex data pipelines. The architecture is built around a distributed, scalable design that separates concerns between scheduling, execution, and monitoring.\n\n## Core Architectural Components\n\nAirflow's architecture consists of several key components that work together to manage workflow execution across distributed environments.\n\n### Component Overview\n\n| Component | Purpose | Key Files |\n|-----------|---------|-----------|\n| **Scheduler** | Triggers scheduled tasks and submits tasks to executors | `airflow-core/src/airflow/dag_processing/manager.py` |\n| **Executor** | Executes tasks distributed across workers | Configured via `airflow.cfg` |\n| **Web Server** | Provides UI for monitoring and management | `airflow/ui/` |\n| **Database** | Stores DAGs, connections, variables, and execution history | Configured via `airflow.cfg` |\n| **DAG Processor** | Parses and processes DAG files | `airflow-core/src/airflow/dag_processing/manager.py` |\n\n资料来源：[airflow-core/docs/core-concepts/overview.rst]()\n\n## Basic Architecture\n\nThe basic Airflow architecture runs all components on a single machine, suitable for development, testing, and small-scale deployments.\n\n```mermaid\ngraph TB\n subgraph \"Airflow Core\"\n WS[Web Server] <--> DB[(Metadata Database)]\n SCH[Scheduler] <--> DB\n SCH <--> EX[Executor]\n EX <--> DB\n DP[DAG Processor] <--> DB\n end\n \n subgraph \"DAG Storage\"\n DAG[DAG Files] --> DP\n end\n \n WS -->|UI Access| Users\n SCH -->|Schedule| DAG\n```\n\nThis single-node deployment includes all core components running together, with the scheduler handling task scheduling and the web server providing the user interface.\n\n资料来源：[airflow-core/docs/img/diagram_basic_airflow_architecture.py]()\n\n## Distributed Architecture\n\nFor production environments, Airflow supports a distributed architecture where components can scale independently.\n\n```mermaid\ngraph TB\n subgraph \"Web Tier\"\n WS1[Web Server 1]\n WS2[Web Server 2]\n LB[Load Balancer]\n end\n \n subgraph \"Scheduler Tier\"\n SCH1[Scheduler 1]\n SCH2[Scheduler 2]\n end\n \n subgraph \"Worker Tier\"\n W1[Worker 1]\n W2[Worker 2]\n W3[Worker N]\n end\n \n subgraph \"Metadata\"\n DB[(PostgreSQL/MySQL)]\n REDIS[(Redis/Message Broker)]\n end\n \n LB --> WS1\n LB --> WS2\n WS1 <--> DB\n WS2 <--> DB\n SCH1 <--> DB\n SCH2 <--> DB\n SCH1 --> REDIS\n SCH2 --> REDIS\n REDIS --> W1\n REDIS --> W2\n REDIS --> W3\n```\n\n### Scalability Features\n\nThe distributed architecture provides:\n\n- **Horizontal Scaling**: Multiple schedulers and web servers can run in parallel\n- **Worker Flexibility**: Workers can be added or removed based on workload\n- **High Availability**: No single point of failure for critical components\n- **Isolation**: DAG processing is separated from execution\n\n资料来源：[airflow-core/docs/img/diagram_distributed_airflow_architecture.py]()\n\n## DAG Processing Architecture\n\nThe DAG Processor is responsible for reading, parsing, and validating DAG files before the Scheduler can schedule their tasks.\n\n### Processing Pipeline\n\n```mermaid\ngraph LR\n A[DAG Files] -->|Read| B[DAG Processor]\n B -->|Parse| C[DAG Bag]\n C -->|Validate| D[Valid DAGs]\n D -->|Sync| E[(Metadata DB)]\n B -->|Log| F[Processor Logs]\n```\n\n### Key Processing Manager\n\nThe `DagFileProcessorManager` handles:\n\n1. **File Discovery**: Scanning DAG directories for Python files\n2. **Parsing**: Converting Python DAG definitions into Airflow DAG objects\n3. **Serialization**: Storing parsed DAGs in the database\n4. **Callback Handling**: Processing DAG-level callbacks\n\n```python\n# Simplified from airflow-core/src/airflow/dag_processing/manager.py\nclass DagFileProcessorManager:\n def process_file(self, filepath):\n \"\"\"Process a single DAG file and return list of DAGs.\"\"\"\n dagbag = DagBag(dag_folder=filepath)\n for dag in dagbag.dags.values():\n dag.sync_to_db()\n return dagbag.dags\n```\n\n资料来源：[airflow-core/src/airflow/dag_processing/manager.py]()\n\n## Authentication and Authorization Architecture\n\nAirflow supports pluggable authentication through the Auth Manager interface, allowing integration with various authentication backends.\n\n```mermaid\ngraph TB\n U[User] -->|Auth Request| AM[Auth Manager]\n AM -->|User Lookup| DB[(Metadata DB)]\n AM -->|Backend Check| BE[External Backend OIDC/SAML/LDAP]\n BE -->|Validation| AM\n AM -->|Permissions| PERMS[Permission Set]\n PERMS -->|Grant Access| RES[Resources]\n```\n\n### Auth Manager Components\n\n| Component | Responsibility |\n|-----------|----------------|\n| `AuthManager` | Core interface for authentication |\n| `FastAPIAuthManager` | Default implementation for Airflow 3.0+ |\n| `Backends` | External identity providers |\n\nThe auth manager architecture enables:\n\n- Integration with enterprise identity providers\n- Role-based access control (RBAC)\n- Fine-grained permissions on DAGs and tasks\n\n资料来源：[airflow-core/docs/img/diagram_auth_manager_airflow_architecture.py]()\n\n## Configuration Management\n\nAirflow 3.0 introduced significant configuration changes from Airflow 2.x:\n\n### Configuration Changes Summary\n\n| Old Parameter | New Parameter | Section |\n|---------------|---------------|---------|\n| `processor_poll_interval` | `scheduler_idle_sleep_time` | scheduler |\n| `deactivate_stale_dags_interval` | `parsing_cleanup_interval` | scheduler |\n| `statsd_on` | `statsd_on` | metrics |\n| `max_threads` | `parsing_processes` | dag_processor |\n| `create_cron_data_intervals` | unchanged | scheduler |\n| `create_delta_data_intervals` | unchanged | scheduler |\n\n### Default Behavior Changes\n\nIn Airflow 3.0, the default for `catchup_by_default` is `False`, meaning DAGs without explicit catchup configuration will not backfill past runs.\n\n资料来源：[airflow-core/src/airflow/cli/commands/config_command.py]()\n\n## Executor Architecture\n\nAirflow supports multiple executor types for different deployment scenarios:\n\n| Executor | Use Case | Scalability |\n|----------|----------|-------------|\n| **LocalExecutor** | Single machine, development | Limited |\n| **SequentialExecutor** | Debugging, minimal resources | None |\n| **CeleryExecutor** | Production, distributed | High |\n| **KubernetesExecutor** | Containerized environments | Very High |\n| **RayExecutor** | Ray cluster integration | High |\n\n### Executor Selection\n\nExecutors are configured in `airflow.cfg`:\n\n```ini\n[core]\nexecutor = KubernetesExecutor\n```\n\n资料来源：[airflow-core/docs/core-concepts/overview.rst]()\n\n## CLI and Command Architecture\n\nThe Airflow CLI provides a comprehensive command-line interface for managing Airflow components:\n\n### Command Structure\n\n```\nairflow\n├── config # View configuration\n├── connections # Manage connections\n├── dags # DAG management\n├── db-manager # Database management\n├── info # System information\n├── plugins # Plugin dump\n├── providers # Provider information\n├── rotate-fernet-key # Credential rotation\n├── standalone # All-in-one mode\n└── version # Version display\n```\n\n### Key CLI Commands\n\n| Command | Purpose |\n|---------|---------|\n| `airflow dags backfill` | Run historical DAG executions |\n| `airflow dags list-runs` | List DAG run instances |\n| `airflow connections list` | Show configured connections |\n| `airflow providers list` | Display loaded providers |\n| `airflow rotate-fernet-key` | Rotate encryption keys |\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py]()\n\n## Provider Architecture\n\nProviders extend Airflow's capabilities by integrating with external systems:\n\n### Provider Categories\n\n- **Cloud Providers**: Google Cloud, AWS, Azure\n- **Service Integrations**: HTTP, SSH, GraphQL\n- **Database Connectors**: PostgreSQL, MySQL, Snowflake\n- **Data Processing**: Spark, Databricks, dbt\n\n### Provider Communication\n\n```mermaid\ngraph LR\n A[Airflow Task] -->|Hook| B[Provider Hook]\n B -->|API| C[External Service]\n C -->|Response| B\n B -->|Result| A\n```\n\nProviders are discovered and managed through the `airflow providers` CLI commands.\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py]()\n\n## Installation Modes\n\n### Docker Installation\n\nAirflow provides official Docker images with multiple variants:\n\n| Image Type | Description | Size |\n|------------|-------------|------|\n| `apache/airflow:latest` | Latest stable, default Python | ~1GB |\n| `apache/airflow:3.x.x` | Versioned release | ~1GB |\n| `apache/airflow:slim-latest` | Minimal installation | ~500MB |\n\n### Installation Methods\n\n```bash\n# Basic installation\npip install 'apache-airflow==3.2.0' \\\n --constraint \"https://raw.githubusercontent.com/apache/airflow/constraints-3.2.0/constraints-3.10.txt\"\n\n# With extras\npip install 'apache-airflow[postgres,google]==3.2.0' \\\n --constraint \"https://raw.githubusercontent.com/apache/airflow/constraints-3.2.0/constraints-3.10.txt\"\n```\n\n资料来源：[docker-stack-docs/README.md]()\n资料来源：[generated/PYPI_README.md]()\n\n## Default Connections\n\nAirflow ships with pre-configured default connections for common integrations:\n\n| Connection ID | Type | Purpose |\n|---------------|------|---------|\n| `google_cloud_default` | google_cloud_platform | GCP resources |\n| `fs_default` | fs | File system access |\n| `http_default` | http | HTTP endpoints |\n| `ftp_default` | ftp | FTP/SFTP transfers |\n| `hive_cli_default` | hive_cli | Hive CLI connections |\n| `hiveserver2_default` | hiveserver2 | HiveServer2 connections |\n\n资料来源：[airflow-core/src/airflow/utils/db.py]()\n\n## Development and Testing Architecture\n\nThe Breeze development environment provides an integrated development setup:\n\n### Breeze Features\n\n- Pre-configured Docker-based development environment\n- Multiple Python version support\n- Integration testing framework\n- Static code analysis tools\n- Documentation building capabilities\n\n### Development Commands\n\n```bash\n# Start development shell\nbreeze shell\n\n# Run tests\nbreeze test\n\n# Build documentation\nbreeze build-docs\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/developer_commands.py]()\n\n## Shared Distribution Architecture\n\nAirflow supports shared code distributions for cross-project functionality:\n\n### Configuration\n\n```toml\n[tool.airflow]\nshared_distributions = [\n \"apache-airflow-shared-timezones\",\n]\n```\n\nShared distributions are:\n\n1. Defined in `pyproject.toml` under `tool.airflow`\n2. Symlinked via `_shared` folder\n3. Automatically synchronized by pre-commit hooks\n\n资料来源：[shared/README.md]()\n\n## MyPy Type Checking Integration\n\nAirflow provides custom MyPy plugins for enhanced type checking:\n\n### Available Plugins\n\n| Plugin | Purpose |\n|--------|---------|\n| `airflow_mypy.plugins.decorators` | Type checking for Airflow decorators |\n| `airflow_mypy.plugins.outputs` | Type inference for XCom arguments |\n\n### Configuration\n\n```ini\n[mypy]\nplugins = airflow_mypy.plugins.decorators, airflow_mypy.plugins.outputs\n```\n\nOr in `pyproject.toml`:\n\n```toml\n[tool.mypy]\nplugins = [\"airflow_mypy.plugins.decorators\", \"airflow_mypy.plugins.outputs\"]\n```\n\n资料来源：[dev/mypy/README.md]()\n\n## Build and Release Architecture\n\n### SBOM (Software Bill of Materials)\n\nAirflow generates SBOMs for security and compliance tracking:\n\n- Dependency tree generation via `uv tree`\n- Dependency depth analysis\n- Version-specific SBOM files\n\n### Documentation Build\n\nThe documentation system includes:\n\n- Sphinx-based documentation generation\n- Pagefind search integration\n- Multi-version documentation support\n- Third-party inventory tracking\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/sbom_commands.py]()\n资料来源：[devel-common/src/sphinx_exts/pagefind_search/README.md]()\n\n## Summary\n\nApache Airflow's architecture is designed for scalability, reliability, and extensibility:\n\n- **Modular Design**: Components can be scaled independently\n- **Pluggable Executors**: Support for various execution backends\n- **Extensible Providers**: Integration with external systems\n- **Production-Ready**: High availability and monitoring capabilities\n- **Developer-Friendly**: Comprehensive tooling and documentation\n\nThe architecture supports deployments from single-machine development environments to large-scale, distributed production systems handling thousands of workflows.\n\n---\n\n\n\n## Scheduler and Executor Architecture\n\n### 相关页面\n\n相关主题：[Architecture Overview](#architecture-overview), [Kubernetes Deployment](#kubernetes-deployment)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [airflow-core/src/airflow/jobs/scheduler_job_runner.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/jobs/scheduler_job_runner.py)\n- [airflow-core/src/airflow/executors/base_executor.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/executors/base_executor.py)\n- [airflow-core/src/airflow/executors/local_executor.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/executors/local_executor.py)\n- [airflow-core/src/airflow/executors/executor_loader.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/executors/executor_loader.py)\n- [airflow-core/src/airflow/dag_processing/collection.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/dag_processing/collection.py)\n- [airflow-core/src/airflow/timetables/base.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/timetables/base.py)\n- [airflow-core/docs/administration-and-deployment/scheduler.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/administration-and-deployment/scheduler.rst)\n\n\n# Scheduler and Executor Architecture\n\nApache Airflow's scheduling and execution system is a distributed architecture that coordinates the parsing of Directed Acyclic Graphs (DAGs), scheduling of task instances, and execution of tasks across worker nodes. This document provides a comprehensive overview of how the Scheduler and Executors interact to process and execute workflows.\n\n## Overview\n\nThe Scheduler and Executor architecture in Apache Airflow consists of several interconnected components that work together to transform DAG definitions into executed tasks. The system separates concerns between **scheduling decisions** (when to run tasks based on dependencies and timetable data) and **execution** (how and where tasks actually run).\n\n```mermaid\ngraph TD\n A[DAG Files] --> B[DAG Processor]\n B --> C[DAG Parsing]\n C --> D[Serialized DAGs]\n D --> E[Metadata Database]\n E --> F[Scheduler]\n F --> G[Executor]\n G --> H[Workers]\n H --> I[Task Execution]\n I --> E\n```\n\n## Scheduler Architecture\n\n### Scheduler Process\n\nThe Scheduler is a long-running daemon process that continuously monitors DAGs and schedules task instances for execution. It is configured through CLI commands defined in the system.\n\n**CLI Configuration:**\n\nThe scheduler command is defined in `cli_config.py` and accepts multiple configuration parameters for controlling its behavior.\n\n| Parameter | Purpose | Default |\n|-----------|---------|---------|\n| `--num-runs` | Number of scheduler runs before exiting | -1 (infinite) |\n| `--only-idle` | Only schedule DAGs with idle tasks | False |\n| `--pid` | PID file location | None |\n| `--daemon` | Run as daemon process | False |\n| `--stdout` | stdout log file | None |\n| `--stderr` | stderr log file | None |\n| `--log-file` | Log file path | None |\n| `--skip-serve-logs` | Skip serving logs | False |\n| `--dev` | Development mode | False |\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n\n### Job Lifecycle\n\nThe Scheduler creates and manages Jobs that represent its operational cycles. Each scheduler run follows a specific lifecycle that involves database interactions.\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI Component\n participant JobRunner as JobRunner\n participant DB as Database\n participant TaskRunner as TaskRunner\n\n activate CLI\n CLI->>JobRunner: Create Job\n activate JobRunner\n JobRunner->>DB: Create Job Record\n activate DB\n DB-->>JobRunner: Job Created\n JobRunner->>DB: Create Session\n DB->>JobRunner: Session\n deactivate DB\n JobRunner->>CLI: Job Created\n deactivate JobRunner\n CLI->>JobRunner: Execute Job\n activate JobRunner\n par\n JobRunner->>DB: Schedule Tasks\n activate DB\n DB-->>JobRunner: Scheduled Tasks\n deactivate DB\n and\n JobRunner->>JobRunner: Process DAG Files\n end\n JobRunner->>DB: Perform Heartbeat\n activate DB\n DB->>JobRunner: Heartbeat Response\n JobRunner->>JobRunner: Heartbeat Callback\n DB-->>JobRunner: Close Session\n deactivate DB\n JobRunner->>CLI: Job Completed\n deactivate JobRunner\n deactivate CLI\n```\n\n资料来源：[airflow-core/src/airflow/jobs/JOB_LIFECYCLE.md](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/jobs/JOB_LIFECYCLE.md)\n\n### Scheduler Responsibilities\n\nThe Scheduler performs the following key operations:\n\n1. **DAG Parsing**: Reads DAG files and parses them into Python objects\n2. **Task Scheduling**: Determines which tasks are ready to execute based on dependencies\n3. **DagRun Creation**: Creates DagRun records for scheduled DAG runs\n4. **TaskInstance Creation**: Creates TaskInstance records for tasks to be executed\n5. **Heartbeating**: Maintains its presence and reports health to the database\n\n## Executor Architecture\n\nExecutors are responsible for the actual execution of tasks. Airflow supports multiple executor types, each with different deployment characteristics.\n\n### Executor Types\n\n| Executor | Description | Use Case |\n|----------|-------------|----------|\n| SequentialExecutor | Executes tasks sequentially in the same process | Development/Debugging |\n| LocalExecutor | Executes tasks in parallel processes on a single machine | Single-node deployments |\n| CeleryExecutor | Distributes tasks across multiple machines using Celery | Distributed production deployments |\n| KubernetesExecutor | Creates pods per task in Kubernetes | Kubernetes-native deployments |\n| LocalKubernetesExecutor | Hybrid of Local and Kubernetes executors | Testing/minimal Kubernetes |\n\n### Executor Loader\n\nThe `ExecutorLoader` class is responsible for loading and configuring executors based on Airflow configuration. It supports both simple executor names and complex module paths with optional aliases.\n\n```mermaid\ngraph TD\n A[Executor Config] --> B{ExecutorLoader}\n B --> C{Check Format}\n C -->|Simple Name| D[Load Core Executor]\n C -->|Team:Executor| E[Parse Team Config]\n E --> F[Alias:Module/Name]\n F --> G[Resolve Module Path]\n D --> H[Return ExecutorName]\n G --> H\n```\n\n**Executor Configuration Parsing:**\n\nThe loader parses executor configurations in multiple formats:\n\n- **Simple name**: `SequentialExecutor`, `LocalExecutor`\n- **Module path**: `airflow.executors.local_executor.LocalExecutor`\n- **With alias**: `MyAlias:LocalExecutor`\n- **Team-based**: `team_name:executor_name` or `team_name:alias:executor_name`\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/executors/executor_loader.py)\n\n### Base Executor Interface\n\nAll executors inherit from `BaseExecutor` which defines the standard interface:\n\n| Method | Purpose |\n|--------|---------|\n| `execute_async()` | Execute a single task |\n| `sync()` | Sync state with metadata database |\n| `end()` | Cleanup executor resources |\n| `terminate()` | Force terminate all running tasks |\n| `try_adopt_task_instances()` | Adopt orphaned task instances |\n| `render_slots()` | Render available executor slots |\n\n### Local Executor\n\nThe Local Executor executes tasks in parallel worker processes on a single machine, providing a balance between simplicity and parallelism.\n\n**Key Features:**\n- Configurable parallelism (number of parallel workers)\n- Supports task-level parallelism within a single node\n- Inherits configuration from core executor registry\n- Can be configured with aliases for multi-team deployments\n\n```python\n# Example: Loading LocalExecutor with team configuration\nexecutor_names_per_team.append(\n ExecutorName(\n alias=None, \n module_path=cls.executors[module_or_name], \n team_name=team_name\n )\n)\n```\n\n资料来源：[airflow-core/src/airflow/executors/local_executor.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/executors/local_executor.py)\n\n## Task Scheduling Flow\n\nThe complete task scheduling flow involves multiple stages from DAG definition to task execution:\n\n```mermaid\ngraph LR\n A[DAG File] --> B[DAG Processor]\n B --> C[Parse DAG]\n C --> D[Serialize DAG]\n D --> E[Store in DB]\n E --> F[Scheduler]\n F --> G[Evaluate Timetable]\n G --> H{Check Dependencies}\n H -->|Met| I[Create TaskInstance]\n H -->|Not Met| J[Skip]\n I --> K[Queue Task]\n K --> L[Executor]\n L --> M[Worker]\n M --> N[Execute Task]\n N --> O[Update State]\n O --> P[Record XCom]\n```\n\n### DAG Processing\n\nThe DAG collection module handles parsing and synchronization of DAGs:\n\n| Component | Responsibility |\n|-----------|----------------|\n| `DagBag` | Collection of parsed DAGs from file system |\n| `DagFileProcessor` | Parses individual DAG files |\n| `DagFileProcessorAgent` | Manages multiple DAG processors |\n| `SerializedDagModel` | Database representation of serialized DAGs |\n\n资料来源：[airflow-core/src/airflow/dag_processing/collection.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/dag_processing/collection.py)\n\n### Timetables\n\nTimetables determine when DAGs should be triggered. They provide schedule information and calculate logical dates for DAG runs.\n\n**Key Timetable Methods:**\n\n| Method | Purpose |\n|--------|---------|\n| `describe()` | Human-readable schedule description |\n| `infer_data_interval()` | Infer run boundaries from logical date |\n| `get_next_runtime()` | Calculate next scheduled run time |\n| `validate()` | Validate timetable configuration |\n\n资料来源：[airflow-core/src/airflow/timetables/base.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/timetables/base.py)\n\n## Task State Management\n\nTask instances maintain state throughout their lifecycle. The `TaskState` class provides methods for managing task state via supervisor communications.\n\n```mermaid\ngraph TD\n A[Task Starts] --> B[Scheduled]\n B --> C[Queued]\n C --> D[Started]\n D --> E{Ran Successfully?}\n E -->|Yes| F[Success]\n E -->|No| G{Retryable?}\n G -->|Yes| H[Up for Retry]\n H --> C\n G -->|No| I[Failed]\n F --> J[Emit XCom]\n I --> J\n```\n\n### TaskState API\n\nThe TaskState class provides key-value storage for task state information:\n\n| Method | Description |\n|--------|-------------|\n| `get(key)` | Retrieve task state value by key |\n| `set(key, value)` | Store task state value |\n| `delete(key)` | Delete a specific key |\n| `clear(all_map_indices)` | Clear all keys or map-index specific keys |\n\n资料来源：[task-sdk/src/airflow/sdk/execution_time/context.py](https://github.com/apache/airflow/blob/main/task-sdk/src/airflow/sdk/execution_time/context.py)\n\n## DAG Runs and Task Instances\n\n### DagRun States\n\n| State | Description |\n|-------|-------------|\n| `queued` | Initial state when DAG run is created |\n| `running` | DAG run is currently executing |\n| `success` | All tasks in the DAG completed successfully |\n| `failed` | DAG run failed due to task or system failure |\n\n### Run Types\n\n| Type | Trigger Mechanism |\n|------|-------------------|\n| `scheduled` | Triggered automatically by timetable |\n| `manual` | Triggered by user action via CLI or UI |\n| `dataset` | Triggered by dataset dependency |\n| `backfill` | Triggered by explicit backfill command |\n\n资料来源：[airflow-core/src/airflow/ui/src/pages/DagRuns.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/DagRuns.tsx)\n\n## CLI Commands for Scheduler and Executor\n\n### Scheduler Commands\n\n```bash\n# Start the scheduler\nairflow scheduler\n\n# Start with specific number of runs\nairflow scheduler --num-runs 10\n\n# Run in daemon mode\nairflow scheduler --daemon --log-file /path/to/scheduler.log\n\n# Development mode\nairflow scheduler --dev\n```\n\n### DAG Processing Commands\n\n```bash\n# Trigger DAG run\nairflow dags trigger \n\n# Test task\nairflow tasks test \n\n# Clear task instances\nairflow tasks clear \n\n# Render task template\nairflow tasks render \n```\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n\n## Configuration\n\n### Executor Configuration\n\nExecutors are configured in `airflow.cfg` or through environment variables:\n\n```ini\n[core]\nexecutor = LocalExecutor\n\n[celery]\ncelery_executor_config = ...\n```\n\n### Scheduler Configuration\n\n| Configuration | Description | Default |\n|---------------|--------------|---------|\n| `scheduler_num_runs` | Number of scheduler runs | -1 (infinite) |\n| `scheduler_idle_sleep_time` | Seconds between scheduler loops | 1 |\n| `num_runs` | Alternative parameter for number of runs | -1 |\n| `only_idle` | Only schedule idle DAGs | False |\n\n## Signal Handling\n\nThe scheduler supports the following signals for operational control:\n\n| Signal | Action |\n|--------|--------|\n| `SIGUSR2` | Dump a snapshot of task state being tracked by the executor |\n\nExample usage:\n```bash\npkill -f -USR2 \"airflow scheduler\"\n```\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n\n## Related Components\n\n### Triggerer\n\nThe Triggerer is a separate daemon that manages lightweight asynchronous triggers for tasks that need to wait for external conditions:\n\n```bash\nairflow triggerer --capacity 1000 --queues queue1,queue2\n```\n\n| Parameter | Purpose |\n|-----------|---------|\n| `--capacity` | Maximum concurrent triggers |\n| `--queues` | Queues to consume from |\n| `--pid` | PID file location |\n| `--daemon` | Run as daemon |\n\n### DAG Processor\n\nThe DAG Processor parses and validates DAG files before they are scheduled:\n\n```bash\nairflow dag-processor --bundle-name --num-runs 5\n```\n\n## Summary\n\nThe Scheduler and Executor Architecture in Apache Airflow provides a robust, scalable system for orchestrating complex workflows. Key architectural principles include:\n\n1. **Separation of Concerns**: Scheduler handles scheduling decisions; Executors handle task execution\n2. **Pluggable Executors**: Multiple executor types support different deployment scenarios\n3. **Database-Driven State**: All state is persisted in the metadata database for durability\n4. **Continuous Loop**: Scheduler runs continuously, periodically evaluating DAGs and scheduling tasks\n5. **Team-Based Execution**: Modern Airflow supports team-based executor configuration with aliases\n\n---\n\n\n\n## REST API\n\n### 相关页面\n\n相关主题：[User Interface](#user-interface), [Architecture Overview](#architecture-overview)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [airflow-core/src/airflow/api_fastapi/core_api/app.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/app.py)\n- [airflow-core/src/airflow/api_fastapi/core_api/routes/ui/dag_runs.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/routes/ui/dag_runs.py)\n- [airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py)\n- [airflow-core/src/airflow/api_fastapi/auth/managers/simple/simple_auth_manager.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/auth/managers/simple/simple_auth_manager.py)\n- [airflow-core/src/airflow/api_fastapi/execution_api/app.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/execution_api/app.py)\n- [airflow-core/docs/stable-rest-api-ref.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/stable-rest-api-ref.rst)\n\n\n# REST API\n\nApache Airflow provides a comprehensive REST API for programmatic interaction with the workflow automation platform. The API is built using FastAPI and enables external systems and applications to manage DAGs, trigger executions, monitor workflows, and interact with task instances.\n\n## Architecture Overview\n\nApache Airflow's REST API is architected as a multi-layer FastAPI application that separates concerns between the core API and the execution API.\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n A[External Clients]\n B[CLI Tools]\n C[UI Dashboard]\n end\n \n subgraph \"REST API Layer\"\n D[Core API /api/v1]\n E[Execution API /execution]\n end\n \n subgraph \"Service Layer\"\n F[DAG Management Service]\n G[Task Execution Service]\n H[Configuration Service]\n end\n \n subgraph \"Data Layer\"\n I[Airflow Database]\n J[Metadata DB]\n end\n \n A --> D\n B --> D\n C --> D\n C --> E\n D --> F\n D --> H\n E --> G\n F --> I\n G --> I\n H --> J\n```\n\n### Core API (`/api/v1`)\n\nThe Core API provides the primary interface for DAG management, monitoring, and administrative operations. It handles:\n\n- DAG run creation and management\n- Task instance operations\n- Connection and variable management\n- User and permission management\n- Plugin and provider information\n\n资料来源：[airflow-core/src/airflow/api_fastapi/core_api/app.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/app.py)\n\n### Execution API (`/execution`)\n\nThe Execution API is designed for lightweight, high-performance task execution operations. It provides endpoints for:\n\n- Task state updates\n- XCom value operations\n- Task heartbeat signals\n- Execution context retrieval\n\n资料来源：[airflow-core/src/airflow/api_fastapi/execution_api/app.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/execution_api/app.py)\n\n## Authentication and Authorization\n\nAirflow's REST API supports multiple authentication mechanisms through a pluggable auth manager architecture.\n\n### Authentication Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant API as REST API\n participant Auth as Auth Manager\n participant DB as Database\n \n Client->>API: Request with credentials\n API->>Auth: Validate credentials\n Auth->>DB: Check user/permissions\n DB-->>Auth: User info + permissions\n Auth-->>API: Auth result\n alt Authentication Success\n API-->>Client: 200 + Response data\n else Authentication Failure\n API-->>Client: 401/403 + Error\n end\n```\n\n### Simple Auth Manager\n\nFor development and testing environments, Airflow provides a Simple Auth Manager that supports basic authentication mechanisms.\n\n资料来源：[airflow-core/src/airflow/api_fastapi/auth/managers/simple/simple_auth_manager.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/auth/managers/simple/simple_auth_manager.py)\n\n### Access Control\n\nThe REST API implements granular access control through DAG-level permissions:\n\n| Permission | Description |\n|------------|-------------|\n| `GET` | Read access to DAG information |\n| `POST` | Create/modify DAG resources |\n| `DELETE` | Remove DAG resources |\n| `EDIT` | Modify DAG configuration |\n\nAccess control is enforced through dependency injection on route handlers:\n\n```python\ndependencies=[\n Depends(requires_access_dag(\"GET\")),\n Depends(requires_access_dag(\"GET\", DagAccessEntity.DEPENDENCIES)),\n Depends(requires_access_dag(\"GET\", DagAccessEntity.TASK_INSTANCE)),\n]\n```\n\n资料来源：[airflow-core/src/airflow/api_fastapi/core_api/routes/ui/structure.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/routes/ui/structure.py)\n\n## DAG Runs API\n\nDAG Runs represent individual executions of a Directed Acyclic Graph (DAG). The DAG Runs API provides comprehensive endpoints for managing workflow executions.\n\n### DAG Run Data Model\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `dag_id` | string | Unique identifier for the DAG |\n| `run_id` | string | Unique identifier for this execution |\n| `state` | enum | Current state (queued, running, success, failed) |\n| `conf` | object | Configuration passed to the DAG |\n| `logical_date` | datetime | Scheduled execution time |\n| `start_date` | datetime | Actual execution start time |\n| `end_date` | datetime | Execution completion time |\n| `external_trigger` | boolean | Whether triggered externally |\n\n资料来源：[airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py)\n\n### Key Endpoints\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/dags/{dag_id}/dagRuns` | GET | List DAG runs with filtering |\n| `/dags/{dag_id}/dagRuns` | POST | Trigger a new DAG run |\n| `/dags/{dag_id}/dagRuns/{run_id}` | GET | Get specific DAG run details |\n| `/dags/{dag_id}/dagRuns/{run_id}` | DELETE | Delete a DAG run |\n| `/dags/{dag_id}/dagRuns/{run_id}/clear` | POST | Clear task instances |\n| `/dags/{dag_id}/dagRuns/{run_id}/confirm` | POST | Confirm a DAG run |\n| `/dags/{dag_id}/dagRuns/{run_id}/update` | PATCH | Update DAG run state |\n\n资料来源：[airflow-core/src/airflow/api_fastapi/core_api/routes/ui/dag_runs.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/routes/ui/dag_runs.py)\n\n### Query Parameters\n\nThe DAG Runs list endpoint supports extensive filtering:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `limit` | integer | Maximum number of results (default: 100) |\n| `offset` | integer | Pagination offset |\n| `order_by` | string | Sort field |\n| `state` | enum | Filter by state |\n| `dag_run_id` | string | Filter by run ID |\n| `logical_date` | datetime | Filter by logical date |\n| `start_date` | datetime | Filter by start date |\n| `end_date` | datetime | Filter by end date |\n| `include_upstream` | boolean | Include upstream dependencies |\n| `include_downstream` | boolean | Include downstream tasks |\n| `depth` | integer | Tree depth limit |\n| `root` | string | Root node filter |\n| `external_dependencies` | boolean | Include external dependencies |\n\n## API Structure and Organization\n\n### Route Organization\n\nThe REST API routes are organized by functional area within the FastAPI application structure:\n\n```mermaid\ngraph LR\n subgraph \"/api/v1\"\n A[UI Routes]\n B[DAG Routes]\n C[Task Routes]\n D[Connection Routes]\n E[Variable Routes]\n F[Plugin Routes]\n end\n \n subgraph \"/execution\"\n G[Task Execution]\n H[XCom Operations]\n end\n```\n\n### Response Models\n\nAll API endpoints return structured responses using Pydantic models. Responses include:\n\n- **Data**: The requested resource or operation result\n- **Meta**: Pagination information and metadata\n- **Links**: HATEOAS-style navigation links\n\n### Error Handling\n\nThe API implements consistent error handling with structured error responses:\n\n| Status Code | Category |\n|-------------|----------|\n| 400 | Bad Request - Invalid parameters |\n| 401 | Unauthorized - Authentication required |\n| 403 | Forbidden - Insufficient permissions |\n| 404 | Not Found - Resource doesn't exist |\n| 409 | Conflict - State conflict |\n| 500 | Internal Server Error |\n\n## Security Considerations\n\n### Session Management\n\nThe REST API integrates with Airflow's session management system. When authentication is enabled:\n\n1. Clients must authenticate to receive a session cookie\n2. Subsequent requests include the session cookie\n3. Sessions expire based on configuration settings\n\n### Role-Based Access Control (RBAC)\n\nThe API supports RBAC through integration with the auth manager:\n\n- **Admin**: Full access to all resources\n- **Op**: Access to DAG operations\n- **User**: Read access to DAGs, limited write access\n- **Viewer**: Read-only access\n\n## Configuration\n\n### Enabling the REST API\n\nThe REST API is enabled by default when Airflow is configured with a supported auth manager. Key configuration options:\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `auth_manager` | simple | Authentication backend |\n| `api_url` | - | Base URL for API endpoints |\n| `secret_key` | - | Session encryption key |\n\n### CORS Configuration\n\nCross-Origin Resource Sharing (CORS) can be configured to allow web clients to access the API:\n\n| Setting | Description |\n|---------|-------------|\n| `access_control_allow_origins` | Allowed origins |\n| `access_control_allow_methods` | Allowed HTTP methods |\n| `access_control_allow_headers` | Allowed headers |\n\n## API Versioning\n\nApache Airflow maintains API stability through versioning:\n\n- **Current Version**: `/api/v1`\n- **Version Prefix**: All endpoints are prefixed with the version\n- **Stability Guarantee**: Within a major version, breaking changes are avoided\n\n资料来源：[airflow-core/docs/stable-rest-api-ref.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/stable-rest-api-ref.rst)\n\n## Usage Examples\n\n### Triggering a DAG Run\n\n```bash\ncurl -X POST \"http://airflow-server:8080/api/v1/dags/my_dag/dagRuns\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\n \"dag_run_id\": \"manual_run_001\",\n \"logical_date\": \"2024-01-15T10:00:00Z\",\n \"conf\": {\"key\": \"value\"}\n }'\n```\n\n### Listing DAG Runs\n\n```bash\ncurl \"http://airflow-server:8080/api/v1/dags/my_dag/dagRuns?state=running&limit=10\" \\\n -H \"Authorization: Bearer \"\n```\n\n## See Also\n\n- [CLI Commands](cli-commands) - Alternative command-line interface\n- [Authentication](authentication) - Auth manager configuration\n- [DAG Runs](dag-runs) - DAG execution management\n- [Task Instances](task-instances) - Task operation API\n\n---\n\n\n\n## User Interface\n\n### 相关页面\n\n相关主题：[REST API](#rest-api), [Core Concepts](#core-concepts)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [airflow-core/src/airflow/ui/src/layouts/Details/Grid/Grid.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/layouts/Details/Grid/Grid.tsx)\n- [airflow-core/src/airflow/ui/src/layouts/Details/Graph/Graph.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/layouts/Details/Graph/Graph.tsx)\n- [airflow-core/src/airflow/ui/src/pages/Dashboard/Dashboard.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/Dashboard/Dashboard.tsx)\n- [airflow-core/src/airflow/ui/src/router.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/router.tsx)\n- [airflow-core/src/airflow/ui/package.json](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/package.json)\n- [airflow-core/docs/ui.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/ui.rst)\n- [airflow-core/src/airflow/ui/src/pages/DagRuns.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/DagRuns.tsx)\n- [airflow-core/src/airflow/ui/src/pages/Dag/Overview/Overview.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/Dag/Overview/Overview.tsx)\n- [airflow-core/src/airflow/ui/src/components/Clear/TaskInstance/ClearTaskInstanceConfirmationDialog.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/Clear/TaskInstance/ClearTaskInstanceConfirmationDialog.tsx)\n- [airflow-core/src/airflow/ui/src/pages/Connections/EditConnectionButton.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/Connections/EditConnectionButton.tsx)\n- [providers/edge3/src/airflow/providers/edge3/plugins/www/src/pages/WorkerPage.tsx](https://github.com/apache/airflow/blob/main/providers/edge3/src/airflow/providers/edge3/plugins/www/src/pages/WorkerPage.tsx)\n\n\n# User Interface\n\n## Overview\n\nApache Airflow's User Interface (UI) is a modern web-based frontend built with React and TypeScript that provides comprehensive workflow management, monitoring, and operational capabilities. The UI serves as the primary visual interface for data engineers and operators to interact with DAGs, task instances, DAG runs, connections, and various Airflow components.\n\nThe UI framework is organized under `airflow-core/src/airflow/ui/` and leverages contemporary React patterns including component composition, lazy loading, and type-safe TypeScript implementations. 资料来源：[airflow-core/docs/ui.rst:1-50]()\n\n## Architecture Overview\n\n### Technology Stack\n\n| Component | Technology | Purpose |\n|-----------|------------|---------|\n| Framework | React 18+ | UI component library |\n| Language | TypeScript | Type safety and better DX |\n| State Management | TanStack Query / React Query | Server state management |\n| Routing | React Router v7 | Client-side routing |\n| Styling | Chakra UI | Component library and styling |\n| Build Tool | Vite | Fast development and building |\n| Icons | Lucide React | Consistent iconography |\n\n资料来源：[airflow-core/src/airflow/ui/package.json:1-30]()\n\n### Directory Structure\n\n```\nairflow/\n├── ui/\n│ ├── src/\n│ │ ├── layouts/ # Page layout components\n│ │ │ └── Details/ # Detail view layouts\n│ │ │ ├── Grid/ # Grid view for DAGs\n│ │ │ └── Graph/ # Graph view for DAGs\n│ │ ├── pages/ # Page components\n│ │ │ ├── Dashboard/ # Dashboard pages\n│ │ │ ├── Dag/ # DAG detail pages\n│ │ │ ├── Run/ # Run detail pages\n│ │ │ └── Connections/ # Connection management\n│ │ ├── components/ # Reusable UI components\n│ │ │ ├── Clear/ # Clear action components\n│ │ │ └── TriggerDag/ # DAG triggering components\n│ │ └── router.tsx # Application routing configuration\n│ └── package.json\n└── providers/\n └── edge3/ # Edge provider with custom UI\n └── plugins/www/src/\n ├── pages/ # Edge-specific pages\n └── components/ # Edge-specific components\n```\n\n## Routing System\n\nThe UI uses React Router v7 for client-side navigation. Routes are defined in `router.tsx` and organized into two main categories: main application routes and detail views.\n\n```mermaid\ngraph TD\n A[\"/\"] --> B[\"Dashboard\"]\n A --> C[\"DAGs List\"]\n A --> D[\"DAG Detail\"]\n D --> D1[\"Grid View\"]\n D --> D2[\"Graph View\"]\n D --> D3[\"Overview\"]\n A --> E[\"DAG Runs\"]\n A --> F[\"Connections\"]\n A --> G[\"Providers\"]\n \n style A fill:#e1f5fe\n style D1 fill:#fff3e0\n style D2 fill:#e8f5e9\n style D3 fill:#f3e5f5\n```\n\n### Core Route Definitions\n\nThe router configuration maps URL paths to page components and handles lazy loading for improved performance:\n\n```typescript\n// Simplified route structure from router.tsx\nroutes = [\n { path: \"/\", component: Dashboard },\n { path: \"/dags\", component: DagList },\n { path: \"/dags/:dagId\", component: DagDetail },\n { path: \"/dags/:dagId/runs\", component: DagRuns },\n { path: \"/runs/:dagRunId\", component: RunDetail },\n { path: \"/connections\", component: Connections },\n]\n```\n\n## Page Components\n\n### Dashboard\n\nThe Dashboard (`Dashboard.tsx`) serves as the landing page, providing an overview of the Airflow environment. It typically includes:\n\n- DAG statistics and health metrics\n- Recent DAG runs\n- Failed or stuck tasks requiring attention\n- Quick access to frequently used DAGs\n\n资料来源：[airflow-core/src/airflow/ui/src/pages/Dashboard/Dashboard.tsx:1-50]()\n\n### DAG Detail Views\n\nDAG detail pages provide comprehensive views of individual DAGs with multiple visualization modes:\n\n#### Grid View\n\nThe Grid view (`Grid.tsx`) displays DAG tasks in a tabular format, allowing users to:\n\n- View task states across multiple DAG runs\n- Navigate through historical runs\n- Identify failed or running tasks quickly\n\n```mermaid\ngraph LR\n subgraph \"Grid View Structure\"\n H[\"Header: DAG Info\"]\n T[\"Task Grid Table\"]\n F[\"Filter/Sort Controls\"]\n end\n \n T --> T1[\"Task Columns\"]\n T --> T2[\"Run Rows\"]\n T1 --> Cell[\"State Cell\"]\n```\n\n资料来源：[airflow-core/src/airflow/ui/src/layouts/Details/Grid/Grid.tsx:1-80]()\n\n#### Graph View\n\nThe Graph view (`Graph.tsx`) renders the DAG structure visually as a directed acyclic graph, showing:\n\n- Task dependencies and relationships\n- Task execution states with color coding\n- Interactive node selection and navigation\n\n资料来源：[airflow-core/src/airflow/ui/src/layouts/Details/Graph/Graph.tsx:1-80]()\n\n#### Overview Page\n\nThe Overview page (`Overview.tsx`) provides a comprehensive dashboard for a specific DAG:\n\n```typescript\ninterface OverviewComponents {\n dagStats: DagStats; // DAG statistics\n failedRuns: FailedRuns; // Failed run alerts\n durationChart: DurationChart; // Duration visualization\n assetEvents: AssetEvents; // Asset event tracking\n dagDeadlines: DagDeadlines; // Deadline management\n failedLogs: FailedLogs; // Failed task logs\n}\n```\n\n资料来源：[airflow-core/src/airflow/ui/src/pages/Dag/Overview/Overview.tsx:1-100]()\n\n### DAG Runs Page\n\nThe DAG Runs page (`DagRuns.tsx`) displays a table of all DAG runs with the following columns:\n\n| Column | Description | Features |\n|--------|-------------|----------|\n| DAG Run ID | Unique identifier | Link to run detail |\n| State | Current state | Colored badge |\n| Run Type | Scheduled, manual, etc. | Icon + text |\n| Run After | Scheduled execution time | Time component |\n| Triggering User | User who triggered | Username display |\n| Start Date | Execution start time | Timestamp |\n| End Date | Execution end time | Timestamp |\n| Duration | Total execution time | Calculated field |\n| DAG Versions | Version tracking | Version badges |\n\n资料来源：[airflow-core/src/airflow/ui/src/pages/DagRuns.tsx:1-100]()\n\n## Dialog Components\n\nDialogs are used throughout the UI for focused interactions, confirmations, and detailed forms.\n\n### Confirmation Dialogs\n\nThe `ClearTaskInstanceConfirmationDialog.tsx` demonstrates the dialog pattern used for critical operations:\n\n```tsx\n\n \n \n \n \n {translate(\"dags:runAndTaskActions.confirmationDialog.title\")}\n \n \n \n {/* Confirmation details */}\n \n \n \n \n \n\n```\n\nKey characteristics:\n- **lazyMount**: Content renders only when opened\n- **unmountOnExit**: Complete cleanup when closed\n- **backdrop**: Modal overlay for focus\n- **size variants**: sm, md, lg, xl for different content types\n\n资料来源：[airflow-core/src/airflow/ui/src/components/Clear/TaskInstance/ClearTaskInstanceConfirmationDialog.tsx:1-60]()\n\n### Edit Dialogs\n\nThe `EditConnectionButton.tsx` demonstrates dialog usage for editing forms:\n\n```tsx\n\n \n \n {translate(\"connections.edit\")}\n \n \n \n \n \n\n```\n\n资料来源：[airflow-core/src/airflow/ui/src/pages/Connections/EditConnectionButton.tsx:1-50]()\n\n## Component Library\n\n### Clear Actions\n\nThe UI provides comprehensive task and group clearing functionality:\n\n```mermaid\ngraph TD\n A[\"Clear Action Trigger\"] --> B{\"Single vs Group\"}\n B -->|Single| C[\"ClearTaskInstanceDialog\"]\n B -->|Group| D[\"ClearGroupTaskInstanceDialog\"]\n \n C --> E[\"Confirmation Dialog\"]\n D --> F[\"Options Selection\"]\n F --> F1[\"Past Tasks\"]\n F --> F2[\"Future Tasks\"]\n F --> F3[\"Upstream\"]\n F --> F4[\"Downstream\"]\n F --> F5[\"Only Failed\"]\n \n E --> G[\"Action Accordion\"]\n F --> G\n G --> H[\"API Execution\"]\n```\n\nComponents in `airflow-core/src/airflow/ui/src/components/Clear/TaskInstance/`:\n\n- `ClearTaskInstanceDialog.tsx` - Single task clearing\n- `ClearTaskInstanceConfirmationDialog.tsx` - Confirmation UI\n- `ClearGroupTaskInstanceDialog.tsx` - Bulk task clearing\n\n### Trigger DAG Components\n\nThe `TriggerDAGAdvancedOptions.tsx` provides advanced options when triggering DAGs:\n\n| Option | Purpose |\n|--------|---------|\n| dagRunId | Custom run identifier |\n| partitionKey | Partition-based execution |\n| note | Execution notes/documentation |\n\n```tsx\n (\n \n \n {translate(\"runId\")}\n \n \n \n {translate(\"components:triggerDag.runIdHelp\")}\n \n \n )}\n/>\n```\n\n资料来源：[airflow-core/src/airflow/ui/src/components/TriggerDag/TriggerDAGAdvancedOptions.tsx:1-80]()\n\n## Edge Provider UI\n\nThe Edge provider (`providers/edge3/`) extends the base UI with worker-specific pages and components.\n\n### Worker Management Page\n\nThe `WorkerPage.tsx` provides a table-based interface for managing edge workers:\n\n```mermaid\ngraph LR\n subgraph \"Worker Page Structure\"\n T[\"Worker Table\"]\n H[\"Header Actions\"]\n F[\"Filter Controls\"]\n end\n \n T --> C1[\"Worker Name\"]\n T --> C2[\"Queues\"]\n T --> C3[\"Active Jobs\"]\n T --> C4[\"System Info\"]\n T --> C5[\"Operations\"]\n```\n\nWorker operations include:\n- **Delete**: Available for offline, unknown, or offline maintenance states\n- **Shutdown**: Available for idle, running, maintenance states\n- **Enter Maintenance**: Set worker to maintenance mode with comment\n- **Exit Maintenance**: Remove worker from maintenance mode\n\n资料来源：[providers/edge3/src/airflow/providers/edge3/plugins/www/src/pages/WorkerPage.tsx:1-100]()\n\n### Worker Operation Dialogs\n\nBulk operations are supported via `BulkWorkerOperations.tsx`:\n\n```tsx\n\n \n \n \n \n \n \n Delete {deleteWorkers.length} selected worker(s)\n \n \n \n \n {deleteWorkers.map((worker) => (\n {worker.worker_name}\n ))}\n \n \n \n \n \n \n \n \n\n```\n\n## Internationalization\n\nThe UI uses i18n (internationalization) patterns for all user-facing text:\n\n```typescript\n// Translation usage example\ntranslate(\"dagRun.runAfter\") // Column headers\ntranslate(\"dags:runAndTaskActions.confirmationDialog.title\")\ntranslate(\"common:modal.confirm\")\ntranslate(\"taskInstance\", { count: affectedTasks.total_entries })\n```\n\nTranslation keys are organized by:\n- **common**: Shared UI elements\n- **components**: Component-specific strings\n- **dags**: DAG-related UI strings\n- **dagRun**: DAG run specific strings\n\n## State Management and Data Fetching\n\nThe UI uses TanStack Query (React Query) for server state management:\n\n```typescript\n// Typical data fetching pattern\nconst { data, isLoading, error } = useQuery({\n queryKey: ['dagRuns', dagId, page],\n queryFn: () => fetchDagRuns(dagId, page),\n});\n```\n\nKey patterns:\n- **Optimistic updates**: Immediate UI feedback during mutations\n- **Lazy loading**: Components render only when needed\n- **Error boundaries**: Graceful error handling with `ErrorAlert` components\n- **Loading states**: Skeleton loaders for better UX\n\n## Pagination\n\nPaginated lists are implemented consistently throughout the UI:\n\n```tsx\n setPage(event.page)}\n page={page}\n pageSize={PAGE_LIMIT}\n>\n \n \n \n \n \n\n```\n\nStandard pagination constants:\n- **PAGE_LIMIT**: Default items per page (typically 25-50)\n- **total_entries**: Total count from API response\n\n## Summary\n\nApache Airflow's User Interface is a comprehensive React-based frontend that provides:\n\n1. **Multi-view DAG Visualization**: Grid, Graph, and Overview views for different use cases\n2. **Comprehensive Task Management**: Clear, trigger, and manage task instances\n3. **Connection Management**: Visual interface for managing Airflow connections\n4. **Edge Worker Control**: Dedicated UI for edge worker deployment management\n5. **Consistent Component Patterns**: Reusable dialogs, tables, and forms\n6. **Internationalization**: Full i18n support for global deployments\n7. **Type Safety**: Full TypeScript coverage for reliable development\n\nThe UI architecture emphasizes modularity, lazy loading, and consistent patterns to ensure maintainability and performance across large-scale Airflow deployments.\n\n---\n\n\n\n## Data Flow and State Management\n\n### 相关页面\n\n相关主题：[Core Concepts](#core-concepts), [Connections and Variables](#connections-variables)\n\n\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [airflow-core/src/airflow/models/xcom.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/xcom.py)\n- [airflow-core/src/airflow/models/xcom_arg.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/xcom_arg.py)\n- [airflow-core/src/airflow/models/asset.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/asset.py)\n- [airflow-core/src/airflow/models/asset_state.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/asset_state.py)\n- [airflow-core/src/airflow/models/task_state.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/task_state.py)\n- [airflow-core/src/airflow/serialization/definitions/xcom_arg.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/serialization/definitions/xcom_arg.py)\n- [airflow-core/docs/core-concepts/xcoms.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/core-concepts/xcoms.rst)\n\n\n# Data Flow and State Management\n\n## Overview\n\nData Flow and State Management in Apache Airflow encompasses the mechanisms by which tasks communicate, share state, and coordinate execution across a Directed Acyclic Graph (DAG). Airflow provides several interconnected systems to manage how data moves between tasks, how task states are tracked, and how assets trigger workflow execution.\n\nThe core components involved in data flow include XCom (Cross-Communication), Assets, and Task State management. These systems work together to enable complex workflows where tasks can pass data, react to external events, and maintain execution context throughout the DAG lifecycle.\n\n## XCom (Cross-Communication)\n\n### Purpose and Role\n\nXCom is Airflow's primary mechanism for inter-task communication. It allows tasks to push and pull values that can be used by downstream tasks in the same DAG. XComs are stored in the Airflow metadata database and can contain any serializable Python object.\n\n### XCom Data Model\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `key` | String | Identifier for the XCom value |\n| `value` | Any | The actual data being passed |\n| `task_id` | String | Task that produced the XCom |\n| `dag_id` | String | DAG containing the task |\n| `run_id` | String | DAG run identifier |\n| `map_index` | Integer | Index for mapped tasks (-1 for non-mapped) |\n| `timestamp` | DateTime | When the XCom was created |\n| `connection_id` | String | Optional connection for large data |\n\n### XCom API Operations\n\n#### Push (Sending XCom Values)\n\nTasks can push XCom values using the `xcom_push()` method:\n\n```python\ntask_instance.xcom_push(key=\"result\", value={\"data\": \"example\"})\n```\n\nOr implicitly by returning a value from a task:\n\n```python\n@task\ndef process_data():\n return {\"processed\": True, \"count\": 42}\n```\n\n#### Pull (Receiving XCom Values)\n\nDownstream tasks can retrieve XCom values using `xcom_pull()`:\n\n```python\nupstream_result = ti.xcom_pull(task_ids=[\"process_data\"], key=\"result\")\n```\n\n### XComArg\n\n`XComArg` provides a more declarative way to reference XCom values, enabling type-safe access to task outputs:\n\n```python\nfrom airflow.models.xcom_arg import XComArg\n\nprocessed_data = XComArg(task_id=\"process_data\")\nresult = processed_data(map_indexes=[0])\n```\n\nXComArg supports the following parameters:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `task_id` | String | Source task identifier |\n| `dag_id` | String | Optional DAG identifier |\n| `map_index` | Integer/List | Specific map index or indices |\n| `key` | String | XCom key to retrieve |\n\n## Asset Management\n\n### Asset Model\n\nAssets represent data sources or sinks that Airflows can monitor. They enable event-driven scheduling where DAGs can be triggered when underlying data changes.\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `name` | String | Human-readable asset name |\n| `uri` | String | Unique identifier (URN, path, etc.) |\n| `group` | String | Logical grouping of assets |\n| `extra` | Dict | Additional metadata |\n| `created_at` | DateTime | Creation timestamp |\n| `updated_at` | DateTime | Last modification timestamp |\n\n### Asset States\n\nAsset states track the lifecycle and availability of assets:\n\n```python\nclass AssetState:\n \"\"\"Represents the state of an asset in the system.\"\"\"\n \n IDLE = \"idle\"\n SCHEDULED = \"scheduled\"\n RUNNING = \"running\"\n SUCCESS = \"success\"\n FAILED = \"failed\"\n```\n\n#### State Transitions\n\n```mermaid\ngraph TD\n A[IDLE] -->|Asset referenced| B[SCHEDULED]\n B -->|Scheduler picks up| C[RUNNING]\n C -->|Success| D[SUCCESS]\n C -->|Failure| E[FAILED]\n D -->|Next schedule| B\n E -->|Retry| B\n```\n\n## Task State Management\n\n### Task States\n\nTask instances progress through a defined set of states:\n\n| State | Description |\n|-------|-------------|\n| `none` | Task has not been triggered |\n| `queued` | Task is queued for execution |\n| `running` | Task is currently executing |\n| `success` | Task completed successfully |\n| `failed` | Task failed during execution |\n| `upstream_failed` | Upstream task dependency failed |\n| `skipped` | Task was skipped due to branching |\n| `up_for_retry` | Task failed but will be retried |\n| `up_for_reschedule` | Task is waiting for reschedule |\n\n### TaskState Model\n\n```python\nclass TaskState:\n \"\"\"Tracks the current state and context of a task instance.\"\"\"\n \n task_id: str\n dag_id: str\n run_id: str\n state: TaskInstanceState\n try_number: int\n max_tries: int\n start_date: Optional[datetime]\n end_date: Optional[datetime]\n duration: Optional[float]\n```\n\n### State Persistence\n\nTask states are persisted to the metadata database, enabling:\n\n- Recovery from scheduler restarts\n- Historical execution tracking\n- DAG run state reconstruction\n- SLA monitoring and alerting\n\n## Data Flow Architecture\n\n### Task Execution Flow\n\n```mermaid\ngraph TD\n A[DAG Trigger] --> B[Scheduler]\n B --> C{Dependency Check}\n C -->|All met| D[Queue Task]\n C -->|Not met| E[Wait]\n D --> F[Executor]\n F --> G[Worker]\n G --> H[Execute Task]\n H --> I{Push XCom}\n I -->|Yes| J[Store in DB]\n J --> K[Task Complete]\n I -->|No| K\n K --> L[Update TaskState]\n L --> M[Check Downstream]\n M --> C\n```\n\n### XCom Storage Flow\n\n```mermaid\ngraph LR\n A[Task Instance] -->|xcom_push| B[XCom Table]\n C[Task Instance] -->|xcom_pull| B\n B -->|query| D[Metadata DB]\n D -->|result| C\n```\n\n## Serialization and Deserialization\n\n### XComArg Serialization\n\nWhen DAGs are serialized (for example, for the webserver or worker), XComArg references must be properly handled:\n\n```python\nclass XComArgBase:\n \"\"\"Base class for serializable XCom arguments.\"\"\"\n \n def serialize(self) -> dict:\n \"\"\"Convert XComArg to dictionary format.\"\"\"\n return {\n \"task_id\": self.task_id,\n \"dag_id\": self.dag_id,\n \"key\": self.key,\n \"map_index\": self.map_index,\n }\n \n @staticmethod\n def deserialize(data: dict) -> \"XComArgBase\":\n \"\"\"Reconstruct XComArg from dictionary.\"\"\"\n return XComArg(**data)\n```\n\n## Best Practices\n\n### Data Flow Design\n\n1. **Minimize XCom payload size** - Large XCom values impact database performance\n2. **Use Assets for external data** - Let the scheduler handle dependency tracking\n3. **Prefer pull over push patterns** - Downstream tasks should pull required data\n4. **Clear XCom when unnecessary** - Use `xcom_clear()` to prevent accumulation\n\n### State Management\n\n1. **Monitor task durations** - Track state transitions for performance analysis\n2. **Configure appropriate retries** - Set `retries` and `retry_delay` based on task reliability\n3. **Use SLA alerts** - Configure `sla` parameter for critical task deadlines\n4. **Clean up failed states** - Implement proper error handling and state recovery\n\n## Configuration Options\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `xcom_pickle_tasks_on_error` | False | Serialize task data to XCom on error |\n| `max_xcom_size` | 1048576 | Maximum XCom value size in bytes |\n| `xcom_backend` | airflow.models.xcom.BaseXCom | Custom XCom backend class |\n| `enable_asset_uri_validation` | True | Validate asset URIs on creation |\n\n## Related Documentation\n\n- [XCom Documentation](airflow-core/docs/core-concepts/xcoms.rst)\n- [Assets Guide](https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/asset-management.html)\n- [Task Lifecycle](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/tasks.html#task-instances)\n\n---\n\n\n\n## Connections and Variables\n\n### 相关页面\n\n相关主题：[Data Flow and State Management](#data-flow-xcom), [Docker and Helm Deployment](#docker-helm)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [airflow-core/src/airflow/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n- [airflow-core/src/airflow/utils/db.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/utils/db.py)\n- [providers/google/src/airflow/providers/google/cloud/hooks/cloud_composer.py](https://github.com/apache/airflow/blob/main/providers/google/src/airflow/providers/google/cloud/hooks/cloud_composer.py)\n- [dev/breeze/src/airflow_breeze/params/build_prod_params.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/params/build_prod_params.py)\n- [generated/README.md](https://github.com/apache/airflow/blob/main/generated/README.md)\n- [dev/breeze/src/airflow_breeze/commands/sbom_commands.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/sbom_commands.py)\n\n\n# Connections and Variables\n\n## Overview\n\nConnections and Variables are two fundamental abstractions in Apache Airflow for managing configuration and external system integrations. They enable DAGs to store, retrieve, and utilize configuration data and credentials without hardcoding sensitive information.\n\n**Connections** provide a secure way to store and manage credentials for external systems such as databases, APIs, cloud services, and file systems. They centralize authentication configuration in one place, making it easy to manage, update, and audit access to external resources.\n\n**Variables** provide a simple key-value store for storing arbitrary configuration data that can be accessed across DAGs and tasks. They are useful for storing environment-specific settings, feature flags, and general configuration values.\n\nBoth features support multiple backend storage mechanisms and can be managed through the Airflow UI, CLI, or programmatically via the API.\n\n## Connections\n\n### Purpose and Scope\n\nConnections in Airflow encapsulate all the information needed to connect to an external system. Each connection includes:\n\n- A unique connection identifier (conn_id)\n- Connection type (conn_type) specifying the external system category\n- Host, port, login, and password fields\n- Schema and extra parameters for additional configuration\n\nConnections are stored in the Airflow metadata database by default but can also be backed by secrets backends such as HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, or Google Cloud Secret Manager.\n\n### Connection Types\n\nAirflow supports numerous connection types through provider packages. The core supported types include:\n\n| Connection Type | Description | Default Port |\n|-----------------|-------------|-------------|\n| `facebook_social` | Facebook OAuth/social authentication | N/A |\n| `fs` | Filesystem connection | N/A |\n| `ftp` | FTP/SFTP server | 21 |\n| `google_cloud_platform` | Google Cloud Platform services | N/A |\n| `gremlin` | Apache TinkerPop Gremlin server | 8182 |\n| `hive_cli` | Hive command-line interface | 10000 |\n| `hiveserver2` | HiveServer2 JDBC interface | 10000 |\n| `http` | HTTP/HTTPS endpoints | 443 |\n| `iceberg` | Apache Iceberg catalog | N/A |\n\n资料来源：[airflow-core/src/airflow/utils/db.py:200-260]()\n\n### Connection Management via CLI\n\nThe Airflow CLI provides comprehensive commands for managing connections:\n\n```bash\n# List all connections\nairflow connections list\n\n# Get a specific connection\nairflow connections get \n\n# Add a new connection\nairflow connections add --conn-type http --host https://api.example.com\n\n# Delete a connection\nairflow connections delete \n\n# Export all connections\nairflow connections export /tmp/connections.json\n\n# Import connections from file\nairflow connections import /tmp/connections.json\n\n# Test a connection\nairflow connections test \n```\n\nThe connection commands are defined in the CLI configuration with lazy-loaded implementations:\n\n```python\nCONNECTIONS_COMMANDS = (\n ActionCommand(name=\"get\", func=lazy_load_command(\"airflow.cli.commands.connection_command.connections_get\"), ...),\n ActionCommand(name=\"list\", func=lazy_load_command(\"airflow.cli.commands.connection_command.connections_list\"), ...),\n ActionCommand(name=\"add\", func=lazy_load_command(\"airflow.cli.commands.connection_command.connections_add\"), ...),\n ActionCommand(name=\"delete\", func=lazy_load_command(\"airflow.cli.commands.connection_command.connections_delete\"), ...),\n ActionCommand(name=\"export\", func=lazy_load_command(\"airflow.cli.commands.connection_command.connections_export\"), ...),\n ActionCommand(name=\"import\", func=lazy_load_command(\"airflow.cli.commands.connection_command.connections_import\"), ...),\n ActionCommand(name=\"test\", func=lazy_load_command(\"airflow.cli.commands.connection_command.connections_test\"), ...),\n)\n```\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:1-50]()\n\n### Connection Storage Architecture\n\n```mermaid\ngraph TD\n A[Airflow CLI/UI/API] --> B[Connection CRUD Operations]\n B --> C{Secrets Backend}\n C -->|None/Default| D[Airflow Metadata Database]\n C -->|HashiCorp Vault| E[Vault Secrets]\n C -->|AWS| F[AWS Secrets Manager]\n C -->|Azure| G[Azure Key Vault]\n C -->|GCP| H[GCP Secret Manager]\n D --> I[connection Table]\n E --> J[Vault Path]\n F --> K[AWS Secrets]\n G --> L[Azure Keys]\n H --> M[GCP Secrets]\n```\n\n### Using Connections in DAGs\n\nConnections are accessed in DAGs through the `BaseHook` class:\n\n```python\nfrom airflow.hooks.base import BaseHook\n\ndef get_external_api_data():\n conn = BaseHook.get_connection(\"my_external_api\")\n api_key = conn.password\n base_url = conn.host\n \n # Use credentials to make API calls\n ...\n```\n\nConnections with custom configurations can utilize the `extra` field for JSON-encoded parameters:\n\n```python\nConnection(\n conn_id=\"ftp_default\",\n conn_type=\"ftp\",\n host=\"localhost\",\n port=21,\n login=\"airflow\",\n password=\"airflow\",\n extra='{\"key_file\": \"~/.ssh/id_rsa\", \"no_host_key_check\": true}'\n)\n```\n\n资料来源：[airflow-core/src/airflow/utils/db.py:230-240]()\n\n## Variables\n\n### Purpose and Scope\n\nVariables provide a simple key-value storage mechanism for storing configuration data that can be shared across DAGs and tasks. They support string values with optional JSON serialization for complex data structures.\n\nKey characteristics of Variables:\n\n- Key-value pairs stored in the Airflow metadata database\n- Optional JSON serialization for non-string values\n- Support for environment-specific configuration\n- Accessible from all DAGs and tasks\n- Can be exported/imported in bulk\n\n### Variable Management via CLI\n\nThe Airflow CLI provides comprehensive commands for managing variables:\n\n```bash\n# List all variables\nairflow variables list\n\n# Get a specific variable\nairflow variables get \n\n# Set a variable\nairflow variables set \n\n# Set a variable with JSON serialization\nairflow variables set config_json '{\"setting\": true}' --serialize-json\n\n# Delete a variable\nairflow variables delete \n\n# Export all variables\nairflow variables export /tmp/variables.json\n\n# Import variables from file\nairflow variables import /tmp/variables.json\n```\n\nThe variable commands are defined with support for serialization options:\n\n```python\nVARIABLES_COMMANDS = (\n ActionCommand(name=\"list\", func=lazy_load_command(\"airflow.cli.commands.variable_command.variables_list\"), ...),\n ActionCommand(name=\"get\", func=lazy_load_command(\"airflow.cli.commands.variable_command.variables_get\"), \n args=(ARG_VAR, ARG_DESERIALIZE_JSON, ARG_DEFAULT, ARG_VERBOSE)),\n ActionCommand(name=\"set\", func=lazy_load_command(\"airflow.cli.commands.variable_command.variables_set\"),\n args=(ARG_VAR, ARG_VAR_VALUE, ARG_VAR_DESCRIPTION, ARG_SERIALIZE_JSON, ARG_VERBOSE)),\n ActionCommand(name=\"delete\", func=lazy_load_command(\"airflow.cli.commands.variable_command.variables_delete\"), ...),\n ActionCommand(name=\"export\", func=lazy_load_command(\"airflow.cli.commands.variable_command.variables_export\"), ...),\n ActionCommand(name=\"import\", func=lazy_load_command(\"airflow.cli.commands.variable_command.variables_import\"), ...),\n)\n```\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:50-80]()\n\n### Variable Storage Architecture\n\n```mermaid\ngraph TD\n A[DAG/Task Code] --> B[Variable API]\n B --> C[Secrets Backend]\n C -->|Default| D[Metadata Database]\n C -->|Backend| E[External Secrets]\n D --> F[variable Table]\n E --> F\n B --> G[JSON Deserializer]\n G --> H[Python Objects]\n F --> I[Key-Value Store]\n```\n\n### Using Variables in DAGs\n\nVariables can be accessed using the `Variable` class:\n\n```python\nfrom airflow.models import Variable\n\n# Get a simple string variable\napi_endpoint = Variable.get(\"api_endpoint\")\n\n# Get with default value\ntimeout = Variable.get(\"timeout\", default_var=30)\n\n# Get and deserialize JSON\nconfig = Variable.get(\"my_config\", deserialize_json=True)\n\n# Set a variable\nVariable.set(\"my_key\", \"my_value\")\nVariable.set(\"config\", {\"setting\": True}, serialize_json=True)\n```\n\n## Secrets Backend Integration\n\nBoth Connections and Variables can be backed by external secrets backends for enhanced security. This allows storing sensitive data in enterprise-grade secret management systems while maintaining the same Airflow API interface.\n\n### Available Secrets Backends\n\n| Backend | Package | Description |\n|---------|---------|-------------|\n| HashiCorp Vault | `airflow.providers.hashicorp` | HashiCorp Vault KV secrets engine |\n| AWS Secrets Manager | `airflow.providers.amazon` | AWS Secrets Manager and SSM Parameter Store |\n| Azure Key Vault | `airflow.providers.microsoft.azure` | Azure Key Vault secrets |\n| GCP Secret Manager | `airflow.providers.google` | Google Cloud Secret Manager |\n| Environment Variables | Built-in | Read from OS environment variables |\n| Local Files | Built-in | Read from JSON/YAML files |\n\n### Configuring Secrets Backends\n\nThe secrets backend is configured via the `[secrets]` section in `airflow.cfg`:\n\n```ini\n[secrets]\nbackend = airflow.providers.google.cloud.secrets.secret_manager.CloudSecretManagerBackend\nbackend_kwargs = {\"project_id\": \"my-project\", \"connections_prefix\": \"airflow-connections\"}\n```\n\n## Best Practices\n\n### Security Considerations\n\n1. **Never hardcode credentials** - Always use Connections or Variables for sensitive data\n2. **Use secrets backends** - For production environments, use enterprise secret management systems\n3. **Enable encryption** - Ensure the Airflow metadata database is encrypted at rest\n4. **Rotate credentials** - Regularly rotate passwords and API keys stored in connections\n5. **Audit access** - Monitor and log access to sensitive connections and variables\n\n### Performance Considerations\n\n1. **Avoid frequent variable reads** - Cache variable values when used repeatedly in a task\n2. **Use connection pooling** - Many hooks automatically pool connections; configure appropriately\n3. **Limit extra field size** - Keep connection `extra` JSON data minimal for performance\n\n### Operational Considerations\n\n1. **Use meaningful conn_ids** - Follow naming conventions like `{env}_{system}_{purpose}`\n2. **Document connections** - Use the description field to document connection purpose and owners\n3. **Export for disaster recovery** - Regularly export connections and variables for backup\n\n```bash\n# Backup connections and variables\nairflow connections export /opt/airflow/backups/connections_$(date +%Y%m%d).json\nairflow variables export /opt/airflow/backups/variables_$(date +%Y%m%d).json\n```\n\n## CLI Command Reference\n\n### Connection Commands\n\n| Command | Description |\n|---------|-------------|\n| `airflow connections list` | List all connections |\n| `airflow connections get ` | Get connection details |\n| `airflow connections add [options]` | Create a connection |\n| `airflow connections delete ` | Delete a connection |\n| `airflow connections export ` | Export connections to file |\n| `airflow connections import ` | Import connections from file |\n| `airflow connections test ` | Test connection availability |\n| `airflow connections create-default-connections` | Initialize provider default connections |\n\n### Variable Commands\n\n| Command | Description |\n|---------|-------------|\n| `airflow variables list` | List all variables |\n| `airflow variables get ` | Get variable value |\n| `airflow variables set ` | Set variable value |\n| `airflow variables delete ` | Delete a variable |\n| `airflow variables export ` | Export variables to file |\n| `airflow variables import ` | Import variables from file |\n\n## See Also\n\n- [Airflow Connections Documentation](https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/connections.html)\n- [Airflow Variables Documentation](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/variables.html)\n- [Secrets Backend Configuration](https://airflow.apache.org/docs/apache-airflow/stable/security/secrets/secrets-backend/index.html)\n- [Google Cloud Composer Hook](https://github.com/apache/airflow/blob/main/providers/google/src/airflow/providers/google/cloud/hooks/cloud_composer.py) - Example of connection usage in provider hooks\n\n---\n\n\n\n## Docker and Helm Deployment\n\n### 相关页面\n\n相关主题：[Kubernetes Deployment](#kubernetes-deployment), [Architecture Overview](#architecture-overview)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [dev/breeze/src/airflow_breeze/commands/release_management_commands.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/release_management_commands.py)\n- [docker-stack-docs/README.md](https://github.com/apache/airflow/blob/main/docker-stack-docs/README.md)\n- [generated/PYPI_README.md](https://github.com/apache/airflow/blob/main/generated/PYPI_README.md)\n- [dev/breeze/src/airflow_breeze/commands/sbom_commands.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/sbom_commands.py)\n- [dev/breeze/src/airflow_breeze/global_constants.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/global_constants.py)\n\n\n# Docker and Helm Deployment\n\nApache Airflow provides comprehensive support for containerized and Kubernetes-based deployments through Docker images and Helm charts. This documentation covers the deployment mechanisms, configuration options, and best practices for running Airflow in these environments.\n\n## Overview\n\nApache Airflow can be deployed using two primary methods:\n\n| Deployment Method | Use Case | Primary Files |\n|------------------|----------|---------------|\n| **Docker** | Local development, single-node deployments, CI/CD pipelines | `Dockerfile`, `Dockerfile.ci` |\n| **Helm Chart** | Production Kubernetes deployments, distributed systems | `chart/Chart.yaml`, `chart/values.yaml` |\n\n资料来源：[docker-stack-docs/README.md](https://github.com/apache/airflow/blob/main/docker-stack-docs/README.md)\n\n## Docker Image Architecture\n\nApache Airflow ships with two main Docker images optimized for different use cases.\n\n### Production Image (`Dockerfile`)\n\nThe production Docker image is built using multi-stage builds and includes all necessary components for running Airflow in production environments. The image uses `python:{DEFAULT_PYTHON_MAJOR_MINOR_VERSION}-slim-{ALLOWED_DEBIAN_VERSIONS[0]}` as its base.\n\nKey characteristics of the production image:\n\n- **Base OS**: Debian slim variant for minimal footprint\n- **Package Manager**: Uses `uv` (Ultraviolet) for faster pip installations\n- **Architecture**: Multi-stage build for optimized image size\n- **User Space**: Runs as non-root user for security\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/release_management_commands.py:55-62](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/release_management_commands.py)\n\n### CI Image (`Dockerfile.ci`)\n\nThe CI image is designed for continuous integration workflows and includes additional tooling for testing and development.\n\n```dockerfile\n# syntax=docker/dockerfile:1.4\nFROM python:{DEFAULT_PYTHON_MAJOR_MINOR_VERSION}-slim-{ALLOWED_DEBIAN_VERSIONS[0]}\nRUN apt-get update && apt-get install -y --no-install-recommends libatomic1 git curl\nRUN pip install uv=={UV_VERSION}\nRUN --mount=type=cache,id=cache-airflow-build-dockerfile-installation,target=/root/.cache/ \\\n uv pip install --system ignore pip=={AIRFLOW_PIP_VERSION} hatch=={HATCH_VERSION} \\\n pyyaml=={PYYAML_VERSION} gitpython=={GITPYTHON_VERSION} rich=={RICH_VERSION} \\\n prek=={PREK_VERSION}\nCOPY . /opt/airflow\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/release_management_commands.py:56-65](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/release_management_commands.py)\n\n### Version Constants\n\nThe build process uses the following pinned version constants:\n\n| Constant | Version | Purpose |\n|----------|---------|---------|\n| `AIRFLOW_PIP_VERSION` | `26.1.1` | pip package manager |\n| `AIRFLOW_UV_VERSION` | `0.11.11` | Fast Python package installer |\n| `GITPYTHON_VERSION` | `3.1.50` | Git operations in Python |\n| `RICH_VERSION` | `15.0.0` | Rich terminal output |\n| `HATCH_VERSION` | `1.16.5` | Python packaging |\n| `PYYAML_VERSION` | `6.0.3` | YAML parsing |\n| `PREK_VERSION` | `0.3.13` | Pre-commit hooks |\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/release_management_commands.py:70-76](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/release_management_commands.py)\n\n## Helm Chart Deployment\n\nThe Apache Airflow Helm chart provides a production-ready deployment mechanism for Kubernetes clusters.\n\n### Chart Metadata\n\n| Property | Value |\n|----------|-------|\n| Chart Name | `airflow` |\n| Repository | Apache Airflow Official |\n| Kubernetes Support | v1.30+, v1.31+, v1.32+, v1.33+ |\n\nSupported Kubernetes versions are determined by the major cloud providers (EKS, AKS, GKE) support windows.\n\n资料来源：[dev/breeze/src/airflow_breeze/global_constants.py:48-54](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/global_constants.py)\n\n### Core Components\n\nThe Helm chart deploys the following core Airflow components:\n\n```mermaid\ngraph TD\n A[Helm Chart] --> B[Webserver]\n A --> C[Scheduler]\n A --> D[Triggerer]\n A --> E[Worker]\n A --> F[Flower]\n A --> G[StatsD]\n A --> H[Redis]\n A --> I[PostgreSQL/MySQL]\n \n B -->|Read/Write| I\n C -->|Queue Jobs| H\n D -->|Async Tasks| H\n E -->|Process Tasks| H\n```\n\n### Scheduler Deployment\n\nThe scheduler is deployed as a Kubernetes Deployment with the following characteristics:\n\n- **Replicas**: Configurable via `replicas` parameter\n- **Resources**: Configurable CPU and memory limits\n- **Health Checks**: Liveness and readiness probes\n- **Persistence**: Optional volume mounts for DAGs and logs\n\n资料来源：[chart/templates/scheduler/scheduler-deployment.yaml](https://github.com/apache/airflow/blob/main/chart/templates/scheduler/scheduler-deployment.yaml)\n\n### Worker Deployment\n\nWorkers process tasks from the message queue and are deployed as:\n\n- **Deployment Type**: StatefulSet or Deployment based on configuration\n- **Scaling**: Horizontal Pod Autoscaler (HPA) support\n- **Queue Configuration**: Multiple queues supported\n- **Resource Management**: Configurable resource requests and limits\n\n资料来源：[chart/templates/workers/worker-deployment.yaml](https://github.com/apache/airflow/blob/main/chart/templates/workers/worker-deployment.yaml)\n\n## Installation Methods\n\n### Installing from PyPI\n\nWhile it is possible to install Airflow using tools like Poetry or pip-tools, only `pip` installation is currently officially supported.\n\n> **Note**: Installing via Poetry or pip-tools is not currently supported.\n\nFor repeatable installation, Airflow maintains \"known-to-be-working\" constraint files in the orphan `constraints-main` and `constraints-2-0` branches. These constraint files are maintained per major/minor Python version.\n\n资料来源：[generated/PYPI_README.md](https://github.com/apache/airflow/blob/main/generated/PYPI_README.md)\n\n### Installing Providers from Sources\n\nProviders can be installed from source with SHA512 verification:\n\n```bash\nshasum -a 512 {{ package_name }}-{{ package_version }}.tar.gz | diff - {{ package_name }}-{{ package_version }}.tar.gz.sha512\n```\n\nThis ensures the integrity of the downloaded package against the provided checksum.\n\n资料来源：[devel-common/src/sphinx_exts/includes/installing-providers-from-sources.rst](https://github.com/apache/airflow/blob/main/devel-common/src/sphinx_exts/includes/installing-providers-from-sources.rst)\n\n## Helm Chart Package Preparation\n\nThe release management tooling includes commands for preparing Helm chart packages:\n\n```mermaid\ngraph LR\n A[Chart Source] --> B[helm package]\n B --> C[Deterministic Repack]\n C --> D[PGP Signature]\n D --> E[Distribution Archive]\n```\n\n### Package Signing\n\nHelm chart packages can be signed using GPG for verification:\n\n```bash\nhelm gpg sign -u \n```\n\nThe signing process generates a provenance file (`.tgz.prov`) that can be used to verify the package integrity.\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/release_management_commands.py:400-420](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/release_management_commands.py)\n\n## Software Bill of Materials (SBOM)\n\nThe Airflow project generates and maintains SBOM information for security and compliance purposes.\n\n### SBOM Commands\n\nThe `breeze` CLI provides commands for managing SBOM information:\n\n```bash\nbreeze sbom update-sbom-information [OPTIONS]\n```\n\n#### Command Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `--airflow-site-archive-path` | Path | Directory for airflow-site-archive |\n| `--airflow-root-path` | Path | Root of the airflow repository |\n| `--airflow-version` | String | Version of airflow to update SBOM |\n| `--airflow-constraints-reference` | String | Constraints reference for SBOM generation |\n\nThese files are placed in `airflow-site-archive/docs-archive/` or `generated/_build/docs/apache-airflow/stable/` depending on the configuration.\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/sbom_commands.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/sbom_commands.py)\n\n### SBOM File Generation\n\nSBOM files are generated based on:\n\n- `provider.yaml` files\n- Airflow constraints\n- Provider tags and releases\n\nThe SBOM information is automatically regenerated using the `breeze release-management generate-providers-metadata` command.\n\n资料来源：[generated/README.md](https://github.com/apache/airflow/blob/main/generated/README.md)\n\n## Docker Compose Deployment\n\nFor development and testing purposes, Airflow can be deployed using Docker Compose.\n\n### Prerequisites\n\n- Docker Engine\n- Docker Compose v2+\n- SQLite database (automatically created if `AIRFLOW_HOME` is not set)\n\n### Basic Usage\n\nFor example commands that start Airflow, refer to the [Executing commands](https://airflow.apache.org/docs/docker-stack/entrypoint.html#entrypoint-commands) documentation.\n\n资料来源：[docker-stack-docs/README.md](https://github.com/apache/airflow/blob/main/docker-stack-docs/README.md)\n\n## Deployment Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n A[Airflow CLI] --> B[REST API]\n C[Web UI] --> B\n end\n \n subgraph \"Core Services\"\n D[Scheduler] --> E[(Metadata DB)]\n F[Triggerer] --> E\n G[Webserver] --> E\n end\n \n subgraph \"Task Execution\"\n H[Workers] --> I[Message Queue]\n D --> I\n F --> I\n end\n \n subgraph \"Storage\"\n J[DAGs Repository]\n K[Logs Storage]\n L[Plugins]\n end\n \n H --> K\n G --> K\n D --> J\n```\n\n## Default Connections\n\nThe Airflow deployment includes pre-configured connection templates for common services:\n\n| Connection ID | Type | Default Settings |\n|---------------|------|-------------------|\n| `google_cloud_default` | Google Cloud Platform | Schema: default |\n| `http_default` | HTTP | Host: https://www.httpbin.org/ |\n| `ftp_default` | FTP | localhost:21 |\n| `hive_cli_default` | Hive CLI | localhost:10000 |\n| `hiveserver2_default` | HiveServer2 | localhost:10000 |\n| `fs_default` | File System | Path: / |\n| `gremlin_default` | Gremlin | Host: gremlin:8182 |\n| `iceberg_default` | Iceberg | HTTPS endpoint |\n\n资料来源：[airflow-core/src/airflow/utils/db.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/utils/db.py)\n\n## Verification and Security\n\n### Package Verification\n\nPyPI releases can be verified by downloading the package, signature, and SHA sum files:\n\n```bash\n#!/bin/bash\nPACKAGE_VERSION={{ package_version }}\nPACKAGE_NAME={{ package_name }}\nprovider_download_dir=$(mktemp -d)\npip download --no-deps \"${PACKAGE_NAME}==${PACKAGE_VERSION}\" --dest \"${provider_download_dir}\"\ncurl \"{{ base_url }}/{{ package_name_underscores }}-{{ package_version }}-py3-none-any.whl.asc\" \\\n -L -o \"${provider_download_dir}/{{ package_name_underscores }}-{{ package_version }}-py3-none-any.whl.asc\"\ncurl \"{{ base_url }}/{{ package_name_underscores }}-{{ package_version }}-py3-none-any.whl.sha512\" \\\n -L -o \"${provider_download_dir}/{{ package_name_underscores }}-{{ package_version }}-py3-none-any.whl.sha512\"\necho \"Please verify files downloaded to ${provider_download_dir}\"\nls -\n```\n\n资料来源：[devel-common/src/sphinx_exts/includes/installing-providers-from-sources.rst](https://github.com/apache/airflow/blob/main/devel-common/src/sphinx_exts/includes/installing-providers-from-sources.rst)\n\n## Related Documentation\n\n- [Docker Stack Documentation](https://airflow.apache.org/docs/docker-stack/)\n- [Helm Chart Documentation](https://airflow.apache.org/docs/helm-chart/)\n- [Docker Compose Guide](https://airflow.apache.org/docs/apache-airflow/stable/howto/docker-compose/index.html)\n- [Executing Commands in Docker](https://airflow.apache.org/docs/docker-stack/entrypoint.html)\n\n---\n\n\n\n## Kubernetes Deployment\n\n### 相关页面\n\n相关主题：[Docker and Helm Deployment](#docker-helm), [Scheduler and Executor Architecture](#scheduler-executor)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/executors/kubernetes_executor.py](https://github.com/apache/airflow/blob/main/providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/executors/kubernetes_executor.py)\n- [providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/operators/pod.py](https://github.com/apache/airflow/blob/main/providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/operators/pod.py)\n- [providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/kube_config.py](https://github.com/apache/airflow/blob/main/providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/kube_config.py)\n- [providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/pod_generator.py](https://github.com/apache/airflow/blob/main/providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/pod_generator.py)\n- [chart/templates/triggerer/triggerer-deployment.yaml](https://github.com/apache/airflow/blob/main/chart/templates/triggerer/triggerer-deployment.yaml)\n- [airflow-core/docs/administration-and-deployment/kubernetes.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/administration-and-deployment/kubernetes.rst)\n- [dev/breeze/src/airflow_breeze/commands/kubernetes_commands.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/kubernetes_commands.py)\n\n\n# Kubernetes Deployment\n\nApache Airflow provides comprehensive Kubernetes support through the CNCF Kubernetes provider package. This integration enables Airflow to run tasks as Kubernetes Pods, providing dynamic resource allocation, isolation, and scalability for workflow execution.\n\n## Architecture Overview\n\nAirflow's Kubernetes deployment consists of multiple components that work together to provide a flexible, scalable execution environment.\n\n### Kubernetes Executor Architecture\n\nThe Kubernetes Executor is one of Airflow's core executors that launches a new Pod for each task instance. Unlike the Celery Executor which reuses workers, the Kubernetes Executor creates isolated Pods for each task execution.\n\n```mermaid\ngraph TD\n A[Airflow Scheduler] -->|submits task| B[Kubernetes Executor]\n B -->|creates| C[Task Pod]\n B -->|watches| C\n C -->|completes| D[Pod Status Update]\n D -->|pods cleaned up| E[Resource Cleanup]\n \n F[Kubernetes API Server] -->|manages| C\n G[Worker Nodes] -->|hosts| C\n```\n\n### Core Components\n\n| Component | File Path | Purpose |\n|-----------|-----------|---------|\n| KubernetesExecutor | `providers/cncf/kubernetes/.../executors/kubernetes_executor.py` | Main executor implementation |\n| KubernetesPodOperator | `providers/cncf/kubernetes/.../operators/pod.py` | Operator for running pods |\n| KubeConfig | `providers/cncf/kubernetes/.../kube_config.py` | Configuration management |\n| PodGenerator | `providers/cncf/kubernetes/.../pod_generator.py` | Pod specification builder |\n\n## Configuration\n\n### Kubernetes Executor Configuration\n\nThe Kubernetes Executor requires configuration in the `airflow.cfg` file under the `[kubernetes]` section.\n\n```ini\n[core]\nexecutor = airflow.providers.cncf.kubernetes.executors.kubernetes_executor.KubernetesExecutor\n\n[kubernetes]\nnamespace = default\npod_template_file = /path/to/pod_template.yaml\nworker_container_repository = apache/airflow\nworker_container_tag = latest\n```\n\n### Key Configuration Parameters\n\n| Parameter | Description | Default |\n|-----------|-------------|---------|\n| `namespace` | Kubernetes namespace for task pods | `default` |\n| `pod_template_file` | Path to pod template yaml | - |\n| `worker_container_repository` | Docker image repository | `apache/airflow` |\n| `worker_container_tag` | Docker image tag | `latest` |\n| `delete_worker_pods` | Delete pods after task completion | `True` |\n| `delete_worker_pods_on_failure` | Delete pods on task failure | `False` |\n| `worker_pods_creation_batch_size` | Batch size for pod creation | `2` |\n\n资料来源：[providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/kube_config.py]()\n\n## Pod Generation\n\nThe `PodGenerator` class is responsible for constructing Kubernetes Pod specifications from Airflow task definitions.\n\n### Pod Template System\n\nAirflow supports custom pod templates that define the base pod specification. These templates use Jinja2 templating to allow dynamic value injection.\n\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n name: airflow-worker-pod\nspec:\n containers:\n - name: base\n image: \"{{ container_image }}\"\n env:\n - name: AIRFLOW__CORE__EXECUTOR\n value: LocalExecutor\n```\n\n资料来源：[providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/pod_generator.py]()\n\n### Dynamic Pod Configuration\n\nThe KubernetesPodOperator allows dynamic configuration of pod specifications at runtime:\n\n```python\nfrom airflow.providers.cncf.kubernetes.operators.pod import KubernetesPodOperator\n\nrun_pod = KubernetesPodOperator(\n task_id=\"run_kubernetes_pod\",\n name=\"my-task-pod\",\n namespace=\"default\",\n image=\"python:3.9-slim\",\n cmds=[\"python\", \"-c\", \"print('Hello from Kubernetes')\"],\n labels={\"app\": \"airflow\", \"environment\": \"production\"},\n volumes=[config_volume],\n volume_mounts=[config_volume_mount],\n get_logs=True,\n is_delete_operator_pod=True,\n)\n```\n\n## Airflow Components on Kubernetes\n\n### Triggerer Deployment\n\nThe Airflow Triggerer runs as a Kubernetes Deployment to manage triggering logic in a distributed environment.\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: airflow-triggerer\n namespace: airflow\nspec:\n replicas: 2\n selector:\n matchLabels:\n component: triggerer\n tier: airflow\n template:\n metadata:\n labels:\n component: triggerer\n tier: airflow\n spec:\n serviceAccountName: airflow-triggerer\n containers:\n - name: triggerer\n image: {{ .Values.images.triggerer }}\n args: [\"triggerer\"]\n ports:\n - name: logs\n containerPort: 8793\n```\n\n资料来源：[chart/templates/triggerer/triggerer-deployment.yaml]()\n\n### Component Services\n\n| Component | Kubernetes Object | Purpose |\n|-----------|-------------------|---------|\n| Scheduler | Deployment | DAG parsing and task scheduling |\n| Webserver | Deployment | Airflow UI serving |\n| Triggerer | Deployment | Deferred task handling |\n| Worker | Deployment/DaemonSet | Task execution |\n| Flower | Deployment | Celery monitoring (optional) |\n| Database | StatefulSet | Metadata storage |\n| Redis | StatefulSet | Message broker |\n\n## Local Development with Skaffold\n\nAirflow provides development workflows using Skaffold for hot-reloading code changes into running Kubernetes pods.\n\n### Skaffold Dev Loop\n\n```bash\nbreeze k8s dev\n```\n\nThis command runs the Skaffold dev loop to sync DAGs and airflow-core sources to running pods including scheduler, triggerer, dag-processor, and API Server with hot-reload support.\n\n```python\n@pulumi_benchmark.group.command(\n name=\"dev\",\n help=(\n \"Run skaffold dev loop to sync dags and airflow-core sources to running pods \"\n \"(scheduler/triggerer/dag-processor/API Server hot-reload; UI auto-refresh not supported yet).\"\n ),\n)\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/kubernetes_commands.py]()\n\n## KubernetesPodOperator\n\nThe KubernetesPodOperator allows users to define and execute arbitrary Kubernetes Pods as Airflow tasks.\n\n### Operator Features\n\n| Feature | Description |\n|---------|-------------|\n| Full Pod Spec | Define complete pod specifications |\n| Volume Management | Support for ConfigMaps, Secrets, PVCs |\n| Image Pull | Private registry authentication |\n| Resource Limits | CPU and memory constraints |\n| Node Selection | Pod affinity and node selectors |\n| Sidecars | Support for sidecar containers |\n\n### Basic Usage\n\n```python\nfrom airflow.providers.cncf.kubernetes.operators.pod import KubernetesPodOperator\n\nwith dag:\n k = KubernetesPodOperator(\n task_id=\"demo_pod\",\n name=\"demo-pod\",\n image=\"python:3.9\",\n cmds=[\"python\", \"-c\", \"print('Hello World')\"],\n namespace=\"default\",\n is_delete_operator_pod=True,\n get_logs=True,\n )\n```\n\n资料来源：[providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/operators/pod.py]()\n\n## Executor Implementation\n\n### Task Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Scheduler\n participant K8sExecutor\n participant KubeAPI\n participant Pod\n \n Scheduler->>K8sExecutor: Queue task for execution\n K8sExecutor->>KubeAPI: Create Pod\n KubeAPI->>Pod: Launch pod\n Pod->>Pod: Execute task\n Pod->>KubeAPI: Report completion\n KubeAPI->>K8sExecutor: Pod completed\n K8sExecutor->>Scheduler: Task result\n```\n\n### Executor Configuration\n\n```python\nclass KubernetesExecutor:\n \"\"\"Kubernetes executor implementation.\"\"\"\n \n def __init__(self):\n self.kube_config = KubeConfig()\n self.manager = PodLauncher(\n kube_config=self.kube_config,\n in_cluster=self.kube_config.get(\"in_cluster\", False),\n )\n```\n\n资料来源：[providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/executors/kubernetes_executor.py]()\n\n## Security Considerations\n\n### Service Account Configuration\n\nRunning Airflow on Kubernetes requires proper service account configuration with appropriate RBAC permissions.\n\n```yaml\napiVersion: v1\nkind: ServiceAccount\nmetadata:\n name: airflow-executor\n namespace: airflow\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: Role\nmetadata:\n name: airflow-executor\nrules:\n - apiGroups: [\"\"]\n resources: [\"pods\"]\n verbs: [\"create\", \"delete\", \"get\", \"list\", \"patch\", \"watch\"]\n - apiGroups: [\"\"]\n resources: [\"pods/log\"]\n verbs: [\"get\"]\n```\n\n### Security Context\n\nPods can be configured with security contexts for enhanced isolation:\n\n```python\nKubernetesPodOperator(\n task_id=\"secure_pod\",\n security_context={\n \"runAsUser\": 1000,\n \"fsGroup\": 2000,\n \"capabilities\": {\"drop\": [\"ALL\"]},\n },\n container_security_context={\n \"readOnlyRootFilesystem\": True,\n \"runAsNonRoot\": True,\n },\n)\n```\n\n## Resource Management\n\n### Pod Resources\n\nTasks can define resource requests and limits:\n\n```python\nKubernetesPodOperator(\n task_id=\"resource_limited_task\",\n container_resources={\n \"request_memory\": \"128Mi\",\n \"request_cpu\": 0.5,\n \"limit_memory\": \"256Mi\",\n \"limit_cpu\": 1,\n },\n)\n```\n\n### Node Affinity and Tolerations\n\n```python\nKubernetesPodOperator(\n task_id=\"specific_node_task\",\n node_selector={\n \"disktype\": \"ssd\",\n \"kubernetes.io/arch\": \"amd64\",\n },\n tolerations=[\n {\n \"key\": \"dedicated\",\n \"operator\": \"Equal\",\n \"value\": \"airflow\",\n \"effect\": \"NoSchedule\",\n }\n ],\n)\n```\n\n## Monitoring and Logging\n\n### Log Aggregation\n\nThe KubernetesPodOperator supports automatic log retrieval from pods:\n\n```python\nKubernetesPodOperator(\n task_id=\"task_with_logs\",\n get_logs=True,\n log_events_on_failure=True,\n)\n```\n\n### Pod Monitoring\n\nPod status can be monitored through the Kubernetes API:\n\n```python\nfrom airflow.providers.cncf.kubernetes.utils import delete_from_dict, create_from_dict\n\n# Watch pod status\nwatcher = PodWatcher(kube_config)\nfor event in watcher.poll_for_pod_completion(task_instance):\n if event[\"type\"] == \"DELETED\":\n break\n```\n\n## Best Practices\n\n### 1. Use Pod Templates\n\nDefine reusable pod templates to ensure consistency across tasks:\n\n```yaml\n# pod_template.yaml\napiVersion: v1\nkind: Pod\nspec:\n securityContext:\n runAsUser: 1000\n fsGroup: 2000\n containers:\n - name: base\n resources:\n requests:\n memory: \"128Mi\"\n cpu: 0.25\n limits:\n memory: \"256Mi\"\n cpu: 0.5\n```\n\n### 2. Implement Graceful Cleanup\n\nConfigure pod deletion policies to manage resource cleanup:\n\n```python\nKubernetesPodOperator(\n task_id=\"cleanup_example\",\n is_delete_operator_pod=True,\n on_finish_callback=cleanup_handler,\n)\n```\n\n### 3. Set Appropriate Timeouts\n\nAlways define task timeouts to prevent orphaned pods:\n\n```python\nKubernetesPodOperator(\n task_id=\"timeout_task\",\n execution_timeout=timedelta(minutes=30),\n task_concurrency=10,\n)\n```\n\n## Helm Chart Deployment\n\nThe official Airflow Helm chart provides production-ready Kubernetes deployment configurations.\n\n### Minimal Installation\n\n```bash\nhelm install airflow apache-airflow/airflow \\\n --namespace airflow \\\n --create-namespace \\\n --set executor=CeleryExecutor \\\n --set webserver.service.type=LoadBalancer\n```\n\n### Production Installation\n\n```bash\nhelm install airflow apache-airflow/airflow \\\n --namespace airflow \\\n --values production-values.yaml\n```\n\nThe Helm chart supports extensive customization through values files, including:\n- Multi-tier architecture configuration\n- Ingress setup for webserver access\n- External database and message broker\n- Persistent volume claims for DAG storage\n- Resource limits per component\n- Security contexts and pod policies\n\n## References\n\nFor further information, refer to the official documentation at `airflow-core/docs/administration-and-deployment/kubernetes.rst` and the Kubernetes provider source code in `providers/cncf/kubernetes/`.\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：apache/airflow\n\n摘要：发现 19 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：`ExternalTaskSensor` can succeed early for task groups with NULL task states。\n\n## 1. 安装坑 · 来源证据：`ExternalTaskSensor` can succeed early for task groups with NULL task states\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`ExternalTaskSensor` can succeed early for task groups with NULL task states\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c746f7ce44f43f1a5a81840f4ee741a | https://github.com/apache/airflow/issues/66877 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:33884891 | https://github.com/apache/airflow | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:33884891 | https://github.com/apache/airflow | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:33884891 | https://github.com/apache/airflow | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:33884891 | https://github.com/apache/airflow | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:33884891 | https://github.com/apache/airflow | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 来源证据：Apache Airflow 3.1.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.1.6\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c94c5b79bb91454c9e0ad22b4a36dc11 | https://github.com/apache/airflow/releases/tag/3.1.6 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 8. 安全/权限坑 · 来源证据：Apache Airflow 3.1.7\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.1.7\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_80a5614167b44ecca96422caa56afca4 | https://github.com/apache/airflow/releases/tag/3.1.7 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 9. 安全/权限坑 · 来源证据：Apache Airflow 3.1.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.1.8\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3437fcfc89ff40a0ba17b7e5a5d8aa2c | https://github.com/apache/airflow/releases/tag/3.1.8 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 安全/权限坑 · 来源证据：Apache Airflow 3.2.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.2.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d18a498a98ed48f0bb3f813aaa554aea | https://github.com/apache/airflow/releases/tag/3.2.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 11. 安全/权限坑 · 来源证据：Apache Airflow 3.2.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.2.1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_41889eab2c0240bbb0bd010262d41346 | https://github.com/apache/airflow/releases/tag/3.2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：Apache Airflow Ctl (airflowctl) 0.1.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow Ctl (airflowctl) 0.1.2\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_df5b495084624a899a4674d4b0193ec7 | https://github.com/apache/airflow/releases/tag/airflow-ctl/0.1.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：Apache Airflow Helm Chart 1.19.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow Helm Chart 1.19.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0f5ecc599d634c1daa9ee6c9f2434849 | https://github.com/apache/airflow/releases/tag/helm-chart/1.19.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：Apache Airflow Helm Chart 1.20.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow Helm Chart 1.20.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c13fe02283094cffa9e186716cc8dcf5 | https://github.com/apache/airflow/releases/tag/helm-chart/1.20.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：Apache Airflow Helm Chart 1.21.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow Helm Chart 1.21.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d29213d0ae2441e8907f407d8dc9b861 | https://github.com/apache/airflow/releases/tag/helm-chart/1.21.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：airflow-ctl/0.1.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：airflow-ctl/0.1.3\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9096523c7ba541c6ac1b6b926d6f6bc0 | https://github.com/apache/airflow/releases/tag/airflow-ctl/0.1.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：edge3: upgrade from 1.x silently leaves schema stale — `BaseDBManager.upgradedb` stamps `alembic_version_edge3` to head…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：edge3: upgrade from 1.x silently leaves schema stale — `BaseDBManager.upgradedb` stamps `alembic_version_edge3` to head without running migrations\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2bc80550929a49ddbce05c557bb225e0 | https://github.com/apache/airflow/issues/66524 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:33884891 | https://github.com/apache/airflow | issue_or_pr_quality=unknown\n\n## 19. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:33884891 | https://github.com/apache/airflow | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：apache/airflow\n\n摘要：发现 19 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：`ExternalTaskSensor` can succeed early for task groups with NULL task states。\n\n## 1. 安装坑 · 来源证据：`ExternalTaskSensor` can succeed early for task groups with NULL task states\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`ExternalTaskSensor` can succeed early for task groups with NULL task states\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c746f7ce44f43f1a5a81840f4ee741a | https://github.com/apache/airflow/issues/66877 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:33884891 | https://github.com/apache/airflow | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:33884891 | https://github.com/apache/airflow | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:33884891 | https://github.com/apache/airflow | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:33884891 | https://github.com/apache/airflow | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:33884891 | https://github.com/apache/airflow | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 来源证据：Apache Airflow 3.1.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.1.6\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c94c5b79bb91454c9e0ad22b4a36dc11 | https://github.com/apache/airflow/releases/tag/3.1.6 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 8. 安全/权限坑 · 来源证据：Apache Airflow 3.1.7\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.1.7\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_80a5614167b44ecca96422caa56afca4 | https://github.com/apache/airflow/releases/tag/3.1.7 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 9. 安全/权限坑 · 来源证据：Apache Airflow 3.1.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.1.8\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3437fcfc89ff40a0ba17b7e5a5d8aa2c | https://github.com/apache/airflow/releases/tag/3.1.8 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 安全/权限坑 · 来源证据：Apache Airflow 3.2.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.2.0\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d18a498a98ed48f0bb3f813aaa554aea | https://github.com/apache/airflow/releases/tag/3.2.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 11. 安全/权限坑 · 来源证据：Apache Airflow 3.2.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow 3.2.1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_41889eab2c0240bbb0bd010262d41346 | https://github.com/apache/airflow/releases/tag/3.2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：Apache Airflow Ctl (airflowctl) 0.1.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow Ctl (airflowctl) 0.1.2\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_df5b495084624a899a4674d4b0193ec7 | https://github.com/apache/airflow/releases/tag/airflow-ctl/0.1.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：Apache Airflow Helm Chart 1.19.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow Helm Chart 1.19.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0f5ecc599d634c1daa9ee6c9f2434849 | https://github.com/apache/airflow/releases/tag/helm-chart/1.19.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：Apache Airflow Helm Chart 1.20.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow Helm Chart 1.20.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c13fe02283094cffa9e186716cc8dcf5 | https://github.com/apache/airflow/releases/tag/helm-chart/1.20.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：Apache Airflow Helm Chart 1.21.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Apache Airflow Helm Chart 1.21.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d29213d0ae2441e8907f407d8dc9b861 | https://github.com/apache/airflow/releases/tag/helm-chart/1.21.0 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：airflow-ctl/0.1.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：airflow-ctl/0.1.3\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9096523c7ba541c6ac1b6b926d6f6bc0 | https://github.com/apache/airflow/releases/tag/airflow-ctl/0.1.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：edge3: upgrade from 1.x silently leaves schema stale — `BaseDBManager.upgradedb` stamps `alembic_version_edge3` to head…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：edge3: upgrade from 1.x silently leaves schema stale — `BaseDBManager.upgradedb` stamps `alembic_version_edge3` to head without running migrations\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2bc80550929a49ddbce05c557bb225e0 | https://github.com/apache/airflow/issues/66524 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:33884891 | https://github.com/apache/airflow | issue_or_pr_quality=unknown\n\n## 19. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:33884891 | https://github.com/apache/airflow | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# airflow - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 airflow 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的流程自动化任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-introduction：Project Introduction。围绕“Project Introduction”模拟一次用户任务，不展示安装或运行结果。\n2. core-concepts：Core Concepts。围绕“Core Concepts”模拟一次用户任务，不展示安装或运行结果。\n3. architecture-overview：Architecture Overview。围绕“Architecture Overview”模拟一次用户任务，不展示安装或运行结果。\n4. scheduler-executor：Scheduler and Executor Architecture。围绕“Scheduler and Executor Architecture”模拟一次用户任务，不展示安装或运行结果。\n5. rest-api：REST API。围绕“REST API”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-introduction\n输入：用户提供的“Project Introduction”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. core-concepts\n输入：用户提供的“Core Concepts”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture-overview\n输入：用户提供的“Architecture Overview”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. scheduler-executor\n输入：用户提供的“Scheduler and Executor Architecture”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. rest-api\n输入：用户提供的“REST API”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-introduction：Step 1 必须围绕“Project Introduction”形成一个小中间产物，并等待用户确认。\n- Step 2 / core-concepts：Step 2 必须围绕“Core Concepts”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture-overview：Step 3 必须围绕“Architecture Overview”形成一个小中间产物，并等待用户确认。\n- Step 4 / scheduler-executor：Step 4 必须围绕“Scheduler and Executor Architecture”形成一个小中间产物，并等待用户确认。\n- Step 5 / rest-api：Step 5 必须围绕“REST API”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/apache/airflow\n- https://github.com/apache/airflow#readme\n- .github/skills/aip-user-stories/SKILL.md\n- .github/skills/airflow-translations/SKILL.md\n- .github/skills/maintainer-review/SKILL.md\n- .github/skills/pr-stats/SKILL.md\n- .github/skills/pr-triage/SKILL.md\n- .github/skills/prepare-providers-documentation/SKILL.md\n- README.md\n- INSTALLING.md\n- PROVIDERS.rst\n- airflow-core/src/airflow/version.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 airflow 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：apache/airflow\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install apache-airflow\n```\n\n来源：https://github.com/apache/airflow#readme\n\n## 来源\n\n- repo: https://github.com/apache/airflow\n- docs: https://github.com/apache/airflow#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_8d9084c3d733430f996064066351670c"
}