Skip to content
系列教程 · 第 16 篇

v2.7.0:中断恢复与排水调度

执行开始即落库、心跳判活、按策略补偿中断任务、停机可排水,以及 v2.7.1 的收尾修复。

更新于 2026-11-17MIT 开源

v2.7.0:中断恢复与排水调度 ​

v2.7.0 发布于 2026-11-14,主线是可靠性:进程崩溃或发布重启后,那些跑到一半的任务能不能被发现、被补偿,停机时能不能等任务收尾。

先看三个实际场景:

场景v2.7.0 之前v2.7.0
发布重启,任务执行到一半日志里没有记录,不知道谁被终止标记「中断」,按策略补跑
数据库抖动导致失败需要自己翻日志「仅看异常」一键筛出失败 + 中断
停机维护想等任务跑完只能硬停或干等「排水」:停接新触发,等收尾后自动停

v2.7.1 补丁(2026-11-15)

删除 / 禁用 / 清空作业以及手动停止调度器时,会中断正在执行的实例,修复「运行中」计数长期不归零的问题;心跳服务判定僵尸记录后立即触发补偿,待补偿扫描改为每 60 秒兜底;列表页签切回时统一刷新数据;「停机与恢复」卡片新增「恢复默认」。无数据库结构变更。

1. 为什么以前“看不见中断” ​

Quartz 使用内存 JobStore(UseInMemoryStore),进程退出后触发器与运行态全部丢失;而执行日志是在执行结束后才写一条。两件事叠加,结果是:

进程崩溃时,跑到一半的任务在后端没有任何记录。

既不知道是哪个作业被终止,也不知道跑了多久,更谈不上补跑。因此 v2.7.0 的顺序是:先让执行过程可见,再谈恢复。

2. 执行日志生命周期 ​

2.1 开始即写 Running ​

JobToBeExecuted 钩子在暂停、依赖等校验全部通过之后,创建一条 Running 日志并写入存储;JobWasExecuted 收尾时更新同一条记录。

带来的变化:

  • 页面能看到「运行中」的作业,耗时每秒递增;
  • 进程被强杀时,这条 Running 记录仍在,成为判定中断的依据;
  • JobExecutionVetoed 也会按 logId 收尾,避免留下永不结束的记录。

2.2 心跳续期 ​

新增 JobHeartbeatHostedService,按 HeartbeatIntervalSeconds(默认 15 秒)为本进程的活跃执行批量续期:

  • 只在有执行时写库,空闲无开销;
  • 文件存储一次写入,数据库存储一条 ExecuteUpdate;
  • 心跳失败只记录警告,不阻断作业。

2.3 判定中断 ​

一条日志被判为中断,条件如下:

text
Status == Running
且 (HeartbeatTime ?? StartTime) < now - LeaseDurationSeconds
且 条件更新成功(Status: Running → Interrupted)

数据库使用 UPDATE ... WHERE LogId = @id AND Status = Running,影响行数为 1 才算抢到;多实例同时启动时只有一方成功。文件存储在同一把锁内完成“读—判—写”。

3. 启动补偿 ​

3.1 决策顺序 ​

判定为中断后,按下列顺序短路判断,第一条命中即生效:

#条件结果
1未启用中断补偿只标记,不补跑
2该记录已补偿过跳过
3已达最大执行次数(默认 3)跳过,防“启动即崩”死循环
4作业不存在跳过
5作业已禁用跳过
6作业关闭了自动重跑跳过
7距下次触发不足阈值(默认 120 秒)跳过,等正常触发
8补偿策略为「只标记不补偿」跳过
9策略为「补最近一次」且存在更新的中断跳过
10触发失败记为失败并写原因

暂停中的作业仍会补偿:这次执行在崩溃前已通过校验,暂停不应追溯取消;禁用与删除才会跳过。

3.2 语义边界 ​

  • 不是断点续传:从头再跑一遍;
  • 不是 exactly-once:语义为 at-least-once,非幂等作业请在作业上关闭自动重跑;
  • 不是集群调度:Quartz 仍是内存存储,多实例只共享作业定义与日志表。

3.3 补偿链可追溯 ​

补偿产生的新日志是一条正常执行记录:

  • TriggerType = Recovery;
  • RecoverySourceLogId 指回被补偿的中断记录;
  • 源记录的 CompensationLogId 反向指向新记录。

日志列表的「触发来源」显示「补偿重跑」,悬浮可看原执行时间与第几次执行。即使补偿触发瞬间进程又崩了,预建的 Running 行会被下一轮扫描按中断处理,RecoveryAttempt + 1 继续传递。

3.4 手动重新执行 ​

中断记录支持「重新执行」:

  • 只有中断行显示按钮;
  • 提交前确认“将整段重跑,可能产生重复副作用”;
  • 已补偿、作业被禁用或暂停、调度器未运行时直接拒绝并提示;
  • 新记录来源为「补偿重跑」,可追溯源记录。

4. 排水与优雅停机 ​

4.1 三种停止方式 ​

操作停止接收新触发等待执行中任务可恢复
停止调度器是否,立即关闭重新启动
排水是是,等待或超时排水未完成可「恢复调度」
应用关闭是按停机策略下次启动恢复

4.2 排水过程 ​

  1. 调度器进入 Standby,不再接收新触发;
  2. 后台每 500ms–1s 检查执行中任务数;
  3. 归零后平滑 Shutdown,状态自动回落到「已停止」;
  4. 超时则强制关闭,并把本进程仍在执行的登记项标记为中断,交由下次启动补偿。

排水期间:

  • 作业页顶部显示「排水 · 等待 N 个任务完成」;
  • 启动按钮置灰;
  • 手动触发会被拒绝并提示原因。

4.3 应用关闭钩子 ​

新增 GracefulShutdownHostedService,在 Quartz 关闭前执行停机策略:

停机模式行为
立即停止不等待,直接终止
排水后停止(默认)停接新触发,最多等 DrainTimeoutSeconds(默认 60 秒)

WARNING

宿主的 HostOptions.ShutdownTimeout 默认 30 秒,会先于自定义等待触发。希望等待更久时,需要同步调大宿主超时。kill -9 或断电不会走该钩子,但下次启动扫描的结果一致。

5. 停机与恢复配置 ​

系统设置页新增独立的「停机与恢复」分区,顶部汇总「重启后生效 N 项」,可查看每一项的旧值 → 新值。

分组配置项默认值
停机停机模式排水后停止
停机排水超时(秒)60
恢复启用中断补偿开启
恢复补偿延迟(秒)30
恢复心跳间隔(秒)15
恢复租约时长(秒)60
恢复临近触发跳过阈值(秒)120
恢复补偿策略每个作业补最近一次
恢复最大执行次数3
恢复默认允许中断补跑开启
恢复中断日志保留(天)30

几个细节:

  • 都是启动期配置,保存只落库,需重启生效;
  • 服务端强校验「租约 ≥ 2 × 心跳」,不满足直接拒绝;
  • 补偿策略选「全部补偿」会二次确认,避免瞬时补跑风暴;
  • 补偿关闭或策略为「只标记不补偿」时,不生效的参数会置灰并提示;
  • v2.7.1 起支持「恢复默认」。

5.1 作业级三态 ​

作业编辑对话框新增「中断补跑」:

选项含义
跟随全局(默认)由系统配置决定
开启该作业一律补跑
关闭该作业一律不补跑,优先级最高

作业列表状态列后显示图标:⚡ 开启、⊘ 关闭、— 跟随全局。

6. 启动恢复提示 ​

应用启动后若检测到中断,会弹出提示:

text
本次启动检测到 2 个中断执行
已自动重跑 1 个,跳过 1 个,失败 0 个
  • 按 bootId 去重,刷新页面不重复弹;
  • 补偿进行中最多再轮询 3 次;
  • 「查看详情」跳转日志页异常筛选;
  • 接口缺失或失败时静默跳过,不影响首屏。

7. 页面同步调整 ​

7.1 分析页 ​

KPI 调整为四张卡:

卡片内容
作业总览总数、启用 / 禁用 / 暂停
调度运行态执行中线程与槽位、调度器状态、运行时长、待补偿数,5 秒轮询
执行质量近 7 日成功率、成功 / 失败数
风险巡检沉默作业、失败最多的作业

同时修复了执行趋势按天聚合口径与筛选切换的请求竞态,补齐深色主题图表与热力图空格子。

7.2 日志页 ​

  • 状态新增「中断」;
  • 新增「触发来源」列;
  • 「仅看异常」只看失败 + 中断;
  • 中断行支持「重新执行」;
  • 详情补充最后心跳、失联时长、补偿状态、跳过原因;
  • 日志配置迁到日志页,可直接查看当前日志总量;
  • 修复列设置持久化。

7.3 通知页 ​

  • 模板改为卡片式选择器,实时预览;
  • 新增 JSON 模板;
  • 模板预览改为悬停浮层。

7.4 系统设置 ​

  • 「停机与恢复 / 数据迁移」分区导航放大;
  • 强化环境标识;
  • 预检结果与迁移摘要改为弹窗;
  • 仅配置一种存储时给出空状态提示。

8. 稳定性与性能修复 ​

问题处理
文件存储并发读写互相阻塞读不加锁,写临时文件后原子替换
SQLite 查询被作业写入卡住启用 WAL 与 busy_timeout
页面查询带变更跟踪、白占内存统一 AsNoTracking,清空日志改用 ExecuteDelete
配置与迁移把中文写成 Unicode 转义统一 JSON 序列化选项
作业类名与 API 地址切换类型时互相带值拆成独立字段维护
搜索后表头排序标识丢失统一 grid 排序标识组件
日志详情执行时长换行错位调整列宽与样式
中断日志误判、重试状态显示错误修正状态机与重试判定
排水状态残留、停机策略不统一状态机收敛,Wait 作为 Drain 别名

CI 也做了调整:站点部署与 NuGet 发布拆成两个工作流,NuGet 发布改用 Trusted Publishing (OIDC)。

9. 升级指南 ​

9.1 更新包(版本必须一致) ​

建议直接安装包含补丁的 2.7.1:

bash
dotnet add package Chet.QuartzNet.UI --version 2.7.1

数据库存储模式必须同步更新:

bash
dotnet add package Chet.QuartzNet.EFCore.MySQL --version 2.7.1
dotnet add package Chet.QuartzNet.EFCore.PostgreSQL --version 2.7.1
dotnet add package Chet.QuartzNet.EFCore.SqlServer --version 2.7.1
dotnet add package Chet.QuartzNet.EFCore.SQLite --version 2.7.1

2.7.1 与 2.7.0 的数据库结构一致,无需额外迁移。

四个提供程序均包含 AddRecoveryAndDrainFields 迁移。只升级主包而不升级扩展包时,新字段写入会失败。

9.2 数据库结构 ​

启动时自动执行 MigrateAsync(),新增内容:

表变更
quartz_jobsRerunOnRecovery(可空 bool)
quartz_job_logs实例标识、启动标识、触发来源、补偿链、心跳、中断时间等 11 列
索引(Status, HeartbeatTime)、(Status, CompensationStatus)、RecoverySourceLogId

新列全部可空或有默认值,老库可直接升级。回滚旧版本后中断记录仍可见,但旧版本不会补偿。

9.3 文件存储 ​

无需操作,旧 JSON 缺少字段时使用默认值。

9.4 升级后建议 ​

  1. 梳理非幂等作业,把「中断补跑」设为关闭;
  2. 检查宿主 ShutdownTimeout 是否大于排水超时,否则排水会被宿主提前打断;
  3. 多实例部署时确认只有一个实例承担调度(Quartz 仍是内存 JobStore)。

10. 本次更新一览 ​

能力类型说明
执行日志生命周期新增开始即落库 + 心跳续期
中断识别与补偿新增心跳过期判定,按策略补跑,可追溯
手动重新执行新增中断记录一键重跑
启动恢复提示新增本次启动检测到 N 个中断,已补 X / 跳过 Y
排水调度新增停接新触发、等待收尾、超时标中断
优雅停机策略新增立即停止 / 排水后停止
停机与恢复配置新增11 项启动期配置
作业级补跑开关新增跟随全局 / 开启 / 关闭
分析页 KPI优化调度运行态与风险巡检
日志页优化中断状态、触发来源、仅看异常、日志配置
JSON 模板新增结构化推送
存储与查询优化文件原子写、SQLite WAL、AsNoTracking

11. 小结 ​

v2.7.0 的主线可以概括为:让“出事”这件事可见、可控、可追溯。

  • 崩了 → 知道哪条执行被中断,最后心跳是什么时候;
  • 想补 → 自动补或手动点一下,来源链路清晰;
  • 停服 → 排水等收尾,超时也有交代;
  • 排查 → 「仅看异常」一次捞出失败与中断。

关键链路依赖定时任务时,这一版值得升级;但务必先确认作业的幂等性。

相关阅读 ​

让 Quartz.Net 调度,从未如此简单