Cleos 故障排查实战指南RPC 端点连接失败与 Missing Authorizations 权限错误的完整诊断【免费下载链接】eosAn open source smart contract platform项目地址: https://gitcode.com/gh_mirrors/eo/eos本篇技术指南聚焦 EOSIO 生态中cleos命令行工具的两类高频故障无法连接到 RPC 端点Cannot connect to RPC endpoint与事务签名报错 Missing Authorizations。结合 EOSIO 开源仓库 中docs/02_cleos/04_troubleshooting.md的官方排查说明以及仓库内cleos、http_plugin、chain_plugin的源码实现本文将从诊断命令、底层配置到权限模型逐层拆解帮助读者在本地开发与远程接入场景下快速定位并解决这两类问题。理解 cleos 与 nodeos 的通信链路要排查连接问题首先需要理解cleos与nodeos之间的交互方式cleos本质上是一个 RPC 客户端它通过 HTTP 请求与运行中的nodeos节点或其他链上 API 服务通信再由节点执行链上查询或提交事务。这一设计在 programs/cleos/main.cpp 中体现得非常直接cleos的核心参数-u, --url用于指定节点地址默认值为http://localhost:8888/main.cpp而 main.cpp 中将其注册为“The http/https URL where nodeos is running”。也就是说几乎所有cleos命令都会先向该地址发起 RPC 请求。反过来nodeos侧由http_plugin负责监听并响应这些请求。在 plugins/http_plugin/http_plugin.cpp 中可以看到http-server-address配置项默认值为127.0.0.1:8888即节点默认只在本机回环地址的 8888 端口提供 HTTP RPC 服务(http-server-address, bpo::valuestring()-default_value(127.0.0.1: std::to_string(current_http_plugin_defaults.default_http_port)), The local IP and port to listen for incoming http connections; set blank to disable.);因此连不上 RPC 绝大多数情况下要么是节点进程没起来要么是 cleos 指向的地址与节点实际监听的地址不一致。问题一Cannot connect to RPC endpoint无法连接 RPC 端点这是cleos使用中最常见的报错。官方文档 docs/02_cleos/04_troubleshooting.md 给出了最直接的判断手段先在浏览器或终端中直接访问节点的 RPC 接口绕开cleos本身确认节点是否存活。1. 先探测本地 nodeos 是否在运行在终端执行curl http://localhost:8888/v1/chain/get_info若返回一段包含server_version、chain_id、head_block_num、head_block_time等字段的 JSON说明本地节点运行正常问题出在别处若提示Connection refused或curl: (7) Failed to connect说明 8888 端口上没有服务在监听nodeos很可能没有启动或未加载http_plugin。get_info是链上只读查询中最具代表性的探测接口它由chain_plugin的只读 API 实现。从源码 plugins/chain_plugin/chain_plugin.cpp 可以看到该接口会返回服务器版本、链 ID、头区块号、不可逆区块号LIB、头区块时间、头区块生产者、CPU/网络资源虚拟限额与真实限额、完整版本字符串等丰富信息。换句话说只要这个接口能通就说明节点的 HTTP RPC 服务、链数据库与资源管理模块都处于健康状态是判断“节点活着没”的最佳单点探测。2. 远程 API 端点如何探测如果cleos连接的是远程nodeosAPI 端点则把探测 URL 换成对应主机的地址与端口http://API_ENDPOINT:PORT/v1/chain/get_info将API_ENDPOINT与PORT替换为远程节点的实际主机名/IP 与端口即可。例如curl http://my-api.example.com:8888/v1/chain/get_info3. 本地能通、cleos 却连不上检查 -u/--url如果curl探测成功但cleos依然报错重点检查两点cleos 连接的地址与节点监听地址是否一致节点可能通过--http-server-address 0.0.0.0:8888绑定了非默认地址而 cleos 仍使用默认的http://localhost:8888/。用-u显式指定即可cleos -u http://127.0.0.1:8888 get info cleos -u http://192.168.1.10:8888 get info防火墙 / 监听绑定问题远程连接时节点需要将http-server-address配置为对外可访问的 IP 或0.0.0.0且宿主机防火墙需放行对应端口。4. 结合 http_plugin 配置进行预防性检查除了http-server-addresshttp_plugin 官方文档 与源码还提供了其他相关配置排查连接问题时值得一并核对unix-socket-path在>FC_DECLARE_DERIVED_EXCEPTION( missing_auth_exception, authorization_exception, 3090004, Missing required authority )它属于authorization_exception授权异常体系错误码为3090004错误消息即 Missing required authority。同一异常族还包括错误码异常类含义3090001tx_duplicate_sig事务中包含重复签名3090002tx_irrelevant_sig事务中包含无关签名3090003unsatisfied_authorization提供的密钥、权限与延迟不满足声明的授权3090004missing_auth_exception缺少所需权限3090005irrelevant_auth_exception包含了无关的权限3090006insufficient_delay_exception延迟不足3090007invalid_permission权限无效这组异常定义清晰地说明EOSIO 的每个动作在执行前都会被apply_context校验权限事务中声明的授权authorization必须由签名者的密钥或权限结构覆盖否则节点直接拒绝执行。这也是文档中所说的“You are not using the required authorizations”——你用来签名事务的账户或权限级别不对。2. 最常见原因使用了错误的账户或权限级别cleos在构造事务时通过-p, --permission参数声明授权其格式为accountpermission。从 main.cpp 的选项定义可见-p,--permission TEXT ... An account and permission level to authorize, as in accountpermission (defaults to creatoractive)结合 main.cpp 的add_standard_transaction_options实现可以看到各事务类命令的默认权限并不相同例如create account默认creatoractivetransfer类命令默认fromactive、buyram默认payeractivevoteproducer默认voteractivecanceldelay默认canceling_accountcanceling_permission。因此最常见的两种错误场景是账户名写错或大小写不规范EOSIO 账户名是 12 字符以内的 a-z、1-5 字符集参考 如何创建账户敲错一个字符就会导致签名使用的账户与动作要求不一致权限级别不足或与声明不符动作需要accountactive或更高权限但 cleos 实际使用accountactive之外、权限等级更低的custom权限签名或者签名账户根本没有该权限。3. 检查签名链路的四步排查法EOSIO 的签名由keosd钱包服务完成cleos只负责组装事务与声明授权。遇到 Missing Authorizations 时按以下顺序排查确认钱包已解锁且密钥已导入执行cleos wallet list查看钱包状态*表示已解锁cleos wallet keys查看当前钱包中的公钥。如果私钥缺失需要cleos wallet import导入参见 如何创建钱包 与 如何导入密钥确认签名账户与权限正确在命令末尾用-p accountpermission显式声明授权例如cleos transfer -p aliceactive alice bob 10.0000 EOS memo确认私钥对应账户可通过cleos get account 账户名查看账户的权限结构owner/active 公钥与钱包内密钥一一对应参考 如何获取账户信息确认目标动作要求的授权使用cleos get abi或查阅合约 ABI 了解动作的授权字段必要时用-p accountowner提权重试。4. 进阶权限模型与 multisig如果账户使用的是自定义权限结构例如 active 是多重签名Missing Authorizations 可能源于权限权重与阈值未满足而非单纯缺密钥。这种情况下需要检查权限的threshold阈值与各 key/account 的weight权重配置使用 multisig 提案流程 收集足够的签名后再执行cleos multisig propose/approve/exec借助 如何链接权限 理解动作与最小权限linkauth的绑定关系——动作被链接到更高权限时使用默认 active 也可能报授权不足。值得注意的是Missing Authorizations 与 Missing required authority3090004并不完全等同于签名缺失tx_duplicate_sig、tx_irrelevant_sig等相近错误见上文异常表通常意味着钱包中存在多余或重复的密钥例如钱包里导入了多把无关私钥。此时可考虑清理钱包密钥仅保留与签名账户对应的私钥避免节点因“无关签名”而拒绝事务。5. 与其它常见错误的区分排查时注意将本错误与以下两类问题区分开连接类错误对应本文问题一报错发生在 RPC 请求阶段通常伴随connection refused或Failed to connect属于网络/节点问题余额或资源类错误如insufficient RAM、transaction net usage is too high属于账户资源不足与授权无关处理方式完全不同参见 cleos 命令参考 与 FAQ。快速诊断清单症状第一步操作修复方向cleos报连接失败curl http://localhost:8888/v1/chain/get_info启动 nodeos / 检查 http_plugin / 修正-u地址curl 通、cleos 不通核对节点监听地址与 cleos-u是否一致显式指定-u http://IP:PORT远程连不上探测http://API_ENDPOINT:PORT/v1/chain/get_info检查防火墙、http-server-address绑定事务报 Missing Authorizationscleos wallet list/wallet keys核对签名链路导入正确私钥用-p accountpermission声明授权报 3090004 / Missing required authoritycleos get account 账户核对权限与公钥修正账户名、提权至 active/owner 或走 multisig 流程总结连不上 RPC 与 Missing Authorizations 是 EOSIO 开发与运维中最常遇到的两类 cleos 报错前者是通信层问题后者是授权层问题。通过get_info端点探测可以快速圈定节点状态而理解-p accountpermission的签名语义、EOSIO 的权限阈值模型以及 3090004 异常在 exceptions.hpp 中的准确定位则能让开发者从猜报错升级为按异常体系精准定位。掌握本文的排查链路后配合 cleos 命令参考 与 http_plugin 文档即可在本地单机与远程 API 两种接入模式下快速恢复开发与运维流程。【免费下载链接】eosAn open source smart contract platform项目地址: https://gitcode.com/gh_mirrors/eo/eos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考