节点维护工具套件
java-tron Toolkit 维护工具套件在数据库日常运维中的应用：轻节点裁剪、数据库分卷与合并、高速复制、存储引擎转换、LevelDB 启动优化等。
前置阅读
Toolkit 是与 FullNode.jar 配套发布的一套专用数据库维护工具集（Toolkit.jar）。它主要用于对节点的底层数据库执行“整形”和日常管理动作——例如将其裁剪为轻节点快照、在不同存储卷间高效迁移数据、在 LevelDB 和 RocksDB 存储引擎之间转换、将单数据库拆分为多分片，以及优化 LevelDB 的元数据以加速节点启动。
Toolkit 的每个子功能都可以通过 Toolkit.jar 对应的子命令调用。命令行中可使用 -h 参数查看任意子命令的完整选项和说明。
可用子工具
| 工具类型 | 核心用途 | 子命令名称 |
|---|---|---|
| 轻节点裁剪 | 将全节点数据库转化为轻节点快照，或对现有轻节点执行二次裁剪以释放空间 | db lite |
| 高速数据复制 | 节点数据库的跨卷快速复制，由于底层逻辑优化，其速度显著快于常规的 cp -r 命令 | db cp |
| 引擎数据转换 | 在 LevelDB 和 RocksDB 存储引擎之间迁移和转换已有数据 | db convert |
| 数据库分区 | 将单个数据库拆分并分布在不同的磁盘卷上，适用于多盘分发 | db move 及相关命令 |
| LevelDB 启动优化 | 优化 LevelDB 的元数据结构，大幅缩短节点在冷启动或重启时的初始化时间 | db archive |
| Keystore 管理 | 创建、导入、列出 keystore，或修改 keystore 密码 | keystore new/import/list/update |
关于各工具的完整 CLI 参数说明、使用示例及边界情况，请参阅 Toolkit 用户指南。
各工具的具体使用场景
轻节点裁剪
适用于以下场景：
- 从正在运行的全节点中裁剪并导出轻节点状态快照（以便部署新的轻节点）。
- 定期对已运行的轻节点数据目录执行重新裁剪，回收多余的磁盘空间（轻节点在运行后积攒区块的速度与全节点一致，建议定期裁剪以保持轻量）。
java -jar Toolkit.jar db lite -o split -t snapshot -fn /path/to/output-directory -ds /path/to/snapshotGreatVoyage-v4.8.2 新增 --exclude-historical-balance 选项，可在生成 snapshot 时排除 balance-trace 和 account-trace，以缩小数据集：
java -jar Toolkit.jar db lite -o split -t snapshot \
-fn /path/to/output-directory -ds /path/to/snapshot \
--exclude-historical-balance该选项仅影响启用了 storage.balance.history.lookup = true 的源全节点。排除上述数据库后，生成的轻节点不能可靠提供历史余额查询，后续执行 merge 也不会恢复这些数据。如果需要使用 getBlockBalance 或 getAccountBalance 查询历史余额，请勿启用该选项。
关于轻节点快照中包含的具体内容及 65,536 个区块窗口的设计机制，请参阅轻节点概述。
Keystore 管理
在 GreatVoyage-v4.8.2 之前，运行 FullNode.jar --keystore-factory 会进入交互式 keystore 管理器，其中提供 GenKeystore 和 ImportPrivateKey 两项主要操作。从 GreatVoyage-v4.8.2 开始，这些功能已统一集成到 Toolkit.jar：GenKeystore 对应 keystore new，ImportPrivateKey 对应 keystore import；Toolkit 同时新增 keystore list 和 keystore update。--keystore-factory 当前仍保留以兼容旧有用法，但运行时会提示该入口已弃用，并计划在后续版本中移除。新操作建议直接使用 Toolkit.jar keystore 命令组；现有依赖旧入口的脚本或操作流程应逐步切换到 Toolkit。
| 命令 | 用途 | 对应旧操作 |
|---|---|---|
keystore new | 随机生成密钥对并创建加密 keystore | GenKeystore |
keystore import | 将已有私钥导入新的加密 keystore | ImportPrivateKey |
keystore list | 列出指定目录中的 keystore | 4.8.2 新增 |
keystore update | 修改指定 keystore 的密码 | 4.8.2 新增 |
基本用法：
java -jar Toolkit.jar keystore new
java -jar Toolkit.jar keystore import
java -jar Toolkit.jar keystore list
java -jar Toolkit.jar keystore update <address>默认 keystore 目录为当前工作目录下的 Wallet，可用 --keystore-dir 指定其他目录。keystore new 和 keystore import 可通过 --password-file 读取密码，keystore update 使用该参数时文件需依次包含当前密码和新密码两行；keystore import 还可通过 --key-file 读取私钥。包含密码或私钥的文件应设置严格的文件权限，避免提交到代码仓库，并在使用后安全清理。
keystore list的验证范围
keystore list只读取文件中声明的地址，不会解密 keystore 并验证地址与私钥是否匹配。不要信任来源不明的 keystore 文件；只有在解密加载时，地址与私钥的对应关系才会得到校验。
高速数据复制
适用于以下场景：
- 将节点数据库无缝迁移至更快的固态硬盘（SSD）上。
- 在新服务器上从备份目录恢复数据。
- 在运行节点旁预先同步和准备备用数据（以便后续通过重命名目录进行无缝倒换）。
Toolkit 实现了适配 LevelDB / RocksDB 文件结构的专属复制算法，处理海量数据时的传输速度远超系统默认的 cp -r 命令。
引擎数据转换（LevelDB ↔ RocksDB）
适用于需要在节点的两种存储引擎间切换的场景。例如：希望利用 RocksDB 获得更好的随机读取性能，或者需要将数据转换为 LevelDB 以兼容某些仅提供 LevelDB 格式的第三方镜像站快照时。
安全警告请务必先停止节点进程，并在原始数据库的副本上执行转换操作。该转换并非就地（in-place）修改，需要额外的临时空间。
转换完成后，在重启节点前，请记得将 config.conf 配置文件中的 storage.db.engine（即 storage { db.engine = ... }）修改为与新引擎一致。
数据库分区
适用于以下场景：
- 将庞大的数据库文件分散存储到不同的物理磁盘卷上（例如，将高频读写的热数据与不常访问的冷数据分离）。
- 降低单块磁盘的 I/O 读写竞争压力。
- 配合特定的 RAID 卷组规划，提升磁盘读写的吞吐率。
LevelDB 启动优化
适用于以下场景：
- 在开发或预发布环境中需要频繁重启节点。
- 节点由于 LevelDB 压缩（Compaction）或未决的状态恢复过程，导致启动过程耗时过长。
该优化工具会在启动前整理并预压缩 LevelDB 的元数据，使节点在下一次启动时能瞬间完成底层引擎的初始化。
相关资源
- Toolkit 用户指南——附带具体命令示例的 CLI 参考指南
- 数据库快照——从公开的镜像下载站获取预构建的数据库快照
- 轻节点概述——了解何时选用轻节点以降低运维成本
- 部署节点——节点的端到端部署与基本配置
Updated 6 days ago