API Key 与服务接入文档

1. 架构概览

本站部署在云端（SG），监控分两类：

• 云端服务 → 主动检测：服务器每 15 分钟直接探测公网目标（HTTP / TCP / Ping），无需接入。
• 本地服务 → 心跳上报：站点访问不到内网，由内网侧「主动推送」状态。所有上报都走同一个接口：
  GET/POST  /api/push/<监控slug>?key=<API_Key>

心跳上报有两种实现方式：内网探测代理（一台机器替全部目标上报，推荐）和业务程序自行推送（脚本末尾加一行 curl）。

2. 获取 API Key

1. 登录 管理后台 → 「API 密钥」→ 输入备注 → 创建密钥。
2. 完整 Key（sk_ 开头）仅在创建时显示一次，请立即保存；列表中只保留前缀。
3. Key 可随时禁用或删除；丢失后删除旧 Key 重新创建即可。每个用户管理自己的 Key。

权限范围：API Key 只能推送心跳（/api/push）和拉取代理探测清单（/api/agent/targets），不能读取或修改任何后台配置，泄露风险有限，但仍建议妥善保管。

3. 接口参考

3.1 推送心跳 — GET/POST /api/push/{slug}

# 正常心跳
curl -fsS "https://status.chinadong.net/api/push/mac-mini?key=sk_xxx&latency=18"

# 程序自检失败，主动报障（立即告警）
curl -fsS "https://status.chinadong.net/api/push/backup-job?key=sk_xxx&status=down&msg=backup+failed"

返回：{"ok": true, "status": "up"}；Key 无效返回 401，slug 不存在返回 404，非心跳类型返回 400。

3.2 代理探测清单 — GET /api/agent/targets

返回所有已启用且填写了探测目标的心跳监控项，供内网代理使用：

curl -s "https://status.chinadong.net/api/agent/targets?key=sk_xxx"
# → {"targets":[{"slug":"mac-mini","name":"Mac mini SSH",
#     "target":"tcp://192.168.50.91:22","timeout_seconds":10,
#     "interval_seconds":900,"verify_tls":1}, …]}

target 格式（在后台监控表单中填写）：

4. 方式一：内网探测代理 local_agent.py（推荐）

在任意一台能访问内网各目标的机器上运行（纯 Python 标准库，无需 pip 安装依赖）。每轮流程：

启动方式

# 常驻模式（默认每 300 秒一轮）
python3 local_agent.py --server https://status.chinadong.net --key sk_xxx

# 单次模式，配合 crontab（每 5 分钟）
*/5 * * * * /usr/bin/python3 /opt/scripts/local_agent.py \
    --server https://status.chinadong.net --key sk_xxx --once >> /tmp/local_agent.log 2>&1

Linux 常驻推荐 systemd（单元文件模板见脚本头部注释）；macOS 用 cron 或 LaunchAgent 均可。脚本位于仓库 clients/local_agent.py。

免维护：后台新增 / 修改 / 暂停心跳监控项，代理下一轮自动生效，无需改任何配置文件。

5. 方式二：业务程序自行推送

适合备份脚本、定时任务这类「程序活着就该冒个泡」的场景。在后台建一个心跳监控（target 留空），程序末尾加一行：

# Linux / macOS / OpenWrt（包装脚本 clients/heartbeat.sh）
curl -fsS "https://status.chinadong.net/api/push/<slug>?key=sk_xxx"

# Windows PowerShell（包装脚本 clients/heartbeat.ps1，含计划任务注册示例）
Invoke-RestMethod "https://status.chinadong.net/api/push/<slug>?key=sk_xxx&latency=12"

6. 超时判定与推送频率

• 服务器每 30 秒检查一次：超过 检测间隔 + 宽限时间（默认 900s + 300s = 20 分钟）未收到推送 → 判定「心跳超时」，标记异常并发送告警邮件。
• 恢复推送后自动转为正常，并发送恢复邮件（附故障持续时长）。
• 建议推送频率 ≈ 间隔的 1/3（默认配置下每 5 分钟一次），偶尔丢一两轮不会误报。
• 整个内网断电 / 断网时，所有心跳项会在 20 分钟内集体变红——这本身就是内网整体故障的信号。
• 间隔与宽限可在后台按监控项单独调整。