实时数仓开发插件拆解第一篇 | 开发到上线八个阶段详解

目录

• • 一条实时任务，写完 SQL 只是开头^[2]
• • 离线经验直接搬过来，会漏掉什么^[3]
• • 最危险的地方，是三种看起来已经完成的状态^[4]
• • 八个阶段把上线拆成可检查的动作^[5]
• • 提交、发布、启动是三件不同的事^[6]
• • 两种运行模式决定确认节奏^[7]
• • 哪些实时任务适合进来^[8]
• • 它解决了什么，又留下了哪些边界^[9]

一条实时任务，写完 SQL 只是开头

一条常见的实时需求可以写得很短。把订单消息从 Kafka 读出来，按十秒窗口计算商品销售额，结果写入 Paimon，供实时看板查询。

SQL 可能一天就写完了。接下来还有一串动作。Kafka 中的消息有没有重复，窗口按事件时间还是处理时间切分，引用的元表是不是已经发布，作业编译有没有结束，调试输出对不对，提交以后有没有通过发布校验，上线后从哪里恢复，启动失败时回退到哪个版本。

离线任务写完调度，第二天跑一批数据，发现结果不对还可以重跑那一个分区。实时任务盯着一条持续流动的数据流，错误版本一旦接上流量，就会继续写下游。等看板发现数字不对时，可能已经积了一段时间的错数。停下来之后，恢复点、状态和消费位置又会成为新的判断。

realtime-data-pipeline 处理的就是这一段从需求到上线的过程。它把任务发现、设计、构建、调试、配置、提交、发布和启动排成一条有序路径，每一步都要求明确对象、机器证据和必要确认。它不替代 Flink、Kafka 或湖仓平台，负责的是让这些平台上的动作按合适的顺序发生，并把结果留下来。

离线经验直接搬过来，会漏掉什么

离线开发最熟悉的是建表、写 ETL、补调度、跑结果。实时链路多了几层持续变化的状态。

上游消息会一直到达，字段和流量可能变。作业本身有版本，平台里还存在开发版、已发布版和正在运行的实例。任务启动以后有状态、检查点和消费位置，有些动作还要选择恢复点或重置时间。下游看板读取的是持续更新的结果，错一段时间和错一批数据，处理方式并不相同。

这些状态彼此牵连。开发版元表存在，不代表发布版可用。编译命令返回成功字样，不代表作业已经进入终态。提交成功只说明平台受理了请求，发布成功还要看到对象回读和版本。任务显示运行中，也不证明进来的是新款 SQL。

如果这些动作只靠几条聊天消息推进，问题很容易被留到线上。开发者记得昨天发的是 v3，接手的人看到的却是平台上另一个版本。有人以为任务已经停止，实际实例还在消费。超时以后重复点一次提交，平台收到两个请求，后续排查会非常难受。

流水线用状态文件和证据账本记录这些事实。对象编号、版本、追踪 ID、回读时间和当前阶段都有固定位置。换一个会话，先和平台状态对账，不靠上一轮对话恢复记忆。

最危险的地方，是三种看起来已经完成的状态

实时开发里最难识别的风险，经常带着一个合理的完成提示。

编译通过看起来可以继续。它证明代码能够过编译，业务结果是否正确还没验证。过滤条件写错、窗口边界偏了、上游暂时没有流量，调试查询都可能返回零行。查询失败也是一种情况，不能把它写成“没有数据”，更不能把空结果当成业务正确。

提交成功看起来可以去启动。提交和发布是两个动作。发布后要回读待发布对象、版本和平台链接，确认这次发布的是不是审核过的那一版。把提交成功当成上线成功，最后可能启动的是旧版本，或者对象根本没有发布。

平台显示启动完成，看起来已经交付。生产环境启动会消费真实流量，还会写入下游。恢复点从哪里来，原任务是否已经停止，预计停顿多久，回退边界是什么，都需要在动作发生前说清。实例进入运行态只说明启动动作已经执行，监控、延迟、检查点和下游结果仍要继续核对。实时任务启动后的回退成本通常高于离线重跑，确认不能复用上一次的同意。

证据和确认因此要分开。编译回执、提交回执、发布回读来自平台，证明动作发生过。阶段确认和风险确认来自用户，证明某个高风险动作被授权。两类记录不能互相顶替，平台回读不能替用户做决定，用户说“可以”也不能代替平台已经发布。

八个阶段把上线拆成可检查的动作

一条任务从发现到启动，走八个阶段。

discover 先确认任务叫什么、来源是什么、目标是哪张表、属于哪个项目和实例。对象没有定位清楚，后面所有动作都没有可靠对象。

design 处理实时 SQL 和元表关系。引用表必须能回读到已发布版本，开发版存在不算可用。搜索结果是模糊匹配，表名要完全相等。来源查不到时先查项目和权限，不能随手建一张空壳表顶上。

build 负责渲染任务、创建对象和发起编译。编译要看终态，中途返回的成功提示不能直接当成完成。平台回执里要能看到对象和观察时间。

debug 解决结果对不对。调试可以选择线上采样或构造输入。采样要留意流量和延迟，构造输入要先回读服务端字段。输出为空时先查过滤、窗口和上游流量，不把空结果当成验证通过。

configure 明确 SLA、运行参数和资源配置。明确不设置 SLA 也可以是一个决定，但这个决定要由用户当次说清，不能因为字段为空就自动跳过。

submit 发起提交并等待终态。拿到提交回执后，还要看发布前校验。校验停在人工确认时，流程把平台链接交给用户，不自行往下走。

publish 才把通过校验的版本发布。发布后必须回读对象、版本和平台返回的信息。没有对象回读，发布阶段不能结束。

start 处理启停和恢复。启动、重启、热更新、停止、下线、取消部署各有边界。启动前要确认对象、环境、版本、恢复点、SQL 影响、预计停顿和回退安排。迁移任务还要确认原任务已经停止，恢复点由用户给出具体值。

提交、发布、启动是三件不同的事

把这三个动作分开，是实时流水线最重要的设计之一。

提交是平台收到任务请求。发布是把准备上线的对象和版本确定下来。启动是让实例进入消费和计算状态。三个阶段都能显示某种“完成”，实际含义完全不同。

平台上的开发版、待发布对象和运行实例也可能不是同一个版本。发布后回读对象，启动前再次确认版本，能避免“界面上有个任务在跑”被误认为“审核过的那一版已经上线”。

启动前的确认也按动作区分。上一次发布确认不能拿来启动，昨天的重启同意不能覆盖今天的热更新。任务涉及线上流量，确认记录要能对应正在发生的动作。

超时处理同样依赖这些边界。提交或启动超时后，先回读平台状态，确认请求是否受理。不能因为界面没有及时返回，就再发一次。实时任务重复启动、重复消费比离线重复执行更容易把下游写乱。

两种运行模式决定确认节奏

实时流水线在开工前要求用户选一种模式，并把模式和目标写进台账。没有模式或目标，阶段推进和高风险动作都会被拒绝。

manual 适合生产首次上线、口径复杂、上下游影响大或启动会消费真实流量的任务。每个阶段都要在当前阶段确认，确认不会传递到下一阶段。

auto 适合测试环境、低风险批处理或明确要求全自动的任务。它自动推进阶段，但不会跳过元表发布回读、编译终态、提交回执和发布回读。启动用的恢复点必须提前写进 Goal，不能自动取当前时间。

自动模式也不等于权限无限放大。Goal 之外的写操作要停下确认，执行结束要留下追踪 ID。用户把允许动作和启动策略写清楚，AI 才能在这个范围内连续执行。

模式会跟着任务状态保留。换个会话回来，打开状态能看到当初为什么选、允许做什么、当前走到哪一步。确认节奏由任务风险决定，不靠谁当时记得更多。

哪些实时任务适合进来

从消息队列到实时宽表，再供看板和风控消费的新建任务，适合从 discover 一路走到启动。它需要先确认来源元表、字段类型和任务版本，再验证结果，最后处理发布与启动。

老任务迁移也很适合。迁移最容易漏掉的是原任务是否已经停止、恢复点在哪里、迁移前后的对象和版本是否一致。SQL 文件只是其中一部分，流水线把这些动作放在同一个任务记录里。

巡检、诊断、参数调整和生命周期操作，可以使用同一套执行器与证据账本。巡检走只读接口，发现问题后要改状态，就进入另一条带确认的动作路径。开发和运维因此不用在两套完全不同的记录方式之间来回切换。

需要跨会话、跨人交接的实时任务，收益通常更直接。对象编号、当前版本、最近一次发布回读、恢复点和执行追踪 ID 都有固定位置，接手的人先看状态，再决定下一步。

临时查一条流里的数据，不用建完整任务流程。偶尔跑一条 SQL、看一眼当前状态，有更轻的入口。没有配置执行器时，流程会停在环境检查和门控阶段，也不会猜一个命令名继续执行。

它解决了什么，又留下了哪些边界

这条流水线能确认任务对象被定位，引用元表有发布回读，编译和提交有终态回执，发布后能看到对象与版本，启动前有当次确认和恢复点。跨会话继续时，它会先和平台对账，不把旧会话里的结论直接当成现场状态。

它不能替团队定义业务口径。指标怎么算、窗口是否合理、重复消息怎样去重，仍然要由业务和开发给出判断。它也不是调度平台，不负责报警、值班和集群可用性。任务跑起来以后稳不稳，还要靠监控、容量和故障处理。

仓库当前记录了本地开源组件的真实运行路径，也明确标注平台 CLI 和 MCP 路径尚未完成真实环境验证。项目接入自己的平台时，要先做执行器体检和一轮低风险联调，不能因为文档里流程完整，就认为现场命令已经全部可用。

下一篇会拆开实时流水线的架构，讲状态机、证据账本、高风险确认、执行器和知识库读写怎样组合在一起，以及为什么“平台回读”和“用户确认”不能互相替代。

项目地址 MrSuiChuan/realtime-data-pipeline^[1]许可证 Apache-2.0

引用链接

[1] MrSuiChuan/realtime-data-pipeline: https://github.com/MrSuiChuan/realtime-data-pipeline