问题:定时任务为什么会卡在半路
用 cron 或系统定时器启动脚本,是最常见的做法。它只解决了一件事:到点把进程拉起来。至于这次有没有跑完、跑到了哪一步、下次还要不要重跑,cron 完全不管。
于是下面这些情况都会留下不一致的状态:
- 进程被 OOM 杀掉或发布时被重启,任务停在处理第 300 条数据的地方;
- 依赖的下游接口超时,脚本异常退出,但前半段数据已经写进去了;
- 机器下线,任务既没成功也没失败,处于“没人知道它在哪”的状态;
- 上一次执行还没结束,下一次定时又触发了,两份进程同时处理同一批数据。
最直接的补救是“失败就重跑”。但如果任务本身不幂等,重跑会重复发消息、重复扣款、重复插入记录,问题从“没跑完”变成“跑多了”。
所以一个可恢复的定时任务,至少要满足三个属性:可观测(能查到当前状态和进度)、可重入(重复执行不产生额外副作用)、可续跑(从上次的断点继续,而不是从头再来)。
设计骨架:调度层、执行层、状态层分离
不要把“到点触发”和“干活”写在同一个脚本里。拆成三层:
- 调度层:只做登记。到期时向数据库写一条待执行记录,不直接处理业务数据。
- 执行层:独立的 worker,从数据库抢占任务并执行,持有租约。
- 状态层:用表记录任务定义、每次执行的状态、检查点与错误信息。
两张表基本够用:
CREATE TABLE task_run (
id INTEGER PRIMARY KEY AUTOINCREMENT,
task_name TEXT NOT NULL,
scheduled_at TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'pending', -- pending/running/succeeded/dead
attempt INTEGER NOT NULL DEFAULT 0,
max_attempts INTEGER NOT NULL DEFAULT 3,
lease_owner TEXT,
lease_expires_at REAL,
checkpoint TEXT,
last_error TEXT,
UNIQUE(task_name, scheduled_at)
);关键点是 UNIQUE(task_name, scheduled_at)。调度层用“插入或忽略”的方式登记,即使定时器抖动、发布期间重复触发,同一个时间点也只会有一条记录。这一步就把“重复登记”挡住了。
状态字段的作用是让恢复有依据:pending 待执行,running 执行中,succeeded 成功,dead 超出重试上限需人工介入。checkpoint 记录处理到哪一条,attempt 记录已经尝试了几次。
用租约避免重复执行
多 worker 场景下,“谁来做这个任务”需要一个互斥手段。数据库的条件更新可以做这件事,做法是先查后改、以影响行数为准:
import time
LEASE = 60 # 租约秒数
def claim(conn, worker_id):
now = time.time()
row = conn.execute(
"""SELECT id FROM task_run
WHERE (status = 'pending' AND attempt < max_attempts)
OR (status = 'running' AND lease_expires_at < ?)
ORDER BY id LIMIT 1""",
(now,),
).fetchone()
if row is None:
return None
cur = conn.execute(
"""UPDATE task_run
SET status = 'running', lease_owner = ?, lease_expires_at = ?,
attempt = attempt + 1
WHERE id = ?
AND (status = 'pending'
OR (status = 'running' AND lease_expires_at < ?))""",
(worker_id, now + LEASE, row[0], now),
)
conn.commit()
return row[0] if cur.rowcount == 1 else None注意 WHERE 里的条件同时包含了状态和租约过期判断,并且检查 rowcount。如果两个 worker 同时查到同一行,只有一个能把状态改成 running,另一个影响行数为 0,直接放弃。这是可恢复性的核心:worker 崩溃后租约不会再续,过期后任务自动回到可被抢占的状态,不需要人工重置。
执行期间要续租,否则一个正常但耗时较长的任务会被别人抢走:
def heartbeat(conn, run_id, worker_id):
conn.execute(
"UPDATE task_run SET lease_expires_at = ? WHERE id = ? AND lease_owner = ?",
(time.time() + LEASE, run_id, worker_id),
)
conn.commit()执行结束(成功或失败)时释放租约,失败时按剩余次数决定回到 pending 还是标记 dead:
def finish(conn, run_id, error=None):
if error is None:
conn.execute(
"UPDATE task_run SET status='succeeded', lease_owner=NULL WHERE id=?",
(run_id,),
)
else:
conn.execute(
"""UPDATE task_run
SET status = CASE WHEN attempt >= max_attempts
THEN 'dead' ELSE 'pending' END,
last_error = ?, lease_owner = NULL
WHERE id = ?""",
(error, run_id),
)
conn.commit()必须强调:租约不是分布式锁,它只保证“不会有两个 worker 同时认为自己拥有这个任务”。旧 worker 可能还活着、卡在某个网络调用里,租约过期后新 worker 已经开始跑了。因此业务操作本身仍然要幂等,租约只是降低并发概率,不能替代幂等设计。
用检查点实现断点续跑
长任务不要一口气跑完。切成小批次,每批处理完推进一次检查点,下一次从检查点继续。
这里有个容易出错的细节:检查点的推进必须和业务写入在同一个事务里提交。否则会出现“数据写了、检查点没推”,重跑时重复处理;或者“检查点推了、数据没写”,重跑时直接跳过,数据丢失。
def run_batches(conn, run_id, worker_id, batch=500):
while True:
cp = conn.execute(
"SELECT checkpoint FROM task_run WHERE id = ?", (run_id,)
).fetchone()[0]
cursor = int(cp) if cp else 0
with conn: # 同一事务:业务写入 + 推进检查点
rows = conn.execute(
"SELECT id, payload FROM item WHERE id > ? ORDER BY id LIMIT ?",
(cursor, batch),
).fetchall()
if not rows:
conn.execute(
"UPDATE task_run SET status='succeeded' WHERE id=?", (run_id,)
)
return
for item_id, payload in rows:
upsert_result(conn, item_id, payload) # 幂等写入
conn.execute(
"UPDATE task_run SET checkpoint=? WHERE id=?",
(str(rows[-1][0]), run_id),
)
heartbeat(conn, run_id, worker_id) # 每批结束后续租如果副作用发生在外部系统(发消息、调第三方接口),它无法加入本地事务。这时要靠幂等键:每次调用带上由任务名加业务主键组成的唯一键,接收方或本地去重表据此判断是否已处理。同时把“已发出的幂等键”也做成可查询的记录,恢复时先查再发。
另外,心跳放在主循环里只能覆盖“批次之间”。单批处理时间如果可能超过租约的一半,最好用独立线程周期性续租,并让业务代码里的超时时间明显小于租约时长。
常见错误
- 只在 cron 里直接跑业务:没有任何执行记录,重启后无法判断该不该补跑。
- 用内存标志位做去重:多进程、多机器下完全无效,只适用于单进程单线程。
- 缺少唯一约束:发布抖动或定时器重入导致同一时间点登记多条记录。
- 重试无上限、无退避:下游故障时短时间打出大量重复请求,放大故障。
- 检查点与副作用不在同一事务:这是断点续跑最常见的 bug 来源。
- 租约时间短于单批耗时:任务被“合法地”重复执行,而且日志上看不出异常。
- 把租约当互斥锁:认为抢到租约就不会有并发,忽略了旧 worker 可能仍在运行。
- 用时间戳做唯一键但精度或时区不一致:字符串格式不同导致唯一约束失效。
- 没有整体超时:卡死的 worker 一直续租,任务永远不会被接手。
- 失败后静默置为成功:为了让报表好看而吞掉异常,恢复机制彻底失效。
适用边界
这套方案适合“分钟级到小时级、单次处理量可控、能接受至少一次语义”的任务,比如对账、同步、批量通知。
几种情况下要换思路:
- 任务很短且天然幂等,例如每秒刷新一次缓存:cron 加幂等就够,不必引入状态表。
- 触发频率很高、并发量大:数据库条件更新会成为瓶颈,更适合用消息队列或成熟的调度框架,但幂等和状态记录的原则不变。
- 需要端到端“精确一次”:在跨系统的现实条件下通常做不到,工程上的答案是“至少一次投递 + 消费端幂等”,而不是追求调度层的完美去重。
- 任务内部有复杂的外部状态(比如依赖第三方流程的中间态):检查点不足以描述进度,需要额外的补偿逻辑或人工介入入口。
最后一点常被忽略:恢复机制的价值不只在于自动重跑,还在于出问题时能看清发生了什么。哪怕最终还是要人工处理,一条带 attempt、last_error 和执行状态的记录,也比翻半天日志有用得多。