{
"canonical_name": "apache/airflow",
"compilation_id": "pack_9a3e1077c0d7496298fac5abc1b0b4b5",
"created_at": "2026-05-13T22:49:30.334317+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": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli"
},
"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": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"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. intro：Airflow简介与核心概念。围绕“Airflow简介与核心概念”模拟一次用户任务，不展示安装或运行结果。\n2. quickstart：快速开始与安装指南。围绕“快速开始与安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. architecture：系统架构详解。围绕“系统架构详解”模拟一次用户任务，不展示安装或运行结果。\n4. components：核心组件详解。围绕“核心组件详解”模拟一次用户任务，不展示安装或运行结果。\n5. executors：执行器类型与选择。围绕“执行器类型与选择”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. intro\n输入：用户提供的“Airflow简介与核心概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quickstart\n输入：用户提供的“快速开始与安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture\n输入：用户提供的“系统架构详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. components\n输入：用户提供的“核心组件详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. executors\n输入：用户提供的“执行器类型与选择”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / intro：Step 1 必须围绕“Airflow简介与核心概念”形成一个小中间产物，并等待用户确认。\n- Step 2 / quickstart：Step 2 必须围绕“快速开始与安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture：Step 3 必须围绕“系统架构详解”形成一个小中间产物，并等待用户确认。\n- Step 4 / components：Step 4 必须围绕“核心组件详解”形成一个小中间产物，并等待用户确认。\n- Step 5 / executors：Step 5 必须围绕“执行器类型与选择”形成一个小中间产物，并等待用户确认。\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- airflow-core/src/airflow/models/dag.py\n- airflow-core/src/airflow/models/taskinstance.py\n- airflow-core/src/airflow/_shared/state/__init__.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": "code",
"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-13 22:31:12 UTC\n\n## 目录\n\n- [Airflow简介与核心概念](#intro)\n- [快速开始与安装指南](#quickstart)\n- [系统架构详解](#architecture)\n- [核心组件详解](#components)\n- [执行器类型与选择](#executors)\n- [数据流转与交换机制](#data-flow)\n- [FastAPI核心API](#fastapi)\n- [React前端架构](#frontend)\n- [容器化与Kubernetes部署](#deployment)\n- [Provider生态系统](#providers)\n\n\n\n## Airflow简介与核心概念\n\n### 相关页面\n\n相关主题：[系统架构详解](#architecture), [快速开始与安装指南](#quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/apache/airflow/blob/main/README.md)\n- [airflow-core/src/airflow/models/dag.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/dag.py)\n- [airflow-core/src/airflow/models/taskinstance.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/taskinstance.py)\n- [airflow-core/src/airflow/_shared/state/__init__.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/_shared/state/__init__.py)\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\n# Airflow简介与核心概念\n\n## 概述\n\nApache Airflow是一个以编程方式创作、调度和监控工作流的平台。它允许用户使用Python代码定义、调度和执行复杂的批处理工作流。Airflow采用分布式架构，支持大规模工作流编排，是数据工程和MLOps领域广泛使用的开源工作流管理平台。\n\n资料来源：[README.md](https://github.com/apache/airflow/blob/main/README.md)\n\n## 核心架构\n\nAirflow采用主从架构，主要包含以下组件：\n\n| 组件 | 功能 | 说明 |\n|------|------|------|\n| Scheduler | 调度器 | 负责调度DAG运行，将任务分发给执行器 |\n| Executor | 执行器 | 实际执行任务，支持多种类型 |\n| Web Server | Web服务器 | 提供UI界面用于监控和管理 |\n| Worker | 工作进程 | 执行具体任务的进程 |\n| Metadata Database | 元数据库 | 存储DAG、任务、执行状态等元数据 |\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:1-100](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n\n```mermaid\ngraph TD\n A[用户编写的DAG定义] --> B[Scheduler]\n B --> C[Executor]\n C --> D[Worker]\n D --> E[Metadata Database]\n B --> E\n F[Web Server] --> E\n G[用户通过UI/API] --> F\n```\n\n## DAG有向无环图\n\nDAG（Directed Acyclic Graph）是Airflow的核心概念，代表工作流的结构定义。\n\n### DAG定义\n\n```python\nfrom airflow import DAG\nfrom datetime import datetime\n\nwith DAG(\n dag_id='my_first_dag',\n start_date=datetime(2024, 1, 1),\n schedule='@daily',\n catchup=False\n) as dag:\n task1 = BashOperator(task_id='task_1', bash_command='echo Hello')\n task2 = BashOperator(task_id='task_2', bash_command='echo World')\n task1 >> task2\n```\n\n资料来源：[airflow-core/src/airflow/models/dag.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/dag.py)\n\n### DAG属性\n\n| 属性 | 类型 | 描述 |\n|------|------|------|\n| dag_id | str | DAG的唯一标识符 |\n| start_date | datetime | DAG开始日期 |\n| schedule_interval | str/timedelta | 调度间隔 |\n| catchup | bool | 是否补跑历史数据 |\n| max_active_runs | int | 最大同时运行数 |\n| is_paused | bool | DAG是否暂停 |\n\n## 任务与任务实例\n\n### 任务类型\n\nAirflow支持多种任务类型：\n\n| 任务类型 | 说明 |\n|----------|------|\n| BashOperator | 执行Bash命令 |\n| PythonOperator | 执行Python函数 |\n| Sensor | 等待特定条件满足 |\n| TaskGroup | 任务组容器 |\n\n资料来源：[airflow-core/src/airflow/models/taskinstance.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/taskinstance.py)\n\n### 任务实例状态\n\n```mermaid\nstateDiagram-v2\n [*] --> queued: 任务创建\n queued --> scheduled: Scheduler调度\n scheduled --> running: Worker接收\n running --> success: 执行成功\n running --> failed: 执行失败\n running --> upstream_failed: 上游任务失败\n success --> [*]\n failed --> [*]\n upstream_failed --> [*]\n```\n\n资料来源：[airflow-core/src/airflow/_shared/state/__init__.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/_shared/state/__init__.py)\n\n## 执行器类型\n\nAirflow支持多种执行器，用于在不同环境中执行任务：\n\n| 执行器 | 说明 | 适用场景 |\n|--------|------|----------|\n| LocalExecutor | 本地并行执行 | 开发/测试环境 |\n| SequentialExecutor | 顺序执行 | 单任务场景 |\n| CeleryExecutor | 分布式执行 | 生产环境大规模任务 |\n| KubernetesExecutor | K8s Pod执行 | 云原生环境 |\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## CLI命令行接口\n\nAirflow提供丰富的CLI命令用于管理DAG和任务：\n\n| 命令 | 功能 |\n|------|------|\n| airflow dags list | 列出所有DAG |\n| airflow dags list-runs | 列出DAG运行记录 |\n| airflow tasks list | 列出DAG中的任务 |\n| airflow tasks test | 测试单个任务 |\n| airflow connections list | 列出连接 |\n| airflow variables list | 列出变量 |\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### 常用命令示例\n\n```bash\n# 列出所有DAG\nairflow dags list\n\n# 触发DAG手动运行\nairflow dags trigger my_dag_id\n\n# 暂停/恢复DAG\nairflow dags pause my_dag_id\nairflow dags unpause my_dag_id\n\n# 查看任务实例状态\nairflow tasks list my_dag_id\n```\n\n## 连接与变量\n\n### 连接管理\n\nAirflow提供连接（Connection）功能用于存储外部系统访问凭证：\n\n```python\nfrom airflow.models import Connection\nimport json\n\nconn = Connection(\n conn_id='my_postgres_conn',\n conn_type='postgres',\n host='localhost',\n schema='airflow_db',\n login='user',\n password='password',\n port=5432\n)\n```\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### 支持的连接类型\n\n| 连接类型 | 说明 |\n|----------|------|\n| postgres | PostgreSQL数据库 |\n| mysql | MySQL数据库 |\n| google_cloud_platform | GCP云平台 |\n| http | HTTP连接 |\n| ssh | SSH连接 |\n| s3 | AWS S3存储 |\n\n## 配置管理\n\n### airflow.cfg主要配置项\n\n| 配置节 | 配置项 | 说明 |\n|--------|--------|------|\n| core | dags_folder | DAG文件存放路径 |\n| core | executor | 执行器类型 |\n| core | catchup_by_default | 默认是否补跑 |\n| scheduler | num_runs | 调度器循环次数 |\n| webserver | web_server_host | Web服务器地址 |\n| database | sql_alchemy_conn | 数据库连接字符串 |\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## 工作流执行流程\n\n```mermaid\ngraph LR\n A1[DAG定义加载] --> A2[解析DAG结构]\n A2 --> A3[Scheduler创建DAG Run]\n A3 --> A4[任务排队]\n A4 --> A5[Executor分发任务]\n A5 --> A6[Worker执行任务]\n A6 --> A7[更新任务状态]\n A7 --> A8[记录到元数据库]\n A8 --> A9[Web UI展示状态]\n```\n\n## 最佳实践\n\n### DAG编写规范\n\n1. **任务唯一性**：每个任务的task_id在DAG内必须唯一\n2. **正确设置start_date**：避免使用动态时间作为start_date\n3. **合理的retry配置**：为关键任务配置重试策略\n4. **使用描述性命名**：使用清晰的DAG和任务命名\n\n### 调度配置建议\n\n| 配置项 | 建议值 | 说明 |\n|--------|--------|------|\n| catchup | False | 生产环境建议关闭补跑 |\n| max_active_runs | 1-5 | 根据任务复杂度调整 |\n| schedule_interval | @daily/@hourly | 根据业务需求选择 |\n| concurrency | 16-32 | 根据Worker能力设置 |\n\n## 总结\n\nApache Airflow作为强大的工作流编排平台，提供了完整的DAG定义、调度执行、监控告警等功能。理解其核心概念（DAG、Task、Executor、Connection）是有效使用Airflow的基础。通过合理的配置和最佳实践，可以构建稳定可靠的数据管道和工作流系统。\n\n---\n\n\n\n## 快速开始与安装指南\n\n### 相关页面\n\n相关主题：[Airflow简介与核心概念](#intro), [容器化与Kubernetes部署](#deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [INSTALLING.md](https://github.com/apache/airflow/blob/main/INSTALLING.md)\n- [Dockerfile](https://github.com/apache/airflow/blob/main/Dockerfile)\n- [Dockerfile.ci](https://github.com/apache/airflow/blob/main/Dockerfile.ci)\n- [airflow-core/src/airflow/example_dags/tutorial.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/example_dags/tutorial.py)\n- [generated/PYPI_README.md](https://github.com/apache/airflow/blob/main/generated/PYPI_README.md)\n- [airflow-core/src/airflow/_vendor/README.md](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/_vendor/README.md)\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- [dev/breeze/src/airflow_breeze/commands/production_image_commands.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/production_image_commands.py)\n \n\n# 快速开始与安装指南\n\nApache Airflow 是一个开源的工作流编排平台，用于编程创建、调度和监控批处理工作流。本指南将帮助您快速上手安装和配置 Airflow。\n\n## 系统要求\n\n在安装 Apache Airflow 之前，请确保您的系统满足以下基本要求：\n\n| 要求项 | 最低版本 | 说明 |\n|--------|----------|------|\n| Python | 3.9+ | Airflow 核心功能需要 |\n| pip | 最新版本 | Python 包管理器 |\n| 操作系统 | Linux, macOS, Windows (WSL2) | 生产环境推荐使用 Linux |\n| 数据库 | SQLite 3.15+, PostgreSQL 14+, MySQL 8.0+ | 元数据库存储 |\n| 内存 | 4GB RAM | 最小需求，生产环境更高 |\n\n资料来源：[INSTALLING.md:1-50](https://github.com/apache/airflow/blob/main/INSTALLING.md)\n\n## 安装方式概览\n\nAirflow 支持多种安装方式，您可以根据实际需求选择合适的方案：\n\n```mermaid\ngraph TD\n A[安装 Airflow] --> B{使用场景}\n B -->|快速测试| C[pip 直接安装]\n B -->|容器化部署| D[Docker 镜像]\n B -->|深度开发| E[从源码编译]\n C --> F[使用约束文件安装]\n D --> G[官方镜像或自定义]\n E --> H[Breeze 开发环境]\n```\n\n资料来源：[generated/PYPI_README.md:1-30](https://github.com/apache/airflow/blob/main/generated/PYPI_README.md)\n\n## 使用 pip 安装\n\n### 基础安装\n\n使用 pip 安装 Airflow 的标准方式是通过 pip install 命令配合约束文件：\n\n```bash\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\n约束文件确保所有依赖项的版本兼容，避免因依赖冲突导致的安装失败。约束文件根据 Python 版本不同而有所区别。\n\n资料来源：[INSTALLING.md:50-80](https://github.com/apache/airflow/blob/main/INSTALLING.md)\n\n### 安装额外依赖\n\nAirflow 提供了丰富的额外依赖包（extras），可按需安装：\n\n```bash\n# 安装包含 PostgreSQL 和 Google Cloud 支持的版本\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常用额外依赖包包括：\n\n| 额外包名 | 说明 |\n|----------|------|\n| postgres | PostgreSQL 数据库支持 |\n| mysql | MySQL 数据库支持 |\n| google | Google Cloud Platform 集成 |\n| amazon | AWS 集成 |\n| kubernetes | Kubernetes Executor 支持 |\n| sentry | Sentry 错误追踪集成 |\n\n资料来源：[generated/PYPI_README.md:40-60](https://github.com/apache/airflow/blob/main/generated/PYPI_README.md)\n\n### 供应商包安装\n\n除了核心 Airflow 包外，您还可以单独安装各种供应商（Provider）包：\n\n```bash\n# 从 PyPI 安装供应商包\npip install apache-airflow-providers-google\n\n# 从源码安装供应商包\npip install /path/to/apache-airflow-providers-google*.whl\n```\n\n安装后需要验证文件完整性：\n\n```bash\nshasum -a 512 package-name-version.tar.gz | diff - package-name-version.tar.gz.sha512\n```\n\n资料来源：[devel-common/src/sphinx_exts/includes/installing-providers-from-sources.rst:1-50](https://github.com/apache/airflow/blob/main/devel-common/src/sphinx_exts/includes/installing-providers-from-sources.rst)\n\n## Docker 安装\n\n### 官方镜像\n\nAirflow 提供了官方 Docker 镜像，可以快速启动完整的工作环境：\n\n```bash\n# 拉取最新稳定版镜像\ndocker pull apache/airflow:latest\n\n# 使用 Celery Executor 启动\ndocker run -d -p 8080:8080 \\\n -e AIRFLOW__DATABASE__SQL_ALCHEMY_CONN=postgresql+psycopg2://user:pass@host/db \\\n apache/airflow:latest\n```\n\n资料来源：[Dockerfile:1-30](https://github.com/apache/airflow/blob/main/Dockerfile)\n\n### Docker Compose 方式\n\n生产环境推荐使用 Docker Compose 进行部署，Airflow 项目提供了标准化的 docker-compose.yaml：\n\n```yaml\nversion: '3'\nservices:\n postgres:\n image: postgres:13\n environment:\n POSTGRES_USER: airflow\n POSTGRES_PASSWORD: airflow\n POSTGRES_DB: airflow\n \n airflow-webserver:\n image: ${AIRFLOW_IMAGE_NAME:-apache/airflow:latest}\n command: webserver\n ports:\n - \"8080:8080\"\n depends_on:\n - postgres\n```\n\n### 构建自定义镜像\n\n使用 Breeze 工具构建生产镜像：\n\n```bash\n# 使用 breeze 构建生产镜像\nbreeze prod-image build \\\n --installation-method sources \\\n --python 3.10 \\\n --debian-version bullseye\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/production_image_commands.py:1-50](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/production_image_commands.py)\n\n## 从源码安装\n\n### 克隆仓库\n\n```bash\ngit clone https://github.com/apache/airflow.git\ncd airflow\n```\n\n### 使用 Breeze 开发环境\n\nBreeze 是 Airflow 官方提供的开发环境管理工具，提供完整的开发、测试和构建体验：\n\n```bash\n# 进入 breeze shell\n./breeze shell\n\n# 运行测试\n./breeze testing python --test-type unit-tests --package-filter airflow-core\n```\n\nBreeze 使用 Docker 容器化方式，确保开发环境与生产环境的一致性。\n\n资料来源：[airflow-core/src/airflow/_vendor/README.md:1-20](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/_vendor/README.md)\n\n### 编译分发包\n\n构建 Airflow 分发包：\n\n```bash\n# 使用 Breeze 构建 sdist 或 wheel 包\nbreeze release-management build-rc \\\n --airflow-constraints-mode=\"constraints\" \\\n --distribution-format both\n```\n\n编译后的包位于 `dist/` 目录下。\n\n## 初始化数据库\n\n安装完成后，需要初始化 Airflow 的元数据库：\n\n```bash\n# 初始化数据库\nairflow db init\n\n# 创建管理员用户\nairflow users create \\\n --username admin \\\n --firstname Admin \\\n --lastname User \\\n --role Admin \\\n --email admin@example.com\n```\n\n## 启动 Airflow\n\n### Web 服务器\n\n```bash\nairflow webserver --port 8080\n```\n\n### 调度器\n\n在另一个终端启动调度器：\n\n```bash\nairflow scheduler\n```\n\n### 独立模式\n\n对于快速测试，可以使用独立模式：\n\n```bash\nairflow standalone\n```\n\n该命令会启动一个包含 Web 服务器和调度器的单进程环境。\n\n## 验证安装\n\n### 运行示例 DAG\n\nAirflow 自带多个示例 DAG，可用于验证安装：\n\n```python\nfrom airflow import DAG\nfrom airflow.operators.bash import BashOperator\nfrom datetime import datetime\n\nwith DAG('example_dag', start_date=datetime(2024, 1, 1)) as dag:\n t1 = BashOperator(\n task_id='print_date',\n bash_command='date'\n )\n```\n\n资料来源：[airflow-core/src/airflow/example_dags/tutorial.py:1-40](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/example_dags/tutorial.py)\n\n### 检查状态\n\n```bash\n# 查看 Airflow 版本\nairflow version\n\n# 查看已加载的连接\nairflow connections list\n\n# 查看已安装提供程序\nairflow providers list\n```\n\n## 快速安装流程图\n\n```mermaid\ngraph TD\n A[开始安装] --> B{选择安装方式}\n B -->|pip| C[安装 Python 依赖]\n B -->|Docker| D[安装 Docker]\n B -->|源码| E[克隆代码仓库]\n C --> F[初始化数据库]\n D --> G[拉取镜像]\n E --> H[安装依赖]\n F --> I[启动服务]\n G --> I\n H --> I\n I --> J[创建管理员账户]\n J --> K[访问 Web UI]\n K --> L[运行示例 DAG]\n```\n\n## 常见问题排查\n\n### 依赖冲突\n\n如果遇到依赖冲突问题，确保使用正确的约束文件：\n\n```bash\npip install apache-airflow== \\\n --constraint \"https://raw.githubusercontent.com/apache/airflow/constraints-/constraints-.txt\"\n```\n\n### 数据库连接问题\n\n检查数据库连接字符串配置：\n\n```ini\n[database]\nsql_alchemy_conn = postgresql+psycopg2://user:password@localhost/airflow\n```\n\n### 端口占用\n\n如果 8080 端口被占用，可更换端口：\n\n```bash\nairflow webserver --port 8888\n```\n\n## 后续步骤\n\n安装成功后，建议进行以下操作：\n\n1. **配置连接**：设置数据库、API 密钥等连接信息\n2. **配置 Executor**：根据需求选择 Executor 类型（Local、Celery、Kubernetes）\n3. **配置告警**：设置邮件或其他告警渠道\n4. **学习 DAG 编写**：参考官方教程编写第一个生产 DAG\n5. **了解最佳实践**：学习 Airflow 的安全和性能最佳实践\n\n## 相关文档链接\n\n- 官方安装文档：https://airflow.apache.org/docs/apache-airflow/stable/installation/index.html\n- Docker 镜像：https://github.com/apache/airflow/blob/main/Dockerfile\n- Breeze 开发工具：https://github.com/apache/airflow/blob/main/dev/breeze/README.md\n\n---\n\n\n\n## 系统架构详解\n\n### 相关页面\n\n相关主题：[核心组件详解](#components), [执行器类型与选择](#executors)\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/dag_processing/manager.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/dag_processing/manager.py)\n- [airflow-core/src/airflow/dag_processing/processor.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/dag_processing/processor.py)\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/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/_shared/observability/metrics/metrics_template.yaml](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/_shared/observability/metrics/metrics_template.yaml)\n \n\n# 系统架构详解\n\n## 1. 概述\n\nApache Airflow 是一个开源的工作流编排平台，采用分布式架构设计，支持大规模任务调度与执行。Airflow 3.0 在架构上进行了重大升级，引入了更加模块化的组件设计，将 DAG 处理、任务调度和执行进行了清晰的分离。\n\n核心架构由以下几个主要组件构成：\n\n- **Web服务器**：提供用户界面\n- **调度器（Scheduler）**：负责 DAG 调度和任务分发\n- **DAG处理器（DagFileProcessorManager）**：负责解析和验证 DAG 文件\n- **执行器（Executor）**：负责实际任务执行\n- **元数据库**：存储 DAG 定义、任务状态和执行历史\n\n资料来源：[airflow-core/docs/img/diagram_basic_airflow_architecture.py:1-50]()\n\n## 2. 核心组件架构\n\n### 2.1 DAG 处理系统\n\nDAG 处理系统是 Airflow 的核心子系统之一，负责从文件系统读取、解析和验证 DAG 定义。\n\n```mermaid\ngraph TD\n A[DAG 文件目录] --> B[DagFileProcessorManager]\n B --> C[文件扫描器]\n B --> D[文件处理器池]\n C -->|检测文件变更| D\n D --> E[Processor Subprocess]\n E --> F[DAG 对象]\n F --> G[Import Timeout Manager]\n G --> H[数据库更新]\n \n style B fill:#e1f5fe\n style D fill:#fff3e0\n style E fill:#e8f5e9\n```\n\n**关键组件**：\n\n| 组件 | 文件位置 | 职责 |\n|------|---------|------|\n| DagFileProcessorManager | `dag_processing/manager.py` | 管理 DAG 文件处理的生命周期 |\n| DagFileProcessor | `dag_processing/processor.py` | 执行单个 DAG 文件的解析 |\n| ImportTimeoutManager | `dag_processing/manager.py` | 监控 DAG 导入超时 |\n\n资料来源：[airflow-core/src/airflow/dag_processing/manager.py:1-100]()\n\n#### 2.1.1 DAG 文件扫描\n\nDagFileProcessorManager 维护一个文件扫描循环，定期检查配置的 DAG 目录中的文件变更：\n\n```python\n# 扫描间隔配置\nprocessor_poll_interval -> scheduler_idle_sleep_time\n```\n\n默认配置变更说明：\n\n| 旧配置项 | 新配置项 | 说明 |\n|---------|---------|------|\n| `scheduler.processor_poll_interval` | `scheduler.scheduler_idle_sleep_time` | 调度器空闲休眠时间 |\n| `scheduler.create_cron_data_intervals` | `scheduler.create_cron_data_intervals` | 默认值由 True 改为 False |\n| `scheduler.create_delta_data_intervals` | `scheduler.create_delta_data_intervals` | 默认值由 True 改为 False |\n\n资料来源：[airflow-core/src/airflow/cli/commands/config_command.py:30-80]()\n\n### 2.2 调度器系统\n\n调度器是 Airflow 的大脑，负责决定何时运行哪些任务。\n\n```mermaid\ngraph TD\n A[SchedulerJobRunner] --> B[关键区域锁]\n B --> C{获取锁}\n C -->|成功| D[处理过期 DAG]\n C -->|失败| E[等待]\n D --> F[调度待处理任务]\n F --> G[发送任务到执行器]\n G --> H[更新任务状态]\n H --> I[释放锁]\n I --> B\n \n style A fill:#fff8e1\n style B fill:#ffecb3\n style G fill:#c8e6c9\n```\n\n#### 2.2.1 调度器关键流程\n\n1. **获取关键区域锁**：确保多调度器环境下的安全性\n2. **处理过期 DAG**：清理陈旧的 DAG 数据\n3. **调度任务**：根据依赖关系和执行时间分发任务\n4. **孤儿任务处理**：检测并处理孤立任务\n\n**调度器指标**：\n\n| 指标名称 | 类型 | 说明 |\n|---------|------|------|\n| `scheduler.critical_section_busy` | counter | 关键区域锁竞争次数 |\n| `scheduler.orphaned_tasks.adopted` | counter | 被采纳的孤儿任务数 |\n| `scheduler.orphaned_tasks.cleared` | counter | 被清理的孤儿任务数 |\n| `scheduler.tasks.killed_externally` | counter | 外部杀死任务数 |\n\n资料来源：[airflow-core/src/airflow/_shared/observability/metrics/metrics_template.yaml:50-80]()\n\n### 2.3 任务执行系统\n\n任务执行通过 Task SDK 实现，采用远程进程通信模式。\n\n```mermaid\ngraph LR\n A[任务实例] --> B[任务状态存储]\n A --> C[任务参数]\n A --> D[执行上下文]\n \n B -.->|get| E[...]\n B -.->|set| F[...]\n B -.->|delete| G[...]\n \n style A fill:#e3f2fd\n style B fill:#bbdefb\n```\n\n#### 2.3.1 任务状态管理\n\n任务状态通过 TaskState 类进行管理，提供键值对存储：\n\n```python\nclass TaskState:\n def get(self, key: str) -> str | None\n def set(self, key: str, value: str) -> None\n def delete(self, key: str) -> None\n def clear(self, all_map_indices: bool = False) -> None\n```\n\n| 方法 | 功能 | 说明 |\n|-----|------|------|\n| `get(key)` | 获取值 | 返回存储的值，键不存在返回 None |\n| `set(key, value)` | 设置值 | 写入或覆盖指定键的值 |\n| `delete(key)` | 删除值 | 删除单个键，键不存在无操作 |\n| `clear()` | 清空 | 删除所有 map indices 的状态 |\n\n资料来源：[task-sdk/src/airflow/sdk/execution_time/context.py:80-120]()\n\n## 3. CLI 命令系统\n\nAirflow 提供丰富的命令行接口，用于管理和操作各个组件。\n\n### 3.1 命令分类\n\n| 命令组 | 功能 |\n|-------|------|\n| `airflow dags` | DAG 管理（backfill, list-runs, pause, unpause, test） |\n| `airflow tasks` | 任务操作（run, failed-deps, render, test） |\n| `airflow connections` | 连接管理 |\n| `airflow providers` | 提供者信息 |\n| `airflow config` | 配置查看 |\n| `airflow db-manager` | 数据库管理器 |\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:50-150]()\n\n### 3.2 任务命令详解\n\n| 命令 | 功能 | 关键参数 |\n|------|-----|---------|\n| `airflow tasks run` | 运行单个任务 | `--dag-id`, `--task-id`, `--logical-date-or-run-id` |\n| `airflow tasks render` | 渲染任务模板 | `--dag-id`, `--task-id`, `--logical-date-or-run-id` |\n| `airflow tasks test` | 测试任务（不记录状态） | `--dag-id`, `--task-id`, `--logical-date-or-run-id` |\n| `airflow tasks failed-deps` | 检查未满足依赖 | `--dag-id`, `--task-id`, `--logical-date-or-run-id` |\n\n**测试命令特点**：\n- 不检查依赖关系\n- 不记录状态到数据库\n- 适用于快速验证任务逻辑\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:150-200]()\n\n## 4. 配置系统\n\n### 4.1 关键配置变更（Airflow 2.x → 3.0）\n\n| 配置项 | 变更类型 | 旧值 | 新值 |\n|-------|---------|-----|------|\n| `scheduler.catchup_by_default` | 默认值变更 | True | **False** |\n| `scheduler.create_cron_data_intervals` | 默认值变更 | True | False |\n| `scheduler.create_delta_data_intervals` | 默认值变更 | True | False |\n| `scheduler.processor_poll_interval` | 重命名 | - | `scheduler_idle_sleep_time` |\n| `scheduler.deactivate_stale_dags_interval` | 重命名 | - | `parsing_cleanup_interval` |\n| `scheduler.statsd_on` | 重命名 | - | `metrics.statsd_on` |\n| `scheduler.max_threads` | 重命名 | - | `dag_processor.parsing_processes` |\n\n资料来源：[airflow-core/src/airflow/cli/commands/config_command.py:20-70]()\n\n### 4.2 DAG Processing 配置\n\n```yaml\ndag_processing:\n manager_stalls: Number of stalled DagFileProcessorManager\n processor_timeouts: DAG 处理超时次数\n dag_file_refresh_error: DAG 文件加载失败次数\n```\n\n## 5. 执行架构图\n\n```mermaid\ngraph TD\n subgraph Web层\n UI[Web UI] \n end\n \n subgraph 调度层\n Scheduler[Scheduler Job Runner]\n DagProcessor[DagFileProcessorManager]\n ImportTimeout[Import Timeout Manager]\n end\n \n subgraph 执行层\n Executor[Executor]\n Worker[Worker Process]\n TaskRunner[Task Runner]\n end\n \n subgraph 存储层\n DB[(Metadata DB)]\n DAGFS[DAG File System]\n end\n \n UI <-->|API| Scheduler\n Scheduler <-->|调度决策| Executor\n DagProcessor <-->|解析DAG| DAGFS\n DagProcessor <-->|写入| DB\n Executor <-->|分发任务| Worker\n Worker <-->|执行| TaskRunner\n TaskRunner <-->|状态更新| DB\n \n style Scheduler fill:#ff9800,color:#fff\n style DagProcessor fill:#4caf50,color:#fff\n style Executor fill:#2196f3,color:#fff\n```\n\n## 6. 监控指标\n\nAirflow 提供全面的监控指标体系：\n\n### 6.1 DAG 处理指标\n\n| 指标 | 描述 |\n|------|------|\n| `dag_processing.manager_stalls` | DagFileProcessorManager 停滞次数 |\n| `dag_file_refresh_error` | DAG 文件刷新错误数 |\n| `dag_file_processor_timeouts` | DAG 文件处理器超时（已废弃） |\n\n### 6.2 调度器指标\n\n| 指标 | 描述 |\n|------|------|\n| `scheduler.critical_section_busy` | 调度器关键区域忙次数 |\n| `scheduler.orphaned_tasks.adopted` | 被采纳的孤儿任务 |\n| `scheduler.orphaned_tasks.cleared` | 被清理的孤儿任务 |\n| `scheduler.tasks.killed_externally` | 外部杀死任务数 |\n\n### 6.3 任务执行指标\n\n| 指标 | 描述 |\n|------|------|\n| `ti.start` | 任务启动次数 |\n| `ti.finish` | 任务完成次数 |\n\n资料来源：[airflow-core/src/airflow/_shared/observability/metrics/metrics_template.yaml:30-100]()\n\n## 7. 总结\n\nApache Airflow 采用分布式架构设计，核心组件包括：\n\n1. **DagFileProcessorManager**：负责 DAG 文件的解析和验证\n2. **SchedulerJobRunner**：负责任务的调度和分发\n3. **Executor**：负责实际任务执行\n4. **Task SDK**：提供任务运行时的上下文管理\n\n各组件通过消息队列和数据库进行通信，确保系统的高可用性和可扩展性。\n\n---\n\n\n\n## 核心组件详解\n\n### 相关页面\n\n相关主题：[系统架构详解](#architecture), [数据流转与交换机制](#data-flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [airflow-core/src/airflow/models/dag.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/dag.py)\n- [airflow-core/src/airflow/models/dagrun.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/dagrun.py)\n- [airflow-core/src/airflow/models/connection.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/connection.py)\n- [airflow-core/src/airflow/models/variable.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/variable.py)\n- [airflow-core/src/airflow/models/pool.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/pool.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/cli/commands/config_command.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/commands/config_command.py)\n\n \n\n# 核心组件详解\n\n## 概述\n\nApache Airflow 是一个开源的工作流编排平台，其核心组件构成了整个任务调度和执行的基础架构。这些组件包括DAG（有向无环图）、DAGRun（DAG运行实例）、Connection（连接）、Variable（变量）和Pool（资源池）。理解这些核心组件对于深入掌握Airflow的工作原理至关重要。\n\n## DAG 模型\n\n### 什么是 DAG\n\nDAG（Directed Acyclic Graph，有向无环图）是Airflow中工作流定义的核心抽象。它代表了一组需要执行的任务以及任务之间的依赖关系。\n\n### DAG 关键属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| dag_id | str | DAG的唯一标识符 |\n| description | str | DAG的描述信息 |\n| schedule_interval | - | 调度间隔配置 |\n| start_date | datetime | DAG开始执行的日期 |\n| end_date | datetime | DAG结束执行的日期（可选） |\n| catchup | bool | 是否补跑历史数据 |\n| max_active_runs | int | 最大并发运行数 |\n| concurrency | int | 最大并发任务数 |\n| is_paused | bool | DAG是否暂停 |\n\n### DAG 的生命周期\n\n```mermaid\ngraph LR\n A[创建DAG] --> B[DAG解析]\n B --> C[调度器调度]\n C --> D[创建DAGRun]\n D --> E[执行任务]\n E --> F[DAGRun完成]\n F --> G{是否继续调度}\n G -->|是| C\n G -->|否| H[DAG结束]\n```\n\n## DAGRun 模型\n\n### 概述\n\nDAGRun是DAG的一次具体执行实例。每次触发或调度DAG时，都会创建一个DAGRun实例来跟踪该次执行的状态。\n\n### DAGRun 状态\n\n| 状态 | 说明 |\n|------|------|\n| QUEUED | 排队等待执行 |\n| RUNNING | 正在执行 |\n| SUCCESS | 成功完成 |\n| FAILED | 执行失败 |\n\n### DAGRun 类型\n\n| 类型 | 说明 |\n|------|------|\n| SCHEDULED | 由调度器正常调度触发 |\n| MANUAL | 手动触发的运行 |\n| BACKFILL | 回填作业执行 |\n\n### 核心属性\n\nDAGRun包含以下关键属性用于追踪执行信息：\n\n- **run_id**: 每次运行的唯一标识\n- **state**: 当前运行状态\n- **execution_date**: 执行日期\n- **start_date**: 实际开始时间\n- **end_date**: 结束时间\n- **triggering_user_name**: 触发运行的用户名\n\n## Connection 连接管理\n\n### 连接类型\n\nAirflow支持多种连接类型，用于与外部系统进行交互：\n\n| 连接类型 | 说明 | 默认配置 |\n|----------|------|----------|\n| postgres | PostgreSQL数据库 | 需要host、schema、login、password |\n| mysql | MySQL数据库 | 需要host、schema、login、password |\n| google_cloud_platform | GCP服务 | 使用默认schema |\n| http | HTTP端点 | 需要host地址 |\n| ftp | FTP服务器 | 需要host、login、password |\n| ssh | SSH连接 | 需要host、login、key_file |\n| redis | Redis缓存 | 需要host、port |\n| fs | 文件系统 | 需要path配置 |\n| hive_cli | Hive CLI | 需要host、port、schema |\n| hiveserver2 | HiveServer2 | 需要host、schema、port |\n| gremlin | Gremlin图数据库 | 需要host、port |\n| facebook_social | Facebook社交 | 需要app_id、app_secret等 |\n| iceberg | Iceberg表格式 | 需要host配置 |\n\n### 连接创建示例\n\n```python\nConnection(\n conn_id=\"gcp_default\",\n conn_type=\"google_cloud_platform\",\n schema=\"default\"\n)\n```\n\n## Variable 变量管理\n\n### 变量概述\n\nVariable用于存储和检索Airflow中的键值对配置信息，可在DAG和任务之间共享。\n\n### 变量操作\n\n| 操作 | 说明 | 命令 |\n|------|------|------|\n| list | 列出所有变量 | `airflow variables list` |\n| get | 获取变量值 | `airflow variables get ` |\n| set | 设置变量 | `airflow variables set ` |\n| delete | 删除变量 | `airflow variables delete ` |\n| import | 批量导入 | `airflow variables import ` |\n| export | 批量导出 | `airflow variables export ` |\n\n### JSON序列化支持\n\nVariable支持JSON序列化，可存储复杂数据结构：\n\n```bash\nairflow variables set my_json '{\"key\": \"value\", \"list\": [1, 2, 3]}'\n```\n\n## Pool 资源池管理\n\n### 池的作用\n\nPool用于限制同时执行的任务数量，控制资源使用并管理并发度。\n\n### 内置默认池\n\n| 池名称 | 默认槽位数 | 说明 |\n|--------|------------|------|\n| default_pool | 根据配置 | 用于未指定池的任务 |\n\n### 槽位管理\n\n```mermaid\ngraph TB\n A[任务请求] --> B{槽位可用?}\n B -->|是| C[分配槽位]\n B -->|否| D[排队等待]\n C --> E[执行任务]\n E --> F[释放槽位]\n D --> G{槽位释放?}\n G -->|是| C\n G -->|否| D\n```\n\n## CLI 命令行接口\n\n### 可用命令组\n\nAirflow提供了丰富的CLI命令用于管理核心组件：\n\n| 命令组 | 说明 | 主要子命令 |\n|--------|------|------------|\n| dag | DAG管理 | list, details, list-runs, pause, unpause, backfill, test |\n| dagrun | 运行管理 | list, trigger, clear |\n| connections | 连接管理 | list, add, delete, edit |\n| variables | 变量管理 | list, get, set, delete, import, export |\n| pools | 池管理 | list, set |\n| config | 配置查看 | list, get, show |\n| providers | 提供者信息 | list, details |\n| assets | 资产管理 | list, details, materialize |\n\n### 常用命令示例\n\n```bash\n# 列出所有DAG\nairflow dags list\n\n# 触发DAG运行\nairflow dags trigger \n\n# 暂停DAG\nairflow dags pause \n\n# 列出所有连接\nairflow connections list\n\n# 导出变量\nairflow variables export variables.json\n```\n\n## 配置变更说明\n\n### Airflow 3.0 配置变化\n\n从Airflow 2.x迁移到3.0时，以下配置项发生了变化：\n\n| 旧配置项 | 新配置项 | 变化类型 |\n|----------|----------|----------|\n| scheduler.catchup_by_default | scheduler.catchup | 默认值改为False |\n| scheduler.create_cron_data_intervals | - | 默认值改为False |\n| scheduler.create_delta_data_intervals | - | 默认值改为False |\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\n### catchup 行为变化\n\n> 在 Airflow 3.0 中，`catchup` 的默认值为 `False`。这意味着未明确设置 `catchup` 参数的 DAG 默认不会进行历史数据补跑。如果DAG依赖补跑行为，需要在 `airflow.cfg` 的 `scheduler` 部分将该配置设置为 `True`。资料来源：[airflow-core/src/airflow/cli/commands/config_command.py]()\n\n## 数据模型关系\n\n```mermaid\nerDiagram\n DAG ||--o{ DAGRun : creates\n DAGRun ||--o{ TaskInstance : contains\n TaskInstance ||--|| Pool : uses\n Connection ||--o{ TaskInstance : referenced_by\n Variable ||--o{ TaskInstance : accessed_by\n \n DAG {\n string dag_id\n string description\n string schedule_interval\n datetime start_date\n boolean is_paused\n }\n \n DAGRun {\n string run_id\n string state\n datetime execution_date\n datetime start_date\n datetime end_date\n }\n \n TaskInstance {\n string task_id\n string state\n datetime start_date\n datetime end_date\n }\n \n Pool {\n string pool\n int slots\n string description\n }\n \n Connection {\n string conn_id\n string conn_type\n string host\n string schema\n }\n \n Variable {\n string key\n string val\n string description\n }\n```\n\n## 安全最佳实践\n\n### 连接凭证管理\n\n1. **使用Fernet加密**: Airflow使用Fernet加密存储敏感连接凭证\n2. **轮换加密密钥**: 定期执行 `airflow rotate-fernet-key` 更新加密密钥\n\n```bash\nairflow rotate-fernet-key\n```\n\n### 敏感信息处理\n\n| 类型 | 存储方式 | 建议 |\n|------|----------|------|\n| 密码 | 加密存储 | 使用变量或连接extra字段 |\n| API密钥 | 加密存储 | 使用Secret Backend |\n| 连接凭证 | 加密存储 | 使用连接管理界面 |\n\n## 总结\n\nApache Airflow的核心组件构成了一个完整的工作流编排系统。DAG作为工作流定义的核心，依赖调度器生成DAGRun实例，而DAGRun则管理具体任务的执行。Connection、Variable和Pool等组件提供了与外部系统交互、配置管理和资源控制的能力。深入理解这些组件及其相互关系，对于熟练使用Airflow进行工作流开发和运维至关重要。\n\n---\n\n\n\n## 执行器类型与选择\n\n### 相关页面\n\n相关主题：[系统架构详解](#architecture), [容器化与Kubernetes部署](#deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\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- [airflow-core/src/airflow/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.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/commands/common_options.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/common_options.py)\n- [dev/breeze/src/airflow_breeze/commands/developer_commands.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/developer_commands.py)\n- [airflow-core/src/airflow/utils/db.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/utils/db.py)\n \n\n# 执行器类型与选择\n\n## 概述\n\n执行器（Executor）是 Apache Airflow 架构中的核心组件，负责实际执行任务实例。每个执行器实现了特定的任务调度和执行策略，从单机的本地执行到分布式的集群环境，Airflow 提供了多种执行器类型以满足不同场景的需求。执行器的选择直接影响工作流的性能、可扩展性和可靠性。\n\n执行器系统遵循统一的接口规范，所有执行器都继承自基础执行器类，定义了任务提交、状态查询、心跳维护等标准方法。资料来源：[airflow-core/src/airflow/executors/executor_loader.py:1-50]()\n\n## 执行器架构\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n DAG[DAG 有向无环图] --> Scheduler[调度器]\n Scheduler --> ExecutorLoader[执行器加载器]\n ExecutorLoader --> Executor[执行器实例]\n Executor --> TaskInstance[任务实例]\n Executor --> Worker[Worker 节点]\n \n Executor --> LocalExecutor[LocalExecutor]\n Executor --> CeleryExecutor[CeleryExecutor]\n Executor --> KubernetesExecutor[KubernetesExecutor]\n Executor --> SequentialExecutor[SequentialExecutor]\n \n LocalExecutor --> LocalWorker[本地进程]\n CeleryExecutor --> CeleryWorker[Celery Worker]\n KubernetesExecutor --> K8sPod[K8s Pod]\n```\n\n### 执行器类型总览\n\n| 执行器类型 | 说明 | 适用场景 | 并发能力 |\n|-----------|------|----------|---------|\n| SequentialExecutor | 顺序执行器 | 开发调试、单节点 | 1 |\n| LocalExecutor | 本地执行器 | 单机生产、小规模任务 | 多进程 |\n| CeleryExecutor | Celery 执行器 | 分布式、跨机器 | 集群规模 |\n| KubernetesExecutor | K8s 执行器 | 云原生、自动扩缩容 | Pod 数量 |\n| LocalKubernetesExecutor | 本地 K8s 执行器 | 测试环境 | 可配置 |\n| CeleryKubernetesExecutor | 混合执行器 | 灵活调度 | 集群规模 |\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:50-80]()\n\n## 执行器加载机制\n\n### 执行器加载器职责\n\n`ExecutorLoader` 是 Airflow 中负责动态加载和解析执行器配置的中央组件。它支持多种执行器配置格式，包括简单的单执行器名称和复杂的团队别名配置。\n\n执行器加载器的主要职责包括：\n\n1. 解析 `airflow.cfg` 中的执行器配置\n2. 验证执行器名称的有效性\n3. 实例化对应的执行器类\n4. 处理执行器别名和团队配置\n\n```python\n# 执行器名称解析核心逻辑\nif module_or_name in CORE_EXECUTOR_NAMES:\n executor_names_per_team.append(\n ExecutorName(\n alias=alias, \n module_path=cls.executors[module_or_name], \n team_name=team_name\n )\n )\n```\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:80-120]()\n\n### 执行器配置格式\n\n执行器配置支持以下几种格式：\n\n```mermaid\ngraph LR\n A[配置文件] --> B[执行器名称]\n B --> C[单执行器]\n B --> D[别名配置]\n B --> E[团队配置]\n \n C --> C1[LocalExecutor]\n C --> C2[CeleryExecutor]\n \n D --> D1[MyAlias:LocalExecutor]\n D1 --> D2[alias=MyAlias
module=LocalExecutor]\n \n E --> E1[team:executor]\n E1 --> E2[team_name=team
executor=executor]\n```\n\n#### 简单配置\n\n```ini\nexecutor = LocalExecutor\n```\n\n#### 别名配置\n\n```ini\nexecutor = MyLocalExecutor:LocalExecutor\n```\n\n格式为 `别名:执行器类型`，其中别名用于日志和监控标识。\n\n#### 团队配置\n\n```ini\n[executors]\nTeamA = TeamA: CeleryExecutor\nTeamB = TeamB: KubernetesExecutor\n```\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:100-150]()\n\n## 核心执行器类型详解\n\n### SequentialExecutor\n\n顺序执行器是最基础的执行器，以单线程顺序方式执行任务。此执行器主要用于以下场景：\n\n- **开发环境**：在没有多进程支持的环境中运行\n- **调试场景**：需要逐个追踪任务执行流程\n- **最小化部署**：资源受限的单机环境\n\n```python\n# SequentialExecutor 核心特性\n- 单进程顺序执行\n- 无并发能力\n- 任务队列单一\n- 无需外部依赖\n```\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:150-180]()\n\n### LocalExecutor\n\n本地执行器在单机环境下提供多进程并发执行能力。它使用 Python 的 `multiprocessing` 模块创建工作进程池，每个工作进程可以并行执行多个任务。\n\n```mermaid\ngraph TD\n LocalExecutor --> Worker1[Worker Process 1]\n LocalExecutor --> Worker2[Worker Process 2]\n LocalExecutor --> WorkerN[Worker Process N]\n \n Worker1 --> Task1[Task Instance]\n Worker1 --> Task2[Task Instance]\n Worker2 --> Task3[Task Instance]\n WorkerN --> Task4[Task Instance]\n \n Worker1 -.-> Queue[任务队列]\n Worker2 -.-> Queue\n WorkerN -.-> Queue\n```\n\n**配置参数**：\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| parallelism | 并行任务数上限 | CPU 核心数 |\n| local_worker_kwargs | 工作进程额外参数 | {} |\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:180-220]()\n\n### CeleryExecutor\n\nCeleryExecutor 是分布式执行器，使用 Celery 作为消息队列来处理跨多台机器的任务分发和执行。Celery 是 Python 生态中成熟的任务队列系统，支持 Redis、RabbitMQ 等多种消息代理。\n\n```mermaid\ngraph TD\n Scheduler[Airflow Scheduler] -->|任务提交| CeleryBroker[Celery Broker
Redis/RabbitMQ]\n CeleryBroker --> Worker1[Celery Worker 1]\n CeleryBroker --> Worker2[Celery Worker 2]\n CeleryBroker --> WorkerN[Celery Worker N]\n \n Worker1 -->|执行结果| ResultBackend[Result Backend]\n Worker2 -->|执行结果| ResultBackend\n WorkerN -->|执行结果| ResultBackend\n \n ResultBackend -->|状态同步| Scheduler\n```\n\n**适用场景**：\n\n- 需要水平扩展的任务处理\n- 跨多台机器的分布式部署\n- 需要任务优先级和重试策略\n- 长时间运行的后台任务\n\n**依赖组件**：\n\n- Celery 消息代理（Redis 或 RabbitMQ）\n- Celery Worker 节点\n- 结果后端（数据库或缓存）\n\n资料来源：[providers/celery/src/airflow/providers/celery/executors/celery_executor.py:1-100]()\n\n### KubernetesExecutor\n\nKubernetesExecutor 是原生运行在 Kubernetes 集群上的执行器，每个任务都在独立的 Pod 中执行。这种设计提供了极佳的隔离性和资源弹性。\n\n```mermaid\ngraph TD\n Scheduler[Scheduler] --> K8sAPI[Kubernetes API]\n K8sAPI --> Pod1[Task Pod 1]\n K8sAPI --> Pod2[Task Pod 2]\n K8sAPI --> PodN[Task Pod N]\n \n Pod1 -->|完成| K8sAPI\n Pod2 -->|完成| K8sAPI\n PodN -->|完成| K8sAPI\n \n K8sAPI --> ConfigMap[ConfigMap
任务定义]\n K8sAPI --> Secret[Secret
连接凭证]\n```\n\n**核心优势**：\n\n| 特性 | 说明 |\n|------|------|\n| 任务隔离 | 每个任务独立 Pod，避免资源冲突 |\n| 自动扩缩容 | 根据任务队列动态创建/销毁 Pod |\n| 资源控制 | 支持 CPU、内存 Limits 和 Requests 配置 |\n| 亲和性 | 支持节点亲和性、污点容忍等调度策略 |\n| 生命周期 | 任务完成即销毁，资源高效利用 |\n\n**配置选项**：\n\n| 参数 | 说明 |\n|------|------|\n| namespace | Kubernetes 命名空间 |\n| parallelism | 最大并发 Pod 数 |\n| worker_pods_creation_batch_size | 批量创建大小 |\n| kube_client_request_args | K8s 客户端参数 |\n\n资料来源：[providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/executors/kubernetes_executor.py:1-150]()\n\n## 执行器配置管理\n\n### 配置文件位置\n\n执行器配置通过 `airflow.cfg` 文件管理，主要配置项位于 `[core]` 部分：\n\n```ini\n[core]\nexecutor = LocalExecutor\n```\n\n### Breeze 开发环境配置\n\n在 Airflow Breeze 开发环境中，可以使用统一的命令行选项配置执行器：\n\n```bash\n# 查看执行器列表\nbreeze shell --executor\n\n# 使用指定执行器启动\nbreeze shell --executor KubernetesExecutor\n```\n\n**支持的执行器选项**：\n\n| 选项 | 说明 | 可用值 |\n|------|------|--------|\n| --executor | 执行器类型 | LocalExecutor, CeleryExecutor, KubernetesExecutor 等 |\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/common_options.py:100-150]()\n\n### 执行器别名与团队配置\n\nAirflow 支持通过 `ExecutorLoader` 实现执行器别名和团队级别的配置：\n\n```python\nclass ExecutorName(NamedTuple):\n alias: str | None\n module_path: str\n team_name: str | None\n```\n\n配置示例：\n\n```ini\n[executors]\n# 格式: 别名 = 模块路径\nmy_alias = airflow.executors.local_executor.LocalExecutor\nteam_default = airflow.providers.celery.executors.celery_executor.CeleryExecutor\n```\n\n**配置验证逻辑**：\n\n```python\n# 检查是否为内置执行器名称\nif module_or_name in CORE_EXECUTOR_NAMES:\n executor_names_per_team.append(\n ExecutorName(\n alias=alias, \n module_path=cls.executors[module_or_name], \n team_name=team_name\n )\n )\n# 检查是否为模块路径\nelif \".\" not in module_or_name:\n raise AirflowConfigException(\n \"Incorrectly formatted executor configuration...\"\n )\n```\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:200-260]()\n\n## 执行器选择指南\n\n### 决策流程\n\n```mermaid\ngraph TD\n Start[开始选择执行器] --> Q1{部署规模?}\n \n Q1 -->|单机/开发| Q2{需要并发?}\n Q1 -->|分布式| Q3{K8s 环境?}\n Q1 -->|大规模| Q4{需要灵活调度?}\n \n Q2 -->|是| LocalExecutor\n Q2 -->|否| SequentialExecutor\n \n Q3 -->|是| KubernetesExecutor\n Q3 -->|否| CeleryExecutor\n \n Q4 -->|是| CeleryKubernetesExecutor\n Q4 -->|否| CeleryExecutor\n```\n\n### 场景推荐\n\n| 场景 | 推荐执行器 | 原因 |\n|------|-----------|------|\n| 本地开发调试 | SequentialExecutor | 简单、无依赖 |\n| 单机生产环境 | LocalExecutor | 多进程并发、资源可控 |\n| 小型集群 | CeleryExecutor | 配置简单、成熟稳定 |\n| 云原生/K8s | KubernetesExecutor | 弹性扩缩容、任务隔离 |\n| 混合云环境 | CeleryKubernetesExecutor | 灵活调度、兼容性好 |\n\n### 配置示例\n\n#### 本地执行器配置\n\n```ini\n[core]\nexecutor = LocalExecutor\n\n[local_executor]\nparallelism = 8\n```\n\n#### Celery 执行器配置\n\n```ini\n[core]\nexecutor = CeleryExecutor\n\n[celery]\nbroker_url = redis://redis:6379/0\nresult_backend = redis://redis:6379/1\nworker_concurrency = 16\n```\n\n#### Kubernetes 执行器配置\n\n```ini\n[core]\nexecutor = KubernetesExecutor\n\n[kubernetes]\nnamespace = airflow\nparallelism = 32\n```\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:260-320]()\n\n## 命令行接口\n\n### 查看执行器信息\n\n通过 Airflow CLI 可以查看已配置的执行器信息：\n\n```bash\n# 查看 Airflow 信息（包含执行器）\nairflow info\n\n# 查看提供商执行器列表\nairflow providers executors\n```\n\n**可用的 providers 子命令**：\n\n| 命令 | 说明 |\n|------|------|\n| `providers list` | 列出所有提供商 |\n| `providers executors` | 列出可用的执行器 |\n| `providers details` | 提供商详细信息 |\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:1-100]()\n\n### CLI 配置定义\n\n执行器相关的 CLI 命令在 `cli_config.py` 中定义：\n\n```python\n# 提供商执行器列表命令\nActionCommand(\n name=\"executors\",\n help=\"Get information about executors provided\",\n func=lazy_load_command(\"airflow.cli.commands.provider_command.executors_list\"),\n args=(ARG_OUTPUT, ARG_VERBOSE),\n)\n```\n\n**命令行参数**：\n\n| 参数 | 短标识 | 说明 |\n|------|--------|------|\n| --output | -o | 输出格式（table、json、yaml） |\n| --verbose | -v | 详细输出模式 |\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:100-200]()\n\n## 默认连接配置\n\n执行器运行需要配置相应的连接凭证。Airflow 在初始化数据库时提供默认连接配置：\n\n### 开发环境默认连接\n\n```python\nConnection(\n conn_id=\"fs_default\",\n conn_type=\"fs\",\n extra='{\"path\": \"/\"}',\n)\n\nConnection(\n conn_id=\"google_cloud_default\",\n conn_type=\"google_cloud_platform\",\n schema=\"default\",\n)\n\nConnection(\n conn_id=\"http_default\",\n conn_type=\"http\",\n host=\"https://www.httpbin.org/\",\n)\n```\n\n### 生产环境注意事项\n\n在生产环境中部署时，需要：\n\n1. 配置真实的数据库连接（避免 SQLite）\n2. 根据执行器类型配置相应的消息代理连接\n3. 设置正确的认证凭证和 SSL 选项\n\n资料来源：[airflow-core/src/airflow/utils/db.py:1-100]()\n\n## 最佳实践\n\n### 执行器选择原则\n\n1. **从简单开始**：开发环境使用 LocalExecutor，生产环境根据需求升级\n2. **资源评估**：估算并发任务数、任务运行时长、资源消耗\n3. **运维能力**：评估团队对消息队列或容器编排的熟悉程度\n4. **成本考虑**：云环境优先考虑 KubernetesExecutor 以获得弹性\n5. **扩展性预留**：选择具有一定扩展空间的执行器类型\n\n### 性能优化建议\n\n| 优化项 | LocalExecutor | CeleryExecutor | KubernetesExecutor |\n|--------|--------------|----------------|-------------------|\n| 并发数 | `parallelism` 参数 | `worker_concurrency` | `parallelism` 参数 |\n| 心跳间隔 | 降低网络延迟 | 合理设置超时 | 配置 liveness 探针 |\n| 资源限制 | 进程级限制 | Worker 级限制 | Pod 级限制 |\n| 监控 | 进程监控 | Celery Events | K8s Events |\n\n### 常见问题排查\n\n```mermaid\ngraph TD\n Issue[问题排查] --> Check1{执行器启动失败?}\n Issue --> Check2{任务堆积?}\n Issue --> Check3{连接超时?}\n \n Check1 --> Solution1[检查配置
验证依赖]\n Check2 --> Solution2[增加并发数
优化任务拆分]\n Check3 --> Solution3[检查网络
验证凭证]\n```\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:320-400]()\n\n## 总结\n\nApache Airflow 的执行器系统提供了灵活的任务执行框架，从单机的顺序执行到分布式的 Kubernetes 集群执行，能够满足不同规模和场景的需求。执行器的选择应综合考虑部署环境、团队能力、运维成本和扩展性要求。\n\n对于新项目，建议先使用 LocalExecutor 进行开发和测试，待系统稳定后再根据实际负载和扩展需求迁移到 CeleryExecutor 或 KubernetesExecutor。在选择执行器时，务必参考官方文档中的具体版本要求，确保所有依赖组件正确配置。\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:400-450]()\n\n---\n\n\n\n## 数据流转与交换机制\n\n### 相关页面\n\n相关主题：[核心组件详解](#components), [FastAPI核心API](#fastapi)\n\n\n相关源码文件
\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/asset.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/asset.py)\n- [airflow-core/src/airflow/callbacks/callback_requests.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/callbacks/callback_requests.py)\n- [airflow-core/docs/core-concepts/xcoms.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/core-concepts/xcoms.rst)\n- [airflow-core/docs/authoring-and-scheduling/assets.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/authoring-and-scheduling/assets.rst)\n \n\n# 数据流转与交换机制\n\n## 概述\n\nApache Airflow 中的数据流转与交换机制是工作流编排的核心能力，允许任务之间传递数据、状态和事件。该机制主要由三大支柱组成：**XCom（跨任务通信）**、**Asset（资产）** 和 **Callback（回调）**。这些机制共同构成了 Airflow 工作流中数据流动的完整生态，使得分布式任务执行环境下的数据交换变得可靠且可追踪。\n\nXCom 机制允许任务在执行完成后向元数据库写入值，后续任务可以检索这些值进行后续处理。Asset 机制提供了一种基于数据源状态变化触发 DAG 执行的优雅方式。Callback 机制则支持任务生命周期中的关键节点执行自定义逻辑，如任务失败时发送告警。\n\n## XCom 机制详解\n\n### XCom 核心概念\n\nXCom（Cross-Communication）是 Airflow 中实现任务间数据交换的主要机制。它通过 `airflow.models.xcom.BaseXCom` 类实现，数据默认存储在 Airflow 元数据库中，支持任务执行器在分布式环境下共享数据。\n\n```mermaid\ngraph TD\n A[任务 A 执行] -->|push| B[XCom 写入]\n B --> C[(元数据库)]\n C -->|pull| D[任务 B 读取]\n D --> E[任务 B 继续执行]\n \n F[参数传递] -.->|包含| B\n G[返回值自动推送] -.->|包含| B\n```\n\nXCom 支持推送和拉取两种操作模式。任务可以通过 `xcom_push()` 方法显式推送数据，也可以通过返回 Python 对象让 Airflow 自动推送。拉取操作使用 `xcom_pull()` 方法，可以按任务 ID 或 DAG run ID 筛选特定数据。\n\n### XCom 数据模型\n\nXCom 的数据模型定义在 `BaseXCom` 类中，包含以下核心字段：\n\n| 字段名 | 类型 | 说明 |\n|--------|------|------|\n| key | String | XCom 值的键名，用于标识数据 |\n| value | JSON | 序列化的数据值，支持基础类型和嵌套结构 |\n| timestamp | DateTime | XCom 创建时间戳 |\n| task_id | String | 推送该 XCom 的任务 ID |\n| dag_id | String | 所属 DAG 的唯一标识符 |\n| run_id | String | DAG Run 的执行 ID |\n| map_index | Integer | Map 任务中的索引值（-1 表示非 Map 任务）|\n\n资料来源：[airflow-core/src/airflow/models/xcom.py:1-100]()\n\n### XCom API 与操作方法\n\n#### 推送数据\n\n```python\n# 方式一：显式推送\ntask_instance.xcom_push(key=\"result\", value={\"status\": \"success\", \"data\": [1, 2, 3]})\n\n# 方式二：通过 return 语句自动推送\ndef extract_data(**context):\n return {\"records\": 100, \"source\": \"api\"}\n```\n\n#### 拉取数据\n\n```python\n# 按任务 ID 拉取最新值\nresult = task_instance.xcom_pull(task_ids=[\"transform_data\"])[0]\n\n# 按 task_ids 和 key 精确拉取\nvalue = task_instance.xcom_pull(task_ids=[\"extract\"], key=\"record_count\")\n```\n\n#### 使用 XComArg 简化操作\n\n`XComArg` 提供了一种声明式的数据获取方式，特别适合与 Jinja 模板结合使用：\n\n```python\nfrom airflow.models.baseoperator import xcom_arg\n\nextract_task >> transform_task\n```\n\n### XCom 的序列化与反序列化\n\nXCom 值在存储前会被序列化为 JSON 格式，检索时自动反序列化。支持的类型包括：\n\n| Python 类型 | 序列化格式 | 限制说明 |\n|-------------|-----------|----------|\n| str | JSON String | 无限制 |\n| int, float | JSON Number | 无限制 |\n| bool | JSON Boolean | 无限制 |\n| list, tuple | JSON Array | 元素类型需可序列化 |\n| dict | JSON Object | 键值需可序列化 |\n| datetime | ISO 8601 字符串 | 需正确处理时区 |\n| bytes | Base64 编码 | 大小受 max_xcom_size 限制 |\n\n资料来源：[airflow-core/src/airflow/models/xcom.py:150-200]()\n\n### XCom 配置与性能优化\n\nXCom 的行为可通过以下配置参数调整：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `max_xcom_size` | 48KB | 单个 XCom 值的最大大小 |\n| `xcom_backend` | BaseXCom | 自定义 XCom 后端类 |\n| `enable_xcom_pickling` | True | 是否允许 pickle 序列化（非 JSON） |\n\n在高并发场景下，建议：\n1. 避免传输大型数据集，将大数据存储在外部存储（如 S3、HDFS），XCom 只传递引用\n2. 使用自定义 XCom 后端将数据存储到 GCS、Redis 等外部系统\n3. 及时清理过期 XCom 数据以减少元数据库负担\n\n## Asset 资产机制\n\n### Asset 概述\n\nAsset 是 Airflow 2.10+ 引入的新一代数据依赖管理机制，它代表 DAG 外部的数据源或数据目的地。通过 Asset，Airflow 可以感知数据源的变化并自动触发 DAG 执行，实现数据驱动的工作流编排。\n\n```mermaid\ngraph LR\n A[数据源变化] -->|触发| B[Asset 事件]\n B --> C{DAG 调度}\n C -->|是| D[创建 DAG Run]\n C -->|否| E[等待下次检查]\n \n F[Asset 定义] -->|关联| G[DAG Schedule]\n```\n\n### Asset 数据模型\n\nAsset 模型定义在 `airflow.models.asset` 模块中：\n\n```python\nclass Asset:\n name: str\n uri: str\n group: str | None\n extra: dict | None\n created_at: datetime\n updated_at: datetime\n```\n\n资料来源：[airflow-core/src/airflow/models/asset.py:1-50]()\n\n### Asset 与 DAG Schedule 绑定\n\nDAG 可以通过 `schedule` 参数与一个或多个 Asset 关联：\n\n```python\nfrom airflow.models.asset import Asset\n\n# 单个 Asset\ndaily_sales = Asset(uri=\"s3://data-bucket/daily-sales/\", name=\"daily_sales\")\n\nwith DAG(\n dag_id=\"process_sales\",\n schedule=[daily_sales], # 当 Asset 有新事件时触发\n ...\n):\n process_sales_task()\n```\n\n### Asset Event 事件机制\n\n每当外部数据源发生变化时，可以向 Airflow 报告 Asset Event：\n\n```python\nfrom airflow.sdk import AssetEvent\n\nAssetEvent(\n asset=daily_sales,\n extra={\"partition\": \"2024-01-15\"},\n source_task_instance_id=\"report_ingestion\",\n)\n```\n\n### Asset 命令行操作\n\nAirflow CLI 提供了完整的 Asset 管理命令：\n\n| 命令 | 功能 |\n|------|------|\n| `airflow assets list` | 列出所有注册的 Asset |\n| `airflow assets details` | 查看 Asset 详情 |\n| `airflow assets materialize` | 手动触发 Asset 物化 |\n| `airflow assets events` | 查看 Asset 事件历史 |\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:1-100]()\n\n## Callback 回调机制\n\n### Callback 机制概述\n\nCallback 允许在 DAG 和任务生命周期中的关键节点执行自定义逻辑。这些节点包括任务失败、成功、重试以及 DAG 运行时错误等场景。Callback 通过 `airflow.callbacks.callback_requests` 模块中定义的数据结构传递给执行器。\n\n```mermaid\ngraph TD\n A[任务状态变更] -->|生成| B[CallbackRequest]\n B --> C[(Callback 队列)]\n C -->|处理| D[Callback Executor]\n D --> E[执行用户逻辑]\n \n F[on_failure_callback] -.-> E\n G[on_success_callback] -.-> E\n H[on_retry_callback] -.-> E\n```\n\n### Callback Request 数据结构\n\nCallback 请求通过以下类定义：\n\n| 类名 | 用途 | 触发时机 |\n|------|------|----------|\n| `TaskCallbackRequest` | 任务级回调 | 任务成功/失败/重试 |\n| `DagCallbackRequest` | DAG 级回调 | DAG 运行失败/成功 |\n| `SlaCallbackRequest` | SLA 超时回调 | 任务超出 SLA 阈值 |\n| `DagRunCallbackRequest` | DAG Run 回调 | DAG Run 状态变更 |\n\n资料来源：[airflow-core/src/airflow/callbacks/callback_requests.py:1-80]()\n\n### TaskCallbackRequest 详解\n\n```python\nclass TaskCallbackRequest(CallbackRequest):\n simple_task_instance: SimpleTaskInstance\n msg: str | None\n processor_subprocess: bool\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| simple_task_instance | SimpleTaskInstance | 任务实例的简化表示 |\n| msg | str | 回调消息（如错误信息）|\n| processor_subprocess | bool | 是否在子进程中处理 |\n\n### Callback 注册方式\n\n#### 方式一：任务级别\n\n```python\ndef task_failure_alert(context):\n dag_id = context['dag_run'].dag_id\n task_id = context['task'].task_id\n send_alert(dag_id, task_id)\n\nwith DAG(...) as dag:\n task = PythonOperator(\n task_id=\"example_task\",\n python_callable=my_func,\n on_failure_callback=task_failure_alert,\n )\n```\n\n#### 方式二：DAG 级别\n\n```python\ndef dag_failure_alert(context):\n dag_id = context['dag_run'].dag_id\n send_dag_failure_notification(dag_id)\n\nwith DAG(\n dag_id=\"my_dag\",\n on_failure_callback=dag_failure_alert,\n):\n # tasks...\n```\n\n#### 方式三：使用 Airflow API 动态注册\n\n```python\nfrom airflow.models import TaskCallbackRequest\nfrom airflow.callbacks.callback_requests import _prepare_callback\n\n# 在执行器中动态注册\ncallback_request = _prepare_callback(\n ti=task_instance,\n callback_type=\"failure\",\n msg=\"Task failed with exception\",\n)\n```\n\n## 数据流转最佳实践\n\n### 避免数据膨胀\n\nXCom 数据存储在元数据库中，过大的数据量会影响数据库性能。建议遵循以下原则：\n\n1. **小数据原则**：XCom 值应保持在 10KB 以下\n2. **引用传递**：大型数据使用 URI/路径引用\n3. **定期清理**：配置 XCom 过期策略\n\n### 数据验证与类型安全\n\n在任务间传递数据时，应实施严格的验证策略：\n\n```python\nfrom pydantic import BaseModel, validator\n\nclass DataRecord(BaseModel):\n id: int\n value: float\n tags: list[str]\n \n @validator('value')\n def value_must_be_positive(cls, v):\n if v < 0:\n raise ValueError('value must be positive')\n return v\n\ndef process_data(**context):\n raw_data = context['ti'].xcom_pull(task_ids='extract', key='data')\n validated = DataRecord(**raw_data)\n return validated.dict()\n```\n\n### 幂等性设计\n\n任务应设计为幂等的，即相同输入多次执行产生相同结果。这在使用 XCom 进行数据传递时尤为重要，因为任务可能因重试而多次执行。\n\n### Asset 与 XCom 的选择\n\n| 场景 | 推荐机制 | 原因 |\n|------|----------|------|\n| 触发 DAG 执行 | Asset | 自动调度，感知数据源变化 |\n| 任务间传递结果 | XCom | 轻量，适合小数据量 |\n| 共享大型数据集 | 外部存储 + XCom 引用 | 避免元数据库压力 |\n| 事件驱动工作流 | Asset + TriggerDagRunOperator | 结合使用 |\n\n## 总结\n\nApache Airflow 的数据流转与交换机制通过 XCom、Asset 和 Callback 三大组件，为分布式工作流环境提供了完整的数据协调能力。XCom 专注于任务间的数据传递，Asset 实现了数据驱动的 DAG 触发，而 Callback 则在关键生命周期节点提供了扩展点。理解并合理运用这些机制，能够构建出高效、可靠且可维护的数据流水线。\n\n资料来源：[airflow-core/docs/core-concepts/xcoms.rst:1-50]()\n资料来源：[airflow-core/docs/authoring-and-scheduling/assets.rst:1-50]()\n\n---\n\n\n\n## FastAPI核心API\n\n### 相关页面\n\n相关主题：[React前端架构](#frontend)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [airflow-core/src/airflow/api_fastapi/core_api/app.py](https://github.com/apache/apache-airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/app.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/src/airflow/api_fastapi/core_api/routes/ui/dags.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/routes/ui/dags.py)\n- [airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py](https://github.com/apache/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/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n \n\n# FastAPI核心API\n\n## 概述\n\nApache Airflow的FastAPI核心API是项目现代化Web服务架构的重要组成部分，旨在替代传统的Flask API。这一API层采用FastAPI框架构建，提供了高性能、异步支持、自动文档生成等特性。FastAPI核心API主要分为两个独立的应用程序：**Core API**（核心API）和**Execution API**（执行API），分别承担不同的职责。\n\nFastAPI核心API位于 `airflow-core/src/airflow/api_fastapi/` 目录下，采用模块化设计，将路由、数据模型、认证管理器等组件分离到独立的子模块中。这种架构设计使得代码组织清晰，便于维护和扩展。\n\n## 架构概览\n\n```mermaid\ngraph TB\n subgraph \"FastAPI应用层\"\n CA[Core API
core_api/app.py]\n EA[Execution API
execution_api/app.py]\n end\n \n subgraph \"认证层\"\n SAM[SimpleAuthManager
simple_auth_manager.py]\n AM[Auth Managers]\n end\n \n subgraph \"路由层\"\n UI_DAGS[UI DAG Routes
routes/ui/dags.py]\n API_ROUTES[API Routes]\n end\n \n subgraph \"数据模型层\"\n DM[DAG Run Datamodels
datamodels/dag_run.py]\n DT[其他Datamodels]\n end\n \n CA --> SAM\n EA --> SAM\n CA --> UI_DAGS\n CA --> API_ROUTES\n CA --> DM\n EA --> DM\n```\n\n## 核心组件\n\n### Core API应用\n\nCore API是Airflow的主要REST API服务，负责提供DAG管理、任务调度、监控等核心功能。该应用通过 `core_api/app.py` 文件初始化和配置，包含以下关键特性：\n\n- 异步请求处理支持\n- OpenAPI自动文档生成\n- Pydantic数据验证\n- 依赖注入系统\n- 中间件支持\n\nCore API的路由结构按功能模块划分，包括UI路由、作业路由、配置路由等多个子模块。这种模块化设计使得API扩展和维护更加便捷。\n\n### Execution API应用\n\nExecution API是专门用于任务执行的轻量级API服务，通过 `execution_api/app.py` 实现。该API主要负责：\n\n- 任务实例的执行状态管理\n- XCom消息传递\n- 任务心跳检测\n- 执行结果回调\n\nExecution API采用独立部署模式，与Core API解耦，以提高系统的可靠性和响应速度。\n\n## 数据模型\n\n### DAG Run数据模型\n\nDAG Run数据模型定义了DAG运行实例的结构，是整个调度系统的核心数据结构之一。在 `datamodels/dag_run.py` 中定义的主要字段包括：\n\n| 字段名 | 类型 | 说明 | 资料来源 |\n|--------|------|------|----------|\n| dag_id | str | DAG唯一标识符 | [dag_run.py](airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py) |\n| run_id | str | 运行实例唯一标识 | [dag_run.py](airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py) |\n| state | DagRunState | 运行状态枚举 | [dag_run.py](airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py) |\n| execution_date | datetime | 执行时间戳 | [dag_run.py](airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py) |\n| start_date | datetime | 开始时间 | [dag_run.py](airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py) |\n| end_date | datetime | 结束时间 | [dag_run.py](airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py) |\n| conf | dict | DAG配置参数 | [dag_run.py](airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py) |\n\n### 数据验证\n\n所有通过API接收的数据都会经过Pydantic模型验证，确保数据类型和格式的正确性。这种自动验证机制减少了手动编写数据校验代码的需求，提高了开发效率。\n\n## 路由结构\n\n### UI DAG路由\n\nUI DAG路由是面向Web界面的API端点集合，通过 `routes/ui/dags.py` 文件实现。这些路由主要用于：\n\n- DAG列表查询\n- DAG运行历史记录\n- DAG状态监控\n- 任务依赖关系可视化\n\nUI路由通常需要用户认证，并返回适合前端渲染的数据格式。\n\n### 路由组织方式\n\n```mermaid\ngraph LR\n subgraph \"路由注册\"\n RC[Route Configuration
cli_config.py]\n end\n \n subgraph \"CLI命令\"\n CMD1[airflow dags]\n CMD2[airflow tasks]\n CMD3[airflow connections]\n end\n \n RC --> CMD1\n RC --> CMD2\n RC --> CMD3\n \n CMD1 --> DAG_ROUTES[DAG Routes]\n CMD2 --> TASK_ROUTES[Task Routes]\n CMD3 --> CONN_ROUTES[Connection Routes]\n```\n\n在 `cli_config.py` 中定义了Airflow CLI命令与API路由的映射关系，支持的命令包括：\n\n| 命令组 | 子命令 | 功能说明 |\n|--------|--------|----------|\n| dags | backfill, list-runs, pause, unpause, test | DAG生命周期管理 |\n| tasks | list, run, state, clear | 任务操作管理 |\n| connections | list, add, delete, edit | 连接配置管理 |\n| providers | list, get | Provider信息查询 |\n\n## 认证与授权\n\n### SimpleAuthManager\n\nSimpleAuthManager是FastAPI认证系统的核心组件，位于 `auth/managers/simple/simple_auth_manager.py`。它提供了简化的认证机制，适用于单机部署或开发环境。\n\n主要功能包括：\n\n- 用户身份验证\n- 会话管理\n- 权限检查\n- API密钥验证\n\n### 认证管理器架构\n\n```mermaid\nclassDiagram\n class BaseAuthManager {\n <>\n +authenticate()\n +get_user()\n +is_authorized()\n }\n \n class SimpleAuthManager {\n +authenticate()\n +get_user()\n +is_authorized()\n +get_user_role()\n }\n \n BaseAuthManager <|-- SimpleAuthManager\n```\n\n### 认证流程\n\n认证请求的标准处理流程如下：\n\n1. 客户端发送带认证信息的请求\n2. 中间件拦截请求并提取认证凭证\n3. SimpleAuthManager验证凭证有效性\n4. 根据用户角色确定访问权限\n5. 返回认证结果或拒绝访问\n\n## CLI集成\n\n### 命令注册机制\n\n在 `cli_config.py` 中使用懒加载模式注册CLI命令，这种方式可以提高应用启动速度：\n\n```python\nActionCommand(\n name=\"info\",\n help=\"Show information about current Airflow and environment\",\n func=lazy_load_command(\"airflow.cli.commands.info_command.show_info\"),\n args=(ARG_ANONYMIZE, ARG_FILE_IO, ARG_VERBOSE, ARG_OUTPUT),\n)\n```\n\n### 懒加载命令\n\n懒加载机制确保只有在实际调用命令时才加载对应的模块，这有助于：\n\n- 减少内存占用\n- 加快应用启动时间\n- 避免不必要的模块依赖\n\n支持的懒加载命令类型包括：\n\n- `info_command` - 环境信息展示\n- `plugins_command` - 插件信息导出\n- `standalone_command` - 独立运行模式\n- `config_command` - 配置管理\n- `version_command` - 版本信息\n- `cheat_sheet_command` - 命令速查表\n\n## 配置管理\n\n### 配置命令\n\nFastAPI核心API提供了丰富的配置管理功能，包括：\n\n| 命令 | 功能 | 说明 |\n|------|------|------|\n| config get-value | 获取配置值 | 打印指定配置项的值 |\n| config list | 列出配置 | 显示所有配置选项 |\n| config lint | 配置检查 | 验证配置迁移正确性 |\n| config update | 更新配置 | 修改配置值 |\n\n### 配置参数\n\n配置API支持多种参数用于过滤和格式化输出：\n\n- `--section` - 指定配置章节\n- `--option` - 指定配置选项\n- `--include-descriptions` - 包含描述信息\n- `--include-examples` - 包含示例值\n- `--include-sources` - 显示配置来源\n- `--include-env-vars` - 显示环境变量\n- `--hide-sensitive` - 隐藏敏感信息\n\n## API响应格式\n\n### 统一响应结构\n\nFastAPI核心API采用统一的响应格式，便于客户端处理：\n\n```json\n{\n \"data\": {},\n \"meta\": {\n \"status\": \"success\",\n \"timestamp\": \"2024-01-01T00:00:00Z\"\n }\n}\n```\n\n### 错误响应\n\n错误响应遵循统一的格式，包含错误码、消息和详细信息：\n\n```json\n{\n \"error\": {\n \"code\": \"DAG_NOT_FOUND\",\n \"message\": \"DAG with id 'example_dag' not found\",\n \"details\": {}\n }\n}\n```\n\n## 技术特性\n\n### 异步支持\n\nFastAPI核心API全面支持异步操作，包括：\n\n- 异步数据库查询\n- 异步HTTP请求\n- 异步文件操作\n- 并发任务处理\n\n### 自动文档\n\n基于OpenAPI标准，API自动生成交互式文档：\n\n- Swagger UI 可通过 `/docs` 访问\n- ReDoc 可通过 `/redoc` 访问\n- OpenAPI JSON 可通过 `/openapi.json` 获取\n\n### 数据验证\n\n使用Pydantic v2进行严格的数据验证和转换：\n\n- 类型检查\n- 默认值处理\n- 自定义验证器\n- 嵌套模型支持\n\n## 部署架构\n\n### 多实例部署\n\n在生产环境中，FastAPI核心API支持多实例部署：\n\n```mermaid\ngraph TB\n LB[Load Balancer]\n API1[Core API Instance 1]\n API2[Core API Instance 2]\n API3[Core API Instance 3]\n DB[(Database)]\n Redis[(Redis)]\n \n LB --> API1\n LB --> API2\n LB --> API3\n API1 --> DB\n API2 --> DB\n API3 --> DB\n API1 --> Redis\n API2 --> Redis\n API3 --> Redis\n```\n\n### 与传统Flask API对比\n\n| 特性 | FastAPI | Flask |\n|------|---------|-------|\n| 性能 | 异步原生支持 | 同步为主 |\n| 文档 | 自动生成OpenAPI | 需手动编写 |\n| 验证 | Pydantic自动验证 | 手动验证 |\n| 类型安全 | 完整类型注解 | 运行时检查 |\n| 并发 | 原生异步支持 | 需扩展支持 |\n\n## 安全考虑\n\n### 敏感信息保护\n\nAPI在处理敏感信息时采取以下保护措施：\n\n- 敏感配置加密存储\n- 日志输出脱敏处理\n- 环境变量优先读取\n- 连接凭证安全传输\n\n### 权限控制\n\n基于角色的访问控制（RBAC）确保API操作的安全性：\n\n- 管理员权限 - 完全访问\n- 编辑权限 - 修改配置\n- 只读权限 - 查询数据\n- 无权限 - 拒绝访问\n\n## 扩展开发\n\n### 自定义路由\n\n开发者可以通过以下步骤添加自定义路由：\n\n1. 在相应模块下创建路由文件\n2. 定义路由函数和参数\n3. 注册路由到应用\n4. 添加CLI命令映射\n\n### 自定义认证\n\n扩展认证机制需要实现以下接口：\n\n- `authenticate()` - 用户认证方法\n- `get_user()` - 获取用户信息\n- `is_authorized()` - 权限检查方法\n\n## 最佳实践\n\n### API设计原则\n\n1. **RESTful规范** - 遵循REST设计原则\n2. **版本控制** - 保持API向后兼容\n3. **错误处理** - 返回有意义的错误信息\n4. **性能优化** - 使用异步操作提高吞吐量\n5. **文档维护** - 及时更新API文档\n\n### 性能优化建议\n\n- 使用连接池管理数据库连接\n- 合理使用缓存减少数据库查询\n- 实现请求限流防止滥用\n- 监控API响应时间及时发现问题\n\n## 相关文档\n\n- [Core API完整路由参考](airflow-core/src/airflow/api_fastapi/core_api/routes)\n- [Execution API参考](airflow-core/src/airflow/api_fastapi/execution_api)\n- [认证管理器文档](airflow-core/src/airflow/api_fastapi/auth/managers)\n- [数据模型定义](airflow-core/src/airflow/api_fastapi/core_api/datamodels)\n\n---\n\n\n\n## React前端架构\n\n### 相关页面\n\n相关主题：[FastAPI核心API](#fastapi)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\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- [airflow-core/src/airflow/ui/src/pages/Providers.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/Providers.tsx)\n- [airflow-core/src/airflow/ui/src/pages/DagsList/DagsList.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/DagsList/DagsList.tsx)\n- [airflow-core/src/airflow/ui/src/pages/Run/Header.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/Run/Header.tsx)\n- [airflow-core/src/airflow/ui/src/pages/XCom/XCom.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/XCom/XCom.tsx)\n- [airflow-core/src/airflow/ui/src/pages/HITLTaskInstances/HITLTaskInstances.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/HITLTaskInstances/HITLTaskInstances.tsx)\n- [airflow-core/src/airflow/ui/src/components/Assets/TriggeredRuns.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/Assets/TriggeredRuns.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/components/Clear/TaskInstance/ClearGroupTaskInstanceDialog.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/Clear/TaskInstance/ClearGroupTaskInstanceDialog.tsx)\n- [airflow-core/src/airflow/ui/src/components/Dashboard/Stats/DAGImportErrorsModal.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/Dashboard/Stats/DAGImportErrorsModal.tsx)\n- [airflow-core/src/airflow/ui/src/components/TaskInstanceTooltip.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/TaskInstanceTooltip.tsx)\n- [airflow-core/src/airflow/ui/src/components/ui/Tag.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/ui/Tag.tsx)\n- [dev/react-plugin-tools/react_plugin_template/README.md](https://github.com/apache/airflow/blob/main/dev/react-plugin-tools/react_plugin_template/README.md)\n \n\n# React前端架构\n\n## 概述\n\nApache Airflow 的 React 前端是一个现代化的单页应用（SPA），采用 React 18、TypeScript 和 Chakra UI 构建，为用户提供了直观、高效的 DAG 管理和监控界面。该前端架构遵循组件化设计原则，通过 TanStack Table 实现数据表格功能，使用 react-router-dom 进行路由管理，并集成了 react-i18next 实现国际化支持。资料来源：[dev/react-plugin-tools/react_plugin_template/README.md](https://github.com/apache/airflow/blob/main/dev/react-plugin-tools/react_plugin_template/README.md)\n\n## 技术栈概览\n\n### 核心依赖\n\n| 技术 | 用途 | 版本说明 |\n|------|------|----------|\n| React 18 | UI 框架 | 核心库 |\n| TypeScript | 类型系统 | 类型安全 |\n| Chakra UI | UI 组件库 | 样式和组件 |\n| TanStack Table | 数据表格 | 排序、分页 |\n| react-router-dom | 路由管理 | SPA 导航 |\n| react-i18next | 国际化 | 多语言支持 |\n\n### 构建工具\n\n前端项目使用 **Vite** 作为构建工具，提供快速的开发服务器和优化的生产构建。Vite 配置将 React 和相关生态库标记为外部依赖，以减少插件包体积。资料来源：[dev/react-plugin-tools/react_plugin_template/README.md](https://github.com/apache/airflow/blob/main/dev/react-plugin-tools/react_plugin_template/README.md)\n\n## 页面组件架构\n\n### 页面目录结构\n\nAirflow 前端的页面组件位于 `airflow-core/src/airflow/ui/src/pages/` 目录下，采用模块化组织方式：\n\n```\npages/\n├── DagRuns.tsx # DAG运行列表页\n├── DagsList/ # DAG列表模块\n│ └── DagsList.tsx\n├── Providers.tsx # 提供商信息页\n├── Run/ # 运行详情模块\n│ └── Header.tsx\n├── XCom/ # XCom数据模块\n│ └── XCom.tsx\n└── HITLTaskInstances/ # 人工干预任务实例模块\n └── HITLTaskInstances.tsx\n```\n\n### 页面组件通用模式\n\n每个页面组件通常遵循以下结构模式：\n\n1. **导入依赖**：引入必要的 React hooks、组件和工具函数\n2. **类型定义**：定义页面专用的 TypeScript 接口\n3. **列定义工厂函数**：创建 `createColumns` 函数用于生成 TanStack Table 列配置\n4. **主组件导出**：使用自定义 hooks 获取数据并渲染页面\n\n```typescript\nconst createColumns = (translate: TFunction): Array> => [\n {\n accessorKey: \"package_name\",\n cell: ({ row: { original } }) => (\n \n {original.package_name}\n \n ),\n enableSorting: false,\n header: translate(\"providers.columns.packageName\"),\n },\n // ... 更多列定义\n];\n```\n\n资料来源：[airflow-core/src/airflow/ui/src/pages/Providers.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/Providers.tsx)\n\n## 核心组件体系\n\n### UI 基础组件\n\n基础 UI 组件位于 `airflow-core/src/airflow/ui/src/components/ui/` 目录下，提供可复用的界面元素。\n\n#### Tag 组件\n\n`Tag` 组件是对 Chakra UI Tag 的封装，提供了统一的标签样式：\n\n```typescript\nconst Tag = React.forwardRef(({ \n closable = Boolean(onClose), \n endElement, \n startElement, \n ...rest \n}) => {\n return (\n \n {Boolean(startElement) ? {startElement} : undefined}\n {children}\n {Boolean(endElement) ? {endElement} : undefined}\n {Boolean(closable) ? (\n \n \n \n ) : undefined}\n \n );\n});\n```\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| closable | boolean | 是否显示关闭按钮 |\n| endElement | ReactNode | 标签尾部元素 |\n| startElement | ReactNode | 标签头部元素 |\n| onClose | () => void | 关闭回调函数 |\n\n资料来源：[airflow-core/src/airflow/ui/src/components/ui/Tag.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/ui/Tag.tsx)\n\n### 数据展示组件\n\n#### DAG 触发运行组件 (TriggeredRuns)\n\n`TriggeredRuns` 组件用于展示由 DAG 触发的运行信息，支持单个和多个运行场景：\n\n```typescript\nexport const TriggeredRuns = ({ dagRuns }: Props) => {\n if (dagRuns === undefined || dagRuns.length === 0) {\n return undefined;\n }\n\n return dagRuns.length === 1 ? (\n \n {`${translate(\"triggered\")} ${translate(\"dagRun_one\")}: `}\n \n \n \n {dagRuns[0]?.dag_id}\n \n \n \n ) : (\n \n \n \n \n \n {/* 多个运行时显示下拉列表 */}\n \n \n );\n};\n```\n\n| 场景 | 渲染方式 |\n|------|----------|\n| 单个运行 | 内联展示 DAG ID 和状态徽章 |\n| 多个运行 | 下拉菜单，点击展开列表 |\n\n资料来源：[airflow-core/src/airflow/ui/src/components/Assets/TriggeredRuns.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/Assets/TriggeredRuns.tsx)\n\n### 任务实例工具提示组件\n\n`TaskInstanceTooltip` 组件提供任务实例的详细信息悬浮提示：\n\n```typescript\n\n```\n\n显示的信息包括：任务 ID、状态、运行 ID、调度时间、队列时间、开始时间、结束时间以及重试次数。资料来源：[airflow-core/src/airflow/ui/src/components/TaskInstanceTooltip.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/TaskInstanceTooltip.tsx)\n\n### 对话框组件\n\n#### 清除任务实例确认对话框\n\n`ClearTaskInstanceConfirmationDialog` 是用于确认清除任务实例操作的模态对话框：\n\n```typescript\n\n \n \n \n \n \n \n {translate(\"dags:runAndTaskActions.confirmationDialog.title\")}\n \n \n {translate(\"dags:runAndTaskActions.confirmationDialog.description\", {\n state: taskCurrentState,\n time: getRelativeTime(firstInstance.start_date),\n user: firstInstance?.unixname ?? \"unknown user\",\n })}\n \n \n \n \n \n \n\n```\n\n对话框使用 Radix UI 的 Dialog 组件，提供标题、描述和底部操作区域，支持国际化翻译。资料来源：[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\n#### 批量清除任务实例对话框\n\n`ClearGroupTaskInstanceDialog` 用于批量清除一组任务实例，支持以下参数：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| future | boolean | 是否包含未来运行 |\n| past | boolean | 是否包含过去运行 |\n| upstream | boolean | 是否包含上游任务 |\n| onlyFailed | boolean | 仅清除失败任务 |\n| runOnLatestVersion | boolean | 使用最新 DAG 版本运行 |\n| note | string \\| null | 清除操作备注 |\n| groupTaskIds | string[] | 任务 ID 列表 |\n\n资料来源：[airflow-core/src/airflow/ui/src/components/Clear/TaskInstance/ClearGroupTaskInstanceDialog.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/Clear/TaskInstance/ClearGroupTaskInstanceDialog.tsx)\n\n### 模态框组件\n\n#### DAG 导入错误模态框\n\n`DAGImportErrorsModal` 展示 DAG 导入过程中的错误信息：\n\n- 使用 Accordion 组件折叠/展开每个错误详情\n- 使用 Pagination 组件分页显示错误列表\n- 显示错误时间戳和完整的堆栈跟踪信息\n\n```typescript\n\n {importErrors.map((importError) => (\n \n \n {importError.filename}\n \n \n \n {importError.stack_trace}\n \n \n \n ))}\n\n```\n\n资料来源：[airflow-core/src/airflow/ui/src/components/Dashboard/Stats/DAGImportErrorsModal.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/Dashboard/Stats/DAGImportErrorsModal.tsx)\n\n## 表格列配置系统\n\n### TanStack Table 集成\n\nAirflow 前端使用 TanStack Table（React Table）作为数据表格解决方案，通过列定义工厂函数生成可配置的表格结构。\n\n### DAG 运行列表列配置\n\n`DagRuns.tsx` 中的列配置示例：\n\n| 访问器键 | 组件 | 功能 |\n|----------|------|------|\n| run_after | Time | 显示运行时间 |\n| state | StateBadge | 任务状态徽章 |\n| run_type | RunTypeIcon + Text | 运行类型图标和文字 |\n| triggering_user_name | Text | 触发用户名称 |\n| start_date | Time | 开始时间 |\n| end_date | Time | 结束时间 |\n| duration | renderDuration | 持续时间渲染 |\n\n```typescript\n{\n accessorKey: \"state\",\n cell: ({ row: { original: { state } } }) => (\n \n {translate(`common:states.${state}`)}\n \n ),\n header: () => translate(\"state\"),\n},\n```\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### DAG 列表特殊列\n\n`DagsList.tsx` 包含一些独特的列定义：\n\n```typescript\n{\n accessorKey: \"pending_actions\",\n cell: ({ row: { original: dag } }) => (\n \n ),\n enableSorting: false,\n header: \"\",\n},\n{\n accessorKey: \"trigger\",\n cell: ({ row: { original } }) => (\n \n ),\n enableSorting: false,\n header: \"\",\n},\n```\n\n这些列用于显示待处理操作和 DAG 触发按钮，没有排序功能。资料来源：[airflow-core/src/airflow/ui/src/pages/DagsList/DagsList.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/DagsList/DagsList.tsx)\n\n## 国际化实现\n\n### 翻译函数使用\n\n前端使用 `react-i18next` 的 `useTranslation` hook 获取翻译函数：\n\n```typescript\nconst { t: translate } = useTranslation(\"common\");\n\n// 在列配置中使用\nheader: () => translate(\"dagRun.runAfter\")\n\n// 动态键翻译\n{translate(`common:states.${state}`)}\n```\n\n### 命名空间管理\n\n翻译键使用冒号分隔命名空间，例如 `common:states.running`、`dagRun.runAfter` 等，允许多个翻译文件独立管理。资料来源：[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## 路由与导航\n\n### 路由模式\n\nAirflow 前端使用 `react-router-dom` 进行客户端路由，主要导航模式包括：\n\n```typescript\n// 链接到 DAG 详情\n\n\n// 链接到任务实例\n\n```\n\n### 嵌套路由结构\n\n页面通过嵌套路由组织，支持从 DAG 列表 → DAG 详情 → 任务实例的层级导航。\n\n## React 插件系统\n\n### 插件模板架构\n\nAirflow 提供 React 插件模板，支持第三方开发者构建可集成到主应用的组件库：\n\n```typescript\nimport { PluginComponent } from 'your-plugin-name';\n\n\n```\n\n### 插件开发指南\n\n| 步骤 | 说明 |\n|------|------|\n| 组件开发 | 使用 React + TypeScript 编写功能组件 |\n| 主题适配 | 自动继承 Airflow 主应用主题 |\n| 构建配置 | 使用 Vite 构建为库文件 |\n| 外部依赖 | React 生态库标记为外部以避免冲突 |\n\n资料来源：[dev/react-plugin-tools/react_plugin_template/README.md](https://github.com/apache/airflow/blob/main/dev/react-plugin-tools/react_plugin_template/README.md)\n\n## 数据流架构\n\n```mermaid\ngraph TD\n A[用户交互] --> B[React 组件]\n B --> C[API 请求]\n C --> D[Airflow REST API]\n D --> E[后端数据库]\n E --> D\n D --> C\n C --> F[状态更新]\n F --> B\n B --> G[UI 渲染]\n \n H[TanStack Table] --> I[列定义配置]\n I --> B\n B --> J[数据展示]\n \n K[useTranslation] --> L[翻译键]\n L --> M[翻译文件]\n M --> K\n```\n\n## 组件生命周期管理\n\n### 状态管理\n\n组件使用 React hooks 管理状态：\n\n- `useState`：本地组件状态\n- `useEffect`：副作用处理\n- `useTranslation`：国际化\n- `useParams`：URL 参数获取\n- `useTableURLState`：表格 URL 状态同步\n\n### 条件渲染模式\n\n```typescript\n// 使用短路求值\n{Boolean(dagRuns.length) && }\n\n// 使用三元运算符\n{condition ? : }\n\n// 使用 && 运算符\n{hasCondition && }\n```\n\n## 样式系统\n\n### Chakra UI 集成\n\n前端使用 Chakra UI 作为主要样式解决方案，提供：\n\n- 预设的设计令牌（颜色、间距、字体）\n- 可访问性内置支持\n- 主题定制能力\n- 组件组合模式\n\n### 颜色语义\n\n| 语义颜色 | 用途 | 示例 |\n|----------|------|------|\n| fg.info | 信息文本 | 链接 |\n| fg.error | 错误文本 | 错误消息 |\n| bg.emphasized | 强调背景 | 弹窗背景 |\n\n## 最佳实践\n\n### 组件开发规范\n\n1. **类型安全**：所有组件使用 TypeScript，明确输入输出类型\n2. **可访问性**：使用语义化 HTML 和 ARIA 属性\n3. **国际化**：所有用户可见文本使用翻译函数\n4. **错误处理**：组件包含错误边界和降级处理\n5. **性能优化**：使用 `lazyMount` 和 `unmountOnExit` 延迟加载\n\n### 文件组织原则\n\n- **页面组件**：位于 `pages/` 目录，包含业务逻辑\n- **通用组件**：位于 `components/` 目录，可复用\n- **UI 组件**：位于 `components/ui/` 目录，基础元素\n- **布局组件**：位于 `layouts/` 目录，页面结构\n\n## 总结\n\nApache Airflow 的 React 前端采用了现代化的组件化架构，通过 TanStack Table 实现灵活的数据表格功能，借助 Chakra UI 提供一致的用户界面体验，使用 react-i18next 支持多语言环境。插件系统的设计允许第三方开发者扩展功能，同时保持与主应用的主题一致性。整个前端架构体现了可维护性、可扩展性和用户体验的平衡。\n\n---\n\n\n\n## 容器化与Kubernetes部署\n\n### 相关页面\n\n相关主题：[执行器类型与选择](#executors), [快速开始与安装指南](#quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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- [dev/breeze/src/airflow_breeze/global_constants.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/global_constants.py)\n- [airflow-core/src/airflow/example_dags/example_kubernetes_executor.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/example_dags/example_kubernetes_executor.py)\n- [docker-stack-docs/README.md](https://github.com/apache/airflow/blob/main/docker-stack-docs/README.md)\n- [chart/docs/production-guide.rst](https://github.com/apache/airflow/blob/main/chart/docs/production-guide.rst)\n \n\n# 容器化与Kubernetes部署\n\nApache Airflow 作为分布式工作流编排平台，支持通过容器化和 Kubernetes 实现灵活的部署方案。本文详细介绍 Airflow 的 Docker 镜像构建机制、Kubernetes 部署架构以及生产环境最佳实践。\n\n## 1. Docker 容器化概述\n\nApache Airflow 提供官方的 `apache/airflow` Docker 镜像，该镜像是构建生产级部署环境的基础。镜像采用多阶段构建技术，基于 Python slim 镜像优化体积。\n\n### 1.1 Docker 构建配置\n\nAirflow 的 Dockerfile 使用 Docker BuildKit 语法，支持通过 `--mount=type=cache` 挂载缓存目录以加速构建过程：\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==\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/release_management_commands.py:52-58]()\n\n### 1.2 入口点与初始化\n\nDocker 镜像的入口点脚本负责初始化 SQLite 数据库（当未配置外部数据库时）：\n\n> 如果未设置 `AIRFLOW__DATABASE__SQL_ALCHEMY_CONN` 变量，则在 `${AIRFLOW_HOME}/airflow.db` 创建 SQLite 数据库。\n\n资料来源：[docker-stack-docs/README.md:15-16]()\n\n## 2. Kubernetes 部署架构\n\nAirflow 在 Kubernetes 上的部署通过 Helm Chart 实现，支持高度可配置的分布式架构。\n\n### 2.1 支持的 Kubernetes 版本\n\nApache Airflow 根据三大云服务商的 Kubernetes 支持周期维护兼容版本列表：\n\n| 云服务商 | 生命周期页面 |\n|---------|-------------|\n| Amazon EKS | [endoflife.date/amazon-eks](https://endoflife.date/amazon-eks) |\n| Azure Kubernetes Service | [endoflife.date/azure-kubernetes-service](https://endoflife.date/azure-kubernetes-service) |\n| Google Kubernetes Engine | [endoflife.date/google-kubernetes-engine](https://endoflife.date/google-kubernetes-engine) |\n\n当前允许的 Kubernetes 版本列表：\n\n| 版本 | 状态 |\n|-----|------|\n| v1.30.13 | ✅ 支持 |\n| v1.31.12 | ✅ 支持 |\n| v1.32.8 | ✅ 支持 |\n| v1.33.4 | ✅ 支持 |\n| v1.34.0 | ✅ 支持 |\n\n资料来源：[dev/breeze/src/airflow_breeze/global_constants.py:ALLOWED_KUBERNETES_VERSIONS]()\n\n### 2.2 Kubernetes 组件架构\n\nAirflow 在 Kubernetes 环境中的核心组件包括：\n\n```mermaid\ngraph TD\n subgraph \"Kubernetes 集群\"\n subgraph \"airflow Namespace\"\n Scheduler[\"Scheduler Pod
调度器\"]\n Webserver[\"Webserver Pod
Web服务器\"]\n Triggerer[\"Triggerer Pod
触发器\"]\n DagProcessor[\"Dag Processor Pod
DAG处理器\"]\n end\n \n subgraph \"Pod 配置\"\n Executor[\"Executor
执行器\"]\n Worker[\"Worker Pod
工作节点\"]\n K8SExecutor[\"K8S Executor
Kubernetes执行器\"]\n end\n end\n \n ExternalDB[\"外部数据库
PostgreSQL/MySQL\"]\n Redis[\"消息队列
Redis\"]\n \n Scheduler --> Executor\n Executor --> K8SExecutor\n K8SExecutor --> Worker\n Scheduler --> ExternalDB\n Webserver --> ExternalDB\n Triggerer --> Redis\n```\n\n### 2.3 多命名空间模式\n\nAirflow 支持多命名空间部署模式，允许在不同命名空间中运行测试环境和生产环境：\n\n```python\noption_multi_namespace_mode = click.option(\n \"--multi-namespace-mode\",\n help=\"使用多命名空间模式\",\n is_flag=True,\n envvar=\"MULTI_NAMESPACE_MODE\",\n)\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/kubernetes_commands.py:multi_namespace_mode]()\n\n## 3. Kubernetes 部署命令\n\n### 3.1 部署工作流程\n\n```mermaid\ngraph LR\n A[\"breeze k8s deploy-airflow\"] --> B[\"创建 KinD 集群\"]\n B --> C[\"创建 Kubernetes 命名空间\"]\n C --> D[\"部署 Helm Chart\"]\n D --> E[\"配置 Airflow 组件\"]\n E --> F[\"验证部署状态\"]\n```\n\n### 3.2 核心部署选项\n\n| 参数 | 说明 | 默认值 |\n|-----|------|--------|\n| `--python` | Python 版本 | 3.10 |\n| `--kubernetes-version` | Kubernetes 集群版本 | v1.31.12 |\n| `--executor` | 执行器类型 | LocalExecutor |\n| `--deploy/--no-deploy` | 是否通过 Skaffold 部署 | False |\n| `--upgrade` | 升级而非安装 Helm Chart | False |\n| `--multi-namespace-mode` | 启用多命名空间模式 | False |\n| `--rebuild-base-image` | 重建基础镜像 | False |\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/kubernetes_commands.py:option_executor]()\n\n### 3.3 部署流程代码\n\n部署 Airflow 到 Kubernetes 集群的核心逻辑：\n\n```python\ndef _deploy_airflow(\n python: str,\n kubernetes_version: str,\n output: Output | None,\n executor: str,\n upgrade: bool,\n use_standard_naming: bool,\n wait_time_in_seconds: int,\n extra_options: str,\n multi_namespace_mode: bool,\n):\n cluster_name = get_kubectl_cluster_name(\n python=python, kubernetes_version=kubernetes_version\n )\n # 创建命名空间\n get_console(output=output).print(f\"[info]创建集群 {cluster_name} 的命名空间\")\n run_command_with_k8s_env(\n [\"kubectl\", \"create\", \"namespace\", HELM_AIRFLOW_NAMESPACE],\n python=python,\n kubernetes_version=kubernetes_version,\n output=output,\n check=False,\n )\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/kubernetes_commands.py:_deploy_airflow]()\n\n## 4. Kubernetes 执行器配置\n\n### 4.1 Pod 覆盖机制\n\nKubernetes 执行器允许通过 `pod_override` 动态配置 Pod 规格：\n\n```python\nstart_task_executor_config = {\n \"pod_override\": k8s.V1Pod(\n metadata=k8s.V1ObjectMeta(annotations={\"test\": \"annotation\"})\n )\n}\n\n@task(executor_config=start_task_executor_config)\ndef start_task():\n print_stuff()\n```\n\n资料来源：[airflow-core/src/airflow/example_dags/example_kubernetes_executor.py:20-27]()\n\n### 4.2 Volume 挂载配置\n\n支持在 Task 执行时挂载持久化卷：\n\n```python\nexecutor_config_volume_mount = {\n \"pod_override\": k8s.V1Pod(\n spec=k8s.V1PodSpec(\n containers=[\n k8s.V1Container(\n name=\"base\",\n volume_mounts=[\n k8s.V1VolumeMount(\n mount_path=\"/foo/\",\n name=\"example-kubernetes-test-volume\"\n )\n ],\n )\n ],\n volumes=[\n k8s.V1Volume(\n name=\"example-kubernetes-test-volume\",\n host_path=k8s.V1HostPathVolumeSource(path=\"/tmp/\"),\n )\n ],\n )\n ),\n}\n```\n\n资料来源：[airflow-core/src/airflow/example_dags/example_kubernetes_executor.py:31-56]()\n\n### 4.3 执行器配置参数表\n\n| 配置项 | 类型 | 说明 |\n|-------|------|------|\n| `pod_override` | V1Pod | Pod 覆盖规格 |\n| `annotations` | Dict[str, str] | Pod 注解 |\n| `labels` | Dict[str, str] | Pod 标签 |\n| `node_selector` | Dict[str, str] | 节点选择器 |\n| `tolerations` | List[V1Toleration] | 容忍度配置 |\n| `affinity` | V1Affinity | 亲和性配置 |\n| `resources` | V1ResourceRequirements | 资源限制 |\n\n## 5. Docker Compose 开发环境\n\n对于本地开发，Airflow 提供 Docker Compose 配置：\n\n```yaml\nservices:\n airflow:\n image: ${AIRFLOW_IMAGE_NAME:-apache/airflow:latest}\n environment:\n AIRFLOW__CORE__EXECUTOR: LocalExecutor\n AIRFLOW__DATABASE__SQL_ALCHEMY_CONN: sqlite:////opt/airflow/airflow.db\n AIRFLOW__CORE__FERNET_KEY: ''\n AIRFLOW__CORE__DAGS__FOLDER: ${AIRFLOW_PROJ_DIR:-.}/dags\n AIRFLOW__CORE__LOAD_EXAMPLES: 'true'\n```\n\n资料来源：[airflow-core/docs/howto/docker-compose/docker-compose.yaml]()\n\n### 5.1 Docker Compose 配置参数\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `AIRFLOW__CORE__EXECUTOR` | 执行器类型 | LocalExecutor |\n| `AIRFLOW__DATABASE__SQL_ALCHEMY_CONN` | 数据库连接字符串 | sqlite |\n| `AIRFLOW__CORE__FERNET_KEY` | 加密密钥 | - |\n| `AIRFLOW__CORE__DAGS__FOLDER` | DAG 文件目录 | ./dags |\n| `AIRFLOW__CORE__LOAD_EXAMPLES` | 加载示例 DAG | true |\n| `AIRFLOW__CORE__AIRFLOW_HOME` | Airflow 主目录 | /opt/airflow |\n\n## 6. 生产环境最佳实践\n\n### 6.1 部署检查清单\n\n| 检查项 | 说明 |\n|-------|------|\n| 外部数据库配置 | 使用 PostgreSQL 或 MySQL 而非 SQLite |\n| 执行器选择 | 生产环境推荐 CeleryExecutor 或 KubernetesExecutor |\n| 高可用配置 | 部署多个 Scheduler 和 Webserver 实例 |\n| 资源限制 | 为各组件设置 CPU 和内存限制 |\n| 健康检查 | 配置 readiness 和 liveness 探针 |\n| 持久化存储 | 使用 PVC 持久化 DAG 和日志 |\n\n### 6.2 安全配置\n\n生产环境部署时应考虑以下安全措施：\n\n1. **配置 Fernet 密钥**：启用敏感数据加密\n2. **使用 Secrets**：通过 Kubernetes Secrets 管理凭据\n3. **网络策略**：配置 Pod 间网络隔离\n4. **RBAC**：启用基于角色的访问控制\n5. **审计日志**：启用 Airflow 审计日志功能\n\n### 6.3 监控与告警\n\n建议集成的监控组件：\n\n- **Metrics**: Prometheus + Grafana\n- **Logging**: ELK Stack 或 Loki\n- **Tracing**: Jaeger\n- **Alerting**: Alertmanager\n\n## 7. 快速部署命令\n\n### 7.1 使用 Breeze 部署\n\n```bash\n# 部署到 Kind 集群\nbreeze k8s deploy-airflow --python 3.10 --kubernetes-version v1.31.12\n\n# 升级现有部署\nbreeze k8s deploy-airflow --upgrade\n\n# 启用多命名空间模式\nbreeze k8s deploy-airflow --multi-namespace-mode\n\n# 进入集群 Shell\nbreeze k8s shell\n\n# 运行测试\nbreeze k8s tests\n```\n\n### 7.2 Skaffold 开发循环\n\n对于开发场景，支持热重载功能：\n\n```bash\nbreeze k8s dev --skaffold-args \"--auto-sync\"\n```\n\n该命令会：\n- 同步 DAG 文件到运行中的 Pod\n- 热重载 airflow-core 源码（Scheduler/Triggerer/DAG Processor/API Server）\n- 自动刷新 UI（暂不支持）\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/kubernetes_commands.py:kubernetes_group]()\n\n## 8. 总结\n\nApache Airflow 的容器化和 Kubernetes 部署方案提供了企业级的灵活性。通过官方 Docker 镜像、Helm Chart 以及 Breeze 工具链，开发者和运维人员可以：\n\n- 在本地快速搭建开发环境\n- 在 Kubernetes 上实现弹性扩展\n- 通过 Kubernetes 执行器获得细粒度的资源控制\n- 利用多命名空间支持隔离测试和生产环境\n\n建议在生产部署前仔细评估业务需求，选择合适的执行器类型，并遵循本文档的最佳实践确保系统稳定性和安全性。\n\n---\n\n\n\n## Provider生态系统\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- [providers/amazon/src/airflow/providers/amazon/aws/hooks/ec2.py](https://github.com/apache/airflow/blob/main/providers/amazon/src/airflow/providers/amazon/aws/hooks/ec2.py)\n- [providers/amazon/src/airflow/providers/amazon/aws/hooks/cloud_formation.py](https://github.com/apache/airflow/blob/main/providers/amazon/src/airflow/providers/amazon/aws/hooks/cloud_formation.py)\n- [providers/google/src/airflow/providers/google/event_scheduling/events/pubsub.py](https://github.com/apache/airflow/blob/main/providers/google/src/airflow/providers/google/event_scheduling/events/pubsub.py)\n- [dev/breeze/src/airflow_breeze/prepare_providers/provider_documentation.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/prepare_providers/provider_documentation.py)\n- [dev/breeze/src/airflow_breeze/utils/packages.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/utils/packages.py)\n- [providers/amazon/src/airflow/providers/amazon/get_provider_info.py](https://github.com/apache/airflow/blob/main/providers/amazon/src/airflow/providers/amazon/get_provider_info.py)\n- [airflow-core/src/airflow/utils/db.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/utils/db.py)\n \n\n# Provider生态系统\n\n## 概述\n\nApache Airflow的Provider生态系统是Airflow的核心扩展机制，允许用户通过安装额外的Provider包来集成各种外部服务和平台。每个Provider提供特定的Hook、Operator、Trigger、Sensor和连接类型，使用户能够在DAG中与外部系统进行交互。\n\nProvider作为独立的Python包发布到PyPI，可以通过`pip install apache-airflow-providers-`进行安装。这种模块化设计使得Airflow核心保持精简，同时用户可以根据实际需求选择性地添加所需的集成功能。\n\n## 架构设计\n\n### Provider核心组件\n\n每个Provider包通常包含以下核心组件：\n\n| 组件类型 | 描述 | 用途 |\n|---------|------|------|\n| Hook | 数据连接抽象类 | 提供与外部系统交互的基础接口 |\n| Operator | 任务执行单元 | 定义具体的业务操作逻辑 |\n| Sensor | 外部依赖检查器 | 轮询外部条件直到满足为止 |\n| Trigger | 异步事件触发器 | 支持triggerer组件异步执行 |\n| Connection | 连接配置 | 定义与外部系统的连接参数 |\n\n### 层级架构\n\n```mermaid\ngraph TD\n A[Airflow Core] --> B[Providers Manager]\n B --> C[Provider Package]\n C --> D[Hooks]\n C --> E[Operators]\n C --> F[Sensors]\n C --> G[Triggers]\n D --> H[External Services]\n E --> H\n F --> H\n G --> H\n \n subgraph \"Provider Package Structure\"\n I[get_provider_info.py]\n J[__init__.py]\n K[hooks/*.py]\n L[operators/*.py]\n M[sensors/*.py]\n end\n```\n\n## Hook实现机制\n\nHook是Provider与外部系统交互的基础桥梁。不同Provider的Hook都遵循统一的基类设计规范。\n\n### AWS Hook实现示例\n\n在Amazon Provider中，Hook通过boto3与AWS服务进行交互：\n\n```python\nclass Ec2Hook(AwsBaseHook):\n API_TYPES = frozenset({\"resource_type\", \"client_type\"})\n\n def __init__(self, api_type=\"resource_type\", *args, **kwargs) -> None:\n if api_type not in self.API_TYPES:\n raise AirflowException(\"api_type can only be one of %s\", self.API_TYPES)\n kwargs[api_type] = \"ec2\"\n self._api_type = api_type\n super().__init__(*args, **kwargs)\n```\n\n资料来源：[providers/amazon/src/airflow/providers/amazon/aws/hooks/ec2.py:24-36]()\n\n### 连接类型注册\n\nProvider通过`get_provider_info.py`文件声明其提供的连接类型：\n\n```python\n{\n \"integration-name\": \"AWS EC2\",\n \"external-doc-url\": \"https://aws.amazon.com/ec2/\",\n \"logo\": \"/docs/integration-logos/AWS-EC2_light-bg@4x.png\",\n \"tags\": [\"aws\"],\n}\n```\n\n资料来源：[providers/amazon/src/airflow/providers/amazon/get_provider_info.py:45-52]()\n\n## Provider生命周期管理\n\n### 文档生成流程\n\nProvider的文档通过Breeze工具自动生成，包括README、conf.py等文件：\n\n```python\ndef _generate_docs_conf(context: dict[str, Any], provider_details: ProviderPackageDetails):\n docs_conf_content = render_template(\n template_name=\"conf\",\n context=context,\n extension=\".py\",\n keep_trailing_newline=True,\n )\n docs_conf_path = provider_details.root_provider_path / \"docs\" / \"conf.py\"\n docs_conf_path.write_text(docs_conf_content)\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/prepare_providers/provider_documentation.py:89-97]()\n\n### 版本与依赖管理\n\nProvider的最小Airflow版本依赖通过解析dependencies确定：\n\n```python\ndef get_min_airflow_version(provider_id: str) -> str:\n provider_details = get_provider_details(provider_id=provider_id)\n min_airflow_version = MIN_AIRFLOW_VERSION\n for dependency in provider_details.dependencies:\n if dependency.startswith(\"apache-airflow>=\"):\n current_min_airflow_version = dependency.split(\">=\")[1]\n if \",\" in current_min_airflow_version:\n current_min_airflow_version = current_min_airflow_version.split(\",\")[0]\n if PackagingVersion(current_min_airflow_version) > PackagingVersion(MIN_AIRFLOW_VERSION):\n min_airflow_version = current_min_airflow_version\n return min_airflow_version\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/utils/packages.py:78-91]()\n\n## CLI命令集成\n\nProvider功能通过Airflow CLI暴露，允许用户在命令行执行各种管理操作：\n\n```python\nGroupCommand(\n name=\"providers\",\n help=\"Display providers\",\n subcommands=PROVIDERS_COMMANDS,\n),\n```\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:89-92]()\n\n### Provider相关命令\n\n| 命令 | 功能 |\n|------|------|\n| `airflow providers list` | 列出所有已安装的Provider |\n| `airflow providers links` | 显示Provider提供的链接 |\n| `airflow providers secrets` | 获取secrets后端信息 |\n| `airflow providers executors` | 获取Executor信息 |\n| `airflow providers auth-managers` | 获取认证管理器信息 |\n\n## 默认连接配置\n\nAirflow在初始化数据库时会创建一系列默认连接，这些连接覆盖了常用的外部系统：\n\n| 连接ID | 连接类型 | 默认配置 |\n|--------|----------|----------|\n| facebook_social | facebook_social | Facebook社交登录凭证 |\n| fs_default | fs | 本地文件系统 |\n| ftp_default | ftp | localhost:21 |\n| google_cloud_default | google_cloud_platform | GCP默认项目 |\n| http_default | http | httpbin.org |\n| iceberg_default | iceberg | Iceberg REST服务 |\n\n资料来源：[airflow-core/src/airflow/utils/db.py:180-220]()\n\n## 事件驱动架构\n\n### MessageQueueTrigger集成\n\nProvider支持通过`MessageQueueTrigger`实现事件驱动的任务执行：\n\n```python\nclass GooglePubSubEvent(Protocol):\n scheme = \"google+pubsub\"\n\n def trigger_class(self) -> type[BaseEventTrigger]:\n return PubsubPullTrigger\n```\n\n资料来源：[providers/google/src/airflow/providers/google/event_scheduling/events/pubsub.py:52-57]()\n\n### 异步Trigger架构\n\n```mermaid\nsequenceDiagram\n DAG Task ->> Trigger: 创建Trigger实例\n Trigger ->> MessageQueue: 订阅消息队列\n MessageQueue -->> Trigger: 事件到达\n Trigger ->> Triggerer: 触发条件满足\n Triggerer ->> DAG Task: 任务执行完成\n```\n\n## Provider发现机制\n\n### 自动注册流程\n\n当Airflow启动时，Providers Manager自动扫描并加载所有已安装的Provider：\n\n```mermaid\ngraph LR\n A[启动Airflow] --> B[扫描Provider包]\n B --> C[加载Hook]\n B --> D[加载Operator]\n B --> E[加载Sensor]\n B --> F[注册Connection类型]\n C --> G[注册到UI]\n D --> G\n E --> G\n F --> G\n```\n\n## 主流Provider一览\n\n### Amazon Provider (apache-airflow-providers-amazon)\n\n提供与AWS服务的深度集成，包括：\n\n- **计算服务**：EC2、Lambda、ECS\n- **数据服务**：Glue、S3、Redshift、Athena\n- **编排服务**：Step Functions、CloudFormation\n- **机器学习**：SageMaker、Bedrock\n\n资料来源：[providers/amazon/src/airflow/providers/amazon/aws/hooks/cloud_formation.py:18-25]()\n\n### Google Provider (apache-airflow-providers-google)\n\n集成Google Cloud Platform服务，包括BigQuery、GCS、Cloud Run等。\n\n### Apache Kafka Provider\n\n提供Kafka消息队列的Hook和Operator支持，用于流数据处理场景。\n\n## 总结\n\nProvider生态系统是Apache Airflow实现高度可扩展性的核心机制。通过标准化的组件接口、统一的生命周期管理和灵活的CLI集成，Provider使得Airflow能够优雅地连接各种外部系统。用户可以根据工作需求选择性地安装Provider，实现与云服务商、数据库、消息队列等数十种外部平台的深度集成。\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 项目说明书",
"目录",
"Airflow简介与核心概念",
"概述",
"核心架构",
"DAG有向无环图",
"任务与任务实例",
"执行器类型",
"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": "120dbed3462cedcb980aac022c587ba434249eb1",
"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- 文件总数：11889\n- 重要文件覆盖：40/11889\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）： B[Scheduler]\n B --> C[Executor]\n C --> D[Worker]\n D --> E[Metadata Database]\n B --> E\n F[Web Server] --> E\n G[用户通过UI/API] --> F\n```\n\n## DAG有向无环图\n\nDAG（Directed Acyclic Graph）是Airflow的核心概念，代表工作流的结构定义。\n\n### DAG定义\n\n```python\nfrom airflow import DAG\nfrom datetime import datetime\n\nwith DAG(\n dag_id='my_first_dag',\n start_date=datetime(2024, 1, 1),\n schedule='@daily',\n catchup=False\n) as dag:\n task1 = BashOperator(task_id='task_1', bash_command='echo Hello')\n task2 = BashOperator(task_id='task_2', bash_command='echo World')\n task1 >> task2\n```\n\n资料来源：[airflow-core/src/airflow/models/dag.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/dag.py)\n\n### DAG属性\n\n| 属性 | 类型 | 描述 |\n|------|------|------|\n| dag_id | str | DAG的唯一标识符 |\n| start_date | datetime | DAG开始日期 |\n| schedule_interval | str/timedelta | 调度间隔 |\n| catchup | bool | 是否补跑历史数据 |\n| max_active_runs | int | 最大同时运行数 |\n| is_paused | bool | DAG是否暂停 |\n\n## 任务与任务实例\n\n### 任务类型\n\nAirflow支持多种任务类型：\n\n| 任务类型 | 说明 |\n|----------|------|\n| BashOperator | 执行Bash命令 |\n| PythonOperator | 执行Python函数 |\n| Sensor | 等待特定条件满足 |\n| TaskGroup | 任务组容器 |\n\n资料来源：[airflow-core/src/airflow/models/taskinstance.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/taskinstance.py)\n\n### 任务实例状态\n\n```mermaid\nstateDiagram-v2\n [*] --> queued: 任务创建\n queued --> scheduled: Scheduler调度\n scheduled --> running: Worker接收\n running --> success: 执行成功\n running --> failed: 执行失败\n running --> upstream_failed: 上游任务失败\n success --> [*]\n failed --> [*]\n upstream_failed --> [*]\n```\n\n资料来源：[airflow-core/src/airflow/_shared/state/__init__.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/_shared/state/__init__.py)\n\n## 执行器类型\n\nAirflow支持多种执行器，用于在不同环境中执行任务：\n\n| 执行器 | 说明 | 适用场景 |\n|--------|------|----------|\n| LocalExecutor | 本地并行执行 | 开发/测试环境 |\n| SequentialExecutor | 顺序执行 | 单任务场景 |\n| CeleryExecutor | 分布式执行 | 生产环境大规模任务 |\n| KubernetesExecutor | K8s Pod执行 | 云原生环境 |\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## CLI命令行接口\n\nAirflow提供丰富的CLI命令用于管理DAG和任务：\n\n| 命令 | 功能 |\n|------|------|\n| airflow dags list | 列出所有DAG |\n| airflow dags list-runs | 列出DAG运行记录 |\n| airflow tasks list | 列出DAG中的任务 |\n| airflow tasks test | 测试单个任务 |\n| airflow connections list | 列出连接 |\n| airflow variables list | 列出变量 |\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### 常用命令示例\n\n```bash\n# 列出所有DAG\nairflow dags list\n\n# 触发DAG手动运行\nairflow dags trigger my_dag_id\n\n# 暂停/恢复DAG\nairflow dags pause my_dag_id\nairflow dags unpause my_dag_id\n\n# 查看任务实例状态\nairflow tasks list my_dag_id\n```\n\n## 连接与变量\n\n### 连接管理\n\nAirflow提供连接（Connection）功能用于存储外部系统访问凭证：\n\n```python\nfrom airflow.models import Connection\nimport json\n\nconn = Connection(\n conn_id='my_postgres_conn',\n conn_type='postgres',\n host='localhost',\n schema='airflow_db',\n login='user',\n password='password',\n port=5432\n)\n```\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### 支持的连接类型\n\n| 连接类型 | 说明 |\n|----------|------|\n| postgres | PostgreSQL数据库 |\n| mysql | MySQL数据库 |\n| google_cloud_platform | GCP云平台 |\n| http | HTTP连接 |\n| ssh | SSH连接 |\n| s3 | AWS S3存储 |\n\n## 配置管理\n\n### airflow.cfg主要配置项\n\n| 配置节 | 配置项 | 说明 |\n|--------|--------|------|\n| core | dags_folder | DAG文件存放路径 |\n| core | executor | 执行器类型 |\n| core | catchup_by_default | 默认是否补跑 |\n| scheduler | num_runs | 调度器循环次数 |\n| webserver | web_server_host | Web服务器地址 |\n| database | sql_alchemy_conn | 数据库连接字符串 |\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## 工作流执行流程\n\n```mermaid\ngraph LR\n A1[DAG定义加载] --> A2[解析DAG结构]\n A2 --> A3[Scheduler创建DAG Run]\n A3 --> A4[任务排队]\n A4 --> A5[Executor分发任务]\n A5 --> A6[Worker执行任务]\n A6 --> A7[更新任务状态]\n A7 --> A8[记录到元数据库]\n A8 --> A9[Web UI展示状态]\n```\n\n## 最佳实践\n\n### DAG编写规范\n\n1. **任务唯一性**：每个任务的task_id在DAG内必须唯一\n2. **正确设置start_date**：避免使用动态时间作为start_date\n3. **合理的retry配置**：为关键任务配置重试策略\n4. **使用描述性命名**：使用清晰的DAG和任务命名\n\n### 调度配置建议\n\n| 配置项 | 建议值 | 说明 |\n|--------|--------|------|\n| catchup | False | 生产环境建议关闭补跑 |\n| max_active_runs | 1-5 | 根据任务复杂度调整 |\n| schedule_interval | @daily/@hourly | 根据业务需求选择 |\n| concurrency | 16-32 | 根据Worker能力设置 |\n\n## 总结\n\nApache Airflow作为强大的工作流编排平台，提供了完整的DAG定义、调度执行、监控告警等功能。理解其核心概念（DAG、Task、Executor、Connection）是有效使用Airflow的基础。通过合理的配置和最佳实践，可以构建稳定可靠的数据管道和工作流系统。\n\n---\n\n\n\n## 快速开始与安装指南\n\n### 相关页面\n\n相关主题：[Airflow简介与核心概念](#intro), [容器化与Kubernetes部署](#deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [INSTALLING.md](https://github.com/apache/airflow/blob/main/INSTALLING.md)\n- [Dockerfile](https://github.com/apache/airflow/blob/main/Dockerfile)\n- [Dockerfile.ci](https://github.com/apache/airflow/blob/main/Dockerfile.ci)\n- [airflow-core/src/airflow/example_dags/tutorial.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/example_dags/tutorial.py)\n- [generated/PYPI_README.md](https://github.com/apache/airflow/blob/main/generated/PYPI_README.md)\n- [airflow-core/src/airflow/_vendor/README.md](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/_vendor/README.md)\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- [dev/breeze/src/airflow_breeze/commands/production_image_commands.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/production_image_commands.py)\n \n\n# 快速开始与安装指南\n\nApache Airflow 是一个开源的工作流编排平台，用于编程创建、调度和监控批处理工作流。本指南将帮助您快速上手安装和配置 Airflow。\n\n## 系统要求\n\n在安装 Apache Airflow 之前，请确保您的系统满足以下基本要求：\n\n| 要求项 | 最低版本 | 说明 |\n|--------|----------|------|\n| Python | 3.9+ | Airflow 核心功能需要 |\n| pip | 最新版本 | Python 包管理器 |\n| 操作系统 | Linux, macOS, Windows (WSL2) | 生产环境推荐使用 Linux |\n| 数据库 | SQLite 3.15+, PostgreSQL 14+, MySQL 8.0+ | 元数据库存储 |\n| 内存 | 4GB RAM | 最小需求，生产环境更高 |\n\n资料来源：[INSTALLING.md:1-50](https://github.com/apache/airflow/blob/main/INSTALLING.md)\n\n## 安装方式概览\n\nAirflow 支持多种安装方式，您可以根据实际需求选择合适的方案：\n\n```mermaid\ngraph TD\n A[安装 Airflow] --> B{使用场景}\n B -->|快速测试| C[pip 直接安装]\n B -->|容器化部署| D[Docker 镜像]\n B -->|深度开发| E[从源码编译]\n C --> F[使用约束文件安装]\n D --> G[官方镜像或自定义]\n E --> H[Breeze 开发环境]\n```\n\n资料来源：[generated/PYPI_README.md:1-30](https://github.com/apache/airflow/blob/main/generated/PYPI_README.md)\n\n## 使用 pip 安装\n\n### 基础安装\n\n使用 pip 安装 Airflow 的标准方式是通过 pip install 命令配合约束文件：\n\n```bash\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\n约束文件确保所有依赖项的版本兼容，避免因依赖冲突导致的安装失败。约束文件根据 Python 版本不同而有所区别。\n\n资料来源：[INSTALLING.md:50-80](https://github.com/apache/airflow/blob/main/INSTALLING.md)\n\n### 安装额外依赖\n\nAirflow 提供了丰富的额外依赖包（extras），可按需安装：\n\n```bash\n# 安装包含 PostgreSQL 和 Google Cloud 支持的版本\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常用额外依赖包包括：\n\n| 额外包名 | 说明 |\n|----------|------|\n| postgres | PostgreSQL 数据库支持 |\n| mysql | MySQL 数据库支持 |\n| google | Google Cloud Platform 集成 |\n| amazon | AWS 集成 |\n| kubernetes | Kubernetes Executor 支持 |\n| sentry | Sentry 错误追踪集成 |\n\n资料来源：[generated/PYPI_README.md:40-60](https://github.com/apache/airflow/blob/main/generated/PYPI_README.md)\n\n### 供应商包安装\n\n除了核心 Airflow 包外，您还可以单独安装各种供应商（Provider）包：\n\n```bash\n# 从 PyPI 安装供应商包\npip install apache-airflow-providers-google\n\n# 从源码安装供应商包\npip install /path/to/apache-airflow-providers-google*.whl\n```\n\n安装后需要验证文件完整性：\n\n```bash\nshasum -a 512 package-name-version.tar.gz | diff - package-name-version.tar.gz.sha512\n```\n\n资料来源：[devel-common/src/sphinx_exts/includes/installing-providers-from-sources.rst:1-50](https://github.com/apache/airflow/blob/main/devel-common/src/sphinx_exts/includes/installing-providers-from-sources.rst)\n\n## Docker 安装\n\n### 官方镜像\n\nAirflow 提供了官方 Docker 镜像，可以快速启动完整的工作环境：\n\n```bash\n# 拉取最新稳定版镜像\ndocker pull apache/airflow:latest\n\n# 使用 Celery Executor 启动\ndocker run -d -p 8080:8080 \\\n -e AIRFLOW__DATABASE__SQL_ALCHEMY_CONN=postgresql+psycopg2://user:pass@host/db \\\n apache/airflow:latest\n```\n\n资料来源：[Dockerfile:1-30](https://github.com/apache/airflow/blob/main/Dockerfile)\n\n### Docker Compose 方式\n\n生产环境推荐使用 Docker Compose 进行部署，Airflow 项目提供了标准化的 docker-compose.yaml：\n\n```yaml\nversion: '3'\nservices:\n postgres:\n image: postgres:13\n environment:\n POSTGRES_USER: airflow\n POSTGRES_PASSWORD: airflow\n POSTGRES_DB: airflow\n \n airflow-webserver:\n image: ${AIRFLOW_IMAGE_NAME:-apache/airflow:latest}\n command: webserver\n ports:\n - \"8080:8080\"\n depends_on:\n - postgres\n```\n\n### 构建自定义镜像\n\n使用 Breeze 工具构建生产镜像：\n\n```bash\n# 使用 breeze 构建生产镜像\nbreeze prod-image build \\\n --installation-method sources \\\n --python 3.10 \\\n --debian-version bullseye\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/production_image_commands.py:1-50](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/production_image_commands.py)\n\n## 从源码安装\n\n### 克隆仓库\n\n```bash\ngit clone https://github.com/apache/airflow.git\ncd airflow\n```\n\n### 使用 Breeze 开发环境\n\nBreeze 是 Airflow 官方提供的开发环境管理工具，提供完整的开发、测试和构建体验：\n\n```bash\n# 进入 breeze shell\n./breeze shell\n\n# 运行测试\n./breeze testing python --test-type unit-tests --package-filter airflow-core\n```\n\nBreeze 使用 Docker 容器化方式，确保开发环境与生产环境的一致性。\n\n资料来源：[airflow-core/src/airflow/_vendor/README.md:1-20](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/_vendor/README.md)\n\n### 编译分发包\n\n构建 Airflow 分发包：\n\n```bash\n# 使用 Breeze 构建 sdist 或 wheel 包\nbreeze release-management build-rc \\\n --airflow-constraints-mode=\"constraints\" \\\n --distribution-format both\n```\n\n编译后的包位于 `dist/` 目录下。\n\n## 初始化数据库\n\n安装完成后，需要初始化 Airflow 的元数据库：\n\n```bash\n# 初始化数据库\nairflow db init\n\n# 创建管理员用户\nairflow users create \\\n --username admin \\\n --firstname Admin \\\n --lastname User \\\n --role Admin \\\n --email admin@example.com\n```\n\n## 启动 Airflow\n\n### Web 服务器\n\n```bash\nairflow webserver --port 8080\n```\n\n### 调度器\n\n在另一个终端启动调度器：\n\n```bash\nairflow scheduler\n```\n\n### 独立模式\n\n对于快速测试，可以使用独立模式：\n\n```bash\nairflow standalone\n```\n\n该命令会启动一个包含 Web 服务器和调度器的单进程环境。\n\n## 验证安装\n\n### 运行示例 DAG\n\nAirflow 自带多个示例 DAG，可用于验证安装：\n\n```python\nfrom airflow import DAG\nfrom airflow.operators.bash import BashOperator\nfrom datetime import datetime\n\nwith DAG('example_dag', start_date=datetime(2024, 1, 1)) as dag:\n t1 = BashOperator(\n task_id='print_date',\n bash_command='date'\n )\n```\n\n资料来源：[airflow-core/src/airflow/example_dags/tutorial.py:1-40](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/example_dags/tutorial.py)\n\n### 检查状态\n\n```bash\n# 查看 Airflow 版本\nairflow version\n\n# 查看已加载的连接\nairflow connections list\n\n# 查看已安装提供程序\nairflow providers list\n```\n\n## 快速安装流程图\n\n```mermaid\ngraph TD\n A[开始安装] --> B{选择安装方式}\n B -->|pip| C[安装 Python 依赖]\n B -->|Docker| D[安装 Docker]\n B -->|源码| E[克隆代码仓库]\n C --> F[初始化数据库]\n D --> G[拉取镜像]\n E --> H[安装依赖]\n F --> I[启动服务]\n G --> I\n H --> I\n I --> J[创建管理员账户]\n J --> K[访问 Web UI]\n K --> L[运行示例 DAG]\n```\n\n## 常见问题排查\n\n### 依赖冲突\n\n如果遇到依赖冲突问题，确保使用正确的约束文件：\n\n```bash\npip install apache-airflow== \\\n --constraint \"https://raw.githubusercontent.com/apache/airflow/constraints-/constraints-.txt\"\n```\n\n### 数据库连接问题\n\n检查数据库连接字符串配置：\n\n```ini\n[database]\nsql_alchemy_conn = postgresql+psycopg2://user:password@localhost/airflow\n```\n\n### 端口占用\n\n如果 8080 端口被占用，可更换端口：\n\n```bash\nairflow webserver --port 8888\n```\n\n## 后续步骤\n\n安装成功后，建议进行以下操作：\n\n1. **配置连接**：设置数据库、API 密钥等连接信息\n2. **配置 Executor**：根据需求选择 Executor 类型（Local、Celery、Kubernetes）\n3. **配置告警**：设置邮件或其他告警渠道\n4. **学习 DAG 编写**：参考官方教程编写第一个生产 DAG\n5. **了解最佳实践**：学习 Airflow 的安全和性能最佳实践\n\n## 相关文档链接\n\n- 官方安装文档：https://airflow.apache.org/docs/apache-airflow/stable/installation/index.html\n- Docker 镜像：https://github.com/apache/airflow/blob/main/Dockerfile\n- Breeze 开发工具：https://github.com/apache/airflow/blob/main/dev/breeze/README.md\n\n---\n\n\n\n## 系统架构详解\n\n### 相关页面\n\n相关主题：[核心组件详解](#components), [执行器类型与选择](#executors)\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/dag_processing/manager.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/dag_processing/manager.py)\n- [airflow-core/src/airflow/dag_processing/processor.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/dag_processing/processor.py)\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/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/_shared/observability/metrics/metrics_template.yaml](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/_shared/observability/metrics/metrics_template.yaml)\n \n\n# 系统架构详解\n\n## 1. 概述\n\nApache Airflow 是一个开源的工作流编排平台，采用分布式架构设计，支持大规模任务调度与执行。Airflow 3.0 在架构上进行了重大升级，引入了更加模块化的组件设计，将 DAG 处理、任务调度和执行进行了清晰的分离。\n\n核心架构由以下几个主要组件构成：\n\n- **Web服务器**：提供用户界面\n- **调度器（Scheduler）**：负责 DAG 调度和任务分发\n- **DAG处理器（DagFileProcessorManager）**：负责解析和验证 DAG 文件\n- **执行器（Executor）**：负责实际任务执行\n- **元数据库**：存储 DAG 定义、任务状态和执行历史\n\n资料来源：[airflow-core/docs/img/diagram_basic_airflow_architecture.py:1-50]()\n\n## 2. 核心组件架构\n\n### 2.1 DAG 处理系统\n\nDAG 处理系统是 Airflow 的核心子系统之一，负责从文件系统读取、解析和验证 DAG 定义。\n\n```mermaid\ngraph TD\n A[DAG 文件目录] --> B[DagFileProcessorManager]\n B --> C[文件扫描器]\n B --> D[文件处理器池]\n C -->|检测文件变更| D\n D --> E[Processor Subprocess]\n E --> F[DAG 对象]\n F --> G[Import Timeout Manager]\n G --> H[数据库更新]\n \n style B fill:#e1f5fe\n style D fill:#fff3e0\n style E fill:#e8f5e9\n```\n\n**关键组件**：\n\n| 组件 | 文件位置 | 职责 |\n|------|---------|------|\n| DagFileProcessorManager | `dag_processing/manager.py` | 管理 DAG 文件处理的生命周期 |\n| DagFileProcessor | `dag_processing/processor.py` | 执行单个 DAG 文件的解析 |\n| ImportTimeoutManager | `dag_processing/manager.py` | 监控 DAG 导入超时 |\n\n资料来源：[airflow-core/src/airflow/dag_processing/manager.py:1-100]()\n\n#### 2.1.1 DAG 文件扫描\n\nDagFileProcessorManager 维护一个文件扫描循环，定期检查配置的 DAG 目录中的文件变更：\n\n```python\n# 扫描间隔配置\nprocessor_poll_interval -> scheduler_idle_sleep_time\n```\n\n默认配置变更说明：\n\n| 旧配置项 | 新配置项 | 说明 |\n|---------|---------|------|\n| `scheduler.processor_poll_interval` | `scheduler.scheduler_idle_sleep_time` | 调度器空闲休眠时间 |\n| `scheduler.create_cron_data_intervals` | `scheduler.create_cron_data_intervals` | 默认值由 True 改为 False |\n| `scheduler.create_delta_data_intervals` | `scheduler.create_delta_data_intervals` | 默认值由 True 改为 False |\n\n资料来源：[airflow-core/src/airflow/cli/commands/config_command.py:30-80]()\n\n### 2.2 调度器系统\n\n调度器是 Airflow 的大脑，负责决定何时运行哪些任务。\n\n```mermaid\ngraph TD\n A[SchedulerJobRunner] --> B[关键区域锁]\n B --> C{获取锁}\n C -->|成功| D[处理过期 DAG]\n C -->|失败| E[等待]\n D --> F[调度待处理任务]\n F --> G[发送任务到执行器]\n G --> H[更新任务状态]\n H --> I[释放锁]\n I --> B\n \n style A fill:#fff8e1\n style B fill:#ffecb3\n style G fill:#c8e6c9\n```\n\n#### 2.2.1 调度器关键流程\n\n1. **获取关键区域锁**：确保多调度器环境下的安全性\n2. **处理过期 DAG**：清理陈旧的 DAG 数据\n3. **调度任务**：根据依赖关系和执行时间分发任务\n4. **孤儿任务处理**：检测并处理孤立任务\n\n**调度器指标**：\n\n| 指标名称 | 类型 | 说明 |\n|---------|------|------|\n| `scheduler.critical_section_busy` | counter | 关键区域锁竞争次数 |\n| `scheduler.orphaned_tasks.adopted` | counter | 被采纳的孤儿任务数 |\n| `scheduler.orphaned_tasks.cleared` | counter | 被清理的孤儿任务数 |\n| `scheduler.tasks.killed_externally` | counter | 外部杀死任务数 |\n\n资料来源：[airflow-core/src/airflow/_shared/observability/metrics/metrics_template.yaml:50-80]()\n\n### 2.3 任务执行系统\n\n任务执行通过 Task SDK 实现，采用远程进程通信模式。\n\n```mermaid\ngraph LR\n A[任务实例] --> B[任务状态存储]\n A --> C[任务参数]\n A --> D[执行上下文]\n \n B -.->|get| E[...]\n B -.->|set| F[...]\n B -.->|delete| G[...]\n \n style A fill:#e3f2fd\n style B fill:#bbdefb\n```\n\n#### 2.3.1 任务状态管理\n\n任务状态通过 TaskState 类进行管理，提供键值对存储：\n\n```python\nclass TaskState:\n def get(self, key: str) -> str | None\n def set(self, key: str, value: str) -> None\n def delete(self, key: str) -> None\n def clear(self, all_map_indices: bool = False) -> None\n```\n\n| 方法 | 功能 | 说明 |\n|-----|------|------|\n| `get(key)` | 获取值 | 返回存储的值，键不存在返回 None |\n| `set(key, value)` | 设置值 | 写入或覆盖指定键的值 |\n| `delete(key)` | 删除值 | 删除单个键，键不存在无操作 |\n| `clear()` | 清空 | 删除所有 map indices 的状态 |\n\n资料来源：[task-sdk/src/airflow/sdk/execution_time/context.py:80-120]()\n\n## 3. CLI 命令系统\n\nAirflow 提供丰富的命令行接口，用于管理和操作各个组件。\n\n### 3.1 命令分类\n\n| 命令组 | 功能 |\n|-------|------|\n| `airflow dags` | DAG 管理（backfill, list-runs, pause, unpause, test） |\n| `airflow tasks` | 任务操作（run, failed-deps, render, test） |\n| `airflow connections` | 连接管理 |\n| `airflow providers` | 提供者信息 |\n| `airflow config` | 配置查看 |\n| `airflow db-manager` | 数据库管理器 |\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:50-150]()\n\n### 3.2 任务命令详解\n\n| 命令 | 功能 | 关键参数 |\n|------|-----|---------|\n| `airflow tasks run` | 运行单个任务 | `--dag-id`, `--task-id`, `--logical-date-or-run-id` |\n| `airflow tasks render` | 渲染任务模板 | `--dag-id`, `--task-id`, `--logical-date-or-run-id` |\n| `airflow tasks test` | 测试任务（不记录状态） | `--dag-id`, `--task-id`, `--logical-date-or-run-id` |\n| `airflow tasks failed-deps` | 检查未满足依赖 | `--dag-id`, `--task-id`, `--logical-date-or-run-id` |\n\n**测试命令特点**：\n- 不检查依赖关系\n- 不记录状态到数据库\n- 适用于快速验证任务逻辑\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:150-200]()\n\n## 4. 配置系统\n\n### 4.1 关键配置变更（Airflow 2.x → 3.0）\n\n| 配置项 | 变更类型 | 旧值 | 新值 |\n|-------|---------|-----|------|\n| `scheduler.catchup_by_default` | 默认值变更 | True | **False** |\n| `scheduler.create_cron_data_intervals` | 默认值变更 | True | False |\n| `scheduler.create_delta_data_intervals` | 默认值变更 | True | False |\n| `scheduler.processor_poll_interval` | 重命名 | - | `scheduler_idle_sleep_time` |\n| `scheduler.deactivate_stale_dags_interval` | 重命名 | - | `parsing_cleanup_interval` |\n| `scheduler.statsd_on` | 重命名 | - | `metrics.statsd_on` |\n| `scheduler.max_threads` | 重命名 | - | `dag_processor.parsing_processes` |\n\n资料来源：[airflow-core/src/airflow/cli/commands/config_command.py:20-70]()\n\n### 4.2 DAG Processing 配置\n\n```yaml\ndag_processing:\n manager_stalls: Number of stalled DagFileProcessorManager\n processor_timeouts: DAG 处理超时次数\n dag_file_refresh_error: DAG 文件加载失败次数\n```\n\n## 5. 执行架构图\n\n```mermaid\ngraph TD\n subgraph Web层\n UI[Web UI] \n end\n \n subgraph 调度层\n Scheduler[Scheduler Job Runner]\n DagProcessor[DagFileProcessorManager]\n ImportTimeout[Import Timeout Manager]\n end\n \n subgraph 执行层\n Executor[Executor]\n Worker[Worker Process]\n TaskRunner[Task Runner]\n end\n \n subgraph 存储层\n DB[(Metadata DB)]\n DAGFS[DAG File System]\n end\n \n UI <-->|API| Scheduler\n Scheduler <-->|调度决策| Executor\n DagProcessor <-->|解析DAG| DAGFS\n DagProcessor <-->|写入| DB\n Executor <-->|分发任务| Worker\n Worker <-->|执行| TaskRunner\n TaskRunner <-->|状态更新| DB\n \n style Scheduler fill:#ff9800,color:#fff\n style DagProcessor fill:#4caf50,color:#fff\n style Executor fill:#2196f3,color:#fff\n```\n\n## 6. 监控指标\n\nAirflow 提供全面的监控指标体系：\n\n### 6.1 DAG 处理指标\n\n| 指标 | 描述 |\n|------|------|\n| `dag_processing.manager_stalls` | DagFileProcessorManager 停滞次数 |\n| `dag_file_refresh_error` | DAG 文件刷新错误数 |\n| `dag_file_processor_timeouts` | DAG 文件处理器超时（已废弃） |\n\n### 6.2 调度器指标\n\n| 指标 | 描述 |\n|------|------|\n| `scheduler.critical_section_busy` | 调度器关键区域忙次数 |\n| `scheduler.orphaned_tasks.adopted` | 被采纳的孤儿任务 |\n| `scheduler.orphaned_tasks.cleared` | 被清理的孤儿任务 |\n| `scheduler.tasks.killed_externally` | 外部杀死任务数 |\n\n### 6.3 任务执行指标\n\n| 指标 | 描述 |\n|------|------|\n| `ti.start` | 任务启动次数 |\n| `ti.finish` | 任务完成次数 |\n\n资料来源：[airflow-core/src/airflow/_shared/observability/metrics/metrics_template.yaml:30-100]()\n\n## 7. 总结\n\nApache Airflow 采用分布式架构设计，核心组件包括：\n\n1. **DagFileProcessorManager**：负责 DAG 文件的解析和验证\n2. **SchedulerJobRunner**：负责任务的调度和分发\n3. **Executor**：负责实际任务执行\n4. **Task SDK**：提供任务运行时的上下文管理\n\n各组件通过消息队列和数据库进行通信，确保系统的高可用性和可扩展性。\n\n---\n\n\n\n## 核心组件详解\n\n### 相关页面\n\n相关主题：[系统架构详解](#architecture), [数据流转与交换机制](#data-flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [airflow-core/src/airflow/models/dag.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/dag.py)\n- [airflow-core/src/airflow/models/dagrun.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/dagrun.py)\n- [airflow-core/src/airflow/models/connection.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/connection.py)\n- [airflow-core/src/airflow/models/variable.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/variable.py)\n- [airflow-core/src/airflow/models/pool.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/pool.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/cli/commands/config_command.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/commands/config_command.py)\n\n \n\n# 核心组件详解\n\n## 概述\n\nApache Airflow 是一个开源的工作流编排平台，其核心组件构成了整个任务调度和执行的基础架构。这些组件包括DAG（有向无环图）、DAGRun（DAG运行实例）、Connection（连接）、Variable（变量）和Pool（资源池）。理解这些核心组件对于深入掌握Airflow的工作原理至关重要。\n\n## DAG 模型\n\n### 什么是 DAG\n\nDAG（Directed Acyclic Graph，有向无环图）是Airflow中工作流定义的核心抽象。它代表了一组需要执行的任务以及任务之间的依赖关系。\n\n### DAG 关键属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| dag_id | str | DAG的唯一标识符 |\n| description | str | DAG的描述信息 |\n| schedule_interval | - | 调度间隔配置 |\n| start_date | datetime | DAG开始执行的日期 |\n| end_date | datetime | DAG结束执行的日期（可选） |\n| catchup | bool | 是否补跑历史数据 |\n| max_active_runs | int | 最大并发运行数 |\n| concurrency | int | 最大并发任务数 |\n| is_paused | bool | DAG是否暂停 |\n\n### DAG 的生命周期\n\n```mermaid\ngraph LR\n A[创建DAG] --> B[DAG解析]\n B --> C[调度器调度]\n C --> D[创建DAGRun]\n D --> E[执行任务]\n E --> F[DAGRun完成]\n F --> G{是否继续调度}\n G -->|是| C\n G -->|否| H[DAG结束]\n```\n\n## DAGRun 模型\n\n### 概述\n\nDAGRun是DAG的一次具体执行实例。每次触发或调度DAG时，都会创建一个DAGRun实例来跟踪该次执行的状态。\n\n### DAGRun 状态\n\n| 状态 | 说明 |\n|------|------|\n| QUEUED | 排队等待执行 |\n| RUNNING | 正在执行 |\n| SUCCESS | 成功完成 |\n| FAILED | 执行失败 |\n\n### DAGRun 类型\n\n| 类型 | 说明 |\n|------|------|\n| SCHEDULED | 由调度器正常调度触发 |\n| MANUAL | 手动触发的运行 |\n| BACKFILL | 回填作业执行 |\n\n### 核心属性\n\nDAGRun包含以下关键属性用于追踪执行信息：\n\n- **run_id**: 每次运行的唯一标识\n- **state**: 当前运行状态\n- **execution_date**: 执行日期\n- **start_date**: 实际开始时间\n- **end_date**: 结束时间\n- **triggering_user_name**: 触发运行的用户名\n\n## Connection 连接管理\n\n### 连接类型\n\nAirflow支持多种连接类型，用于与外部系统进行交互：\n\n| 连接类型 | 说明 | 默认配置 |\n|----------|------|----------|\n| postgres | PostgreSQL数据库 | 需要host、schema、login、password |\n| mysql | MySQL数据库 | 需要host、schema、login、password |\n| google_cloud_platform | GCP服务 | 使用默认schema |\n| http | HTTP端点 | 需要host地址 |\n| ftp | FTP服务器 | 需要host、login、password |\n| ssh | SSH连接 | 需要host、login、key_file |\n| redis | Redis缓存 | 需要host、port |\n| fs | 文件系统 | 需要path配置 |\n| hive_cli | Hive CLI | 需要host、port、schema |\n| hiveserver2 | HiveServer2 | 需要host、schema、port |\n| gremlin | Gremlin图数据库 | 需要host、port |\n| facebook_social | Facebook社交 | 需要app_id、app_secret等 |\n| iceberg | Iceberg表格式 | 需要host配置 |\n\n### 连接创建示例\n\n```python\nConnection(\n conn_id=\"gcp_default\",\n conn_type=\"google_cloud_platform\",\n schema=\"default\"\n)\n```\n\n## Variable 变量管理\n\n### 变量概述\n\nVariable用于存储和检索Airflow中的键值对配置信息，可在DAG和任务之间共享。\n\n### 变量操作\n\n| 操作 | 说明 | 命令 |\n|------|------|------|\n| list | 列出所有变量 | `airflow variables list` |\n| get | 获取变量值 | `airflow variables get ` |\n| set | 设置变量 | `airflow variables set ` |\n| delete | 删除变量 | `airflow variables delete ` |\n| import | 批量导入 | `airflow variables import ` |\n| export | 批量导出 | `airflow variables export ` |\n\n### JSON序列化支持\n\nVariable支持JSON序列化，可存储复杂数据结构：\n\n```bash\nairflow variables set my_json '{\"key\": \"value\", \"list\": [1, 2, 3]}'\n```\n\n## Pool 资源池管理\n\n### 池的作用\n\nPool用于限制同时执行的任务数量，控制资源使用并管理并发度。\n\n### 内置默认池\n\n| 池名称 | 默认槽位数 | 说明 |\n|--------|------------|------|\n| default_pool | 根据配置 | 用于未指定池的任务 |\n\n### 槽位管理\n\n```mermaid\ngraph TB\n A[任务请求] --> B{槽位可用?}\n B -->|是| C[分配槽位]\n B -->|否| D[排队等待]\n C --> E[执行任务]\n E --> F[释放槽位]\n D --> G{槽位释放?}\n G -->|是| C\n G -->|否| D\n```\n\n## CLI 命令行接口\n\n### 可用命令组\n\nAirflow提供了丰富的CLI命令用于管理核心组件：\n\n| 命令组 | 说明 | 主要子命令 |\n|--------|------|------------|\n| dag | DAG管理 | list, details, list-runs, pause, unpause, backfill, test |\n| dagrun | 运行管理 | list, trigger, clear |\n| connections | 连接管理 | list, add, delete, edit |\n| variables | 变量管理 | list, get, set, delete, import, export |\n| pools | 池管理 | list, set |\n| config | 配置查看 | list, get, show |\n| providers | 提供者信息 | list, details |\n| assets | 资产管理 | list, details, materialize |\n\n### 常用命令示例\n\n```bash\n# 列出所有DAG\nairflow dags list\n\n# 触发DAG运行\nairflow dags trigger \n\n# 暂停DAG\nairflow dags pause \n\n# 列出所有连接\nairflow connections list\n\n# 导出变量\nairflow variables export variables.json\n```\n\n## 配置变更说明\n\n### Airflow 3.0 配置变化\n\n从Airflow 2.x迁移到3.0时，以下配置项发生了变化：\n\n| 旧配置项 | 新配置项 | 变化类型 |\n|----------|----------|----------|\n| scheduler.catchup_by_default | scheduler.catchup | 默认值改为False |\n| scheduler.create_cron_data_intervals | - | 默认值改为False |\n| scheduler.create_delta_data_intervals | - | 默认值改为False |\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\n### catchup 行为变化\n\n> 在 Airflow 3.0 中，`catchup` 的默认值为 `False`。这意味着未明确设置 `catchup` 参数的 DAG 默认不会进行历史数据补跑。如果DAG依赖补跑行为，需要在 `airflow.cfg` 的 `scheduler` 部分将该配置设置为 `True`。资料来源：[airflow-core/src/airflow/cli/commands/config_command.py]()\n\n## 数据模型关系\n\n```mermaid\nerDiagram\n DAG ||--o{ DAGRun : creates\n DAGRun ||--o{ TaskInstance : contains\n TaskInstance ||--|| Pool : uses\n Connection ||--o{ TaskInstance : referenced_by\n Variable ||--o{ TaskInstance : accessed_by\n \n DAG {\n string dag_id\n string description\n string schedule_interval\n datetime start_date\n boolean is_paused\n }\n \n DAGRun {\n string run_id\n string state\n datetime execution_date\n datetime start_date\n datetime end_date\n }\n \n TaskInstance {\n string task_id\n string state\n datetime start_date\n datetime end_date\n }\n \n Pool {\n string pool\n int slots\n string description\n }\n \n Connection {\n string conn_id\n string conn_type\n string host\n string schema\n }\n \n Variable {\n string key\n string val\n string description\n }\n```\n\n## 安全最佳实践\n\n### 连接凭证管理\n\n1. **使用Fernet加密**: Airflow使用Fernet加密存储敏感连接凭证\n2. **轮换加密密钥**: 定期执行 `airflow rotate-fernet-key` 更新加密密钥\n\n```bash\nairflow rotate-fernet-key\n```\n\n### 敏感信息处理\n\n| 类型 | 存储方式 | 建议 |\n|------|----------|------|\n| 密码 | 加密存储 | 使用变量或连接extra字段 |\n| API密钥 | 加密存储 | 使用Secret Backend |\n| 连接凭证 | 加密存储 | 使用连接管理界面 |\n\n## 总结\n\nApache Airflow的核心组件构成了一个完整的工作流编排系统。DAG作为工作流定义的核心，依赖调度器生成DAGRun实例，而DAGRun则管理具体任务的执行。Connection、Variable和Pool等组件提供了与外部系统交互、配置管理和资源控制的能力。深入理解这些组件及其相互关系，对于熟练使用Airflow进行工作流开发和运维至关重要。\n\n---\n\n\n\n## 执行器类型与选择\n\n### 相关页面\n\n相关主题：[系统架构详解](#architecture), [容器化与Kubernetes部署](#deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\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- [airflow-core/src/airflow/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.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/commands/common_options.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/common_options.py)\n- [dev/breeze/src/airflow_breeze/commands/developer_commands.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/commands/developer_commands.py)\n- [airflow-core/src/airflow/utils/db.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/utils/db.py)\n \n\n# 执行器类型与选择\n\n## 概述\n\n执行器（Executor）是 Apache Airflow 架构中的核心组件，负责实际执行任务实例。每个执行器实现了特定的任务调度和执行策略，从单机的本地执行到分布式的集群环境，Airflow 提供了多种执行器类型以满足不同场景的需求。执行器的选择直接影响工作流的性能、可扩展性和可靠性。\n\n执行器系统遵循统一的接口规范，所有执行器都继承自基础执行器类，定义了任务提交、状态查询、心跳维护等标准方法。资料来源：[airflow-core/src/airflow/executors/executor_loader.py:1-50]()\n\n## 执行器架构\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n DAG[DAG 有向无环图] --> Scheduler[调度器]\n Scheduler --> ExecutorLoader[执行器加载器]\n ExecutorLoader --> Executor[执行器实例]\n Executor --> TaskInstance[任务实例]\n Executor --> Worker[Worker 节点]\n \n Executor --> LocalExecutor[LocalExecutor]\n Executor --> CeleryExecutor[CeleryExecutor]\n Executor --> KubernetesExecutor[KubernetesExecutor]\n Executor --> SequentialExecutor[SequentialExecutor]\n \n LocalExecutor --> LocalWorker[本地进程]\n CeleryExecutor --> CeleryWorker[Celery Worker]\n KubernetesExecutor --> K8sPod[K8s Pod]\n```\n\n### 执行器类型总览\n\n| 执行器类型 | 说明 | 适用场景 | 并发能力 |\n|-----------|------|----------|---------|\n| SequentialExecutor | 顺序执行器 | 开发调试、单节点 | 1 |\n| LocalExecutor | 本地执行器 | 单机生产、小规模任务 | 多进程 |\n| CeleryExecutor | Celery 执行器 | 分布式、跨机器 | 集群规模 |\n| KubernetesExecutor | K8s 执行器 | 云原生、自动扩缩容 | Pod 数量 |\n| LocalKubernetesExecutor | 本地 K8s 执行器 | 测试环境 | 可配置 |\n| CeleryKubernetesExecutor | 混合执行器 | 灵活调度 | 集群规模 |\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:50-80]()\n\n## 执行器加载机制\n\n### 执行器加载器职责\n\n`ExecutorLoader` 是 Airflow 中负责动态加载和解析执行器配置的中央组件。它支持多种执行器配置格式，包括简单的单执行器名称和复杂的团队别名配置。\n\n执行器加载器的主要职责包括：\n\n1. 解析 `airflow.cfg` 中的执行器配置\n2. 验证执行器名称的有效性\n3. 实例化对应的执行器类\n4. 处理执行器别名和团队配置\n\n```python\n# 执行器名称解析核心逻辑\nif module_or_name in CORE_EXECUTOR_NAMES:\n executor_names_per_team.append(\n ExecutorName(\n alias=alias, \n module_path=cls.executors[module_or_name], \n team_name=team_name\n )\n )\n```\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:80-120]()\n\n### 执行器配置格式\n\n执行器配置支持以下几种格式：\n\n```mermaid\ngraph LR\n A[配置文件] --> B[执行器名称]\n B --> C[单执行器]\n B --> D[别名配置]\n B --> E[团队配置]\n \n C --> C1[LocalExecutor]\n C --> C2[CeleryExecutor]\n \n D --> D1[MyAlias:LocalExecutor]\n D1 --> D2[alias=MyAlias
module=LocalExecutor]\n \n E --> E1[team:executor]\n E1 --> E2[team_name=team
executor=executor]\n```\n\n#### 简单配置\n\n```ini\nexecutor = LocalExecutor\n```\n\n#### 别名配置\n\n```ini\nexecutor = MyLocalExecutor:LocalExecutor\n```\n\n格式为 `别名:执行器类型`，其中别名用于日志和监控标识。\n\n#### 团队配置\n\n```ini\n[executors]\nTeamA = TeamA: CeleryExecutor\nTeamB = TeamB: KubernetesExecutor\n```\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:100-150]()\n\n## 核心执行器类型详解\n\n### SequentialExecutor\n\n顺序执行器是最基础的执行器，以单线程顺序方式执行任务。此执行器主要用于以下场景：\n\n- **开发环境**：在没有多进程支持的环境中运行\n- **调试场景**：需要逐个追踪任务执行流程\n- **最小化部署**：资源受限的单机环境\n\n```python\n# SequentialExecutor 核心特性\n- 单进程顺序执行\n- 无并发能力\n- 任务队列单一\n- 无需外部依赖\n```\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:150-180]()\n\n### LocalExecutor\n\n本地执行器在单机环境下提供多进程并发执行能力。它使用 Python 的 `multiprocessing` 模块创建工作进程池，每个工作进程可以并行执行多个任务。\n\n```mermaid\ngraph TD\n LocalExecutor --> Worker1[Worker Process 1]\n LocalExecutor --> Worker2[Worker Process 2]\n LocalExecutor --> WorkerN[Worker Process N]\n \n Worker1 --> Task1[Task Instance]\n Worker1 --> Task2[Task Instance]\n Worker2 --> Task3[Task Instance]\n WorkerN --> Task4[Task Instance]\n \n Worker1 -.-> Queue[任务队列]\n Worker2 -.-> Queue\n WorkerN -.-> Queue\n```\n\n**配置参数**：\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| parallelism | 并行任务数上限 | CPU 核心数 |\n| local_worker_kwargs | 工作进程额外参数 | {} |\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:180-220]()\n\n### CeleryExecutor\n\nCeleryExecutor 是分布式执行器，使用 Celery 作为消息队列来处理跨多台机器的任务分发和执行。Celery 是 Python 生态中成熟的任务队列系统，支持 Redis、RabbitMQ 等多种消息代理。\n\n```mermaid\ngraph TD\n Scheduler[Airflow Scheduler] -->|任务提交| CeleryBroker[Celery Broker
Redis/RabbitMQ]\n CeleryBroker --> Worker1[Celery Worker 1]\n CeleryBroker --> Worker2[Celery Worker 2]\n CeleryBroker --> WorkerN[Celery Worker N]\n \n Worker1 -->|执行结果| ResultBackend[Result Backend]\n Worker2 -->|执行结果| ResultBackend\n WorkerN -->|执行结果| ResultBackend\n \n ResultBackend -->|状态同步| Scheduler\n```\n\n**适用场景**：\n\n- 需要水平扩展的任务处理\n- 跨多台机器的分布式部署\n- 需要任务优先级和重试策略\n- 长时间运行的后台任务\n\n**依赖组件**：\n\n- Celery 消息代理（Redis 或 RabbitMQ）\n- Celery Worker 节点\n- 结果后端（数据库或缓存）\n\n资料来源：[providers/celery/src/airflow/providers/celery/executors/celery_executor.py:1-100]()\n\n### KubernetesExecutor\n\nKubernetesExecutor 是原生运行在 Kubernetes 集群上的执行器，每个任务都在独立的 Pod 中执行。这种设计提供了极佳的隔离性和资源弹性。\n\n```mermaid\ngraph TD\n Scheduler[Scheduler] --> K8sAPI[Kubernetes API]\n K8sAPI --> Pod1[Task Pod 1]\n K8sAPI --> Pod2[Task Pod 2]\n K8sAPI --> PodN[Task Pod N]\n \n Pod1 -->|完成| K8sAPI\n Pod2 -->|完成| K8sAPI\n PodN -->|完成| K8sAPI\n \n K8sAPI --> ConfigMap[ConfigMap
任务定义]\n K8sAPI --> Secret[Secret
连接凭证]\n```\n\n**核心优势**：\n\n| 特性 | 说明 |\n|------|------|\n| 任务隔离 | 每个任务独立 Pod，避免资源冲突 |\n| 自动扩缩容 | 根据任务队列动态创建/销毁 Pod |\n| 资源控制 | 支持 CPU、内存 Limits 和 Requests 配置 |\n| 亲和性 | 支持节点亲和性、污点容忍等调度策略 |\n| 生命周期 | 任务完成即销毁，资源高效利用 |\n\n**配置选项**：\n\n| 参数 | 说明 |\n|------|------|\n| namespace | Kubernetes 命名空间 |\n| parallelism | 最大并发 Pod 数 |\n| worker_pods_creation_batch_size | 批量创建大小 |\n| kube_client_request_args | K8s 客户端参数 |\n\n资料来源：[providers/cncf/kubernetes/src/airflow/providers/cncf/kubernetes/executors/kubernetes_executor.py:1-150]()\n\n## 执行器配置管理\n\n### 配置文件位置\n\n执行器配置通过 `airflow.cfg` 文件管理，主要配置项位于 `[core]` 部分：\n\n```ini\n[core]\nexecutor = LocalExecutor\n```\n\n### Breeze 开发环境配置\n\n在 Airflow Breeze 开发环境中，可以使用统一的命令行选项配置执行器：\n\n```bash\n# 查看执行器列表\nbreeze shell --executor\n\n# 使用指定执行器启动\nbreeze shell --executor KubernetesExecutor\n```\n\n**支持的执行器选项**：\n\n| 选项 | 说明 | 可用值 |\n|------|------|--------|\n| --executor | 执行器类型 | LocalExecutor, CeleryExecutor, KubernetesExecutor 等 |\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/common_options.py:100-150]()\n\n### 执行器别名与团队配置\n\nAirflow 支持通过 `ExecutorLoader` 实现执行器别名和团队级别的配置：\n\n```python\nclass ExecutorName(NamedTuple):\n alias: str | None\n module_path: str\n team_name: str | None\n```\n\n配置示例：\n\n```ini\n[executors]\n# 格式: 别名 = 模块路径\nmy_alias = airflow.executors.local_executor.LocalExecutor\nteam_default = airflow.providers.celery.executors.celery_executor.CeleryExecutor\n```\n\n**配置验证逻辑**：\n\n```python\n# 检查是否为内置执行器名称\nif module_or_name in CORE_EXECUTOR_NAMES:\n executor_names_per_team.append(\n ExecutorName(\n alias=alias, \n module_path=cls.executors[module_or_name], \n team_name=team_name\n )\n )\n# 检查是否为模块路径\nelif \".\" not in module_or_name:\n raise AirflowConfigException(\n \"Incorrectly formatted executor configuration...\"\n )\n```\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:200-260]()\n\n## 执行器选择指南\n\n### 决策流程\n\n```mermaid\ngraph TD\n Start[开始选择执行器] --> Q1{部署规模?}\n \n Q1 -->|单机/开发| Q2{需要并发?}\n Q1 -->|分布式| Q3{K8s 环境?}\n Q1 -->|大规模| Q4{需要灵活调度?}\n \n Q2 -->|是| LocalExecutor\n Q2 -->|否| SequentialExecutor\n \n Q3 -->|是| KubernetesExecutor\n Q3 -->|否| CeleryExecutor\n \n Q4 -->|是| CeleryKubernetesExecutor\n Q4 -->|否| CeleryExecutor\n```\n\n### 场景推荐\n\n| 场景 | 推荐执行器 | 原因 |\n|------|-----------|------|\n| 本地开发调试 | SequentialExecutor | 简单、无依赖 |\n| 单机生产环境 | LocalExecutor | 多进程并发、资源可控 |\n| 小型集群 | CeleryExecutor | 配置简单、成熟稳定 |\n| 云原生/K8s | KubernetesExecutor | 弹性扩缩容、任务隔离 |\n| 混合云环境 | CeleryKubernetesExecutor | 灵活调度、兼容性好 |\n\n### 配置示例\n\n#### 本地执行器配置\n\n```ini\n[core]\nexecutor = LocalExecutor\n\n[local_executor]\nparallelism = 8\n```\n\n#### Celery 执行器配置\n\n```ini\n[core]\nexecutor = CeleryExecutor\n\n[celery]\nbroker_url = redis://redis:6379/0\nresult_backend = redis://redis:6379/1\nworker_concurrency = 16\n```\n\n#### Kubernetes 执行器配置\n\n```ini\n[core]\nexecutor = KubernetesExecutor\n\n[kubernetes]\nnamespace = airflow\nparallelism = 32\n```\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:260-320]()\n\n## 命令行接口\n\n### 查看执行器信息\n\n通过 Airflow CLI 可以查看已配置的执行器信息：\n\n```bash\n# 查看 Airflow 信息（包含执行器）\nairflow info\n\n# 查看提供商执行器列表\nairflow providers executors\n```\n\n**可用的 providers 子命令**：\n\n| 命令 | 说明 |\n|------|------|\n| `providers list` | 列出所有提供商 |\n| `providers executors` | 列出可用的执行器 |\n| `providers details` | 提供商详细信息 |\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:1-100]()\n\n### CLI 配置定义\n\n执行器相关的 CLI 命令在 `cli_config.py` 中定义：\n\n```python\n# 提供商执行器列表命令\nActionCommand(\n name=\"executors\",\n help=\"Get information about executors provided\",\n func=lazy_load_command(\"airflow.cli.commands.provider_command.executors_list\"),\n args=(ARG_OUTPUT, ARG_VERBOSE),\n)\n```\n\n**命令行参数**：\n\n| 参数 | 短标识 | 说明 |\n|------|--------|------|\n| --output | -o | 输出格式（table、json、yaml） |\n| --verbose | -v | 详细输出模式 |\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:100-200]()\n\n## 默认连接配置\n\n执行器运行需要配置相应的连接凭证。Airflow 在初始化数据库时提供默认连接配置：\n\n### 开发环境默认连接\n\n```python\nConnection(\n conn_id=\"fs_default\",\n conn_type=\"fs\",\n extra='{\"path\": \"/\"}',\n)\n\nConnection(\n conn_id=\"google_cloud_default\",\n conn_type=\"google_cloud_platform\",\n schema=\"default\",\n)\n\nConnection(\n conn_id=\"http_default\",\n conn_type=\"http\",\n host=\"https://www.httpbin.org/\",\n)\n```\n\n### 生产环境注意事项\n\n在生产环境中部署时，需要：\n\n1. 配置真实的数据库连接（避免 SQLite）\n2. 根据执行器类型配置相应的消息代理连接\n3. 设置正确的认证凭证和 SSL 选项\n\n资料来源：[airflow-core/src/airflow/utils/db.py:1-100]()\n\n## 最佳实践\n\n### 执行器选择原则\n\n1. **从简单开始**：开发环境使用 LocalExecutor，生产环境根据需求升级\n2. **资源评估**：估算并发任务数、任务运行时长、资源消耗\n3. **运维能力**：评估团队对消息队列或容器编排的熟悉程度\n4. **成本考虑**：云环境优先考虑 KubernetesExecutor 以获得弹性\n5. **扩展性预留**：选择具有一定扩展空间的执行器类型\n\n### 性能优化建议\n\n| 优化项 | LocalExecutor | CeleryExecutor | KubernetesExecutor |\n|--------|--------------|----------------|-------------------|\n| 并发数 | `parallelism` 参数 | `worker_concurrency` | `parallelism` 参数 |\n| 心跳间隔 | 降低网络延迟 | 合理设置超时 | 配置 liveness 探针 |\n| 资源限制 | 进程级限制 | Worker 级限制 | Pod 级限制 |\n| 监控 | 进程监控 | Celery Events | K8s Events |\n\n### 常见问题排查\n\n```mermaid\ngraph TD\n Issue[问题排查] --> Check1{执行器启动失败?}\n Issue --> Check2{任务堆积?}\n Issue --> Check3{连接超时?}\n \n Check1 --> Solution1[检查配置
验证依赖]\n Check2 --> Solution2[增加并发数
优化任务拆分]\n Check3 --> Solution3[检查网络
验证凭证]\n```\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:320-400]()\n\n## 总结\n\nApache Airflow 的执行器系统提供了灵活的任务执行框架，从单机的顺序执行到分布式的 Kubernetes 集群执行，能够满足不同规模和场景的需求。执行器的选择应综合考虑部署环境、团队能力、运维成本和扩展性要求。\n\n对于新项目，建议先使用 LocalExecutor 进行开发和测试，待系统稳定后再根据实际负载和扩展需求迁移到 CeleryExecutor 或 KubernetesExecutor。在选择执行器时，务必参考官方文档中的具体版本要求，确保所有依赖组件正确配置。\n\n资料来源：[airflow-core/src/airflow/executors/executor_loader.py:400-450]()\n\n---\n\n\n\n## 数据流转与交换机制\n\n### 相关页面\n\n相关主题：[核心组件详解](#components), [FastAPI核心API](#fastapi)\n\n\n相关源码文件
\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/asset.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/models/asset.py)\n- [airflow-core/src/airflow/callbacks/callback_requests.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/callbacks/callback_requests.py)\n- [airflow-core/docs/core-concepts/xcoms.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/core-concepts/xcoms.rst)\n- [airflow-core/docs/authoring-and-scheduling/assets.rst](https://github.com/apache/airflow/blob/main/airflow-core/docs/authoring-and-scheduling/assets.rst)\n \n\n# 数据流转与交换机制\n\n## 概述\n\nApache Airflow 中的数据流转与交换机制是工作流编排的核心能力，允许任务之间传递数据、状态和事件。该机制主要由三大支柱组成：**XCom（跨任务通信）**、**Asset（资产）** 和 **Callback（回调）**。这些机制共同构成了 Airflow 工作流中数据流动的完整生态，使得分布式任务执行环境下的数据交换变得可靠且可追踪。\n\nXCom 机制允许任务在执行完成后向元数据库写入值，后续任务可以检索这些值进行后续处理。Asset 机制提供了一种基于数据源状态变化触发 DAG 执行的优雅方式。Callback 机制则支持任务生命周期中的关键节点执行自定义逻辑，如任务失败时发送告警。\n\n## XCom 机制详解\n\n### XCom 核心概念\n\nXCom（Cross-Communication）是 Airflow 中实现任务间数据交换的主要机制。它通过 `airflow.models.xcom.BaseXCom` 类实现，数据默认存储在 Airflow 元数据库中，支持任务执行器在分布式环境下共享数据。\n\n```mermaid\ngraph TD\n A[任务 A 执行] -->|push| B[XCom 写入]\n B --> C[(元数据库)]\n C -->|pull| D[任务 B 读取]\n D --> E[任务 B 继续执行]\n \n F[参数传递] -.->|包含| B\n G[返回值自动推送] -.->|包含| B\n```\n\nXCom 支持推送和拉取两种操作模式。任务可以通过 `xcom_push()` 方法显式推送数据，也可以通过返回 Python 对象让 Airflow 自动推送。拉取操作使用 `xcom_pull()` 方法，可以按任务 ID 或 DAG run ID 筛选特定数据。\n\n### XCom 数据模型\n\nXCom 的数据模型定义在 `BaseXCom` 类中，包含以下核心字段：\n\n| 字段名 | 类型 | 说明 |\n|--------|------|------|\n| key | String | XCom 值的键名，用于标识数据 |\n| value | JSON | 序列化的数据值，支持基础类型和嵌套结构 |\n| timestamp | DateTime | XCom 创建时间戳 |\n| task_id | String | 推送该 XCom 的任务 ID |\n| dag_id | String | 所属 DAG 的唯一标识符 |\n| run_id | String | DAG Run 的执行 ID |\n| map_index | Integer | Map 任务中的索引值（-1 表示非 Map 任务）|\n\n资料来源：[airflow-core/src/airflow/models/xcom.py:1-100]()\n\n### XCom API 与操作方法\n\n#### 推送数据\n\n```python\n# 方式一：显式推送\ntask_instance.xcom_push(key=\"result\", value={\"status\": \"success\", \"data\": [1, 2, 3]})\n\n# 方式二：通过 return 语句自动推送\ndef extract_data(**context):\n return {\"records\": 100, \"source\": \"api\"}\n```\n\n#### 拉取数据\n\n```python\n# 按任务 ID 拉取最新值\nresult = task_instance.xcom_pull(task_ids=[\"transform_data\"])[0]\n\n# 按 task_ids 和 key 精确拉取\nvalue = task_instance.xcom_pull(task_ids=[\"extract\"], key=\"record_count\")\n```\n\n#### 使用 XComArg 简化操作\n\n`XComArg` 提供了一种声明式的数据获取方式，特别适合与 Jinja 模板结合使用：\n\n```python\nfrom airflow.models.baseoperator import xcom_arg\n\nextract_task >> transform_task\n```\n\n### XCom 的序列化与反序列化\n\nXCom 值在存储前会被序列化为 JSON 格式，检索时自动反序列化。支持的类型包括：\n\n| Python 类型 | 序列化格式 | 限制说明 |\n|-------------|-----------|----------|\n| str | JSON String | 无限制 |\n| int, float | JSON Number | 无限制 |\n| bool | JSON Boolean | 无限制 |\n| list, tuple | JSON Array | 元素类型需可序列化 |\n| dict | JSON Object | 键值需可序列化 |\n| datetime | ISO 8601 字符串 | 需正确处理时区 |\n| bytes | Base64 编码 | 大小受 max_xcom_size 限制 |\n\n资料来源：[airflow-core/src/airflow/models/xcom.py:150-200]()\n\n### XCom 配置与性能优化\n\nXCom 的行为可通过以下配置参数调整：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `max_xcom_size` | 48KB | 单个 XCom 值的最大大小 |\n| `xcom_backend` | BaseXCom | 自定义 XCom 后端类 |\n| `enable_xcom_pickling` | True | 是否允许 pickle 序列化（非 JSON） |\n\n在高并发场景下，建议：\n1. 避免传输大型数据集，将大数据存储在外部存储（如 S3、HDFS），XCom 只传递引用\n2. 使用自定义 XCom 后端将数据存储到 GCS、Redis 等外部系统\n3. 及时清理过期 XCom 数据以减少元数据库负担\n\n## Asset 资产机制\n\n### Asset 概述\n\nAsset 是 Airflow 2.10+ 引入的新一代数据依赖管理机制，它代表 DAG 外部的数据源或数据目的地。通过 Asset，Airflow 可以感知数据源的变化并自动触发 DAG 执行，实现数据驱动的工作流编排。\n\n```mermaid\ngraph LR\n A[数据源变化] -->|触发| B[Asset 事件]\n B --> C{DAG 调度}\n C -->|是| D[创建 DAG Run]\n C -->|否| E[等待下次检查]\n \n F[Asset 定义] -->|关联| G[DAG Schedule]\n```\n\n### Asset 数据模型\n\nAsset 模型定义在 `airflow.models.asset` 模块中：\n\n```python\nclass Asset:\n name: str\n uri: str\n group: str | None\n extra: dict | None\n created_at: datetime\n updated_at: datetime\n```\n\n资料来源：[airflow-core/src/airflow/models/asset.py:1-50]()\n\n### Asset 与 DAG Schedule 绑定\n\nDAG 可以通过 `schedule` 参数与一个或多个 Asset 关联：\n\n```python\nfrom airflow.models.asset import Asset\n\n# 单个 Asset\ndaily_sales = Asset(uri=\"s3://data-bucket/daily-sales/\", name=\"daily_sales\")\n\nwith DAG(\n dag_id=\"process_sales\",\n schedule=[daily_sales], # 当 Asset 有新事件时触发\n ...\n):\n process_sales_task()\n```\n\n### Asset Event 事件机制\n\n每当外部数据源发生变化时，可以向 Airflow 报告 Asset Event：\n\n```python\nfrom airflow.sdk import AssetEvent\n\nAssetEvent(\n asset=daily_sales,\n extra={\"partition\": \"2024-01-15\"},\n source_task_instance_id=\"report_ingestion\",\n)\n```\n\n### Asset 命令行操作\n\nAirflow CLI 提供了完整的 Asset 管理命令：\n\n| 命令 | 功能 |\n|------|------|\n| `airflow assets list` | 列出所有注册的 Asset |\n| `airflow assets details` | 查看 Asset 详情 |\n| `airflow assets materialize` | 手动触发 Asset 物化 |\n| `airflow assets events` | 查看 Asset 事件历史 |\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:1-100]()\n\n## Callback 回调机制\n\n### Callback 机制概述\n\nCallback 允许在 DAG 和任务生命周期中的关键节点执行自定义逻辑。这些节点包括任务失败、成功、重试以及 DAG 运行时错误等场景。Callback 通过 `airflow.callbacks.callback_requests` 模块中定义的数据结构传递给执行器。\n\n```mermaid\ngraph TD\n A[任务状态变更] -->|生成| B[CallbackRequest]\n B --> C[(Callback 队列)]\n C -->|处理| D[Callback Executor]\n D --> E[执行用户逻辑]\n \n F[on_failure_callback] -.-> E\n G[on_success_callback] -.-> E\n H[on_retry_callback] -.-> E\n```\n\n### Callback Request 数据结构\n\nCallback 请求通过以下类定义：\n\n| 类名 | 用途 | 触发时机 |\n|------|------|----------|\n| `TaskCallbackRequest` | 任务级回调 | 任务成功/失败/重试 |\n| `DagCallbackRequest` | DAG 级回调 | DAG 运行失败/成功 |\n| `SlaCallbackRequest` | SLA 超时回调 | 任务超出 SLA 阈值 |\n| `DagRunCallbackRequest` | DAG Run 回调 | DAG Run 状态变更 |\n\n资料来源：[airflow-core/src/airflow/callbacks/callback_requests.py:1-80]()\n\n### TaskCallbackRequest 详解\n\n```python\nclass TaskCallbackRequest(CallbackRequest):\n simple_task_instance: SimpleTaskInstance\n msg: str | None\n processor_subprocess: bool\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| simple_task_instance | SimpleTaskInstance | 任务实例的简化表示 |\n| msg | str | 回调消息（如错误信息）|\n| processor_subprocess | bool | 是否在子进程中处理 |\n\n### Callback 注册方式\n\n#### 方式一：任务级别\n\n```python\ndef task_failure_alert(context):\n dag_id = context['dag_run'].dag_id\n task_id = context['task'].task_id\n send_alert(dag_id, task_id)\n\nwith DAG(...) as dag:\n task = PythonOperator(\n task_id=\"example_task\",\n python_callable=my_func,\n on_failure_callback=task_failure_alert,\n )\n```\n\n#### 方式二：DAG 级别\n\n```python\ndef dag_failure_alert(context):\n dag_id = context['dag_run'].dag_id\n send_dag_failure_notification(dag_id)\n\nwith DAG(\n dag_id=\"my_dag\",\n on_failure_callback=dag_failure_alert,\n):\n # tasks...\n```\n\n#### 方式三：使用 Airflow API 动态注册\n\n```python\nfrom airflow.models import TaskCallbackRequest\nfrom airflow.callbacks.callback_requests import _prepare_callback\n\n# 在执行器中动态注册\ncallback_request = _prepare_callback(\n ti=task_instance,\n callback_type=\"failure\",\n msg=\"Task failed with exception\",\n)\n```\n\n## 数据流转最佳实践\n\n### 避免数据膨胀\n\nXCom 数据存储在元数据库中，过大的数据量会影响数据库性能。建议遵循以下原则：\n\n1. **小数据原则**：XCom 值应保持在 10KB 以下\n2. **引用传递**：大型数据使用 URI/路径引用\n3. **定期清理**：配置 XCom 过期策略\n\n### 数据验证与类型安全\n\n在任务间传递数据时，应实施严格的验证策略：\n\n```python\nfrom pydantic import BaseModel, validator\n\nclass DataRecord(BaseModel):\n id: int\n value: float\n tags: list[str]\n \n @validator('value')\n def value_must_be_positive(cls, v):\n if v < 0:\n raise ValueError('value must be positive')\n return v\n\ndef process_data(**context):\n raw_data = context['ti'].xcom_pull(task_ids='extract', key='data')\n validated = DataRecord(**raw_data)\n return validated.dict()\n```\n\n### 幂等性设计\n\n任务应设计为幂等的，即相同输入多次执行产生相同结果。这在使用 XCom 进行数据传递时尤为重要，因为任务可能因重试而多次执行。\n\n### Asset 与 XCom 的选择\n\n| 场景 | 推荐机制 | 原因 |\n|------|----------|------|\n| 触发 DAG 执行 | Asset | 自动调度，感知数据源变化 |\n| 任务间传递结果 | XCom | 轻量，适合小数据量 |\n| 共享大型数据集 | 外部存储 + XCom 引用 | 避免元数据库压力 |\n| 事件驱动工作流 | Asset + TriggerDagRunOperator | 结合使用 |\n\n## 总结\n\nApache Airflow 的数据流转与交换机制通过 XCom、Asset 和 Callback 三大组件，为分布式工作流环境提供了完整的数据协调能力。XCom 专注于任务间的数据传递，Asset 实现了数据驱动的 DAG 触发，而 Callback 则在关键生命周期节点提供了扩展点。理解并合理运用这些机制，能够构建出高效、可靠且可维护的数据流水线。\n\n资料来源：[airflow-core/docs/core-concepts/xcoms.rst:1-50]()\n资料来源：[airflow-core/docs/authoring-and-scheduling/assets.rst:1-50]()\n\n---\n\n\n\n## FastAPI核心API\n\n### 相关页面\n\n相关主题：[React前端架构](#frontend)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [airflow-core/src/airflow/api_fastapi/core_api/app.py](https://github.com/apache/apache-airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/app.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/src/airflow/api_fastapi/core_api/routes/ui/dags.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/api_fastapi/core_api/routes/ui/dags.py)\n- [airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py](https://github.com/apache/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/cli/cli_config.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/cli/cli_config.py)\n \n\n# FastAPI核心API\n\n## 概述\n\nApache Airflow的FastAPI核心API是项目现代化Web服务架构的重要组成部分，旨在替代传统的Flask API。这一API层采用FastAPI框架构建，提供了高性能、异步支持、自动文档生成等特性。FastAPI核心API主要分为两个独立的应用程序：**Core API**（核心API）和**Execution API**（执行API），分别承担不同的职责。\n\nFastAPI核心API位于 `airflow-core/src/airflow/api_fastapi/` 目录下，采用模块化设计，将路由、数据模型、认证管理器等组件分离到独立的子模块中。这种架构设计使得代码组织清晰，便于维护和扩展。\n\n## 架构概览\n\n```mermaid\ngraph TB\n subgraph \"FastAPI应用层\"\n CA[Core API
core_api/app.py]\n EA[Execution API
execution_api/app.py]\n end\n \n subgraph \"认证层\"\n SAM[SimpleAuthManager
simple_auth_manager.py]\n AM[Auth Managers]\n end\n \n subgraph \"路由层\"\n UI_DAGS[UI DAG Routes
routes/ui/dags.py]\n API_ROUTES[API Routes]\n end\n \n subgraph \"数据模型层\"\n DM[DAG Run Datamodels
datamodels/dag_run.py]\n DT[其他Datamodels]\n end\n \n CA --> SAM\n EA --> SAM\n CA --> UI_DAGS\n CA --> API_ROUTES\n CA --> DM\n EA --> DM\n```\n\n## 核心组件\n\n### Core API应用\n\nCore API是Airflow的主要REST API服务，负责提供DAG管理、任务调度、监控等核心功能。该应用通过 `core_api/app.py` 文件初始化和配置，包含以下关键特性：\n\n- 异步请求处理支持\n- OpenAPI自动文档生成\n- Pydantic数据验证\n- 依赖注入系统\n- 中间件支持\n\nCore API的路由结构按功能模块划分，包括UI路由、作业路由、配置路由等多个子模块。这种模块化设计使得API扩展和维护更加便捷。\n\n### Execution API应用\n\nExecution API是专门用于任务执行的轻量级API服务，通过 `execution_api/app.py` 实现。该API主要负责：\n\n- 任务实例的执行状态管理\n- XCom消息传递\n- 任务心跳检测\n- 执行结果回调\n\nExecution API采用独立部署模式，与Core API解耦，以提高系统的可靠性和响应速度。\n\n## 数据模型\n\n### DAG Run数据模型\n\nDAG Run数据模型定义了DAG运行实例的结构，是整个调度系统的核心数据结构之一。在 `datamodels/dag_run.py` 中定义的主要字段包括：\n\n| 字段名 | 类型 | 说明 | 资料来源 |\n|--------|------|------|----------|\n| dag_id | str | DAG唯一标识符 | [dag_run.py](airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py) |\n| run_id | str | 运行实例唯一标识 | [dag_run.py](airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py) |\n| state | DagRunState | 运行状态枚举 | [dag_run.py](airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py) |\n| execution_date | datetime | 执行时间戳 | [dag_run.py](airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py) |\n| start_date | datetime | 开始时间 | [dag_run.py](airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py) |\n| end_date | datetime | 结束时间 | [dag_run.py](airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py) |\n| conf | dict | DAG配置参数 | [dag_run.py](airflow-core/src/airflow/api_fastapi/core_api/datamodels/dag_run.py) |\n\n### 数据验证\n\n所有通过API接收的数据都会经过Pydantic模型验证，确保数据类型和格式的正确性。这种自动验证机制减少了手动编写数据校验代码的需求，提高了开发效率。\n\n## 路由结构\n\n### UI DAG路由\n\nUI DAG路由是面向Web界面的API端点集合，通过 `routes/ui/dags.py` 文件实现。这些路由主要用于：\n\n- DAG列表查询\n- DAG运行历史记录\n- DAG状态监控\n- 任务依赖关系可视化\n\nUI路由通常需要用户认证，并返回适合前端渲染的数据格式。\n\n### 路由组织方式\n\n```mermaid\ngraph LR\n subgraph \"路由注册\"\n RC[Route Configuration
cli_config.py]\n end\n \n subgraph \"CLI命令\"\n CMD1[airflow dags]\n CMD2[airflow tasks]\n CMD3[airflow connections]\n end\n \n RC --> CMD1\n RC --> CMD2\n RC --> CMD3\n \n CMD1 --> DAG_ROUTES[DAG Routes]\n CMD2 --> TASK_ROUTES[Task Routes]\n CMD3 --> CONN_ROUTES[Connection Routes]\n```\n\n在 `cli_config.py` 中定义了Airflow CLI命令与API路由的映射关系，支持的命令包括：\n\n| 命令组 | 子命令 | 功能说明 |\n|--------|--------|----------|\n| dags | backfill, list-runs, pause, unpause, test | DAG生命周期管理 |\n| tasks | list, run, state, clear | 任务操作管理 |\n| connections | list, add, delete, edit | 连接配置管理 |\n| providers | list, get | Provider信息查询 |\n\n## 认证与授权\n\n### SimpleAuthManager\n\nSimpleAuthManager是FastAPI认证系统的核心组件，位于 `auth/managers/simple/simple_auth_manager.py`。它提供了简化的认证机制，适用于单机部署或开发环境。\n\n主要功能包括：\n\n- 用户身份验证\n- 会话管理\n- 权限检查\n- API密钥验证\n\n### 认证管理器架构\n\n```mermaid\nclassDiagram\n class BaseAuthManager {\n <>\n +authenticate()\n +get_user()\n +is_authorized()\n }\n \n class SimpleAuthManager {\n +authenticate()\n +get_user()\n +is_authorized()\n +get_user_role()\n }\n \n BaseAuthManager <|-- SimpleAuthManager\n```\n\n### 认证流程\n\n认证请求的标准处理流程如下：\n\n1. 客户端发送带认证信息的请求\n2. 中间件拦截请求并提取认证凭证\n3. SimpleAuthManager验证凭证有效性\n4. 根据用户角色确定访问权限\n5. 返回认证结果或拒绝访问\n\n## CLI集成\n\n### 命令注册机制\n\n在 `cli_config.py` 中使用懒加载模式注册CLI命令，这种方式可以提高应用启动速度：\n\n```python\nActionCommand(\n name=\"info\",\n help=\"Show information about current Airflow and environment\",\n func=lazy_load_command(\"airflow.cli.commands.info_command.show_info\"),\n args=(ARG_ANONYMIZE, ARG_FILE_IO, ARG_VERBOSE, ARG_OUTPUT),\n)\n```\n\n### 懒加载命令\n\n懒加载机制确保只有在实际调用命令时才加载对应的模块，这有助于：\n\n- 减少内存占用\n- 加快应用启动时间\n- 避免不必要的模块依赖\n\n支持的懒加载命令类型包括：\n\n- `info_command` - 环境信息展示\n- `plugins_command` - 插件信息导出\n- `standalone_command` - 独立运行模式\n- `config_command` - 配置管理\n- `version_command` - 版本信息\n- `cheat_sheet_command` - 命令速查表\n\n## 配置管理\n\n### 配置命令\n\nFastAPI核心API提供了丰富的配置管理功能，包括：\n\n| 命令 | 功能 | 说明 |\n|------|------|------|\n| config get-value | 获取配置值 | 打印指定配置项的值 |\n| config list | 列出配置 | 显示所有配置选项 |\n| config lint | 配置检查 | 验证配置迁移正确性 |\n| config update | 更新配置 | 修改配置值 |\n\n### 配置参数\n\n配置API支持多种参数用于过滤和格式化输出：\n\n- `--section` - 指定配置章节\n- `--option` - 指定配置选项\n- `--include-descriptions` - 包含描述信息\n- `--include-examples` - 包含示例值\n- `--include-sources` - 显示配置来源\n- `--include-env-vars` - 显示环境变量\n- `--hide-sensitive` - 隐藏敏感信息\n\n## API响应格式\n\n### 统一响应结构\n\nFastAPI核心API采用统一的响应格式，便于客户端处理：\n\n```json\n{\n \"data\": {},\n \"meta\": {\n \"status\": \"success\",\n \"timestamp\": \"2024-01-01T00:00:00Z\"\n }\n}\n```\n\n### 错误响应\n\n错误响应遵循统一的格式，包含错误码、消息和详细信息：\n\n```json\n{\n \"error\": {\n \"code\": \"DAG_NOT_FOUND\",\n \"message\": \"DAG with id 'example_dag' not found\",\n \"details\": {}\n }\n}\n```\n\n## 技术特性\n\n### 异步支持\n\nFastAPI核心API全面支持异步操作，包括：\n\n- 异步数据库查询\n- 异步HTTP请求\n- 异步文件操作\n- 并发任务处理\n\n### 自动文档\n\n基于OpenAPI标准，API自动生成交互式文档：\n\n- Swagger UI 可通过 `/docs` 访问\n- ReDoc 可通过 `/redoc` 访问\n- OpenAPI JSON 可通过 `/openapi.json` 获取\n\n### 数据验证\n\n使用Pydantic v2进行严格的数据验证和转换：\n\n- 类型检查\n- 默认值处理\n- 自定义验证器\n- 嵌套模型支持\n\n## 部署架构\n\n### 多实例部署\n\n在生产环境中，FastAPI核心API支持多实例部署：\n\n```mermaid\ngraph TB\n LB[Load Balancer]\n API1[Core API Instance 1]\n API2[Core API Instance 2]\n API3[Core API Instance 3]\n DB[(Database)]\n Redis[(Redis)]\n \n LB --> API1\n LB --> API2\n LB --> API3\n API1 --> DB\n API2 --> DB\n API3 --> DB\n API1 --> Redis\n API2 --> Redis\n API3 --> Redis\n```\n\n### 与传统Flask API对比\n\n| 特性 | FastAPI | Flask |\n|------|---------|-------|\n| 性能 | 异步原生支持 | 同步为主 |\n| 文档 | 自动生成OpenAPI | 需手动编写 |\n| 验证 | Pydantic自动验证 | 手动验证 |\n| 类型安全 | 完整类型注解 | 运行时检查 |\n| 并发 | 原生异步支持 | 需扩展支持 |\n\n## 安全考虑\n\n### 敏感信息保护\n\nAPI在处理敏感信息时采取以下保护措施：\n\n- 敏感配置加密存储\n- 日志输出脱敏处理\n- 环境变量优先读取\n- 连接凭证安全传输\n\n### 权限控制\n\n基于角色的访问控制（RBAC）确保API操作的安全性：\n\n- 管理员权限 - 完全访问\n- 编辑权限 - 修改配置\n- 只读权限 - 查询数据\n- 无权限 - 拒绝访问\n\n## 扩展开发\n\n### 自定义路由\n\n开发者可以通过以下步骤添加自定义路由：\n\n1. 在相应模块下创建路由文件\n2. 定义路由函数和参数\n3. 注册路由到应用\n4. 添加CLI命令映射\n\n### 自定义认证\n\n扩展认证机制需要实现以下接口：\n\n- `authenticate()` - 用户认证方法\n- `get_user()` - 获取用户信息\n- `is_authorized()` - 权限检查方法\n\n## 最佳实践\n\n### API设计原则\n\n1. **RESTful规范** - 遵循REST设计原则\n2. **版本控制** - 保持API向后兼容\n3. **错误处理** - 返回有意义的错误信息\n4. **性能优化** - 使用异步操作提高吞吐量\n5. **文档维护** - 及时更新API文档\n\n### 性能优化建议\n\n- 使用连接池管理数据库连接\n- 合理使用缓存减少数据库查询\n- 实现请求限流防止滥用\n- 监控API响应时间及时发现问题\n\n## 相关文档\n\n- [Core API完整路由参考](airflow-core/src/airflow/api_fastapi/core_api/routes)\n- [Execution API参考](airflow-core/src/airflow/api_fastapi/execution_api)\n- [认证管理器文档](airflow-core/src/airflow/api_fastapi/auth/managers)\n- [数据模型定义](airflow-core/src/airflow/api_fastapi/core_api/datamodels)\n\n---\n\n\n\n## React前端架构\n\n### 相关页面\n\n相关主题：[FastAPI核心API](#fastapi)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\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- [airflow-core/src/airflow/ui/src/pages/Providers.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/Providers.tsx)\n- [airflow-core/src/airflow/ui/src/pages/DagsList/DagsList.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/DagsList/DagsList.tsx)\n- [airflow-core/src/airflow/ui/src/pages/Run/Header.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/Run/Header.tsx)\n- [airflow-core/src/airflow/ui/src/pages/XCom/XCom.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/XCom/XCom.tsx)\n- [airflow-core/src/airflow/ui/src/pages/HITLTaskInstances/HITLTaskInstances.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/HITLTaskInstances/HITLTaskInstances.tsx)\n- [airflow-core/src/airflow/ui/src/components/Assets/TriggeredRuns.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/Assets/TriggeredRuns.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/components/Clear/TaskInstance/ClearGroupTaskInstanceDialog.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/Clear/TaskInstance/ClearGroupTaskInstanceDialog.tsx)\n- [airflow-core/src/airflow/ui/src/components/Dashboard/Stats/DAGImportErrorsModal.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/Dashboard/Stats/DAGImportErrorsModal.tsx)\n- [airflow-core/src/airflow/ui/src/components/TaskInstanceTooltip.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/TaskInstanceTooltip.tsx)\n- [airflow-core/src/airflow/ui/src/components/ui/Tag.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/ui/Tag.tsx)\n- [dev/react-plugin-tools/react_plugin_template/README.md](https://github.com/apache/airflow/blob/main/dev/react-plugin-tools/react_plugin_template/README.md)\n \n\n# React前端架构\n\n## 概述\n\nApache Airflow 的 React 前端是一个现代化的单页应用（SPA），采用 React 18、TypeScript 和 Chakra UI 构建，为用户提供了直观、高效的 DAG 管理和监控界面。该前端架构遵循组件化设计原则，通过 TanStack Table 实现数据表格功能，使用 react-router-dom 进行路由管理，并集成了 react-i18next 实现国际化支持。资料来源：[dev/react-plugin-tools/react_plugin_template/README.md](https://github.com/apache/airflow/blob/main/dev/react-plugin-tools/react_plugin_template/README.md)\n\n## 技术栈概览\n\n### 核心依赖\n\n| 技术 | 用途 | 版本说明 |\n|------|------|----------|\n| React 18 | UI 框架 | 核心库 |\n| TypeScript | 类型系统 | 类型安全 |\n| Chakra UI | UI 组件库 | 样式和组件 |\n| TanStack Table | 数据表格 | 排序、分页 |\n| react-router-dom | 路由管理 | SPA 导航 |\n| react-i18next | 国际化 | 多语言支持 |\n\n### 构建工具\n\n前端项目使用 **Vite** 作为构建工具，提供快速的开发服务器和优化的生产构建。Vite 配置将 React 和相关生态库标记为外部依赖，以减少插件包体积。资料来源：[dev/react-plugin-tools/react_plugin_template/README.md](https://github.com/apache/airflow/blob/main/dev/react-plugin-tools/react_plugin_template/README.md)\n\n## 页面组件架构\n\n### 页面目录结构\n\nAirflow 前端的页面组件位于 `airflow-core/src/airflow/ui/src/pages/` 目录下，采用模块化组织方式：\n\n```\npages/\n├── DagRuns.tsx # DAG运行列表页\n├── DagsList/ # DAG列表模块\n│ └── DagsList.tsx\n├── Providers.tsx # 提供商信息页\n├── Run/ # 运行详情模块\n│ └── Header.tsx\n├── XCom/ # XCom数据模块\n│ └── XCom.tsx\n└── HITLTaskInstances/ # 人工干预任务实例模块\n └── HITLTaskInstances.tsx\n```\n\n### 页面组件通用模式\n\n每个页面组件通常遵循以下结构模式：\n\n1. **导入依赖**：引入必要的 React hooks、组件和工具函数\n2. **类型定义**：定义页面专用的 TypeScript 接口\n3. **列定义工厂函数**：创建 `createColumns` 函数用于生成 TanStack Table 列配置\n4. **主组件导出**：使用自定义 hooks 获取数据并渲染页面\n\n```typescript\nconst createColumns = (translate: TFunction): Array> => [\n {\n accessorKey: \"package_name\",\n cell: ({ row: { original } }) => (\n \n {original.package_name}\n \n ),\n enableSorting: false,\n header: translate(\"providers.columns.packageName\"),\n },\n // ... 更多列定义\n];\n```\n\n资料来源：[airflow-core/src/airflow/ui/src/pages/Providers.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/Providers.tsx)\n\n## 核心组件体系\n\n### UI 基础组件\n\n基础 UI 组件位于 `airflow-core/src/airflow/ui/src/components/ui/` 目录下，提供可复用的界面元素。\n\n#### Tag 组件\n\n`Tag` 组件是对 Chakra UI Tag 的封装，提供了统一的标签样式：\n\n```typescript\nconst Tag = React.forwardRef(({ \n closable = Boolean(onClose), \n endElement, \n startElement, \n ...rest \n}) => {\n return (\n \n {Boolean(startElement) ? {startElement} : undefined}\n {children}\n {Boolean(endElement) ? {endElement} : undefined}\n {Boolean(closable) ? (\n \n \n \n ) : undefined}\n \n );\n});\n```\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| closable | boolean | 是否显示关闭按钮 |\n| endElement | ReactNode | 标签尾部元素 |\n| startElement | ReactNode | 标签头部元素 |\n| onClose | () => void | 关闭回调函数 |\n\n资料来源：[airflow-core/src/airflow/ui/src/components/ui/Tag.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/ui/Tag.tsx)\n\n### 数据展示组件\n\n#### DAG 触发运行组件 (TriggeredRuns)\n\n`TriggeredRuns` 组件用于展示由 DAG 触发的运行信息，支持单个和多个运行场景：\n\n```typescript\nexport const TriggeredRuns = ({ dagRuns }: Props) => {\n if (dagRuns === undefined || dagRuns.length === 0) {\n return undefined;\n }\n\n return dagRuns.length === 1 ? (\n \n {`${translate(\"triggered\")} ${translate(\"dagRun_one\")}: `}\n \n \n \n {dagRuns[0]?.dag_id}\n \n \n \n ) : (\n \n \n \n \n \n {/* 多个运行时显示下拉列表 */}\n \n \n );\n};\n```\n\n| 场景 | 渲染方式 |\n|------|----------|\n| 单个运行 | 内联展示 DAG ID 和状态徽章 |\n| 多个运行 | 下拉菜单，点击展开列表 |\n\n资料来源：[airflow-core/src/airflow/ui/src/components/Assets/TriggeredRuns.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/Assets/TriggeredRuns.tsx)\n\n### 任务实例工具提示组件\n\n`TaskInstanceTooltip` 组件提供任务实例的详细信息悬浮提示：\n\n```typescript\n\n```\n\n显示的信息包括：任务 ID、状态、运行 ID、调度时间、队列时间、开始时间、结束时间以及重试次数。资料来源：[airflow-core/src/airflow/ui/src/components/TaskInstanceTooltip.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/TaskInstanceTooltip.tsx)\n\n### 对话框组件\n\n#### 清除任务实例确认对话框\n\n`ClearTaskInstanceConfirmationDialog` 是用于确认清除任务实例操作的模态对话框：\n\n```typescript\n\n \n \n \n \n \n \n {translate(\"dags:runAndTaskActions.confirmationDialog.title\")}\n \n \n {translate(\"dags:runAndTaskActions.confirmationDialog.description\", {\n state: taskCurrentState,\n time: getRelativeTime(firstInstance.start_date),\n user: firstInstance?.unixname ?? \"unknown user\",\n })}\n \n \n \n \n \n \n\n```\n\n对话框使用 Radix UI 的 Dialog 组件，提供标题、描述和底部操作区域，支持国际化翻译。资料来源：[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\n#### 批量清除任务实例对话框\n\n`ClearGroupTaskInstanceDialog` 用于批量清除一组任务实例，支持以下参数：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| future | boolean | 是否包含未来运行 |\n| past | boolean | 是否包含过去运行 |\n| upstream | boolean | 是否包含上游任务 |\n| onlyFailed | boolean | 仅清除失败任务 |\n| runOnLatestVersion | boolean | 使用最新 DAG 版本运行 |\n| note | string \\| null | 清除操作备注 |\n| groupTaskIds | string[] | 任务 ID 列表 |\n\n资料来源：[airflow-core/src/airflow/ui/src/components/Clear/TaskInstance/ClearGroupTaskInstanceDialog.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/Clear/TaskInstance/ClearGroupTaskInstanceDialog.tsx)\n\n### 模态框组件\n\n#### DAG 导入错误模态框\n\n`DAGImportErrorsModal` 展示 DAG 导入过程中的错误信息：\n\n- 使用 Accordion 组件折叠/展开每个错误详情\n- 使用 Pagination 组件分页显示错误列表\n- 显示错误时间戳和完整的堆栈跟踪信息\n\n```typescript\n\n {importErrors.map((importError) => (\n \n \n {importError.filename}\n \n \n \n {importError.stack_trace}\n \n \n \n ))}\n\n```\n\n资料来源：[airflow-core/src/airflow/ui/src/components/Dashboard/Stats/DAGImportErrorsModal.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/components/Dashboard/Stats/DAGImportErrorsModal.tsx)\n\n## 表格列配置系统\n\n### TanStack Table 集成\n\nAirflow 前端使用 TanStack Table（React Table）作为数据表格解决方案，通过列定义工厂函数生成可配置的表格结构。\n\n### DAG 运行列表列配置\n\n`DagRuns.tsx` 中的列配置示例：\n\n| 访问器键 | 组件 | 功能 |\n|----------|------|------|\n| run_after | Time | 显示运行时间 |\n| state | StateBadge | 任务状态徽章 |\n| run_type | RunTypeIcon + Text | 运行类型图标和文字 |\n| triggering_user_name | Text | 触发用户名称 |\n| start_date | Time | 开始时间 |\n| end_date | Time | 结束时间 |\n| duration | renderDuration | 持续时间渲染 |\n\n```typescript\n{\n accessorKey: \"state\",\n cell: ({ row: { original: { state } } }) => (\n \n {translate(`common:states.${state}`)}\n \n ),\n header: () => translate(\"state\"),\n},\n```\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### DAG 列表特殊列\n\n`DagsList.tsx` 包含一些独特的列定义：\n\n```typescript\n{\n accessorKey: \"pending_actions\",\n cell: ({ row: { original: dag } }) => (\n \n ),\n enableSorting: false,\n header: \"\",\n},\n{\n accessorKey: \"trigger\",\n cell: ({ row: { original } }) => (\n \n ),\n enableSorting: false,\n header: \"\",\n},\n```\n\n这些列用于显示待处理操作和 DAG 触发按钮，没有排序功能。资料来源：[airflow-core/src/airflow/ui/src/pages/DagsList/DagsList.tsx](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/ui/src/pages/DagsList/DagsList.tsx)\n\n## 国际化实现\n\n### 翻译函数使用\n\n前端使用 `react-i18next` 的 `useTranslation` hook 获取翻译函数：\n\n```typescript\nconst { t: translate } = useTranslation(\"common\");\n\n// 在列配置中使用\nheader: () => translate(\"dagRun.runAfter\")\n\n// 动态键翻译\n{translate(`common:states.${state}`)}\n```\n\n### 命名空间管理\n\n翻译键使用冒号分隔命名空间，例如 `common:states.running`、`dagRun.runAfter` 等，允许多个翻译文件独立管理。资料来源：[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## 路由与导航\n\n### 路由模式\n\nAirflow 前端使用 `react-router-dom` 进行客户端路由，主要导航模式包括：\n\n```typescript\n// 链接到 DAG 详情\n\n\n// 链接到任务实例\n\n```\n\n### 嵌套路由结构\n\n页面通过嵌套路由组织，支持从 DAG 列表 → DAG 详情 → 任务实例的层级导航。\n\n## React 插件系统\n\n### 插件模板架构\n\nAirflow 提供 React 插件模板，支持第三方开发者构建可集成到主应用的组件库：\n\n```typescript\nimport { PluginComponent } from 'your-plugin-name';\n\n\n```\n\n### 插件开发指南\n\n| 步骤 | 说明 |\n|------|------|\n| 组件开发 | 使用 React + TypeScript 编写功能组件 |\n| 主题适配 | 自动继承 Airflow 主应用主题 |\n| 构建配置 | 使用 Vite 构建为库文件 |\n| 外部依赖 | React 生态库标记为外部以避免冲突 |\n\n资料来源：[dev/react-plugin-tools/react_plugin_template/README.md](https://github.com/apache/airflow/blob/main/dev/react-plugin-tools/react_plugin_template/README.md)\n\n## 数据流架构\n\n```mermaid\ngraph TD\n A[用户交互] --> B[React 组件]\n B --> C[API 请求]\n C --> D[Airflow REST API]\n D --> E[后端数据库]\n E --> D\n D --> C\n C --> F[状态更新]\n F --> B\n B --> G[UI 渲染]\n \n H[TanStack Table] --> I[列定义配置]\n I --> B\n B --> J[数据展示]\n \n K[useTranslation] --> L[翻译键]\n L --> M[翻译文件]\n M --> K\n```\n\n## 组件生命周期管理\n\n### 状态管理\n\n组件使用 React hooks 管理状态：\n\n- `useState`：本地组件状态\n- `useEffect`：副作用处理\n- `useTranslation`：国际化\n- `useParams`：URL 参数获取\n- `useTableURLState`：表格 URL 状态同步\n\n### 条件渲染模式\n\n```typescript\n// 使用短路求值\n{Boolean(dagRuns.length) && }\n\n// 使用三元运算符\n{condition ? : }\n\n// 使用 && 运算符\n{hasCondition && }\n```\n\n## 样式系统\n\n### Chakra UI 集成\n\n前端使用 Chakra UI 作为主要样式解决方案，提供：\n\n- 预设的设计令牌（颜色、间距、字体）\n- 可访问性内置支持\n- 主题定制能力\n- 组件组合模式\n\n### 颜色语义\n\n| 语义颜色 | 用途 | 示例 |\n|----------|------|------|\n| fg.info | 信息文本 | 链接 |\n| fg.error | 错误文本 | 错误消息 |\n| bg.emphasized | 强调背景 | 弹窗背景 |\n\n## 最佳实践\n\n### 组件开发规范\n\n1. **类型安全**：所有组件使用 TypeScript，明确输入输出类型\n2. **可访问性**：使用语义化 HTML 和 ARIA 属性\n3. **国际化**：所有用户可见文本使用翻译函数\n4. **错误处理**：组件包含错误边界和降级处理\n5. **性能优化**：使用 `lazyMount` 和 `unmountOnExit` 延迟加载\n\n### 文件组织原则\n\n- **页面组件**：位于 `pages/` 目录，包含业务逻辑\n- **通用组件**：位于 `components/` 目录，可复用\n- **UI 组件**：位于 `components/ui/` 目录，基础元素\n- **布局组件**：位于 `layouts/` 目录，页面结构\n\n## 总结\n\nApache Airflow 的 React 前端采用了现代化的组件化架构，通过 TanStack Table 实现灵活的数据表格功能，借助 Chakra UI 提供一致的用户界面体验，使用 react-i18next 支持多语言环境。插件系统的设计允许第三方开发者扩展功能，同时保持与主应用的主题一致性。整个前端架构体现了可维护性、可扩展性和用户体验的平衡。\n\n---\n\n\n\n## 容器化与Kubernetes部署\n\n### 相关页面\n\n相关主题：[执行器类型与选择](#executors), [快速开始与安装指南](#quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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- [dev/breeze/src/airflow_breeze/global_constants.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/global_constants.py)\n- [airflow-core/src/airflow/example_dags/example_kubernetes_executor.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/example_dags/example_kubernetes_executor.py)\n- [docker-stack-docs/README.md](https://github.com/apache/airflow/blob/main/docker-stack-docs/README.md)\n- [chart/docs/production-guide.rst](https://github.com/apache/airflow/blob/main/chart/docs/production-guide.rst)\n \n\n# 容器化与Kubernetes部署\n\nApache Airflow 作为分布式工作流编排平台，支持通过容器化和 Kubernetes 实现灵活的部署方案。本文详细介绍 Airflow 的 Docker 镜像构建机制、Kubernetes 部署架构以及生产环境最佳实践。\n\n## 1. Docker 容器化概述\n\nApache Airflow 提供官方的 `apache/airflow` Docker 镜像，该镜像是构建生产级部署环境的基础。镜像采用多阶段构建技术，基于 Python slim 镜像优化体积。\n\n### 1.1 Docker 构建配置\n\nAirflow 的 Dockerfile 使用 Docker BuildKit 语法，支持通过 `--mount=type=cache` 挂载缓存目录以加速构建过程：\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==\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/release_management_commands.py:52-58]()\n\n### 1.2 入口点与初始化\n\nDocker 镜像的入口点脚本负责初始化 SQLite 数据库（当未配置外部数据库时）：\n\n> 如果未设置 `AIRFLOW__DATABASE__SQL_ALCHEMY_CONN` 变量，则在 `${AIRFLOW_HOME}/airflow.db` 创建 SQLite 数据库。\n\n资料来源：[docker-stack-docs/README.md:15-16]()\n\n## 2. Kubernetes 部署架构\n\nAirflow 在 Kubernetes 上的部署通过 Helm Chart 实现，支持高度可配置的分布式架构。\n\n### 2.1 支持的 Kubernetes 版本\n\nApache Airflow 根据三大云服务商的 Kubernetes 支持周期维护兼容版本列表：\n\n| 云服务商 | 生命周期页面 |\n|---------|-------------|\n| Amazon EKS | [endoflife.date/amazon-eks](https://endoflife.date/amazon-eks) |\n| Azure Kubernetes Service | [endoflife.date/azure-kubernetes-service](https://endoflife.date/azure-kubernetes-service) |\n| Google Kubernetes Engine | [endoflife.date/google-kubernetes-engine](https://endoflife.date/google-kubernetes-engine) |\n\n当前允许的 Kubernetes 版本列表：\n\n| 版本 | 状态 |\n|-----|------|\n| v1.30.13 | ✅ 支持 |\n| v1.31.12 | ✅ 支持 |\n| v1.32.8 | ✅ 支持 |\n| v1.33.4 | ✅ 支持 |\n| v1.34.0 | ✅ 支持 |\n\n资料来源：[dev/breeze/src/airflow_breeze/global_constants.py:ALLOWED_KUBERNETES_VERSIONS]()\n\n### 2.2 Kubernetes 组件架构\n\nAirflow 在 Kubernetes 环境中的核心组件包括：\n\n```mermaid\ngraph TD\n subgraph \"Kubernetes 集群\"\n subgraph \"airflow Namespace\"\n Scheduler[\"Scheduler Pod
调度器\"]\n Webserver[\"Webserver Pod
Web服务器\"]\n Triggerer[\"Triggerer Pod
触发器\"]\n DagProcessor[\"Dag Processor Pod
DAG处理器\"]\n end\n \n subgraph \"Pod 配置\"\n Executor[\"Executor
执行器\"]\n Worker[\"Worker Pod
工作节点\"]\n K8SExecutor[\"K8S Executor
Kubernetes执行器\"]\n end\n end\n \n ExternalDB[\"外部数据库
PostgreSQL/MySQL\"]\n Redis[\"消息队列
Redis\"]\n \n Scheduler --> Executor\n Executor --> K8SExecutor\n K8SExecutor --> Worker\n Scheduler --> ExternalDB\n Webserver --> ExternalDB\n Triggerer --> Redis\n```\n\n### 2.3 多命名空间模式\n\nAirflow 支持多命名空间部署模式，允许在不同命名空间中运行测试环境和生产环境：\n\n```python\noption_multi_namespace_mode = click.option(\n \"--multi-namespace-mode\",\n help=\"使用多命名空间模式\",\n is_flag=True,\n envvar=\"MULTI_NAMESPACE_MODE\",\n)\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/kubernetes_commands.py:multi_namespace_mode]()\n\n## 3. Kubernetes 部署命令\n\n### 3.1 部署工作流程\n\n```mermaid\ngraph LR\n A[\"breeze k8s deploy-airflow\"] --> B[\"创建 KinD 集群\"]\n B --> C[\"创建 Kubernetes 命名空间\"]\n C --> D[\"部署 Helm Chart\"]\n D --> E[\"配置 Airflow 组件\"]\n E --> F[\"验证部署状态\"]\n```\n\n### 3.2 核心部署选项\n\n| 参数 | 说明 | 默认值 |\n|-----|------|--------|\n| `--python` | Python 版本 | 3.10 |\n| `--kubernetes-version` | Kubernetes 集群版本 | v1.31.12 |\n| `--executor` | 执行器类型 | LocalExecutor |\n| `--deploy/--no-deploy` | 是否通过 Skaffold 部署 | False |\n| `--upgrade` | 升级而非安装 Helm Chart | False |\n| `--multi-namespace-mode` | 启用多命名空间模式 | False |\n| `--rebuild-base-image` | 重建基础镜像 | False |\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/kubernetes_commands.py:option_executor]()\n\n### 3.3 部署流程代码\n\n部署 Airflow 到 Kubernetes 集群的核心逻辑：\n\n```python\ndef _deploy_airflow(\n python: str,\n kubernetes_version: str,\n output: Output | None,\n executor: str,\n upgrade: bool,\n use_standard_naming: bool,\n wait_time_in_seconds: int,\n extra_options: str,\n multi_namespace_mode: bool,\n):\n cluster_name = get_kubectl_cluster_name(\n python=python, kubernetes_version=kubernetes_version\n )\n # 创建命名空间\n get_console(output=output).print(f\"[info]创建集群 {cluster_name} 的命名空间\")\n run_command_with_k8s_env(\n [\"kubectl\", \"create\", \"namespace\", HELM_AIRFLOW_NAMESPACE],\n python=python,\n kubernetes_version=kubernetes_version,\n output=output,\n check=False,\n )\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/kubernetes_commands.py:_deploy_airflow]()\n\n## 4. Kubernetes 执行器配置\n\n### 4.1 Pod 覆盖机制\n\nKubernetes 执行器允许通过 `pod_override` 动态配置 Pod 规格：\n\n```python\nstart_task_executor_config = {\n \"pod_override\": k8s.V1Pod(\n metadata=k8s.V1ObjectMeta(annotations={\"test\": \"annotation\"})\n )\n}\n\n@task(executor_config=start_task_executor_config)\ndef start_task():\n print_stuff()\n```\n\n资料来源：[airflow-core/src/airflow/example_dags/example_kubernetes_executor.py:20-27]()\n\n### 4.2 Volume 挂载配置\n\n支持在 Task 执行时挂载持久化卷：\n\n```python\nexecutor_config_volume_mount = {\n \"pod_override\": k8s.V1Pod(\n spec=k8s.V1PodSpec(\n containers=[\n k8s.V1Container(\n name=\"base\",\n volume_mounts=[\n k8s.V1VolumeMount(\n mount_path=\"/foo/\",\n name=\"example-kubernetes-test-volume\"\n )\n ],\n )\n ],\n volumes=[\n k8s.V1Volume(\n name=\"example-kubernetes-test-volume\",\n host_path=k8s.V1HostPathVolumeSource(path=\"/tmp/\"),\n )\n ],\n )\n ),\n}\n```\n\n资料来源：[airflow-core/src/airflow/example_dags/example_kubernetes_executor.py:31-56]()\n\n### 4.3 执行器配置参数表\n\n| 配置项 | 类型 | 说明 |\n|-------|------|------|\n| `pod_override` | V1Pod | Pod 覆盖规格 |\n| `annotations` | Dict[str, str] | Pod 注解 |\n| `labels` | Dict[str, str] | Pod 标签 |\n| `node_selector` | Dict[str, str] | 节点选择器 |\n| `tolerations` | List[V1Toleration] | 容忍度配置 |\n| `affinity` | V1Affinity | 亲和性配置 |\n| `resources` | V1ResourceRequirements | 资源限制 |\n\n## 5. Docker Compose 开发环境\n\n对于本地开发，Airflow 提供 Docker Compose 配置：\n\n```yaml\nservices:\n airflow:\n image: ${AIRFLOW_IMAGE_NAME:-apache/airflow:latest}\n environment:\n AIRFLOW__CORE__EXECUTOR: LocalExecutor\n AIRFLOW__DATABASE__SQL_ALCHEMY_CONN: sqlite:////opt/airflow/airflow.db\n AIRFLOW__CORE__FERNET_KEY: ''\n AIRFLOW__CORE__DAGS__FOLDER: ${AIRFLOW_PROJ_DIR:-.}/dags\n AIRFLOW__CORE__LOAD_EXAMPLES: 'true'\n```\n\n资料来源：[airflow-core/docs/howto/docker-compose/docker-compose.yaml]()\n\n### 5.1 Docker Compose 配置参数\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `AIRFLOW__CORE__EXECUTOR` | 执行器类型 | LocalExecutor |\n| `AIRFLOW__DATABASE__SQL_ALCHEMY_CONN` | 数据库连接字符串 | sqlite |\n| `AIRFLOW__CORE__FERNET_KEY` | 加密密钥 | - |\n| `AIRFLOW__CORE__DAGS__FOLDER` | DAG 文件目录 | ./dags |\n| `AIRFLOW__CORE__LOAD_EXAMPLES` | 加载示例 DAG | true |\n| `AIRFLOW__CORE__AIRFLOW_HOME` | Airflow 主目录 | /opt/airflow |\n\n## 6. 生产环境最佳实践\n\n### 6.1 部署检查清单\n\n| 检查项 | 说明 |\n|-------|------|\n| 外部数据库配置 | 使用 PostgreSQL 或 MySQL 而非 SQLite |\n| 执行器选择 | 生产环境推荐 CeleryExecutor 或 KubernetesExecutor |\n| 高可用配置 | 部署多个 Scheduler 和 Webserver 实例 |\n| 资源限制 | 为各组件设置 CPU 和内存限制 |\n| 健康检查 | 配置 readiness 和 liveness 探针 |\n| 持久化存储 | 使用 PVC 持久化 DAG 和日志 |\n\n### 6.2 安全配置\n\n生产环境部署时应考虑以下安全措施：\n\n1. **配置 Fernet 密钥**：启用敏感数据加密\n2. **使用 Secrets**：通过 Kubernetes Secrets 管理凭据\n3. **网络策略**：配置 Pod 间网络隔离\n4. **RBAC**：启用基于角色的访问控制\n5. **审计日志**：启用 Airflow 审计日志功能\n\n### 6.3 监控与告警\n\n建议集成的监控组件：\n\n- **Metrics**: Prometheus + Grafana\n- **Logging**: ELK Stack 或 Loki\n- **Tracing**: Jaeger\n- **Alerting**: Alertmanager\n\n## 7. 快速部署命令\n\n### 7.1 使用 Breeze 部署\n\n```bash\n# 部署到 Kind 集群\nbreeze k8s deploy-airflow --python 3.10 --kubernetes-version v1.31.12\n\n# 升级现有部署\nbreeze k8s deploy-airflow --upgrade\n\n# 启用多命名空间模式\nbreeze k8s deploy-airflow --multi-namespace-mode\n\n# 进入集群 Shell\nbreeze k8s shell\n\n# 运行测试\nbreeze k8s tests\n```\n\n### 7.2 Skaffold 开发循环\n\n对于开发场景，支持热重载功能：\n\n```bash\nbreeze k8s dev --skaffold-args \"--auto-sync\"\n```\n\n该命令会：\n- 同步 DAG 文件到运行中的 Pod\n- 热重载 airflow-core 源码（Scheduler/Triggerer/DAG Processor/API Server）\n- 自动刷新 UI（暂不支持）\n\n资料来源：[dev/breeze/src/airflow_breeze/commands/kubernetes_commands.py:kubernetes_group]()\n\n## 8. 总结\n\nApache Airflow 的容器化和 Kubernetes 部署方案提供了企业级的灵活性。通过官方 Docker 镜像、Helm Chart 以及 Breeze 工具链，开发者和运维人员可以：\n\n- 在本地快速搭建开发环境\n- 在 Kubernetes 上实现弹性扩展\n- 通过 Kubernetes 执行器获得细粒度的资源控制\n- 利用多命名空间支持隔离测试和生产环境\n\n建议在生产部署前仔细评估业务需求，选择合适的执行器类型，并遵循本文档的最佳实践确保系统稳定性和安全性。\n\n---\n\n\n\n## Provider生态系统\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- [providers/amazon/src/airflow/providers/amazon/aws/hooks/ec2.py](https://github.com/apache/airflow/blob/main/providers/amazon/src/airflow/providers/amazon/aws/hooks/ec2.py)\n- [providers/amazon/src/airflow/providers/amazon/aws/hooks/cloud_formation.py](https://github.com/apache/airflow/blob/main/providers/amazon/src/airflow/providers/amazon/aws/hooks/cloud_formation.py)\n- [providers/google/src/airflow/providers/google/event_scheduling/events/pubsub.py](https://github.com/apache/airflow/blob/main/providers/google/src/airflow/providers/google/event_scheduling/events/pubsub.py)\n- [dev/breeze/src/airflow_breeze/prepare_providers/provider_documentation.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/prepare_providers/provider_documentation.py)\n- [dev/breeze/src/airflow_breeze/utils/packages.py](https://github.com/apache/airflow/blob/main/dev/breeze/src/airflow_breeze/utils/packages.py)\n- [providers/amazon/src/airflow/providers/amazon/get_provider_info.py](https://github.com/apache/airflow/blob/main/providers/amazon/src/airflow/providers/amazon/get_provider_info.py)\n- [airflow-core/src/airflow/utils/db.py](https://github.com/apache/airflow/blob/main/airflow-core/src/airflow/utils/db.py)\n \n\n# Provider生态系统\n\n## 概述\n\nApache Airflow的Provider生态系统是Airflow的核心扩展机制，允许用户通过安装额外的Provider包来集成各种外部服务和平台。每个Provider提供特定的Hook、Operator、Trigger、Sensor和连接类型，使用户能够在DAG中与外部系统进行交互。\n\nProvider作为独立的Python包发布到PyPI，可以通过`pip install apache-airflow-providers-`进行安装。这种模块化设计使得Airflow核心保持精简，同时用户可以根据实际需求选择性地添加所需的集成功能。\n\n## 架构设计\n\n### Provider核心组件\n\n每个Provider包通常包含以下核心组件：\n\n| 组件类型 | 描述 | 用途 |\n|---------|------|------|\n| Hook | 数据连接抽象类 | 提供与外部系统交互的基础接口 |\n| Operator | 任务执行单元 | 定义具体的业务操作逻辑 |\n| Sensor | 外部依赖检查器 | 轮询外部条件直到满足为止 |\n| Trigger | 异步事件触发器 | 支持triggerer组件异步执行 |\n| Connection | 连接配置 | 定义与外部系统的连接参数 |\n\n### 层级架构\n\n```mermaid\ngraph TD\n A[Airflow Core] --> B[Providers Manager]\n B --> C[Provider Package]\n C --> D[Hooks]\n C --> E[Operators]\n C --> F[Sensors]\n C --> G[Triggers]\n D --> H[External Services]\n E --> H\n F --> H\n G --> H\n \n subgraph \"Provider Package Structure\"\n I[get_provider_info.py]\n J[__init__.py]\n K[hooks/*.py]\n L[operators/*.py]\n M[sensors/*.py]\n end\n```\n\n## Hook实现机制\n\nHook是Provider与外部系统交互的基础桥梁。不同Provider的Hook都遵循统一的基类设计规范。\n\n### AWS Hook实现示例\n\n在Amazon Provider中，Hook通过boto3与AWS服务进行交互：\n\n```python\nclass Ec2Hook(AwsBaseHook):\n API_TYPES = frozenset({\"resource_type\", \"client_type\"})\n\n def __init__(self, api_type=\"resource_type\", *args, **kwargs) -> None:\n if api_type not in self.API_TYPES:\n raise AirflowException(\"api_type can only be one of %s\", self.API_TYPES)\n kwargs[api_type] = \"ec2\"\n self._api_type = api_type\n super().__init__(*args, **kwargs)\n```\n\n资料来源：[providers/amazon/src/airflow/providers/amazon/aws/hooks/ec2.py:24-36]()\n\n### 连接类型注册\n\nProvider通过`get_provider_info.py`文件声明其提供的连接类型：\n\n```python\n{\n \"integration-name\": \"AWS EC2\",\n \"external-doc-url\": \"https://aws.amazon.com/ec2/\",\n \"logo\": \"/docs/integration-logos/AWS-EC2_light-bg@4x.png\",\n \"tags\": [\"aws\"],\n}\n```\n\n资料来源：[providers/amazon/src/airflow/providers/amazon/get_provider_info.py:45-52]()\n\n## Provider生命周期管理\n\n### 文档生成流程\n\nProvider的文档通过Breeze工具自动生成，包括README、conf.py等文件：\n\n```python\ndef _generate_docs_conf(context: dict[str, Any], provider_details: ProviderPackageDetails):\n docs_conf_content = render_template(\n template_name=\"conf\",\n context=context,\n extension=\".py\",\n keep_trailing_newline=True,\n )\n docs_conf_path = provider_details.root_provider_path / \"docs\" / \"conf.py\"\n docs_conf_path.write_text(docs_conf_content)\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/prepare_providers/provider_documentation.py:89-97]()\n\n### 版本与依赖管理\n\nProvider的最小Airflow版本依赖通过解析dependencies确定：\n\n```python\ndef get_min_airflow_version(provider_id: str) -> str:\n provider_details = get_provider_details(provider_id=provider_id)\n min_airflow_version = MIN_AIRFLOW_VERSION\n for dependency in provider_details.dependencies:\n if dependency.startswith(\"apache-airflow>=\"):\n current_min_airflow_version = dependency.split(\">=\")[1]\n if \",\" in current_min_airflow_version:\n current_min_airflow_version = current_min_airflow_version.split(\",\")[0]\n if PackagingVersion(current_min_airflow_version) > PackagingVersion(MIN_AIRFLOW_VERSION):\n min_airflow_version = current_min_airflow_version\n return min_airflow_version\n```\n\n资料来源：[dev/breeze/src/airflow_breeze/utils/packages.py:78-91]()\n\n## CLI命令集成\n\nProvider功能通过Airflow CLI暴露，允许用户在命令行执行各种管理操作：\n\n```python\nGroupCommand(\n name=\"providers\",\n help=\"Display providers\",\n subcommands=PROVIDERS_COMMANDS,\n),\n```\n\n资料来源：[airflow-core/src/airflow/cli/cli_config.py:89-92]()\n\n### Provider相关命令\n\n| 命令 | 功能 |\n|------|------|\n| `airflow providers list` | 列出所有已安装的Provider |\n| `airflow providers links` | 显示Provider提供的链接 |\n| `airflow providers secrets` | 获取secrets后端信息 |\n| `airflow providers executors` | 获取Executor信息 |\n| `airflow providers auth-managers` | 获取认证管理器信息 |\n\n## 默认连接配置\n\nAirflow在初始化数据库时会创建一系列默认连接，这些连接覆盖了常用的外部系统：\n\n| 连接ID | 连接类型 | 默认配置 |\n|--------|----------|----------|\n| facebook_social | facebook_social | Facebook社交登录凭证 |\n| fs_default | fs | 本地文件系统 |\n| ftp_default | ftp | localhost:21 |\n| google_cloud_default | google_cloud_platform | GCP默认项目 |\n| http_default | http | httpbin.org |\n| iceberg_default | iceberg | Iceberg REST服务 |\n\n资料来源：[airflow-core/src/airflow/utils/db.py:180-220]()\n\n## 事件驱动架构\n\n### MessageQueueTrigger集成\n\nProvider支持通过`MessageQueueTrigger`实现事件驱动的任务执行：\n\n```python\nclass GooglePubSubEvent(Protocol):\n scheme = \"google+pubsub\"\n\n def trigger_class(self) -> type[BaseEventTrigger]:\n return PubsubPullTrigger\n```\n\n资料来源：[providers/google/src/airflow/providers/google/event_scheduling/events/pubsub.py:52-57]()\n\n### 异步Trigger架构\n\n```mermaid\nsequenceDiagram\n DAG Task ->> Trigger: 创建Trigger实例\n Trigger ->> MessageQueue: 订阅消息队列\n MessageQueue -->> Trigger: 事件到达\n Trigger ->> Triggerer: 触发条件满足\n Triggerer ->> DAG Task: 任务执行完成\n```\n\n## Provider发现机制\n\n### 自动注册流程\n\n当Airflow启动时，Providers Manager自动扫描并加载所有已安装的Provider：\n\n```mermaid\ngraph LR\n A[启动Airflow] --> B[扫描Provider包]\n B --> C[加载Hook]\n B --> D[加载Operator]\n B --> E[加载Sensor]\n B --> F[注册Connection类型]\n C --> G[注册到UI]\n D --> G\n E --> G\n F --> G\n```\n\n## 主流Provider一览\n\n### Amazon Provider (apache-airflow-providers-amazon)\n\n提供与AWS服务的深度集成，包括：\n\n- **计算服务**：EC2、Lambda、ECS\n- **数据服务**：Glue、S3、Redshift、Athena\n- **编排服务**：Step Functions、CloudFormation\n- **机器学习**：SageMaker、Bedrock\n\n资料来源：[providers/amazon/src/airflow/providers/amazon/aws/hooks/cloud_formation.py:18-25]()\n\n### Google Provider (apache-airflow-providers-google)\n\n集成Google Cloud Platform服务，包括BigQuery、GCS、Cloud Run等。\n\n### Apache Kafka Provider\n\n提供Kafka消息队列的Hook和Operator支持，用于流数据处理场景。\n\n## 总结\n\nProvider生态系统是Apache Airflow实现高度可扩展性的核心机制。通过标准化的组件接口、统一的生命周期管理和灵活的CLI集成，Provider使得Airflow能够优雅地连接各种外部系统。用户可以根据工作需求选择性地安装Provider，实现与云服务商、数据库、消息队列等数十种外部平台的深度集成。\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. intro：Airflow简介与核心概念。围绕“Airflow简介与核心概念”模拟一次用户任务，不展示安装或运行结果。\n2. quickstart：快速开始与安装指南。围绕“快速开始与安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. architecture：系统架构详解。围绕“系统架构详解”模拟一次用户任务，不展示安装或运行结果。\n4. components：核心组件详解。围绕“核心组件详解”模拟一次用户任务，不展示安装或运行结果。\n5. executors：执行器类型与选择。围绕“执行器类型与选择”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. intro\n输入：用户提供的“Airflow简介与核心概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quickstart\n输入：用户提供的“快速开始与安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture\n输入：用户提供的“系统架构详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. components\n输入：用户提供的“核心组件详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. executors\n输入：用户提供的“执行器类型与选择”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / intro：Step 1 必须围绕“Airflow简介与核心概念”形成一个小中间产物，并等待用户确认。\n- Step 2 / quickstart：Step 2 必须围绕“快速开始与安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture：Step 3 必须围绕“系统架构详解”形成一个小中间产物，并等待用户确认。\n- Step 4 / components：Step 4 必须围绕“核心组件详解”形成一个小中间产物，并等待用户确认。\n- Step 5 / executors：Step 5 必须围绕“执行器类型与选择”形成一个小中间产物，并等待用户确认。\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- airflow-core/src/airflow/models/dag.py\n- airflow-core/src/airflow/models/taskinstance.py\n- airflow-core/src/airflow/_shared/state/__init__.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"
}