邻居不肯给块：getblockfrompeer 排障的三步定位法

一、点名单块的工具

节点正常同步靠 inv 广播加 getdata 请求自动完成，多数时候轮不到人操心。但有些场景”自动”会失灵：链尖明显落后而邻居都不主动推块、深度重组后节点死守某条链不动、或者想取回某个已修剪区块做人工核对。比特币核心 22.0 起提供 getblockfrompeer：给出区块哈希和一个对端编号，直接向那个邻居请求这一个块的完整数据。29.0 的发布说明把它与修剪节点的行为写明：即便数据目录开着修剪，这样取回的块也会被持久化落盘，之后再按修剪策略陆续回收——这条RPC是只读取证与定向补数的杠杆，不是链策略开关。

二、返回成功不等于拿到块

最容易踩的语义：调用返回只代表请求已排队发出，区块是否真的到达要靠之后轮询 getblock 确认。与之配套的约束还有两条。其一，对端编号来自 getpeerinfo 的实时输出，是进程内临时分配的整数，节点重启或邻居重连后编号作废，照抄旧编号会打在空气上。其二，这条命令不能替你把区块头补齐——它的定位是”已知这个块该存在、缺的是数据体”，头都还没有的高度请先让头同步追上来，否则请求同样无功。修剪节点上的持久化特性值得再强调一次：反复用它点单大区块，等于给磁盘加了一笔临时负担。

三、三步定位法

第一步分症状：看 getblockchaininfo 里 blocks 与 headers 两个高度——headers 不动，问题在头同步或时钟与连接，转网络排查；headers 领先而 blocks 卡死，才进入这条RPC的主场，若日志伴随 maxtipage 类告警则说明落后已超阈值。第二步挑邻居：getpeerinfo 逐个看对方的 blocks 高度与连接类型，挑一个明显领先且稳定的编号记下来。第三步定向取证：对目标哈希调用 getblockfrompeer，隔几秒 getblock 复查是否落地。块到了却仍不被采用，说明卡点在工作量选择或校验规则，回到日志细查，而不是反复换邻居点单。整套流程的价值，是把”删数据目录重同步”这种核弹级操作，压缩成对一个块的定向验证——多数”同步坏了”的体感，死在这三步的中间某步里，而不是真坏了。

四、修剪节点上的取证姿势

修剪与这条 RPC 的配合是最实用的隐藏功能：修剪模式下旧区块文件被回收，但链上证据有时需要回看——例如核对某笔纠纷交易的原始形态。取回并持久化后立刻做你要的 getblock 取证，然后把不需要的部分用 pruneblockchain 交还给修剪策略，别赌”反正会自动清”。还有一类误用要提醒：向一个同样是修剪节点的邻居点单已修剪的块，对方给不出数据，请求石沉大海——这不构成该邻居作恶的证据，先换有完整数据的对端再下结论。把它记成一条纪律：点单前查 getblockheader 确认目标存在、查 getpeerinfo 挑未修剪或标记完整的邻居，点单后限时复查，超时换邻居重试一次仍失败就转入日志分析，别让一条只读命令变成无限循环的许愿机。

顺带把两个近邻工具的边界画清：preciousblock 与 invalidateblock 改变的是节点对链的取舍，属于链策略手术刀，误操作的代价是让节点掉进孤立分支反复重同步，与本文的只读取证同级但不同科；getdata 一类的原始消息层面操作普通运维根本用不到，也无需知道。日常运维的记忆锚点只需要三个：先分头与块、再挑邻居、后定点取证。三步之外的问题——时钟漂移、防火墙静默丢包、跨机房链路抖动——都不在这条 RPC 的管辖范围内，硬要它背锅只会拖慢排障。

本文内容仅供信息与教育参考，不构成投资建议、法律或税务意见，也不构成对任何产品或服务的推荐。比特币与闪电网络操作不可逆，涉及资产操作前请自行核实关键参数并评估风险。