Hangfire.HttpJob 核心原理深度剖析任务状态如何跨进程同步与心跳保活【免费下载链接】Hangfire.HttpJobhttpjob for Hangfire,restful api for Hangfire,job调度与业务分离项目地址: https://gitcode.com/gh_mirrors/ha/Hangfire.HttpJobHangfire.HttpJob 是一个把job 调度与业务分离的分布式任务调度框架Hangfire 服务端只负责下发指令真正的业务代码跑在独立的 Agent 进程里。这种架构下最核心的问题就是——任务状态如何跨进程同步服务端怎么知道 Agent 还活着Agent 跑完任务怎么把结果告诉服务端本文将结合源码逐层拆解 Hangfire.HttpJob 的心跳保活机制与任务状态同步链路让你彻底看懂这套调度端 Agent 端协作的完整原理。一、为什么需要心跳保活调度与业务分离的架构传统 Hangfire 任务直接跑在服务进程内进程一挂任务就没了状态由 Hangfire 自己管理。而 Hangfire.HttpJob 把业务拆到了独立部署的 Agent 进程中服务端与 Agent 之间只剩一条 HTTP 通道因此必须解决三个问题存活探测服务端要能判断某个 Agent 是否在线才能决定任务往哪下发状态回传Agent 执行完任务后必须把成功/失败、耗时同步回 Hangfire 的任务状态故障兜底Agent 或服务端突然挂掉时卡在 Processing 状态的任务必须被重新标记为失败避免永远滞留。这三件事分别由服务端三个后台服务 Agent 端两个核心类协同完成接下来逐一拆解。二、Agent 心跳保活机制全流程拆解2.1 服务端如何发起心跳探测服务端的心跳探测由 JobAgentHeartBeatServer.cs 驱动它是一个每 5 秒触发一次的定时器。每次触发时会做两件事扫描所有周期性任务RecurringJob找出带AgentClass的 Agent 任务按 URL 的 host:port 去重得到Agent 服务器清单对清单里的每个 Agent 发送一个 POST 请求请求头携带x-job-agent-action: heartbeat、x-job-serverBase64 编码的服务端 ID、x-job-storage等指令信息。这里的巧妙之处在于心跳不是 Agent 主动上报而是由服务端拉起来的。Agent 收到心跳请求后才开始启动自己的上报循环。2.2 Agent 端如何响应并持续上报Agent 端收到心跳请求后由 JobAgentMiddleware.cs 解析出服务端 ID调用HeartBeatReport.ReportHeartBeat()核心逻辑在 Heartbeat.cs每个服务端 ID 只会维护一个心跳上报实例ConcurrentDictionary缓存上报实例每 3 秒执行一次共 300 次5 × 60即 30 分钟每次上报都会把进程快照写入共享存储关键点只要服务端持续每 5 秒来续命一次Agent 的心跳时长就会被重置为 30 分钟。一旦服务端不再来敲门Agent 的心跳会在倒计时结束后自动停止上报——这就是保活的语义。2.3 心跳数据如何落地到共享存储Agent 上报的数据是一份ProcessInfo进程快照包含进程 ID、CPU 占用率、内存WorkingSet、磁盘剩余空间和时间戳。它会被写入存储的 Hash 结构AgentHeart:{服务端ID}字段名是 Agent 的 URL值是进程快照 JSON。服务端则定期从该 Hash 读取每个 Agent 的最新快照判断存活状态只有一行核心逻辑(当前时间 - 快照时间戳) 10 秒 该 Agent 失联同时服务端在心跳响应中会拿到 Agent 返回的agentServerIdAgent 进程每次启动都会生成一个全新的 GUID把它写入activeAgent:{AgentKey}这个 Hash 中。这个 ID 是后面失联检测判断 Agent 是否重启的关键凭证。三、任务状态跨进程同步的核心链路3.1 调度端如何驱动 Agent 执行任务当周期性任务或后台任务触发时服务端执行 HttpJob.cs 中的HttpJob.Excute通过PrepareHttpRequestMessage组装请求头x-job-agent-class指定要执行的 Job 类全名x-job-agent-action指令类型run/stop/detailx-job-bodyBase64 编码的任务参数 JSONx-job-serverBase64 编码的当前服务端 IDx-job-idHangfire 的 JobId用于结果回写时定位任务。Agent 的中间件收到指令后通过反射找到对应的JobAgent子类实例校验任务注册信息后调用Run()/Stop()。3.2 Agent 端状态机与结果回写任务实例在 JobAgent.cs 中维护一个明确的状态机Default → Running → Stopping → Stoped。单例任务SingletonJob同一时刻只允许一个实例运行Run()内部用自旋锁SpinLock 状态双重校验防止并发重复调度多例任务TransientJob每个请求创建独立实例统一缓存在transitentJob字典中超时控制CancellationToken.CancelAfter(AgentTimeout)会在超时后强制停止并上报。任务执行完毕后Agent 通过ReportToHangfireServer()把结果写回共享存储写 Hash_agent_result_{JobId}字段是实际执行毫秒数值是{Id, Action, RunId, R(ok/err), E(异常堆栈)}的 JSON往 Set_agent_result_中加入这个 JobId作为待收割标记。3.3 服务端如何收割任务结果服务端由 JobAgentReportServer.cs 负责收割它每 2 秒轮询一次并通过AcquireDistributedLock分布式锁保证多服务端实例下不重复处理从 Set_agent_result_拿到所有待处理 JobId读取对应 Hash 中的执行结果解析出成功/失败与实际耗时成功则把任务状态改为SucceededState失败则改为FailedState并触发SendFail通知清理 Set 与 Hash完成状态闭环。这样任务的最终状态虽然在 Agent 进程里产生却通过共享存储被服务端翻译成了 Hangfire 认识的任务状态实现了真正的跨进程同步。四、失联任务检测进程挂掉之后的兜底机制即使有心跳保活也无法避免调度指令发出后进程突然崩溃的极端情况。此时任务会永久滞留在 Processing 状态。LosedJobCheckServer.cs 每 5 秒扫描一次 Processing 中的任务专治两类失联Hangfire 服务端挂掉任务所在 Server 不存在或 Server 心跳超过 10 分钟则标记为HangfireServerShutDownError并转入 FailedAgent 进程挂掉或重启读取任务参数里记录的agentServerId与activeAgent:{AgentKey}中最新记录对比——如果 Agent ID 变了说明进程重启过或最后心跳时间超过 10 分钟则标记为HangfireAgentShutDownError并转入 Failed。为了避免误判任务启动的前 5 分钟是缓冲期不会参与失联判定。这套兜底机制保证了无论哪一端崩溃任务状态都不会无限期卡死。五、总结一张图看懂心跳保活与状态同步Hangfire.HttpJob 的整套协作机制可以浓缩成一句话服务端敲门驱动心跳Agent写库回传状态服务端轮询收割结果失联兜底清理残局。环节服务端角色Agent 端角色数据媒介心跳保活每 5s 发起心跳请求每 3s 上报进程快照AgentHeart:{ServerId}Hash指令下发组装 run/stop 请求头中间件解析并驱动 JobAgentHTTP Headers结果回传每 2s 收割结果执行完写结果 HashSet_agent_result_*失联兜底每 5s 扫描 Processing重启后更换 agentServerIdactiveAgent:{Key}Hash理解了这条双通道 共享存储的协作链路你就能明白为什么 Hangfire.HttpJob 能在不改动业务代码的前提下实现 job 调度与业务进程的彻底解耦。如果你正在设计类似的主从式任务调度系统这套心跳续命 存储回写 失联兜底的三角模型是非常值得借鉴的成熟范式。 想动手实践可以先在测试项目 TestHangfireAgent 中跑一个 Agent 实例再通过 TestHangfire 创建周期性任务然后用 Dashboard 观察心跳监控与任务状态变化亲身体验这套跨进程同步机制。【免费下载链接】Hangfire.HttpJobhttpjob for Hangfire,restful api for Hangfire,job调度与业务分离项目地址: https://gitcode.com/gh_mirrors/ha/Hangfire.HttpJob创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考