Kener Heartbeat 心跳监控：为定时任务与内网服务打造推送式健康检查

可观测性后端前端运维【免费下载链接】kenerStunning status pages, batteries included!项目地址https://gitcode.com/gh_mirrors/ke/kener点击查看免费下载Heartbeat心跳监控是 Kener 中一种基于推送push模式的监控类型由你的服务主动向 Kener 发送 HTTP 信号Kener 负责记录最后一次心跳的时间并据此推导服务状态而非像 API/PING 那样由 Kener 主动去探测目标。本文以 Kener 的 Heartbeat 监控文档为主线结合仓库源码深入讲解其工作原理、配置参数、端点格式、状态判定逻辑与安全实践读完你可以直接用 curl 或 cron 为自己的批处理任务、备份脚本、内网守护进程接入心跳上报并看懂 Kener 内部是如何存储与判定这些信号的。为什么需要推送式监控Kener 内置的大多数监控类型API、PING、TCP、DNS、SSL 等都属于拉取pull模式监控调度器按分钟周期主动去请求或探测目标服务。但在以下场景中拉取模式并不适用按计划运行的定时任务例如每天凌晨执行的数据库备份、夜间批量任务它们在绝大多数时间并不在线固定频率的拉取毫无意义无法被直接访问的服务位于内网、防火墙之后或 NAT 环境中的服务Kener 实例无法主动建立连接需要自报健康状态的服务进程本身活着不代表业务正常由服务在完成关键步骤后主动上报更能反映真实状态。Heartbeat 监控正是为这些场景设计的服务在约定时刻主动打卡Kener 根据打卡的间隔时长推导出 UP / DEGRADED / DOWN 三种状态。工作原理心跳监控的运行链路可以概括为四个步骤在 Kener 中创建一个类型为Heartbeat的监控Kener 为这个监控生成一个唯一的 URL 端点由tag与secretString组成你的服务按固定周期向该端点发送 HTTP 请求GET 或 POST 均可Kener 记录每次心跳的时间戳若在配置的时间窗口内未收到任何心跳则将服务标记为DEGRADED或DOWN。整个过程的监控执行并不主动访问任何目标地址而是计算距离上一次心跳过去了多久。这一点可以从源码中直接印证Heartbeat 类型的监控在调度时由 service.ts 分派到HeartbeatCall类见 heartbeatCall.ts其execute()方法既不发起网络请求也不解析响应核心工作只是读取缓存/数据库中的最后一次心跳时间与当前时间做差后与阈值比较。底层存储缓存优先、数据库兜底Kener 记录心跳时采用缓存 数据库双通道缓存通道心跳到达时RegisterHeartbeat会调用SetLastHeartbeat将时间戳写入缓存键为last_heartbeat:tagTTL 为 45 天见 setGet.ts数据库兜底同时以 best-effort 方式向monitoring_data表写入一条type SIGNAL、status UP的监控数据记录用于进程重启后的恢复见 monitorsController.ts。该写入即使失败也不会中断心跳接收属于尽力而为的持久化。状态判定时HeartbeatCall先查缓存缓存缺失再回退查询数据库中的最新 SIGNAL 记录见 monitoring.ts。需要注意时间单位缓存历史上以毫秒存储而数据库以秒存储toMs()会根据数值量级自动换算ts 1e12视为毫秒否则视为秒。创建 Heartbeat 监控与配置项详解在管理后台进入Monitors页面点击Add Monitor选择Heartbeat类型即可看到如下配置项配置项说明默认值与约束Secret String心跳密钥用于认证心跳请求的独有密钥未设置时 Kener 会自动生成至少 12 位仅允许A-Z a-z 0-9 . _ ~ -Degraded After (Minutes)超过该分钟数未收到心跳服务视为 DEGRADED默认5对应degradedRemainingMinutesDown After (Minutes)超过该分钟数未收到心跳服务视为 DOWN默认10对应downRemainingMinutes必须大于 DEGRADED 阈值这些配置项在源码中对应HeartbeatMonitorTypeData接口的三个字段degradedRemainingMinutes、downRemainingMinutes、secretString见 monitor.ts。管理后台的表单组件在 monitor-heartbeat.svelte/manage/app/monitors/[tag]/types/monitor-heartbeat.svelte) 中实现页面初始化时会为未填写的阈值填入默认值5/10并提供New URL按钮一键生成随机密钥。值得一提的是监控管理界面会在配置好tag后直接展示完整的心跳 URL并带有复制按钮——该 URL 由当前站点地址、/ext/heartbeat/tag/secretString路径和密钥拼接而成保存监控前会提示先保存监控才能获得心跳 URL。通过 API 创建除管理界面外也可以通过 API 直接创建心跳监控。请求体中monitor_type取值为HEARTBEATtype_data内设置三个字段。例如{ tag: my-job, name: My job, monitor_type: HEARTBEAT, type_data: { degradedRemainingMinutes: 5, downRemainingMinutes: 10, secretString: my-job-hb-secret-01 } }创建后 API 响应会包含完整的type_data其中含有最终生效的secretString。心跳端点与发送方式端点格式Kener 为每个心跳监控提供唯一的端点。当前v4 起端点格式为路径分隔形式/ext/heartbeat/{tag}/{secret}其中tag是创建监控时配置的监控标识公开可见仅用于路由定位secret是配置的 Secret String真正的认证凭据必须保密。版本演进说明v3 时代的端点形如/api/heartbeat/{tag}:{secret}冒号分隔v4 迁移到/ext/heartbeat/前缀详见仓库内 v4.0.0 变更记录/docs/content/v4/changelogs/v4.0.0.md)v4.1.1 起改为/ext/heartbeat/{tag}/{secret}的路径分隔形式。旧式冒号 URL 仍会自动重写兼容存量 cron 任务无需改动见 v4.1.1 变更记录/docs/content/v4/changelogs/v4.1.1.md)。请求方法端点同时支持GET和POST两种方法。在端点实现 src/routes/(ext)/ext/heartbeat/[tag]/[secret]/server.ts 中两种方法都进入同一个处理函数校验tag与secret非空然后调用RegisterHeartbeat(tag, secret)注册心跳认证失败或监控不存在时返回 HTTP 400成功时返回{ status: OK }。示例curl 直接上报假设监控配置为Tagnightly-backupSecret Stringsuper-secret-key你的服务只需向如下地址发送请求即可上报心跳https://your-kener-instance/ext/heartbeat/nightly-backup/super-secret-key使用 curlcurl https://your-kener-instance/ext/heartbeat/nightly-backup/super-secret-key示例定时任务脚本内嵌上报心跳监控最常见的用法是任务成功后才上报确保上报意味着任务真正跑完#!/bin/bash # 运行你的任务 ./perform-backup.sh # 任务成功完成后向 Kener 发送心跳 curl https://your-kener-instance/ext/heartbeat/nightly-backup/super-secret-key若配合 cron可将心跳与任务用串联只有任务成功才触发上报*/5 * * * * /path/to/job.sh curl -s https://your-kener-host/ext/heartbeat/my-job/my-job-hb-secret-01状态判定逻辑源码级Kener 依据距离最后一次心跳的间隔时长推导监控状态。判定逻辑集中在 heartbeatCall.ts可概括如下若从未收到过任何心跳缓存与数据库均无记录返回NO_DATA错误信息为No heartbeat received yet令diff为当前时间与最后一次心跳的间隔毫秒数diff大于downRemainingMinutes对应阈值 →DOWNdiff大于degradedRemainingMinutes对应阈值 →DEGRADED否则 →UP。一个容易忽视的细节是心跳监控的latency延迟字段记录的正是距上次心跳的间隔毫秒数而非网络往返时间——距离上次心跳越久数值越大这也让状态页上的延迟曲线直观反映信号的及时性。此外两个阈值都有源码级兜底当type_data缺失或数值非法Number.isFinite检查失败时downRemainingMinutes回退为10、degradedRemainingMinutes回退为5。注册心跳时还针对分钟整点做了防碰撞处理若当前时间恰为整分钟nowSec % 60 0会加 1 秒避免与按分钟取整的监控时间戳撞上数据库主键约束见 monitorsController.ts。安全机制由于心跳 URL 中只有tag是公开的真正的访问凭据是secret因此 Kener 对密钥有明确约束长度与字符集至少 12 位且仅允许A-Z a-z 0-9 . _ ~ -见 anywhere.ts。选择这些字符是为了让密钥可以直接放入 URL 路径而无需编码保存时校验创建或修改监控时新设置/变更的secretString若违反规则会被拒绝抛出心跳密钥违反规则错误对应 HTTP 400BAD_REQUEST保存时未提供secretString则会自动生成一个形如focused-galois-sharp-chaum的随机密钥由scaleway/random-name生成克隆时更换克隆Clone心跳监控会为新副本生成全新密钥避免密钥随克隆扩散这些行为均有测试覆盖见 monitorsController.test.ts兼容旧数据规则仅对新增或变更的密钥生效规则引入前存储的旧密钥仍可继续使用管理员保存时不改动密钥也不会被误判为违规。在端点侧RegisterHeartbeat会对传入 secret 与监控type_data.secretString做严格比对不匹配统一抛错Invalid heartbeat secret外部无法枚举出有效密钥见 monitorsController.ts。实际部署时还应做到保持密钥机密任何知晓密钥的人都能伪造心跳切勿将含密钥的 URL 提交到公开仓库或日志使用 HTTPS为 Kener 实例配置 HTTPS加密心跳通信防止密钥在传输中被截获定期轮换密钥通过更新监控配置更换 Secret String并同步更新所有上报方。最佳实践与故障排查最佳实践Degraded After 阈值应略大于预期的两次心跳间隔。例如每 5 分钟上报一次可设为 57 分钟留出网络抖动余量Down After 阈值根据 SLA 要求设定并确保downRemainingMinutes degradedRemainingMinutes关键系统提高上报频率对关键任务可加密上报周期让 Kener 更早发现问题在服务端记录日志记录每次心跳上报的成功/失败便于排查上报链路本身的问题任务完成后才上报把心跳放在任务成功执行的末尾避免任务挂了但心跳还在报的假阳性基础设施即代码场景建议在创建监控时自行指定secretString这样 cron 任务或 Alertmanager 规则可以在监控创建之前就配置好 URL。常见问题现象可能原因与排查方向状态始终为 NO_DATA端点从未被调用或tag/secret拼写错误先确认监控为 ACTIVE 状态返回Invalid heartbeat secretURL 中的 secret 与secretString不一致从监控页面重新复制 URL一直 DOWN / DEGRADED阈值设置低于实际上报间隔检查任务实际执行周期是否稳定信号已收到但状态陈旧心跳是否在任务完成之后发送确保失败任务不会照常上报小结Heartbeat 监控是 Kener 监控体系中对拉取模式的必要补充用最小的成本覆盖定时任务、内网服务与自报健康类场景。它没有复杂的探测逻辑核心就是记录心跳时间 → 与阈值比较 → 推导状态配合密钥认证、缓存加数据库的冗余存储足以支撑生产环境的任务健康监测。如果你想进一步研究实现细节可以重点阅读 heartbeatCall.ts、monitorsController.ts 以及配套测试 monitorsController.test.ts或参考同目录下其他监控类型的文档如 monitors-api.md/docs/content/v3/monitors-api.md)、monitors-group.md/docs/content/v3/monitors-group.md)对比不同监控模式的差异。赞分享可观测性后端前端运维【免费下载链接】kenerStunning status pages, batteries included!项目地址https://gitcode.com/gh_mirrors/ke/kener点击查看免费下载相关推荐Dubbox服务健康检查心跳检测与存活状态监控的完整指南Dubbox服务健康检查心跳检测与存活状态监控的完整指南 Dubbox作为阿里巴巴开源的分布式服务框架提供了强大的服务健康检查机制确保微服务架构的稳定运行后端微服务服务注册发现消息路由如何实现node-cron定时任务的健康检查与告警监控方案如何实现node cron定时任务的健康检查与告警监控方案 在Node.js应用开发中定时任务是自动化流程的核心组件。node cron作为轻量级的Cron实后端任务调度System.CommandLine源码剖析理解解析器内部工作机制System.CommandLine源码剖析理解解析器内部工作机制 System.CommandLine是.NET生态中功能强大的命令行解析库为开发者提供了上一篇Redux Toolkit核心功能详解createSlice与configureStore实战教程下一篇laf平台成本优化策略资源调整与预算控制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考