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 判定中断
一条日志被判为中断,条件如下:
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 排水过程
- 调度器进入
Standby,不再接收新触发; - 后台每 500ms–1s 检查执行中任务数;
- 归零后平滑
Shutdown,状态自动回落到「已停止」; - 超时则强制关闭,并把本进程仍在执行的登记项标记为中断,交由下次启动补偿。
排水期间:
- 作业页顶部显示「排水 · 等待 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. 启动恢复提示
应用启动后若检测到中断,会弹出提示:
本次启动检测到 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:
dotnet add package Chet.QuartzNet.UI --version 2.7.1数据库存储模式必须同步更新:
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.12.7.1 与 2.7.0 的数据库结构一致,无需额外迁移。
四个提供程序均包含 AddRecoveryAndDrainFields 迁移。只升级主包而不升级扩展包时,新字段写入会失败。
9.2 数据库结构
启动时自动执行 MigrateAsync(),新增内容:
| 表 | 变更 |
|---|---|
quartz_jobs | RerunOnRecovery(可空 bool) |
quartz_job_logs | 实例标识、启动标识、触发来源、补偿链、心跳、中断时间等 11 列 |
| 索引 | (Status, HeartbeatTime)、(Status, CompensationStatus)、RecoverySourceLogId |
新列全部可空或有默认值,老库可直接升级。回滚旧版本后中断记录仍可见,但旧版本不会补偿。
9.3 文件存储
无需操作,旧 JSON 缺少字段时使用默认值。
9.4 升级后建议
- 梳理非幂等作业,把「中断补跑」设为关闭;
- 检查宿主
ShutdownTimeout是否大于排水超时,否则排水会被宿主提前打断; - 多实例部署时确认只有一个实例承担调度(Quartz 仍是内存 JobStore)。
10. 本次更新一览
| 能力 | 类型 | 说明 |
|---|---|---|
| 执行日志生命周期 | 新增 | 开始即落库 + 心跳续期 |
| 中断识别与补偿 | 新增 | 心跳过期判定,按策略补跑,可追溯 |
| 手动重新执行 | 新增 | 中断记录一键重跑 |
| 启动恢复提示 | 新增 | 本次启动检测到 N 个中断,已补 X / 跳过 Y |
| 排水调度 | 新增 | 停接新触发、等待收尾、超时标中断 |
| 优雅停机策略 | 新增 | 立即停止 / 排水后停止 |
| 停机与恢复配置 | 新增 | 11 项启动期配置 |
| 作业级补跑开关 | 新增 | 跟随全局 / 开启 / 关闭 |
| 分析页 KPI | 优化 | 调度运行态与风险巡检 |
| 日志页 | 优化 | 中断状态、触发来源、仅看异常、日志配置 |
| JSON 模板 | 新增 | 结构化推送 |
| 存储与查询 | 优化 | 文件原子写、SQLite WAL、AsNoTracking |
11. 小结
v2.7.0 的主线可以概括为:让“出事”这件事可见、可控、可追溯。
- 崩了 → 知道哪条执行被中断,最后心跳是什么时候;
- 想补 → 自动补或手动点一下,来源链路清晰;
- 停服 → 排水等收尾,超时也有交代;
- 排查 → 「仅看异常」一次捞出失败与中断。
关键链路依赖定时任务时,这一版值得升级;但务必先确认作业的幂等性。