# 私钥与授权安全说明

## 结论

不建议做“玩家把私钥上传到网站/服务器”的模式。

推荐提供三种模式让玩家自行选择：

1. 钱包签名模式：最安全，玩家每次在钱包里确认。
2. 授权模式：适合卖出/换出，玩家只授权指定 Token 和数量。
3. 本地机器人模式：需要自动化时，玩家在自己电脑或服务器运行脚本，私钥不上传给项目方。

## 模式一：钱包签名模式

玩家打开 `player.html`，连接 MetaMask、TP、OKX Wallet 等钱包。

特点：

- 不输入私钥。
- 不上传助记词。
- 每笔交易都由钱包弹窗确认。
- 适合普通玩家。

风险：

- 玩家需要手动确认，不能无人值守自动跟单。
- 如果前端被篡改，可能诱导签错误交易，所以合约地址和交易内容仍要核对。

## 模式二：授权模式

玩家给合约授权一定数量 Token，之后合约可以在授权额度内完成卖出/换出。

特点：

- 不需要上传私钥。
- 适合批量卖出、分批卖出。
- 授权额度可以限制。

建议：

- 不要默认无限授权。
- 默认只授权本次要用的数量。
- 页面清楚显示授权 Token、授权合约、授权数量。
- 用完后提醒玩家可以取消授权。

风险：

- 授权给错合约会有丢币风险。
- 无限授权风险很高。
- 授权只能动对应 Token，不能动玩家钱包里的 BNB，除非玩家另外签交易。

## 模式三：本地机器人模式

如果玩家想自动跟单、自动慢出货、定时执行，需要有一个能自动签名的程序。

安全做法是：

- 玩家自己下载本地机器人包。
- 玩家自己在本机 `.env` 填私钥。
- 或玩家自己在本机生成加密钱包库 `data/wallet-vault.json`。
- 私钥不上传项目方服务器。
- 玩家自己运行脚本。

适合：

- 高级用户
- 自己有服务器的玩家
- 明白私钥风险的人

风险：

- 玩家电脑中毒会泄露私钥。
- `.env` 发给别人会泄露私钥。
- `wallet-vault.json` 和钱包库密码同时泄露，也等于私钥泄露。
- 自动脚本参数填错会自动发出错误交易。

本地钱包库说明见：

`WALLET_VAULT_CN.md`

### 本地已有私钥导入

本地钱包控制台允许把已有小钱包私钥添加到加密钱包库：

- 私钥使用密码输入框，只在当前页面内存中参与加密。
- 保存到浏览器和导出钱包库的内容都是加密 JSON。
- 添加结束后立即清空私钥输入框，日志只记录公开地址。
- JavaScript 无法承诺彻底擦除浏览器进程内存，因此不要在被远控、中毒或不可信电脑上操作，也不要导入主钱包。

### 本地明文私钥导出

本地钱包控制台提供明文私钥导出，只用于玩家备份自己已勾选的钱包：

- 必须输入钱包库密码和确认短语，并再次确认系统弹窗。
- 解密和文件生成都在当前浏览器本机完成，不请求上传接口。
- 页面和日志不显示私钥。
- 下载的 JSON 是明文，任何拿到文件的人都能控制对应资产。
- 导出后立即移入离线加密盘或密码管理器，并删除下载目录中的临时副本。

## 不推荐：服务器托管私钥

如果玩家把私钥上传给项目方服务器，本质就是托管钱包。

风险非常高：

- 服务器被黑，所有私钥可能泄露。
- 内部人员可以接触私钥。
- 数据库备份、日志、报错信息都可能泄露。
- 玩家丢币后责任很难切割。
- 这会明显降低玩家信任感。

如果业务上一定要做托管，至少需要：

- 只允许玩家导入新小钱包，不允许主钱包。
- 私钥必须客户端加密后再上传。
- 服务器不能保存明文私钥。
- 使用 KMS/HSM 或专门密钥管理服务。
- 每个玩家独立加密密钥。
- 提现/卖出设置额度限制。
- 后台操作全量审计日志。
- 管理员不能直接查看明文私钥。
- 数据库、备份、日志全部禁止记录私钥。
- 提供一键删除私钥和撤销授权。

即便做到这些，仍然不如玩家本地运行安全。

当前玩家包的处理方式：

- 给玩家本地机器人下载链接。
- 服务器托管入口只做风险说明。
- 不提供私钥上传表单。
- 不提供接收私钥的后端接口。
- 不记录私钥。

## 日志绝对不要记录

- 私钥
- 助记词
- `.env` 文件内容
- 加密前的密钥明文
- HTTP 请求体里的密钥字段
- 报错堆栈里的密钥字段

如果以后做托管服务，必须在进入日志系统前做字段丢弃或脱敏，不是只在界面隐藏。

## 推荐对外说法

普通玩家：

“不用上传私钥，只连接钱包签名交易。”

需要自动化的玩家：

“可以选择本地机器人模式，私钥只保存在你自己的电脑或服务器，我们不接收、不保存。”

不建议说：

“把私钥发给我们，我们帮你跑。”

## 给私钥时的最低安全要求

如果玩家坚持用私钥自动化：

- 必须新建小钱包。
- 不要导入主钱包。
- 钱包里只放本次操作需要的少量 BNB/Token。
- `wallet-vault.json` 和钱包库密码分开保存。
- 自动授权默认只授权本次需要数量，不建议无限授权。
- 操作完成后把剩余资产转走。
- 定期更换钱包。
- 不要把 `.env` 发给任何人。
- 不要在网吧、远程未知电脑、陌生 VPS 上运行。
- 不要在聊天软件里发送私钥。