bitcoin-cli 怎么知道该敲哪台机器：rpcconnect 的主机端口合写与优先级

bitcoin-cli 默认认为你要问的是本机节点。一旦你把节点跑在容器里、虚拟机里，或者同一台机器上开了第二个实例，“该敲哪台机器、哪个端口”就成了第一个要回答的问题。承担这件事的参数是 -rpcconnect，它的规则比大多数人以为的多一层。本文按 Bitcoin Core v31.0 源码逐项核对。

默认值与最简用法

源码里 DEFAULT_RPCCONNECT 是 127.0.0.1，帮助文本一句话：向运行在某个 IP 上的节点发送命令。不带任何参数时，cli 就连本机的回环地址、连当前网络对应的默认 RPC 端口（主网 8332），这套默认值让同机使用完全无感。

端口从哪来：三级优先顺序

源码的注释把取舍顺序写得很清楚，优先级依次是：-rpcport、-rpcconnect 里带的端口、当前链种的默认端口。也就是说 -rpcconnect 支持主机和端口合写，IPv4 写成 192.168.1.50:8332，IPv6 要写成 [::1]:8332 这种方括号形式。如果合写里带了端口，它就盖过默认端口；如果 rpcport 也给了，rpcport 再盖过它。两处都给但不一致时，听 rpcport 的——这类”看起来配了两遍”的写法是远程环境里最常见的隐性错配来源。

端口解析失败：cli 宁可把原样还给你

如果 -rpcconnect 里的端口无法解析（比如写成了主机名加一个非数字端口），cli 不会静默回退，而是抛出”Invalid port provided in -rpcconnect”并把你写的原文打出来。同样的纪律也用在 -rpcport 上：值转不成数字或转成 0，都会直接报错而不是采用默认。这个设计对排障是好事——错误信息里出现的字符串就是你输入的那个，不会被中途改写。

与认证的两条独立轨道

要注意 rpcconnect 只管”敲哪台机器”，不管”以什么身份敲”。凭据走另一条轨道：没给 -rpcpassword 时 cli 会去读 cookie 文件（默认在数据目录下的 .cookie），读不到才报”找不到认证凭据”。远程机器上的 cookie 不会自动跟着跑过来，所以跨机使用通常要么显式给 rpcuser/rpcpassword 或 rpcauth 派生的凭据，要么把请求通过隧道转回本机再读 cookie。地址和凭据两条轨道各自独立，任何一条配错的表现都是不同的错误。

冷启动时它还不够：rpcwait 的等待语义

节点刚启动、RPC 还在预热时会返回 -28 一类的”未就绪”错误。-rpcwait 让 cli 反复重试而不是立刻报错退出，-rpcwaittimeout=<秒> 控制最多等多久、0 表示不限（源码默认就是 0）。配合 systemd 或开机脚本时，这一对比固定 sleep 更稳：它是在等”服务就绪”这个事件，而不是在赌一个时间。

容器与跨机场景的组合拳

把节点跑在 Docker 里时，rpcconnect 的取值取决于你站在哪张网络里说话：宿主机上的 cli 连 127.0.0.1 加映射端口；同容器网络的另一个容器可以直接用服务名——cli 会先对主机名做解析再连。跨云调用时，把 RPC 直接暴露到公网要三思：这条 HTTP 通道本身没有 TLS，凭据与响应都是明文，常规路线是经 SSH 隧道或反向代理转发，再让 cli 对着隧道口的本机地址发命令——此时 rpcconnect 保持默认反而是最安全的写法。另一个实用技巧是用 -rpcwallet=<name> 配合 rpcconnect 指向不同实例：同一台管理机上按脚本切换目标节点与目标钱包，两对参数各自独立，不容易互相覆盖。

排障顺序决定恢复速度

把 cli 侧的失败按信息特征分三类，处置完全不同。第一类”连不上”：错误发生在建立连接阶段，指向地址、端口、防火墙或节点没起来，与凭据无关，先用最轻的 getrpcinfo 探测。第二类”被拒绝”：HTTP 401/403 出现在连接成功之后，说明地址是对的、身份是错的，回到 cookie 与凭据那条轨道排查。第三类”答非所问”：连接与认证都通过但返回 -28 或方法不存在，前者等就绪、后者查版本与 rpcwallet 路径。给这三类各写一行日志前缀，线上脚本的故障归因会清晰一个数量级。顺带一提，测试网与主网不仅端口不同（8332/18332/48332/38332 各归其链），cookie 与 datadir 也随之分离——rpcconnect 与网络选择参数必须同时正确，否则就是”连对了机器、敲错了门”。

风险提示：把 RPC 暴露到非本机地址意味着多一个可被访问的控制面，需自行评估绑定范围与凭据强度；本文为机制说明，不构成投资建议。