中断恢复与排水调度
进程崩溃、发布重启、机器强制回收之后,那些跑到一半的任务去哪了? v2.7.0 给出的答案是:记录下来、认得出、补得回、停得稳。
1. 能力边界先说清楚
| 能力 | 说明 |
|---|---|
| ✅ 执行可见 | 执行开始即写 Running 日志,页面能看到运行中任务与实时耗时 |
| ✅ 中断可识别 | 心跳超时后,记录被标记为「中断」,带上最后心跳与失联时长 |
| ✅ 中断可补偿 | 下次启动按策略自动补跑,也可在页面上手动重新执行 |
| ✅ 停机可排水 | 停止接收新触发,等待执行中任务收尾,超时标记中断 |
| ⚠️ 不是断点续传 | 补偿是整段重跑,不是从中间继续 |
| ⚠️ 不是 exactly-once | 语义为 at-least-once,非幂等作业请关闭自动重跑 |
| ⚠️ 不是集群调度 | Quartz 仍为内存存储,多实例只共享作业定义与日志表 |
2. 工作原理
text
执行开始
└─ 通过暂停 / 依赖校验后 → 写入 Running 日志 → 注册到执行表
执行期间
└─ 心跳服务按间隔批量续期(默认 15 秒),页面耗时每秒递增
执行结束
└─ 更新同一条日志为 成功 / 失败,写出耗时与异常
进程崩溃 / 强杀
└─ 日志停在 Running;下次启动时心跳过期 → 标记「中断」
下次启动
└─ 扫描中断记录 → 按策略补偿 → 弹出本次启动的恢复提示判定条件:
text
Status == Running
且 (HeartbeatTime ?? StartTime) < now - LeaseDurationSeconds
且 条件更新成功(Status = Running → Interrupted)条件更新保证多实例同时启动时只有一方抢到,不会重复补偿。
3. 配置说明
「系统配置」→「停机与恢复」。这些是启动期配置,保存后需重启应用生效;顶部会提示「重启后生效 N 项」,点开可对比每一项的旧值与新值。
3.1 停机策略
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 停机模式 | 排水后停止 | 立即停止 / 排水后停止 |
| 排水超时(秒) | 60 | 排水模式下等待执行中任务的最长时间 |
| 等待完成超时(秒) | 30 | 兼容旧配置保留,实际统一使用排水超时 |
3.2 中断恢复
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 启用中断补偿 | 开启 | 关闭后只标记中断,不补跑 |
| 补偿延迟(秒) | 30 | 启动后延迟多久开始补偿,给依赖服务留启动时间 |
| 心跳间隔(秒) | 15 | 运行中任务写心跳的周期(5–300) |
| 租约时长(秒) | 60 | 超过该时长未续期即判定中断(必须 ≥ 2 × 心跳间隔) |
| 临近触发跳过阈值(秒) | 120 | 距下次触发不足该秒数时跳过补偿,0 = 不跳过 |
| 补偿策略 | 每个作业补最近一次 | 只标记不补偿 / 每个作业补最近一次 / 全部补偿 |
| 最大执行次数 | 3 | 同一执行链的最大补偿次数,防止启动即崩死循环 |
| 默认允许中断补跑 | 开启 | 作业未显式配置时的默认值 |
| 中断日志保留(天) | 30 | 中断与补偿链日志的保留策略 |
租约与心跳的关系
租约必须不小于心跳间隔的 2 倍,保存时前后端都会拦截。默认 60 / 15 相当于 4 个心跳周期的容错,对时钟漂移比较友好;服务器请务必开启 NTP 校时。
4. 补偿决策顺序
判定为中断后,按下列顺序短路判断,第一条命中即生效:
| # | 条件 | 结果 |
|---|---|---|
| 1 | 未启用中断补偿 | 只标记,不补跑 |
| 2 | 该记录已补偿过 | 跳过 |
| 3 | 已达最大执行次数 | 跳过(疑似启动即崩) |
| 4 | 作业不存在 | 跳过 |
| 5 | 作业已禁用 | 跳过 |
| 6 | 作业关闭了自动重跑 | 跳过 |
| 7 | 距下次触发不足阈值 | 跳过(临近下次触发) |
| 8 | 补偿策略为「只标记不补偿」 | 跳过 |
| 9 | 策略为「补最近一次」且存在更新的中断记录 | 跳过 |
| 10 | 触发失败 | 记失败并写原因 |
暂停中的作业仍然补偿:这次执行在崩溃前已经通过校验,暂停不应追溯取消;禁用与删除才会跳过。
5. 作业级开关
作业编辑对话框中的「中断后自动重跑」提供三态:
| 选项 | 含义 |
|---|---|
| 跟随全局 | 由系统配置的「默认允许中断补跑」决定 |
| 开启 | 该作业一律补跑 |
| 关闭 | 该作业一律不补跑(优先级最高) |
作业列表的状态列后会显示图标提示:⚡ 开启、⊘ 关闭、— 跟随全局。
非幂等作业(转账、发消息、扣库存)请显式设为关闭。
6. 页面上的入口
日志页
| 能力 | 说明 |
|---|---|
| 中断状态 | 状态筛选新增「中断」,洋红标识 |
| 触发来源 | 定时 / 手动 / 补偿重跑,补偿可回看原执行时间与第 N 次执行 |
| 仅看异常 | 一键只看失败 + 中断 |
| 重新执行 | 仅中断行可见,提交前提示「整段重跑」风险 |
| 恢复信息 | 详情弹窗展示最后心跳、失联时长、补偿状态、跳过原因 |
启动提示
应用启动后若检测到中断,会弹出提示:
text
本次启动检测到 2 个中断执行
已自动重跑 1 个,跳过 1 个,失败 0 个按启动标识去重,刷新不重复弹;「查看详情」直达日志页异常筛选。
作业页
顶部状态条展示「排水 · 等待 N 个任务完成」,配套按钮:启动调度器、停止调度器、排水、恢复调度。
7. 排水使用步骤
- 需要一个平滑维护窗口时,点击作业页的「排水」;
- 调度器进入
Standby,不再接收新触发,页面显示剩余执行数; - 执行中任务收尾后自动关闭调度器,状态回落到「已停止」;
- 维护完成后点击「启动调度器」恢复;
- 若排水还没结束就需要恢复,点击「恢复调度」即可退出排水。
超时未完成时,未收尾的执行会被标记为中断,下次启动按策略补偿。
8. 接口
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/quartz/DrainScheduler | 开始排水,可选 timeoutSeconds |
| POST | /api/quartz/ResumeScheduler | 退出排水并恢复调度 |
| GET | /api/quartz/GetRecoverySummary | 本次启动的恢复汇总 |
| POST | /api/quartz/RerunInterruptedLog | 手动重新执行一条中断记录 |
| POST | /api/quartz/GetJobLogs | 支持 statuses 多状态筛选 |
9. 注意事项
- 宿主关闭超时:
HostOptions.ShutdownTimeout默认 30 秒,会先于排水等待触发;希望等待更久请同步调大。 - 强杀不留痕:
kill -9/ 断电不会走停机钩子,只能靠下次启动扫描,最终结果一致。 - 文件存储规模:心跳会整文件重写,高频、多任务场景建议使用数据库存储。
- 日志清理保护:待补偿的中断记录不会被自动清理,避免丢失恢复依据。
- 升级顺序:数据库存储模式请把 EFCore Provider 与主包升到同一版本,并确保目标库已由新版本启动完成结构升级。