企业官网建设流程全解析

• 区块链

本篇指南聚焦 EOSIO 智能合约平台（当前仓库 eo/eos）中最常用的密钥管理操作——使用cleos wallet import将已有的公私钥对导入本地钱包，并讲解其前置条件、交互式与非交互式两种导入方式、典型输出，以及从cleos到keosd再到钱包插件的完整调用链。读完本文，你将能够安全地将既有私钥导入keosd管理下的钱包，并能够自行排查“钱包未解锁”“密钥重复”等常见报错。

一、目标与前置条件

本指南的目标是：将一对已有的公私钥（key pair）导入本地钱包，使其能够被cleos在签名交易时使用。

在动手之前，请确认以下前置条件：

• 已安装当前仓库所支持的cleos版本。cleos与keosd随 EOSIO 软件一起发布，通过 00_install 安装指南 安装 EOSIO 即可同时获得这两个命令行工具。
• 理解什么是公钥与私钥对：私钥用于对交易签名，公钥用于验证签名并作为链上账户权限的关联标识。钱包的作用就是以加密形式保管私钥，并在解锁后代替你完成签名。

另外建议先熟悉 wallet 子命令族，尤其是create、open、unlock等命令，因为导入密钥的前提是钱包已创建、已打开且处于解锁状态。

二、cleos wallet import命令速览

命令完整形态如下：

cleos wallet import [OPTIONS]

其中[OPTIONS]为可选项（方括号内的参数均可省略），具体支持以下选项：

依据 wallet/import.md 命令参考，该命令的作用是“将私钥导入钱包”，并且如果keosd尚未运行，本命令会自动将其拉起，无需手动预先启动钱包守护进程。

需要特别强调的是：导入目标钱包必须已打开（open）且已解锁（unlocked），否则导入会失败（详见第六节错误排查）。

三、操作步骤

1. 确保钱包已创建并解锁

导入前，先确认目标钱包存在。若尚未创建钱包，请参考 如何创建一个钱包，例如：

cleos wallet create -n my_wallet -f my_wallet.pwd

创建后需要打开并解锁钱包（以my_wallet为例）：

cleos wallet open -n my_wallet cleos wallet unlock -n my_wallet --password <创建钱包时保存的密码>

解锁细节可参考 wallet/unlock 命令参考。解锁成功后，可用cleos wallet list确认钱包状态——名称后带*号表示该钱包处于解锁状态。

2. 交互式导入私钥（默认钱包）

最简单的方式是直接运行命令，然后按提示输入私钥：

cleos wallet import

终端会提示输入私钥：

private key:

输入你的私钥（输入过程默认不显示字符），回车后应看到类似输出：

private key: imported private key for: EOS8FBXJUfbANf3xeDWPoJxnip3Ych9HjzLBr1VaXRQFdkVAxwLE7

输出中的EOS8FBXJUfbANf3xeDWPoJxnip3Ych9HjzLBr1VaXRQFdkVAxwLE7是由该私钥推导出的公钥（EOS 前缀，K1 曲线格式）。这证明私钥已成功解析、校验并写入钱包。

3. 非交互式导入（直接指定私钥）

为了避免交互输入，可以在命令行中直接通过--private-key传参。示例（导入到默认钱包，要求钱包已打开且解锁）：

cleos wallet import --private-key 5KDNWQvY2seBPVUz7MiiaEDGTwACfuXu78bwZu7w2UDM9A3u3Fs

输出：

imported private key for: EOS5zG7PsdtzQ9achTdRtXwHieL7yyigBFiJDRAQonqBsfKyL3XhC

4. 导入到命名钱包

使用-n, --name指定目标钱包：

cleos wallet import --name my_wallet --private-key 5KDNWQvY2seBPVUz7MiiaEDGTwACfuXu78bwZu7w2UDM9A3u3Fs

参数含义：

• --name my_wallet：将密钥导入名为my_wallet的钱包；
• --private-key 5KDNWQvY2seBPVUz7MiiaEDGTwACfuXu78bwZu7w2UDM9A3u3Fs：要导入的 WIF 格式私钥。

输出：

imported private key for: EOS5zG7PsdtzQ9achTdRtXwHieL7yyigBFiJDRAQonqBsfKyL3XhC

四、导入后验证

导入完成后，可以通过以下命令验证密钥确实已进入钱包：

cleos wallet keys

该命令列出所有已解锁钱包中的私钥（WIF 格式）；而cleos wallet private_keys则列出所有已解锁钱包中的公钥。确认目标公钥出现在列表中，即表示导入成功。

如果密钥来源于链上已有账户，下一步通常是创建账户并绑定该公钥或更新账户权限，之后即可使用该钱包对交易签名。

五、源码原理：一次导入背后发生了什么

理解底层调用链有助于排查问题。整个导入过程跨越三个层次：cleos（CLI 客户端）→keosd（钱包守护进程）→ 钱包插件（wallet_plugin）。

1.cleos侧：子命令注册与交互输入

cleos在 programs/cleos/main.cpp 中注册import子命令：

• 当--private-key未提供时，cleos会输出private key:提示，并调用fc::set_console_echo(false)关闭终端回显后再读取输入，防止私钥泄露在屏幕上；读取完毕恢复回显；
• 读入的字符串会先被构造为private_key_type以校验 WIF 格式合法性，若解析失败则抛出private_key_type_exception（"Invalid private key"）；
• 随后从私钥推导出公钥pubkey，与钱包名一起封装成 RPC 参数。

2. HTTP 层：/v1/wallet/import_key

cleos通过 HTTP 调用keosd的 RPC 接口，端点定义于 programs/cleos/httpc.hpp：

const string wallet_import_key = wallet_func_base + "/import_key";

即请求keosd的POST /v1/wallet/import_key，参数为[钱包名, 私钥]。

3.keosd/wallet_manager侧：状态校验

钱包插件中的wallet_manager收到请求后，在 plugins/wallet_plugin/wallet_manager.cpp 执行导入：

• 若钱包不存在，抛出wallet_nonexistent_exception（"Wallet not found: ..."）；
• 若钱包处于锁定状态，抛出wallet_locked_exception（"Wallet is locked: ..."）；
• 校验通过后调用具体钱包实现（默认软件钱包）的import_key。

这就是“钱包必须已打开且解锁”这一前置条件在代码层面的强制保障。

4. 软件钱包侧：解析、去重与落盘

默认的soft_wallet::import_key实现在 plugins/wallet_plugin/wallet.cpp：

bool import_key(string wif_key) { private_key_type priv(wif_key); eosio::chain::public_key_type wif_pub_key = priv.get_public_key(); auto itr = _keys.find(wif_pub_key); if( itr == _keys.end() ) { _keys[wif_pub_key] = priv; return true; } EOS_THROW( chain::key_exist_exception, "Key already in wallet" ); }

核心逻辑为：用 WIF 私钥构造private_key_type（再次校验格式），推导出对应公钥，然后以公钥为键检查钱包内是否已存在——不存在则存入内存密钥表，已存在则抛出key_exist_exception（"Key already in wallet"）。导入成功后，钱包数据会被序列化加密写回本地钱包文件，完成持久化。

值得注意的是，从源码看该函数返回true表示成功存储，并不校验该公钥是否与链上某个账户匹配——即导入本身与链上状态无关，密钥无论是否对应现有账户都可以先放入钱包。

5. 相关密钥操作

• 若你没有现成私钥，可直接在钱包内生成新密钥对：cleos wallet create_key（对应 wallet/create_key 命令参考）。源码中create_key支持 K1 / R1 两种曲线，生成的私钥同样会通过import_key存入钱包并返回公钥（见 wallet.cpp）；
• 若需要移除密钥，可使用cleos wallet remove_key。

六、常见错误与排查

此外，如果使用的是硬件钱包（如 YubiHSM）或安全元素钱包（SE），import_key由对应实现（yubihsm_wallet.cpp、se_wallet.cpp）提供，其行为与软件钱包不同——通常私钥不落盘在本地文件中。

七、延伸阅读

• 钱包命令全景：wallet 命令参考
• 创建钱包：how-to-create-a-wallet 与 wallet/create 命令参考
• 在钱包内生成新密钥对：wallet/create_key 命令参考
• 生成密钥对的另一种方式：how-to-create-key-pairs
• 导入密钥后创建账户并绑定权限：how-to-create-an-account
• 钱包插件整体实现：wallet_plugin 目录

• 区块链