5.3 插件与Provider

5.3 插件与 Provider

本节摘要：Provider 是官方拆出去的对接包，内含 Operator、Hook、Sensor，用来连数仓、对象存储、消息队列。插件则能加菜单、宏、执行器钩子。扩展让 Airflow 不必为每个系统重写调度器，也让 Worker 镜像和供应链变得更重。装包前问：谁维护、版本如何跟核心走、凭证是否仍走 Connection。

本节导读

阅读完本节，你应当能够：

1. 区分 Provider 与本地插件的职责
2. 把新系统对接优先落到已有 Provider，而不是 Bash 调自制脚本
3. 说明 Worker 与 Scheduler 镜像的依赖为何必须一起升级
4. 列出插件能破坏解析与 UI 的方式

一、为什么要拆 Provider

核心包不可能内置全世界的云 SDK。Provider 机制让社区维护上百个对接。你写 DAG 时 import 的 Postgres 或 Kubernetes 算子，往往来自独立发行的包。好处是核心可以升级调度，对接可以按需装。坏处是版本矩阵：核心升了，Provider 的导入路径改了，解析全红。

安装在执行侧必须有。只在开发笔记本装 Provider，生产 Worker 没有，运行期 ModuleNotFound。K8s 执行器尤其要把 Provider 打进任务镜像。Scheduler 为了解析类名，通常也需要能 import 同一个包，否则文件处理器报导入错误，图都挂不出来。

核心调度 ──► 不负责云 SDK
Provider ──► Hook + Operator + 文档
插件     ──► UI、宏、额外蓝图
​

自定义 Operator 放团队内部包，通过正规插件或 Python 包加载，不要把类定义复制进每一份 DAG 文件。复制会导致修一个超时 bug 要改二十处。

二、插件能做什么、不该做什么

插件可注册菜单、Flask 视图、macros、operator 额外链接。适合加内部血缘页、加公司宏。不适合在插件加载时连生产数据库、做迁移、起后台线程。加载发生在 Web 与调度器启动路径上，慢插件等于慢每一次重启。

宏让模板里出现自定义函数。要用纯函数，输入来自上下文，不要在宏里发网络请求。模板渲染在调度或执行的特定阶段，副作用难测。

三、供应链与发布

锁版本。生产镜像用锁定的依赖清单，CI 里 import 所有会用到的 Operator 类。不要在任务运行时 pip install。那既慢又不审计。

第三方 Provider 看维护活跃度。停更的包等于把调度器绑在旧 SDK。内部封装要薄：只补日志、重试分类、公司 conn 命名，不要把业务 SQL 藏进 Operator 默认参数，否则业务变更必须发平台包。

⚠️ 常见坑：在 DAG 文件里 sys.path 插入临时目录加载未发布插件。调度器多机时有的节点有、有的没有，导入错误随机出现。
💡 关键直觉：扩展的正规入口是包与镜像，不是运行时改路径。能 import 的集合，就是你的攻击面集合。

测试插件要在与生产相同的加载顺序下做。本地 airflow webserver 能起来，不代表调度器子进程能解析。两边都起一次。

文档：每个允许使用的 Provider 写在平台清单里，DAG 评审对照清单。清单外的包默认拒绝，避免数据科学家随手加入来源不明的 Hook。

原文把 Providers 成熟视为连接器事实标准。动手时把它当“公司允许的插座规格”。插座可以多，电线（凭证）仍只能走 Connection。

执行器本身也可以被视为扩展，但自制执行器要完整实现入队、sync、心跳，漏了 sync 就会幽灵 running。除非有不能用 Celery/K8s 的硬约束，不要走这条路。

四、允许清单怎么维护

平台团队维护一张表：Provider 名、锁定版本、用途、谁批准、适用队列。DAG 评审对照 import。清单外的包在 CI 失败。新增包走申请：维护是否活跃、传递依赖体积、是否必须、凭证是否仍走 Connection。批下来才进镜像。数据科学家的笔记本包集合，不是生产清单。

内部 Operator 包版本与核心版本一起发。薄封装：统一日志字段、统一重试分类、统一 conn 命名前缀。禁止在 Operator 默认参数里写死业务表名。业务变化应改 DAG，不该逼平台发版。内部包变成第二框架之日，就是升级核心变得不可能之日。

插件启动耗时要测。Web 冷启动多十秒，滚动发布就会有人以为平台挂了。插件里的视图要走与 UI 相同的认证，不要另开一个无鉴权蓝图“方便内部”。那是第二攻击面。宏只做纯函数，单测宏，不要在宏里读 Variable。

供应链：镜像构建固定源，禁止运行时访问任意 pip 源。CI import 所有允许的 Operator 类。漏洞修复跟 Provider 与系统库，不只跟核心。过时 Provider 强制替换或下线对接。

问题：能不能把公司全部 Hook 写进一个巨包？

能，但升级会变成巨石。按域拆包更好：数仓、对象存储、内部工单。DAG 只依赖用到的包。巨包还会让解析 import 变慢。内部包的第一原则仍是薄，第二原则才是拆。

问题：自制执行器什么时候才正当？

现有 Celery 与 Kubernetes 都无法表达的资源类型，且有人能完整实现 sync 与心跳并接受幽灵任务的责任。这个条件在大多数公司不成立。正当需求更常是“加一个队列”，不是“加一种执行器”。把自制执行器当扩展练习，会在状态机上留下无法值班的洞。

五、下线一个 Provider 的姿势

先从允许清单标记弃用，CI 对新增 import 失败，旧 DAG 限期改写到替代算子或内部薄封装。镜像暂留旧包直到截止日期，到期从镜像删除，导入测试会揪出漏网。不要先删镜像再通知，那会让生产解析全红，像一次无计划故障。下线是供应链卫生，与装新包对称。对称做不好，清单会只进不出，镜像无限膨胀，解析变慢，安全面变大。内部巨包的拆分同样走弃用窗口。插件下线要同时从 Web 与 Scheduler 启动路径移除，避免一台有一台没有的随机菜单。随机是多机部署下插件事故的典型形状。

六、解析侧与执行侧依赖必须同清单

只在 Worker 装 Provider、调度器不装，图会导入失败。只在调度器装、Worker 不装，图绿运行红。清单以“两侧都有”为通过。K8s 任务镜像是执行侧，调度器 Deployment 是解析侧，两边 Dockerfile 应对同一锁定文件，或明确谁少谁多。少必须是有意，例如调度器不需要 GPU SDK。无意的少是事故。CI 的导入测试要在两种镜像里都跑，至少在执行镜像跑、在解析环境跑。只跑一种，会把另一种留给生产发现。生产发现缺包，往往在高峰。高峰缺包的修复是紧急发镜像，紧急发镜像最容易跳过扫描。扫描跳过，供应链洞就从这一次紧急开始。所以同清单是安全问题，不只是方便问题。方便问题可以明天修。安全问题在紧急窗口被放大。放大前用同清单把它缩小。缩小是 5.3 对 6.3 的承诺。

七、镜像锁定文件的评审

锁定文件变更视为供应链变更，与 DAG 变更分开。变更说明写：为何加包、版本、传递依赖是否膨胀、两侧是否同清单。缺说明不准构建生产镜像。不准是牙齿。牙齿防止“顺手加一个 SDK”。顺手会让解析变慢、攻击面变大、升级变难。变难之后，漏洞修不动。修不动则 5.2 的执行侧任意代码风险上升。上升来自过时包。过时包来自顺手。顺手来自无评审的锁定文件。评审在本节。本节把锁定文件当合同附件。附件与 DAG 合同分开，避免一次 PR 既改 SQL 又加包，无法二分。无法二分是 4.1 反对过的。反对在供应链同样成立。成立就要分开。分开后，导入测试在两种镜像跑。跑不过，锁定文件回滚。回滚比生产缺包时紧急构建安全。紧急构建会跳扫描。跳扫描是 5.3 最怕的窗口。窗口用平时评审缩小。缩小靠牙齿。牙齿靠说明。说明靠人写。人写为何。为何要能在三个月后仍读得懂。读不懂的为何等于没有。没有就打回。打回几次，顺手会停。停了，清单才能只进有主的包。有主才能下线。下线姿势在上一节。上一节加本节，构成 Provider 卫生。卫生不是一次性大扫除。是每次锁定变更的小拒绝。小拒绝可值班。大扫除靠运动。运动与 6.1 一样不可持续。持续靠每次构建。每次构建看说明。说明过了才构建。构建过了才部署。部署过了 DAG 才能 import。import 失败会让所有图消失。消失是全局事故。全局事故比一个被打回的 SDK 贵。贵贱再算一次。算清就会写说明。写说明就会少顺手。少顺手则镜像瘦。瘦则解析快。快是 6.2 的第一段。第一段从 5.3 的锁定文件开始。开始在评审。评审结束。构建开始。开始必须有说明。说明结束本节。本节结束 Provider。Provider 结束第 5 章。第 5 章结束于可拒绝。可拒绝才可扩展。扩展结束。

八、紧急构建的补扫描

若生产缺包被迫紧急发镜像，事后二十四小时内必须补跑锁定文件评审与导入测试，否则视为未关闭事故。未关闭不准再发下一次紧急。不准是牙齿。牙齿防止紧急成为常态跳扫描通道。通道是 5.3 最怕的窗口。窗口用事后补扫描关上。关上结束供应链洞的放大。放大结束于平时同清单。同清单结束一种镜像漏测。漏测结束高峰缺包。缺包结束全局导入失败。失败结束于两侧都跑导入。都跑结束随机。随机结束插件多机不一致。不一致结束。卫生成为每次构建的小拒绝。小拒绝结束运动式大扫除。大扫除结束。清单只进有主的包。有主结束停更绑架。绑架结束。5.3 结束于紧急也要补牙。补牙结束本节。

十、解析镜像故意少装 GPU SDK 要写进清单备注

有意的少必须标注，免得下一次紧急构建有人“补全”把调度器镜像撑爆。撑爆结束解析变慢。变慢结束有意。有意结束于备注。备注结束误补。误补结束。清单备注结束 5.3 的最后一牙。牙结束两侧同清单的例外管理。例外结束于写下来。写下来结束口口相传。口口相传结束。

本节速览

• Provider 提供对接，核心提供调度，版本要一起规划
• 解析侧与执行侧都要能 import
• 插件加载禁止重副作用
• 内部封装保持薄，业务留在 DAG 与 SQL
• 禁止运行时装包与临时路径
• 公司维护允许清单，清单外默认拒绝

下一章把写法、性能和测试收成可发布的纪律。