mcpField
C
crontap-heartbeat-for-cron

crontap-heartbeat-for-cron

github.com/crontap云与 DevOps1938 次安装6 周前更新
代码仓库

关于 crontap-heartbeat-for-cron

为已有定时运行的任务添加 Crontap 心跳监控，适用于需要发现漏报或记录失败的团队，并说明密钥管理与验证方法。

主要功能

  1. 01设置周期和宽限时间
  2. 02成功后发送心跳
  3. 03通过 /fail 报告失败
  4. 04查看心跳记录
  5. 05轮换心跳令牌

适用场景

  1. 01监控定时导入是否按时完成
  2. 02检测任务静默并记录显式失败
  3. 03调查部署后的心跳和失败事件

MCP 相关

指导使用 Crontap MCP 的 create_heartbeat、get_heartbeat_pings 和 rotate_heartbeat_token 工具管理心跳；另有 Ultra REST API 方案。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/crontap/skills --skill crontap-heartbeat-for-cron

安装后在 Claude Code 中输入/crontap-heartbeat-for-cron确认已加载。

详细介绍

为周期性任务添加心跳

心跳用于监控已有自身时钟的任务。任务成功完成工作后发送 ping。超过周期和宽限时间仍无响应，就会被视为漏报；而 /fail 变体会报告明确的失败。

前提条件

使用必需的工具前，请检查这些工具是否可用。如果有任何工具缺失，请停止并仅向用户提供以下两种选择：

  1. 连接 Crontap MCP：https://mcp.crontap.com/mcp。所有 Crontap 套餐均支持 MCP 访问。
  2. 为原始 API 配置 $CRONTAP_CLIENT_ID 和 $CRONTAP_API_KEY。原始 API 访问需要 Ultra 套餐。

不要擅自选择路径，也不要在用户作出选择前继续操作。

  • 了解任务的实际最长间隔，包括预期的抖动。
  • 设置足够长的宽限时间，以应对常见延迟和运行时长。
  • 确定由哪个组件安全地存储返回的 ping URL。

工作流

  1. 根据预期周期和宽限时间创建心跳。
  2. 获取返回的 ping URL，并将其保存为机密。
  3. 仅在任务成功完成后添加成功 ping。
  4. 在任务处理失败的路径中添加 /fail ping。
  5. 部署后以及每次事件发生后，检查 ping 历史记录。
  6. 仅在凭据泄露或计划轮换凭据时轮换令牌。

MCP 示例

创建一个宽限时间为 30 分钟的每日心跳：

{
  "tool": "create_heartbeat",
  "arguments": {
    "name": "Nightly import",
    "periodMinutes": 1440,
    "graceMinutes": 30,
    "emailCooldownMinutes": 60
  }
}

响应中包含一个机密 ping URL。不要将其输出到源代码管理、CI 日志、支持工单或之后的 Agent 消息中。

检查某个 UTC 日期：

{
  "tool": "get_heartbeat_pings",
  "arguments": {
    "heartbeatId": "<heartbeat-id>",
    "day": "2026-09-14"
  }
}

明确确认后再轮换：

{
  "tool": "rotate_heartbeat_token",
  "arguments": {
    "heartbeatId": "<heartbeat-id>"
  }
}

轮换后，旧 URL 的两种变体都会立即失效。请在任务的下一个截止时间前，用新返回的 URL 更新任务。

任务集成

使用 CRONTAP_HEARTBEAT_URL 之类的环境变量。

run_the_job &&
  curl --fail --silent --show-error "$CRONTAP_HEARTBEAT_URL"

发生已处理的失败时，调用 "$CRONTAP_HEARTBEAT_URL/fail?msg=bounded-error-summary"。消息中不得包含凭据、个人数据或冗长的堆栈跟踪。

REST 备用方案

REST 需要 Ultra API 访问权限；MCP 不需要。

curl --fail-with-body https://api.crontap.com/v1/heartbeat \
  -X POST \
  -H "ClientId: $CRONTAP_CLIENT_ID" \
  -H "ApiKey: $CRONTAP_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "Nightly import",
    "periodMinutes": 1440,
    "graceMinutes": 30
  }'

验证

  • 从已部署的任务环境发送一次测试成功 ping。
  • 确认收到 ping 后，心跳从待处理状态变为已接收状态。
  • 测试一条安全的失败路径，并验证出现了 fail 事件，同时未泄露 ping URL。
  • 检查周期加宽限时间是否涵盖任务正常运行时的最坏情况。

安全与套餐限制

  • ping URL 是凭据。任何持有该 URL 的人都能报告活动。
  • 心跳只能检测静默状态，不能启动或重启任务。
  • Starter 套餐的心跳频率和数量限制与付费套餐不同。创建响应会根据当前账户执行相应限制。
  • 如果返回套餐限制响应，请提供其包含四个选项的升级阶梯，并说明满足需求的最小选项；不要编造价格。

故障排除

  • 首次成功接收 ping 前，不会开始计算截止时间。
  • 暂停期间发送的 ping 会记录在历史中，但不会改变截止时间。
  • 频繁快速发送 ping 可能受到速率限制，但仍会返回 HTTP 200。
  • 轮换后旧 URL 停止工作是预期行为。请部署替换后的机密 URL。

参考资料

评论

支持 Markdown