RPC cookie 文件从哪来、多久换一次：rpccookiefile 的生成、路径与失效 图 1
RPC cookie 文件从哪来、多久换一次：rpccookiefile 的生成、路径与失效 · 图 1

RPC cookie 文件从哪来、多久换一次：rpccookiefile 的生成、路径与失效

很多人把比特币核心的 RPC 凭据理解成配置文件里的一对用户名和密码，但实际上，默认状态下节点用的是一枚每次启动都重新生成的临时 cookie。搞清这枚 cookie 文件放在哪、由哪个参数挪动、什么时候作废，是排 RPC 连接问题、做多实例部署和写运维脚本之前必须建立的一张地图。本文全部以 Bitcoin Core v31.0 源码为准。

节点启动时，如果配置里没有设置 rpcpassword，认证路径就会走 cookie：源码在 src/rpc/request.cpp 里把常量用户名写死为 __cookie__，把文件名默认设为 .cookie，内容形如 __cookie__:一串随机十六进制。随机口令由 32 字节随机数转成十六进制字符串，每次启动都换新的。这个文件默认落在节点数据目录的网络子目录下，比如主网实例就是 ~/.bitcoin/.cookie，测试网实例在 ~/.bitcoin/testnet3/ 下各有一份。

用 rpccookiefile 把文件挪到别处

-rpccookiefile=<loc> 在服务端和 bitcoin-cli 里都注册了同名的选项，帮助文本的原话是：认证 cookie 的位置，相对路径会被加上网络特定数据目录前缀，默认就是数据目录。这句话里最容易被忽略的是”相对路径加前缀”：如果你写 -rpccookiefile=my.cookie，节点实际用的是数据目录下的 my.cookie，而不是当前工作目录下那个；想完全掌控位置就写绝对路径。把它取反成 -norpccookiefile 则是另一种姿态——源码里对应一条 DISABLED 分支，节点不再生成 cookie 文件，日志会打出一句 cookie 文件生成被禁用。此时你若没有同时配置 rpcuser/rpcpassword 或 rpcauth，客户端就会撞上”找不到认证凭据”的 401 类错误。

每次启动都重生成：抄内容是脚本的慢性毒药

cookie 的口令不是稳定的。源码的做法是先把新内容写进 .cookie.tmp，再原子重命名成 .cookie，随后按需调整文件权限。这意味着节点每重启一次，文件里的字符串就换一次；把某次读到的内容抄进脚本或写进另一个服务的配置，早晚会失效。正确姿势是运行时读文件再拼进 HTTP Basic 认证头：curl --user "$(cat ~/.bitcoin/.cookie)" 这样的写法之所以安全，就是因为它每次执行都现场取最新值，而不是信任某一次的快照。

权限：umask 与 rpccookieperms 的接力

cookie 文件创建时的权限由进程的 umask 决定，核心在 src/common/system.cpp 里把 umask 设为 0077，也就是新建文件默认只有属主能读写。如果你需要让同组用户或更多进程读到它，用 -rpccookieperms 指定 owner、group 或 all 三档之一；传非法值会直接让 RPC 初始化失败并报出可选值。多用户共用一台机器时，这三档权限的取舍就是”谁能替你发 RPC 命令”的安全边界。

多实例：cookie 与端口必须成对核对

一台机器上跑多个节点时，每个实例有自己的数据目录，也就各自维护一份 .cookie。用 A 实例目录里的 cookie 去调 B 实例的 RPC 端口，一定会失败。排查 401 类失败时，先确认端口对应哪个数据目录、再确认那个目录里的 cookie 是不是刚生成的，这个顺序比凭记忆乱试更快。

节点侧的认证路径其实有两条：静态的 rpcauth 与动态的 cookie。前者是”用户名加盐哈希”长期写在配置里，适合多个长期服务、跨重启稳定；后者是本地临时凭据，默认覆盖单机的日常使用。两者可以共存：设置了 rpcuser/rpcpassword 或 rpcauth 后，静态凭据始终可用，cookie 通道依然存在，客户端按自己的参数选择用哪条。理解这个分工能避免一个常见误区——“我配了 rpcauth 为什么 .cookie 还在生成”：它俩互不取消，只是两条并行的门铃。

常见错误与对应动作

401 凭据被拒：先看目标端口对应的数据目录里 .cookie 是否存在、再确认读取者有没有文件权限；权限不足的报错往往来自操作系统而不是节点。找不到文件：检查你传给 cli 的 datadir/网络参数与节点实际使用的目录是否一致，测试网与主网的 cookie 不在同一个文件里。脚本时好时坏：大概率是节点重启过而脚本缓存了旧口令，改成每次现读文件即可根治。把这几步固化成排障顺序，比记住任何一条”民间偏方”都更持久。

风险提示：RPC 接口拥有控制节点与钱包的能力，凭据泄露或权限放开过大可能导致资产被误操作；本文为机制说明，不构成投资建议。