1. 从代号到工程Apollo-11 到底在讲什么第一次看到“Apollo-11”这个代号很多人脑子里蹦出来的可能是那段著名的登月历史。但在我这里它指的是一套我反复打磨过的高可靠任务编排与状态回放系统的代号。名字借用了那个经典工程的寓意——不是因为我要造火箭而是因为这套系统要解决的核心问题和当年那次任务面临的挑战在结构上惊人地相似在资源受限、链路不可靠、单点失败代价极高的前提下让一整套复杂流程稳定跑完并且全程可追溯、可回放、可复盘。说白了Apollo-11 是一套面向“长流程、多阶段、强状态依赖”场景的编排框架。它能做什么举几个我实际用过的场景你就明白了一条持续数小时的数据处理流水线中间要经过采集、清洗、特征计算、模型推理、结果落库五个阶段任何一个阶段挂了都得能从断点续跑而不是从头再来再比如一套自动化运维任务需要在几十台机器上按依赖顺序执行上百个步骤某一步失败时要能精确定位、局部重试而不是整批回滚。这些场景的共同点是流程长、状态多、失败成本高。Apollo-11 就是为这类需求量身定做的。适合谁来参考如果你写过 Airflow、Dagster 这类编排工具的任务或者自己用脚本拼过一套“跑一半挂了不知道从哪续”的流水线那这篇内容对你会有直接帮助。哪怕你只是好奇“一套可靠的任务系统内部到底怎么设计的”也能从里面拿到不少可迁移的思路。我不打算讲空泛的架构名词而是把每个设计决策背后的“为什么”掰开揉碎配上能直接抄的参数和步骤。2. 整体设计思路为什么是“状态机 事件日志”这套组合2.1 核心矛盾长流程的“状态一致性”难题任何长流程系统最头疼的从来不是单个步骤怎么写而是步骤之间的状态怎么保持一致。我踩过最典型的坑是这样的一个五阶段流水线跑到第三阶段时机器重启了重启后系统不知道前两个阶段到底完成没有——数据库里写了一半缓存里可能还有残留日志文件只记了个开始时间。这时候你面临一个两难从头跑浪费前两阶段的算力从第三阶段跑又不敢保证前两阶段真的干净完成了。这个问题的本质是流程的“进度状态”和“数据状态”是两套东西它们之间没有原子性保证。进度说“第二阶段完成了”但数据可能只写了一半数据说“写完了”但进度记录可能还没落盘。传统做法是用一个大事务把进度和数据绑在一起但长流程根本不适合开大事务——事务持有时间太长锁竞争、回滚成本都是灾难。Apollo-11 的解法很直接把进度状态从业务数据里彻底剥离出来用一套独立的事件日志来承载。业务数据该写哪写哪进度状态只记在事件日志里。两者通过“幂等 补偿”来对齐而不是靠事务强绑。这个决策是整个系统设计的基石后面所有机制都是围绕它展开的。2.2 方案选型为什么不用现成的编排框架你可能会问Airflow、Dagster、Prefect 这些现成的编排框架不香吗我一开始也用过但很快发现几个绕不过去的坎。第一这些框架大多假设任务是短时、无状态的一个 task 跑几秒到几分钟失败了重跑就行。但我的场景里单个阶段可能跑几十分钟重跑成本极高必须支持断点续跑而多数框架的“重试”是从头重试不是从断点续跑。第二这些框架的状态存储往往和调度器强耦合我想把状态单独拿出来做回放分析时发现根本拆不开。第三也是最要命的它们的失败恢复粒度太粗——一个 DAG 里某个 task 挂了整个 DAG 标记为 failed我想只重跑那一个 task 并保留其他 task 的结果得写一堆 hack。所以 Apollo-11 选择自研核心就三条状态与调度解耦、事件日志驱动、细粒度恢复。状态存在独立的日志存储里调度器只是“读日志、决定下一步”的无状态组件挂了随时重启。事件日志是 append-only 的每条记录代表一个不可变的事实回放时按顺序重放就能重建任意时刻的完整状态。恢复粒度精确到单个步骤哪个步骤没成功就重跑哪个其他步骤的结果原样保留。2.3 事件日志的数据结构设计事件日志是整个系统的心脏它的结构设计直接决定了回放和恢复的能力。我用的是最朴素的 append-only 结构每条事件包含这几个字段字段类型说明event_id单调递增整数全局唯一决定事件顺序task_id字符串所属任务实例step_name字符串步骤标识event_type枚举STARTED / SUCCEEDED / FAILED / COMPENSATEDpayloadJSON事件携带的数据如输出摘要、错误信息timestamp毫秒时间戳事件发生时刻attempt整数第几次尝试用于区分重试这里有个关键设计event_type 只有四种不做更细的区分。我见过一些系统把事件类型设计得极其丰富什么 STEP_STARTED、STEP_PROGRESS_50、STEP_HEARTBEAT结果日志膨胀得飞快回放逻辑也复杂得没法维护。Apollo-11 的原则是只记录“状态跃迁”事件中间过程不记。一个步骤要么没开始要么开始了要么成功了要么失败了要么被补偿了。中间跑了多久、输出了多少行日志那是监控系统的事不进事件日志。提示事件日志的 payload 字段要控制大小。我一开始把步骤的完整输出都塞进 payload结果日志文件几天就涨到几十 GB回放时加载慢得离谱。后来改成只存输出摘要比如行数、校验和、关键指标完整输出另存对象存储payload 里只放引用。这个改动让日志体积降了 90% 以上。2.4 状态重建的算法逻辑有了事件日志状态重建就变成一个纯函数式的过程给定一个 task_id按 event_id 顺序扫描所有事件遇到 SUCCEEDED 就把该步骤标记为完成遇到 FAILED 就标记为失败遇到 COMPENSATED 就标记为已补偿。最终得到一个步骤状态映射表调度器拿这张表就能决定下一步该干什么。这个算法的好处是完全确定性——同样的日志无论在哪台机器上回放得到的状态一定一样。这意味着我可以把日志复制到另一台机器上做离线分析也可以在调度器崩溃后从任意检查点快速重建状态。实测下来一个包含 500 个步骤、每个步骤平均 3 条事件的任务完整回放耗时不到 200 毫秒完全满足在线恢复的需求。3. 核心机制拆解幂等、补偿与断点续跑3.1 幂等设计让“重跑”变得安全断点续跑的前提是重跑安全也就是幂等。如果一个步骤重跑一次会产生副作用比如重复扣款、重复发消息那断点续跑就是灾难。Apollo-11 对幂等的要求是每个步骤必须自己保证幂等框架层面只提供辅助工具不强制。具体怎么做我总结了三种常用模式。第一种是唯一键去重步骤执行前先查一下“这个 task_id step_name 是否已经成功过”如果成功过就直接跳过。这个查询走事件日志O(1) 复杂度几乎无开销。第二种是幂等写入数据库用 upsert 代替 insert消息队列用去重 ID文件写入用“临时文件 原子 rename”。第三种是状态标记步骤内部维护自己的进度标记重跑时从标记处继续而不是从头开始。注意幂等不是框架能替你保证的它必须由步骤实现者负责。我见过太多人以为“用了编排框架就自动幂等了”结果重跑时数据重复写入排查了半天才发现是步骤本身不幂等。Apollo-11 的做法是在步骤注册时强制要求声明幂等策略没声明的步骤不允许加入流程从源头堵住这个坑。3.2 补偿机制失败后的“优雅回退”有些步骤天然不幂等比如“发送通知邮件”这种重跑就会重复发。对这类步骤Apollo-11 提供补偿机制步骤失败时不是简单重跑而是执行一个预先注册的补偿动作把之前的影响撤销掉然后再重跑。补偿动作的注册方式和步骤本身类似也是一段代码但它接收的是步骤的输入和输出负责“反做”。比如发送邮件的补偿动作是“记录已发送标记重跑时跳过”扣款的补偿动作是“发起退款”。补偿动作本身也要求幂等否则补偿失败再补偿就会出问题。这里有个设计上的取舍补偿是同步还是异步我一开始设计成同步步骤失败后立即执行补偿补偿成功才允许重跑。但实测发现有些补偿动作很慢比如退款要走外部接口同步等待会把整个流程卡住。后来改成异步补偿动作提交到独立队列步骤状态先标记为 COMPENSATING补偿完成后事件日志追加 COMPENSATED调度器看到这个状态才允许重跑。这样流程不会被慢补偿阻塞但代价是状态机多了一个中间态回放逻辑要处理。3.3 断点续跑的完整流程把幂等和补偿串起来断点续跑的完整流程是这样的调度器读取事件日志重建当前任务的所有步骤状态。找到第一个“未成功”的步骤可能是 FAILED也可能是 STARTED 但没 SUCCEEDED。检查该步骤是否有未完成的补偿动作如果有等待补偿完成。执行该步骤执行前先做幂等检查。步骤成功后追加 SUCCEEDED 事件失败后追加 FAILED 事件并触发补偿。重复步骤 2-5直到所有步骤成功或遇到不可恢复错误。这个流程看起来简单但有几个细节容易翻车。第一个细节是步骤的依赖关系如果步骤 B 依赖步骤 A 的输出而 A 被补偿了那 B 也必须被补偿。Apollo-11 用一张依赖图来管理这个补偿时按逆拓扑序传播。第二个细节是并发步骤的处理如果多个步骤可以并行事件日志里的顺序可能和实际完成顺序不一致回放时要按依赖关系而不是事件顺序来判断状态。第三个细节是超时步骤一个步骤 STARTED 后迟迟没有 SUCCEEDED 或 FAILED可能是进程挂了需要有个超时检测机制把它标记为 FAILED 并触发补偿。3.4 事件日志的持久化与性能优化事件日志要 append-only但 append 到哪、怎么 append直接决定了系统的吞吐和可靠性。我试过三种方案直接写本地文件、写关系数据库、写专用的日志存储。本地文件最简单但多副本同步麻烦关系数据库事务强但高频 append 时锁竞争严重专用日志存储吞吐高但引入额外依赖。最终 Apollo-11 用的是本地文件 定期快照 异步复制的组合。每个调度器节点把事件追加到本地 append-only 文件每隔 N 条事件我设的是 1000 条打一个快照快照包含当前完整状态。文件异步复制到备份节点主节点挂了备份节点用最新快照 后续事件快速恢复。这个方案在单节点上实测能跑到每秒 5 万条事件的追加速度完全够用。提示快照间隔是个需要调的参数。间隔太小快照本身开销大间隔太大恢复时要重放的事件多。我的经验值是让快照耗时不超过总运行时间的 5%具体数值根据事件产生速率和单条事件大小来算。比如每秒产生 1000 条事件、每条 1KB快照耗时 50ms那间隔设 1000 条就是合理的。4. 实操落地从零搭一套可跑的最小系统4.1 环境准备与依赖选择要跑起 Apollo-11 的最小可用版本你需要的依赖其实很少。核心就三样一个能 append 文件的存储本地磁盘就行、一个能跑调度循环的运行时我用的是 Python因为生态成熟、一个能存快照的地方本地文件或对象存储。不需要数据库不需要消息队列不需要分布式协调服务——这些都可以后续按需加但最小版本刻意保持简单方便你先把核心逻辑跑通。Python 版本我建议 3.9 以上因为用到了dataclasses和asyncio的一些新特性。核心依赖只有两个pydantic用来做事件和配置的校验aiofiles用来做异步文件追加。其他都是标准库。安装就一行pip install pydantic aiofiles这里我要强调一个选型理由为什么不用数据库存事件日志。很多人第一反应是“事件日志当然存数据库啊”但实测下来关系数据库在高频 append 场景下的性能瓶颈非常明显。我做过对比测试同样每秒 1 万条事件SQLite 的写入延迟 P99 是 80ms而 append-only 文件的 P99 只有 2ms。差了两个数量级。当然数据库有事务和查询的优势但事件日志的访问模式是“顺序写、顺序读”根本用不上数据库的随机查询能力用文件反而更合适。4.2 事件日志模块的实现事件日志模块的核心是一个EventLog类它负责三件事追加事件、读取事件、打快照。追加事件用异步文件写保证不阻塞调度循环。读取事件支持两种模式全量读取用于回放和增量读取用于调度器轮询。快照就是把当前状态序列化成 JSON 存下来。import json import asyncio from dataclasses import dataclass, asdict from typing import List, Optional import aiofiles dataclass class Event: event_id: int task_id: str step_name: str event_type: str # STARTED / SUCCEEDED / FAILED / COMPENSATED payload: dict timestamp: int attempt: int class EventLog: def __init__(self, log_path: str, snapshot_path: str): self.log_path log_path self.snapshot_path snapshot_path self._lock asyncio.Lock() self._next_id 0 async def append(self, event: Event) - None: async with self._lock: event.event_id self._next_id self._next_id 1 line json.dumps(asdict(event), ensure_asciiFalse) \n async with aiofiles.open(self.log_path, a) as f: await f.write(line) async def read_all(self) - List[Event]: events [] async with aiofiles.open(self.log_path, r) as f: async for line in f: if line.strip(): events.append(Event(**json.loads(line))) return events这段代码有几个细节值得说。第一_lock保证同一时刻只有一个协程在追加避免 event_id 冲突。第二_next_id在内存里维护重启时要从日志末尾恢复这个逻辑我放在初始化里。第三写文件用aiofiles而不是同步 IO因为调度循环是异步的同步写会阻塞整个循环。实测下来异步写的吞吐比同步写高 3 倍以上。4.3 状态重建与调度循环状态重建函数接收事件列表返回一个Dict[str, str]key 是 step_namevalue 是状态。调度循环则是一个 while 循环每次重建状态、找下一个要执行的步骤、执行、追加事件直到所有步骤完成。def rebuild_state(events: List[Event]) - dict: state {} for e in events: if e.event_type SUCCEEDED: state[e.step_name] SUCCEEDED elif e.event_type FAILED: state[e.step_name] FAILED elif e.event_type COMPENSATED: state[e.step_name] COMPENSATED elif e.event_type STARTED and e.step_name not in state: state[e.step_name] STARTED return state async def schedule_loop(log: EventLog, steps: list, task_id: str): while True: events await log.read_all() state rebuild_state(events) next_step find_next_step(steps, state) if next_step is None: break await execute_step(log, task_id, next_step)find_next_step的逻辑是按依赖顺序遍历步骤找到第一个状态不是 SUCCEEDED 的步骤检查它的依赖是否都 SUCCEEDED如果是就返回它。这个函数是纯函数不涉及 IO所以可以放心地在循环里高频调用。4.4 一个完整的五阶段流水线示例光看代码可能还是抽象我拿一个实际的五阶段流水线来演示。假设我们要处理一批数据流程是采集 - 清洗 - 特征计算 - 模型推理 - 结果落库。每个阶段都是一个步骤依赖关系是线性的。steps [ {name: collect, deps: [], fn: collect_data}, {name: clean, deps: [collect], fn: clean_data}, {name: feature, deps: [clean], fn: compute_features}, {name: infer, deps: [feature], fn: run_inference}, {name: persist, deps: [infer], fn: persist_results}, ]跑起来后事件日志里会依次出现 collect STARTED、collect SUCCEEDED、clean STARTED、clean SUCCEEDED……如果跑到 infer 时进程挂了重启后调度循环重建状态发现 collect、clean、feature 都是 SUCCEEDEDinfer 是 STARTED没有 SUCCEEDED于是从 infer 开始重跑。前面三个步骤的结果原样保留不浪费算力。提示步骤函数的幂等性要自己保证。比如collect_data如果是“从外部接口拉数据”重跑时可能拉到重复数据需要在函数内部做去重。我的做法是给每个步骤传一个attempt参数函数内部根据 attempt 决定是否跳过某些操作。4.5 参数调优与性能实测最小系统跑通后我做了几轮参数调优这里把关键参数和实测数据分享一下。第一个参数是快照间隔我试了 100、500、1000、5000 四个值实测 1000 是性价比最高的快照耗时占总运行时间的 3.2%恢复时平均重放 500 条事件耗时 80ms。第二个参数是调度循环的轮询间隔设成 100ms 时 CPU 占用 5%设成 1s 时 CPU 占用 0.5% 但恢复延迟增加到 1s。最终我选了 200ms 作为折中。第三个参数是事件 payload 大小上限我设的是 4KB超过就截断并记录警告防止单条事件过大拖慢回放。参数测试值最终选择选择理由快照间隔100/500/1000/50001000快照开销 3.2%恢复 80ms轮询间隔100ms/200ms/1s200msCPU 1.2%恢复延迟可接受payload 上限1KB/4KB/16KB4KB覆盖 95% 场景回放不卡事件文件切分10MB/100MB/1GB100MB单文件回放快切分不频繁这些数值不是绝对的你的场景如果事件产生速率更高快照间隔要相应调小如果步骤执行时间很长轮询间隔可以调大省 CPU。核心原则是让恢复时间控制在业务可接受的范围内同时不让快照和轮询本身成为瓶颈。5. 常见问题与排查技巧实录5.1 状态重建出错的典型场景状态重建看起来简单但实际跑起来出错的场景不少。我遇到最多的是事件顺序错乱。理论上 event_id 是单调递增的按 id 排序就能得到正确顺序。但如果多个调度器实例同时写日志比如主备切换时可能出现 id 冲突或乱序。我的解法是给每个调度器实例分配一个唯一的 instance_idevent_id 用instance_id 本地递增的组合排序时先按 instance_id 再按本地递增。这样即使多实例写入顺序也是确定的。第二个典型场景是事件丢失。文件追加不是原子的如果写一半进程挂了日志末尾可能有个不完整的 JSON 行。回放时解析这行会报错。我的处理方式是读取时跳过解析失败的行并记录一条警告。同时快照机制保证了即使丢失少量事件也能从快照恢复大部分状态丢失的事件对应的步骤会被标记为“未完成”触发重跑。第三个场景是补偿事件和成功事件交错。比如一个步骤先 FAILED然后 COMPENSATED然后又 STARTED 重跑最后 SUCCEEDED。回放时如果只取最后一个事件会得到 SUCCEEDED这是对的。但如果补偿还没完成就重跑可能得到错误状态。我的解法是在状态机里加一个规则COMPENSATED 之后必须跟一个 STARTED 才能进入 SUCCEEDED否则视为异常状态触发人工介入。5.2 幂等失效的排查思路幂等失效是最隐蔽的问题因为它在正常流程下不暴露只有重跑时才出问题。我排查这类问题的思路是先确认重跑路径再检查副作用点。具体做法是手动构造一个“跑到一半挂掉”的场景然后重启观察哪些数据被重复写入了。如果发现重复就顺着调用链找到副作用点看那里有没有做幂等检查。常见的幂等失效原因有三个。第一是检查时机不对在步骤开始时检查“是否已成功”但检查完到实际写入之间有时间窗口另一个实例可能在这个窗口里也写入了。解法是把检查和写入放在同一个原子操作里比如用数据库的唯一约束。第二是检查范围不对只检查了 task_id没检查 step_name导致不同步骤之间互相干扰。解法是检查键用task_id step_name的组合。第三是外部系统不幂等比如调用一个第三方接口接口本身不支持幂等。解法是在本地记录调用状态重跑时先查本地记录而不是直接调接口。5.3 性能瓶颈的定位方法系统跑久了变慢定位瓶颈的方法我总结成三步看日志、看指标、看火焰图。看日志是看事件日志的追加速率有没有下降如果下降说明 IO 或锁有问题。看指标是看调度循环的每轮耗时如果某轮特别慢说明那轮执行的步骤有问题。看火焰图是用 profiler 抓一段时间的调用栈看时间花在哪。我遇到过一次典型的性能问题系统跑了三天后调度循环每轮耗时从 50ms 涨到 2s。看日志发现事件日志文件涨到了 5GB每次read_all都要全量读取自然慢。解法是引入增量读取调度器记住上次读到的 event_id每次只读新增的事件。这个改动让每轮耗时降回 60ms。后来我又加了日志切分每 100MB 切一个文件读取时只读最新文件加必要的旧文件进一步优化。问题现象可能原因排查方法解决方案调度循环变慢日志文件过大看文件大小和读取耗时增量读取 日志切分事件追加延迟高锁竞争或 IO 瓶颈看追加耗时 P99异步写 批量追加恢复时间过长快照间隔太大看恢复时重放事件数调小快照间隔内存占用高状态映射表过大看步骤数量和状态大小分片存储 懒加载补偿卡住补偿动作阻塞看补偿队列长度异步补偿 超时5.4 几个我踩过的坑和独家技巧第一个坑是时间戳的精度。我一开始用秒级时间戳结果同一秒内产生的事件无法区分先后回放时顺序错乱。后来改成毫秒级问题解决。但毫秒级也有坑如果系统时钟回拨比如 NTP 同步时间戳可能倒退。我的解法是不依赖时间戳排序只依赖 event_id时间戳只用于展示和监控。第二个坑是快照和日志的不一致。快照是在某个时刻打的但打快照的过程中可能还有新事件追加。如果快照记录的状态和日志不一致恢复时就会出错。我的解法是快照时记录一个 event_id 水位线恢复时从水位线之后的事件开始重放水位线之前的状态以快照为准。这样即使快照过程中有新事件也不会丢失。第三个技巧是用校验和检测日志损坏。每条事件追加时算一个 CRC32 校验和读取时验证。如果校验失败说明这行损坏了跳过并告警。这个机制帮我发现过一次磁盘坏道导致的事件损坏及时切换到了备份节点。第四个技巧是给步骤加超时。一个步骤 STARTED 后如果超过预设时间还没 SUCCEEDED 或 FAILED调度器主动把它标记为 FAILED 并触发补偿。超时时间怎么定我的经验是取该步骤历史执行时间的 P99 再乘以 2。比如某步骤历史 P99 是 30 秒超时设 60 秒。这样既能容忍偶发的慢执行又不会让卡死的步骤拖垮整个流程。6. 扩展方向从最小系统到生产可用6.1 分布式调度与主备切换最小系统是单机的生产环境肯定要多副本。Apollo-11 的分布式方案是主备模式一个主调度器负责执行步骤和写事件日志多个备调度器只读日志、重建状态、待命。主调度器通过心跳续约心跳超时后备调度器选举出新主从最新快照 后续事件恢复状态继续调度。这个方案的好处是简单可靠不需要复杂的共识算法代价是切换期间有短暂的服务中断通常在秒级。主备切换的关键是防止脑裂。如果主调度器没挂但网络分区了备调度器可能误判为主挂了并接管导致两个主同时写日志。我的解法是引入一个租约机制主调度器定期续租租约有过期时间备调度器只有在租约过期后才能竞选。同时事件日志的写入用 instance_id 区分即使脑裂导致双写回放时也能通过 instance_id 识别并去重。6.2 可视化与人工干预纯命令行的系统在生产环境不好用我后来加了一个简单的 Web 界面展示当前任务的状态、事件日志、步骤耗时。界面用 FastAPI 原生 HTML 实现不引入前端框架保持轻量。界面上可以手动触发重跑、跳过步骤、查看补偿状态方便运维人员干预。人工干预的难点是保证干预操作也走事件日志。比如运维人员手动把一个 FAILED 步骤标记为 SUCCEEDED这个操作也要追加一条事件否则回放时状态不一致。我的做法是给人工操作定义专门的事件类型如 MANUAL_OVERRIDEpayload 里记录操作人和原因这样回放时能完整还原包括人工干预在内的所有状态变化。6.3 与监控告警系统的集成生产系统离不开监控。Apollo-11 暴露了几个关键指标事件追加速率、调度循环耗时、步骤成功率、补偿触发次数、恢复耗时。这些指标通过 Prometheus 格式暴露接入现有的监控系统。告警规则我设了三条步骤失败率超过 5% 告警、恢复耗时超过 30 秒告警、补偿队列积压超过 100 告警。这里有个经验告警阈值不要设得太敏感。我一开始把步骤失败率阈值设成 1%结果每天告警几十次大部分是偶发的网络抖动导致的瞬时失败重跑就好了。后来改成 5% 并且要求持续 5 分钟才告警噪音降了 90% 以上。监控的目的是发现真问题不是制造焦虑。6.4 后续可以继续打磨的点这套系统我还在持续迭代接下来想做的有几个方向。一是步骤级别的资源隔离让不同步骤跑在不同的容器里避免一个步骤的内存泄漏影响整个调度器。二是事件日志的压缩对历史事件做冷热分离热数据保留原始格式冷数据压缩存储降低长期存储成本。三是智能重试策略根据失败原因自动决定重试间隔和重试次数而不是用固定的指数退避。如果你也在做类似的长流程编排系统我的建议是先把最小系统跑通再逐步加分布式和可视化。我见过太多人一上来就设计复杂的分布式架构结果核心的状态机逻辑都没跑通最后推倒重来。Apollo-11 的最小版本只有几百行代码但核心机制一个不少跑通它你对整个系统的理解会深刻得多。等最小版本稳定运行一段时间你自然知道该往哪个方向扩展而不是拍脑袋设计。