面向：搞不清节点状态为什么一会儿在线一会儿离线、或者不明白"为什么刚掉线就判定失联"的人。
这篇讲清三个时间常数从哪来，以及它们怎么影响你的判断。
先说结论
你看到的节点状态，是三套不同节奏的机制叠加的结果：
| 数字 | 是什么 | 谁在跑 | |---|---|---| | 60 秒 | 客户端心跳上报间隔 | Pi 客户端（你的电脑上） | | 30 秒 | 界面刷新状态间隔 | 你用的监控工具 | | 3 分钟 | 判定"失联"的阈值 | 监控规则（人为设定） |
它们不是一个东西，所以"客户端显示在线"和"监控显示离线"可以同时成立，且都不算错。
一、60 秒：客户端的心跳
Pi 客户端后台有一个心跳服务，周期性向官方服务端上报。默认间隔就是 60 秒。
它上报的内容比很多人想的多 —— 整个应用状态，包括节点 UUID、公钥、IP 等。 这不是"报个心跳"，是"把当前状态全量同步一次"。
关键点：这个间隔是可被远程覆盖的。
客户端会读 .env 里的 MAIN_HEARTBEAT_INTERVAL，也能被服务端下发的远程配置覆盖。 所以你不能假设它永远精确是 60 秒 —— 官方调整后，你按固定值去推断状态就会错。
心跳响应不只是"收到"
服务端回给客户端的内容里，能带很多东西：
- 远程配置（比如用哪个 Docker 服务、心跳间隔本身）
- 容器 compose 更新信号（hash 变了就
docker compose up -d重建容器） - 端口检查任务（官方下发，客户端执行后回传结果）
- 后端观测到的公网 IP（客户端据此判断 NAT 类型）
这解释了一个常见困惑：「我没动过任何设置，容器怎么自己重启了/配置怎么变了」。
因为官方可以通过心跳响应下发配置和更新信号，客户端收到就执行。 你以为"我什么都没做"，实际上客户端按官方指令做了。
二、30 秒：你的监控刷新频率
这个数字不是官方的，是监控工具自己的刷新间隔（我们用的默认 30 秒）。
为什么设 30 秒而不是 1 秒？
- 1 秒刷新：对 60 秒才上报一次的心跳来说，大部分刷新都是重复数据，纯属浪费
- 30 秒：在心跳间隔的一半左右，能及时发现变化，又不至于空转
所以：刷新频率应该匹配数据源频率，不是越快越好。
如果心跳 60 秒一次，你界面 1 秒刷一次，看到的 59 次都是"没变化"——除了让服务器更累，没有任何收益。
三、3 分钟：为什么判定失联比心跳慢
心跳 60 秒一次，为什么不在 61 秒就判离线？
因为单次心跳失败是正常的。常见原因：
- 网络瞬时抖动
- 官方服务端短时不可用
- 客户端刚好在做重活（同步区块时 IO 繁忙）
如果 60 秒没收到就报警，你会被误报警淹没，最后干脆不看告警了 —— 那比没有告警更糟。
3 分钟 = 3 个心跳周期。连续丢三个，才认为是真的失联。这是个经验值： 既过滤掉瞬时抖动，又不至于真的挂了很久才知道。
这个数字是可以调的，判断标准很简单：
| 你的容忍度 | 建议阈值 | |---|---| | 想尽早知道 | 2 个周期（120 秒），但误报会变多 | | 平衡 | 3 个周期（180 秒） | | 只想看真的挂了 | 5 个周期（300 秒） |
没有"正确值"，只有"匹配你容忍度的值"。
四、这三个数字怎么影响你的判断
搞清节奏后，很多"异常"其实能自己解释：
| 你看到的 | 实际发生 | 要处理吗 | |---|---|---| | 客户端在线，监控显示离线 | 监控还没收到最近的心跳 | 等 1-2 分钟再看 | | 刚掉线 1 分钟就报警 | 阈值设得太短（<2 周期） | 调阈值，不是修节点 | | 状态一会儿在线一会儿离线反复跳 | 心跳丢包，但没到阈值 | 查网络，不是节点挂了 | | 容器自己重启了 | 官方通过心跳下了 compose 更新 | 正常，看日志确认 | | 一切正常但客户端显示奇怪 | 客户端状态是从本地文件 + docker ps 推断的 | 重启客户端（不是容器）|
最后一行值得展开：客户端界面显示的状态，是它从「磁盘文件存不存在 + docker ps 状态」 推断出来的，不是"服务自己报的"。所以偶尔会出现"实际好好的，界面显示不对劲"—— 这时候先重启客户端看看，别急着动容器。
五、怎么用这三个数字排查
症状：监控显示离线，但客户端显示在线
- 先等 2 分钟（可能只是心跳还没到）
- 还是离线 → 查客户端到服务端的网络通不通
- 通 → 查监控侧是不是自己出了问题（拉数据失败不等于节点挂了）
- 都不通 → 才去看容器
症状：频繁在线/离线跳变
几乎都是网络问题，不是节点问题。你的心跳时通时不通。 查：本地网络稳定性、DNS、到官方服务端的连通质量。
症状：告警太吵
先调阈值，别调节点。3 个周期是基准，觉得自己能接受更多误报就降到 2。
六、一句话总结
60 秒是数据产生的频率，30 秒是你观察的频率，3 分钟是你相信它真的挂了的频率。
三者别混。混了就会出现"明明在线为什么报离线""为什么要等三分钟才告警"这类困惑。
---