心跳检测通过客户端定时上报唯一标识并由服务端校验实现，需包含鉴权、时间戳校验、频次限制及失联判定逻辑，并建议加入抖动、指标上报和查询接口以增强健壮性。

心跳检测通常通过客户端定期向服务端发送轻量请求来实现，自定义脚本的心跳上报接口核心在于：定时触发、携带唯一标识、服务端可验证、失败有重试或告警机制。

1. 客户端脚本定时上报（以 Bash 为例）

在 Linux 环境下，可用 curl 或 wget 调用 HTTP 接口，配合 crontab 或 sleep 循环实现定时：

• 脚本中需包含机器/任务唯一标识（如 hostname、script_id、pid 或配置文件中的 token）
• 推荐使用 POST，带 JSON body 或 query 参数，例如：
  curl -X POST "https://api.example.com/heartbeat?script_id=backup-job-01&status=running" -H "Authorization: Bearer abc123"
• 加上超时和简单错误处理，避免卡死：
  curl --max-time 5 --fail -s -o /dev/null ... || echo "$(date) heartbeat failed" >> /var/log/heartbeat.log

2. 服务端接收与校验（以 Python Flask 为例）

服务端接口需做基础鉴权、时间戳校验、频次限制，防止伪造或刷量：

• 验证 Authorization header 或 API key，拒绝未授权请求
• 记录 last_seen 时间戳，并更新对应 script_id 的状态表（内存缓存如 Redis 更高效）
• 可选增加 ts 参数校验时间偏差（如 ±30 秒），防重放
• 返回简明响应，如 {"ok": true, "server_time": "2024-06-15T10:22:33Z"}，便于客户端调试

3. 心跳“失联”判定逻辑

服务端不能只看单次请求，而要基于“最后上报时间”做滑动窗口判断：

• 设定合理超时阈值（如 90 秒），超过即标记为 offline
• 用定时任务（如每分钟扫描）比对 Redis 中的 last_seen，触发告警或回调
• 支持手动标记（如上报 status=stopping）提前清理，避免误判

4. 进阶建议：增强健壮性

生产环境建议补充以下细节：

• 客户端加随机抖动（如 ±5 秒），避免所有脚本同时请求打爆服务端
• 上报 body 包含简单运行指标（如内存占用、上一次执行耗时），便于后续监控联动
• 服务端提供查询接口：GET /heartbeat/{script_id}，方便运维排查
• 日志中结构化记录 client_ip、user_agent（脚本名）、response_time，便于审计

不复杂但容易忽略的是：心跳不是越频繁越好，而是要匹配业务容忍度；同时必须确保上报通道本身稳定（比如避免依赖同一套可能宕机的网络或 DNS）。