邻居的进出只说给在听的人：SubscribePeerEvents 上下线事件流消费指南

闪电节点的运营者需要回答一个很朴素的问题：邻居什么时候走的、什么时候回来的。翻日志太累，轮询连接列表又拿不到”变化的那一刻”。LND 为此准备了一条订阅流：SubscribePeerEvents，专管对等节点的上线与下线。它没有对应的 lncli 子命令，是一条为监控程序而生的通道。本文基于 0.19.0-beta 源码，讲清事件的内容、消费姿势与一个 proto3 层面的小坑。

一条只报上下线的单向流

proto 对这条流的定义很克制：创建一个从服务端到客户端的单向流，凡是与对等节点状态相关的事件都从这条流上发出，事件内容包括节点上线与下线。事件体只有两个字段：对端身份公钥 pub_key，以及类型枚举 type——取值 PEER_ONLINE 或 PEER_OFFLINE。没有原因码，没有断开的地址细节，也不携带通道维度信息：它报告的是”这个节点现在连着/不连着”这一个原子事实。主动踢除、握手失败、网络掉线、对端自行离开，在流上都是同一条 OFFLINE，想查为什么断，得回到日志与对端信息里去翻；想知道断的影响落在哪条通道上，那是通道维度账本的职责。上下线事件与通道事件在闪电监控里是两个粒度，把两者混成一个面板数字的告警系统，往往在抖动高发时段报出一堆与资金毫无关系的噪音。

默认值的坑：PEER_ONLINE 等于零

枚举定义里 PEER_ONLINE 的数值是 0，PEER_OFFLINE 是 1。在 proto3 语义下，零值就是字段未设置时的默认值——这意味着一条类型字段缺失或被异常构造的消息，反序列化后会安静地读成”上线”，而不是报”未填”。监控程序如果把 PEER_ONLINE 当成”其他情况的兜底”来处理，等于把一切异常默认成绿灯，真正的故障反而被颜色掩盖。稳妥的写法是白名单分发：只承认两个已知值，其余一律按未知事件记日志并忽略，宁可多一条没人看的告警，也不要一个永远不会响的错误分类。

没有 lncli，是设计不是遗漏

对比同一个服务里的其他方法：ListPeers 的定义处直接注明了对应的 lncli 命令，而 SubscribePeerEvents 没有这样的标注，lncli 的命令表里也找不到它的映射——一条只推”活着时发生的事”的长驻流，对人手指敲的命令行意义有限：你得一直开着终端等事件，还得自己在纸上记状态。它真正的用武之地在常驻监控进程里：以 gRPC 客户端身份长驻连接节点，把事件流写进时序数据库或告警管道，让机器而不是人来消化上下线的节奏。

监控闭环的标准拼法

单独消费上下线事件容易出假账，标准做法是快照加增量：节点启动或监控重连时，先用连接列表命令拉一份当前在线邻居的基线；此后事件流每来一条就更新本地状态表——在线集合加名或减名；连接不稳定时段还会遇到同一点位反复上线下线的抖动，去抖动逻辑（比如窗口内聚合）比裸计数更能反映真实稳定性。要强调的是事件流反映的是”你的节点视角的连通性”，同一批对手在全网视角可能健康得很，用它做路由质量判断时只应作为本地信号。把这条流接进面板之后，节点连接数的锯齿、失联邻居的名单、深夜掉线清晨自愈的规律，都会变成一眼可见的曲线——这正是它存在的意义：把散落在日志各处的连接史，变成可查询的结构化时间序列，让”最近网络稳不稳”从一句体感变成一条能复盘的线。

风险提示：连接事件仅反映本节点视角的连通状态，不能直接推断对手方或全网健康状况；事件流以订阅建立为界，断线期间的缺口接口层并未承诺补发，应以快照校正兜底；本文不构成任何投资建议。