李浅浅自用插件

koishi-plugin-ll-sentinel —— 端点可用性值守。

对配置的 host:port 做 TCP 建连探测：服务不可用时保持安静， 一旦恢复监听就在订阅群推送提醒。

个人自用插件。监测目标不预置在代码里，需要在自己的配置中填写。

它凭什么判断服务恢复了

用 TCP 建连探测：连得上 = 服务在监听。

不用 ICMP ping。原因：主机能 ping 通并不代表服务可用—— 很多情况下主机活着但端口是关的。所以「主机活不活」没有意义， 「端口通不通」才是有意义的信号。

⚠️ 这个信号的边界

TCP 建连成功 = 服务在监听。它不等于「客户端一定能正常进游戏」—— 有些服务在维护期间仍然监听端口，只是在应用层回「维护中」。

实测遇到过：同一地址在维护窗口内会来回翻转（通 → 断 → 通）。 所以本插件报的「恢复」是服务可达性的恢复，属于提前信号， 可能早于真正可玩。要判断到应用层，需要额外的协议级探测，本插件不做。

检测延迟

朴素做法是「每 N 秒探一次，连续 M 次成功才算恢复」，延迟 = N × M。

这个插件做了快速确认：一旦探到「通」，不干等下一个轮询周期， 而是隔 recheckDelay 立刻复探，凑够连续次数就立即推送。 仍然是 M 次独立的 TCP 握手，防抖动强度不变，但延迟被压到一个周期以内。

最坏延迟公式：

probeInterval + (confirmCount - 1) × recheckDelay + 推送耗时

| probeInterval | confirmCount | recheckDelay | 最坏检测延迟 | |---|---|---|---| | 30000 | 2 | 1000 | ~31 秒 | | 10000 | 2 | 1000 | ~11 秒 | | 5000（默认） | 2 | 1000 | ~6 秒 | | 5000 | 1 | 1000 | ~5 秒 | | 2000 | 2 | 500 | ~2.5 秒 |

「最坏」指服务刚好在某次探测之后恢复，所以要多等一个周期。 每轮只有几个 TCP SYN，开销可忽略，间隔可以放心调小。

为什么不会误报

1. 基线学习：首次探测只记录当前状态，不推送。启动时若服务本来就是通的，不会误报。
2. 基线持久化：状态写进 sentinel-state.json。服务不可用期间重启机器人，恢复时照样会推。
3. 防抖确认：需连续 confirmCount 次（默认 2 次）探测成功才认定恢复。
4. 单向触发：只在「不通 → 通」推送；「通 → 不通」默认不推（可开 notifyOnClose）。

实测验证过：让服务只接受 1 个连接就关闭（模拟网络抖动），不会触发推送。

指令

只有两条。

| 指令 | 作用 | |---|---| | 开服提醒 | 本群订阅。说这一句就是开提醒 | | 取消开服提醒 | 本群取消 |

不带命令前缀直接发这两个词也能触发。

没有状态查询指令。想看各端点当前状态和翻转历史，看 Koishi 日志里的 端点值守已启动 / 检测到恢复 / 检测到转入维护， 或者直接读状态文件（见下面的 stateFile）。

推送长什么样

推送内容 = openTemplate 的原文（多行 markdown），不带任何端点明细。

openTemplate 是控制台里的多行文本框，直接粘贴多行内容即可，换行会原样保留。例如：

📢 【开服通知】某某服务维护已结束！

服务器现已开启，可以上线啦！⚔️
赶紧上号清日常、打副本！冲冲冲！🏃‍♂️💨

不可用时（notifyOnClose，默认关）：

⚠️ 服务又不可用了

markdown 怎么发出去的

• QQ 官方机器人：走原生 markdown payload { msg_type: 2, markdown: { content } }，在 QQ 里渲染成 markdown 卡片 （需要 QQ 开放平台的原生 MD 权限）。
• 其它平台（onebot 等）：发纯文本，内容一字不差。
• QQ 发送失败（例如没开 MD 权限）：自动回退纯文本，不会把这条推送整个丢掉。

由 qqMarkdown 控制（默认开）。三条路径都有测试覆盖，见 test/markdown-send-test.js。

说明：

• 推送里不会出现端点地址、耗时、时间戳、确认次数。
• 开了 atAll 时，纯文本会带 <at id="all"/>； markdown 路径会去掉它（markdown 里该元素不生效，留着会原样显示出来）。

配置

| 项 | 默认 | 说明 | |---|---|---| | enabled | true | 开关后台监测 | | targets | []（空） | 必须自己填。数组，每项 {name, host, port, enabled} | | probeInterval | 5000 | 常规探测间隔（ms，最小 5000） | | probeTimeout | 500 | 单次 TCP 建连超时（ms）。默认对齐 500ms telnet 参考实现 | | confirmCount | 2 | 连续几次成功才认定恢复 | | recheckDelay | 1000 | 快速复探间隔（ms）：探到通后立即复探，不干等周期 | | notifyOnOpen | true | 恢复时推送 | | openTemplate | ✅ 服务已恢复 | 推送内容，多行 markdown 文本框 | | qqMarkdown | true | QQ 官方机器人以原生 Markdown 卡片发送；失败或非 QQ 平台回退纯文本 | | notifyOnClose | false | 再次不可用也推送 | | atAll | false | 推送是否 @全体成员 | | quietWhenAllDown | true | 全不通时不在日志里刷「仍不可用」 | | stateFile | 空 | 状态与订阅的 JSON 路径，留空用 Koishi 根目录 |

targets 怎么写

[
  { "name": "主端点", "host": "example.com", "port": 6600, "enabled": true },
  { "name": "备用端点", "host": "10.0.0.1", "port": 10900, "enabled": true }
]

host 填域名或 IP 都行，name 只是给自己看的标签。

如果没配 targets，插件启动时会在日志里告警，并且不会做任何探测。

排错

看 Koishi 日志：端点值守已启动（启动时的监测点数量）、 检测到恢复、检测到转入维护。端点的实时状态存在 stateFile 里。

• 端点恢复了但插件没反应 → 该地址可能被防火墙限制、不允许从当前网络直连， 换一个真正会翻转的端点。
• 只有部分端点翻转 → 正常。保留会翻转的，删掉不翻转的，减少无效探测。
• 想调延迟 → 调小 probeInterval，见上面的延迟表。
• 装晚了没收到提醒 → 首次探测会记基线不推送（防误报）。 若挂上时端点已经是通的，那一次不会响；之后的翻转才会。

自测

# 探测 + 状态机冒烟（含对照组：公网必定可连，证明探测代码没坏）
node test/probe-test.js

# 用桩件模拟 Koishi，验证插件加载与命令
node test/koishi-load-test.js

# 端到端计时：本机起真实监听，实测检测延迟 + 抖动不误报
node test/fast-confirm-test.js

License

MIT