比特币 RPC 的 HTTP 超时线：rpcservertimeout 管什么、不管什么

比特币核心的 RPC 在长时间空闲后会让连接断开，或让某个响应迟迟不回来——排查这类问题时，rpcservertimeout 是被搜索引擎提到最多的参数。但它的实际管辖范围比传闻窄得多，本文按 Bitcoin Core v31.0 源码把它到底管什么、不管什么划清楚。

一、默认值与定义

源码 httpserver 里定义默认超时三十秒，-rpcservertimeout=<n> 的官方描述是”HTTP 请求期间的超时”。它作用在 libevent 的 HTTP 连接层：一条 RPC 连接超过这个时长没有被使用，就可能被服务端回收。也就是说这是闲置计时器，不是执行时钟——一个正在被反复使用的连接不受这个值打扰，一个挂着一整天没人碰的 keep-alive 连接才会撞上它。参数归类上也值得注意：它带着仅调试属性，官方立场是普通用户不需要碰。

二、它不管 RPC 执行本身

最容易犯的误读是把三十秒理解成”RPC 调用最多跑三十秒”。核心的执行模型不是这样：请求进来后由工作线程处理，跑多久取决于查询本身的代价——扫描类调用（如 scantxoutset 扫全链）在慢盘上跑几分钟是正常物理现象，不存在”调大 rpcservertimeout 让它跑完”这回事。执行侧真正的守门员是另一族参数：工作线程数与工作队列容量管排队，队列满了新请求直接收到忙错误而不是等待。把超时与排队混为一谈，配置就会往错误方向调。

三、客户端超时永远在链路更上游

一个被忽视的层次学：HTTP 超时的决定权在发起方。脚本里的 requests 库、浏览器、反向代理各自的默认超时都比三十秒有自己的主意，服务器端参数影响不到它们。所以”我的 RPC 调用报超时”的第一步是确认报错来自哪一层——来自客户端库就调客户端；来自反向代理（常见六十秒）就查代理配置；确实来自核心，才轮到 rpcservertimeout 出场。反过来，让节点端超时比链路其他环节更短，等于给客户端制造”服务端先动手”的假象，排障方向会被整个带偏。

四、实用姿势

默认三十秒覆盖绝大多数场景：交互式脚本、钱包轮询、常规 getblock 都不需要动。真正合理的用途很窄——在代理与节点之间链路质量差、连接频繁被中间设备掐断时，把服务端闲置回收调得比中间设备更积极，让回收由核心主动完成而不是靠网络设备悄悄断。另一种姿势是反向操作：把超时留默认，给已知耗时的批量任务改用更短命的新连接或分批查询，让每个请求落在任何一层的舒适区内。参数带仅调试属性这件事本身就是提示：它不是性能旋钮，是兼容性补丁。

五、一次排障演练的完整顺序

把上面的分工串成流程：RPC 调用失败并报超时，第一步确认报错字符串来自客户端库、代理还是核心返回；第二步看核心是否活着，用一个轻量调用如 getblockcount 试探通路；第三步若核心活着但该调用卡住，检查它是不是排队被长任务挡住——工作队列的排队现象和 HTTP 层超时是两种病因，前者解法是给长任务换低峰时段或拆分批次，后者解法是对齐链路各层的超时设置。只有当连接确实需要长期挂起（例如订阅类长轮询用法）时，调 rpcservertimeout 才有正向意义；其余场景它都是方向错误的安慰剂。一个容易被忽略的补充：默认回收的是闲置连接上的会话资源，不影响 cookie 凭证本身，重连自动恢复，把断开理解成故障而盲目改参数，多数时候只是在给日志制造新变量。

顺带一个容易混淆的近邻参数：rpcworkqueue 管的是并发请求的排队容量，和这条闲置超时线同属 RPC 层但各管一段——队列不足的症状是忙错误而不是超时挂起，两者处方完全不同，报错文案里带 work queue 满字样的应该去调队列而不是调超时。

本文所有行为按 Bitcoin Core v31.0 源码核对，不构成任何投资建议。