部署节点

本文涵盖 TRON 网络各类节点的端到端部署：普通全节点（Full Node）、超级代表（SR）出块节点，以及基于数据库快照的轻节点（Lite Full Node）。这些节点本质上都运行同一份客户端 FullNode.jar，配置和启动参数不同，扮演的网络角色就不同。

有关各节点类型的详细对比与选型建议，请参阅节点概述。

支持平台

⚠️

JDK 版本由 CPU 架构决定

上述 JDK 版本不是二选一：x86_64 / amd64 仅支持 JDK 8，ARM64 / aarch64 仅支持 JDK 17。节点启动时会检查架构与 JDK 主版本，不匹配时将直接退出。ARM64 架构从 java-tron 4.8.1 开始受支持。

硬件要求

最低配置

运行 java-tron 节点的最低硬件配置要求如下：

• CPU：8 核
• 内存：16 GB
• SSD：3 TB 以上
• 网络带宽：100 Mbps

该配置能基本满足区块的同步需求并处理轻量级的查询。若需要部署在正式的生产环境，建议选用下方的推荐配置。

推荐配置

超级代表（SR）全节点除了处理普通网络请求，还要承担高频、敏感的共识计算和签名出块，因此 CPU 和内存规格要求更高。轻节点初始占用磁盘小，但启动同步后的数据增长速度与全节点一致，建议定期用裁剪工具清理磁盘（参见轻节点部署）。

您也可使用第三方托管服务，例如 Chainstack Self-Hosted。

1. 获取 FullNode.jar

可以从源码编译，或直接下载已发布的稳定版本。

方式 A：从源码编译

git clone https://github.com/tronprotocol/java-tron.git
cd java-tron
git checkout -t origin/master
./gradlew clean build -x test

编译成功后，生成的 FullNode.jar 会位于 ./build/libs/FullNode.jar。

方式 B：下载发布版本

直接从 java-tron releases 下载最新发布的 JAR 包。发布包都已签名，投入生产前务必验证校验和（Checksum）。

2. 选择配置文件

针对不同的网络，请选择对应的默认配置文件：

下载或准备好配置文件后，将其重命名为 config.conf，并存放在与 FullNode.jar 相同的目录下。

3. 启动节点

基础启动命令

根据 CPU 架构选择对应的 JDK 和启动命令。以下以 16 GB 内存的主机为例：

# x86_64 / amd64：JDK 8
java -Xms9G -Xmx9G -XX:+UseConcMarkSweepGC -jar FullNode.jar -c config.conf

# ARM64 / aarch64：JDK 17
java -Xmx9G -XX:+UseZGC -jar FullNode.jar -c config.conf

以上命令适合首次启动和基本验证。长期运行主网节点时，建议使用下方的完整 JVM 参数。

JVM 参数配置

以下完整命令以 16 GB 内存主机为例，参数与 java-tron 源码中的启动脚本保持一致：

# x86_64 / amd64：JDK 8
java -Xms9G -Xmx9G \
  -XX:+UseConcMarkSweepGC \
  -XX:+PrintGCDetails -Xloggc:./gc.log -XX:+PrintGCDateStamps \
  -XX:+CMSParallelRemarkEnabled \
  -XX:ReservedCodeCacheSize=256m \
  -XX:+UseCodeCacheFlushing \
  -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m \
  -XX:MaxDirectMemorySize=1g \
  -XX:+HeapDumpOnOutOfMemoryError \
  -XX:NewRatio=2 \
  -jar FullNode.jar -c config.conf

# ARM64 / aarch64：JDK 17
java -Xmx9G -XX:+UseZGC \
  -Xlog:gc,gc+heap:file=gc.log:time,tags,level:filecount=10,filesize=100M \
  -XX:ReservedCodeCacheSize=256m \
  -XX:+UseCodeCacheFlushing \
  -XX:MetaspaceSize=256m \
  -XX:MaxMetaspaceSize=512m \
  -XX:MaxDirectMemorySize=1g \
  -XX:+HeapDumpOnOutOfMemoryError \
  -jar FullNode.jar -c config.conf

• -Xms / -Xmx：分别设置 JVM 初始堆和最大堆。对于 32 GB 及以上内存的主机，建议将 -Xmx 设为物理内存的约 40%；x86_64 主机可从 -Xms9G 开始，再根据节点负载和监控结果调整。ARM64 启动脚本默认不设置 -Xms。
• ReservedCodeCacheSize：设置 JIT 代码缓存的最大容量；MetaspaceSize：设置触发元空间垃圾回收的初始阈值；MaxMetaspaceSize：限制元空间的最大容量；MaxDirectMemorySize：限制 NIO 直接内存的最大容量。
• 上述推荐配置在 x86_64 的 JDK 8 上使用 CMS GC 及其日志参数，在 ARM64 的 JDK 17 上使用 ZGC 和统一日志参数。GC 日志采用独立文件，发生内存溢出时会生成 Heap Dump，便于诊断。
• 所有 JVM 参数都必须写在 -jar 之前；-c config.conf 用于指定节点配置文件。

在主网从创世区块（高度 0）开始冷同步可能耗时数月。建议先下载主网数据库快照，解压到 FullNode.jar 同目录的 output-directory 文件夹中快速同步。

如需安全关闭正在运行的节点，请使用：

kill -15 <pid>

出块全节点（超级代表）

如果已成功申请为超级代表（SR）账户，或准备竞选超级代表，就需要部署并运行出块节点。在 TRON 网络中，得票最高的前 27 名超级代表当选活跃超级代表，轮流打包出块并领取产块奖励。

启用全节点出块模块，只需在启动命令里加 --witness 参数，这是超级代表参与共识、领取奖励的前提。此外，出块节点运行时必须加载 SR 的签名私钥：可在配置文件里直接写明文私钥，或用 keystore 文件加密加载。

配置签名私钥

方式 A：在 config.conf 中直接配置私钥——最便捷，但私钥以明文存在磁盘上。

localwitness = [
    650950B1...295BD812   // 64 位 Hex 编码的私钥
]

方式 B：通过加密 keystore 文件加载——生产环境推荐，启动节点时需交互式输入密码。

localwitness = []
localwitnesskeystore = [
    "subdir/localwitnesskeystore.json"
]

这里的路径相对于执行启动命令的目录。从 GreatVoyage-v4.8.2 开始，推荐使用随节点发布的 Toolkit 创建或导入 keystore：

java -jar Toolkit.jar keystore new
# 或导入已有私钥
java -jar Toolkit.jar keystore import

可通过 --keystore-dir 指定输出目录。旧的 FullNode.jar --keystore-factory 入口目前仍可使用，但运行时会提示该入口已弃用，并计划在后续版本中移除。新操作建议直接使用 Toolkit；现有依赖旧入口的脚本或操作流程应逐步切换。完整命令及安全注意事项参阅节点维护工具套件。

使用 --witness 参数启动节点

java -Xms9G -Xmx24G -XX:+UseConcMarkSweepGC -jar FullNode.jar --witness -c config.conf

若配置了 keystore 文件，进程启动时会暂停、等待人工输入密码，因此不要直接用后台无交互命令（如 nohup）启动。建议用会话管理器（如 screen、tmux），或配置 Type=notify 的 systemd 服务，这样输入密码后即可断开终端、保持进程运行。

轻节点部署

轻节点和普通全节点运行同一份 FullNode.jar，但从轻节点数据库快照启动，该快照只含最新全局状态和最近 65,536 个区块。两者的性能对比参阅节点概述。

获取轻节点快照

获取快照主要有以下两种方式：

• 直接下载公开快照：从公开数据备份源下载社区打包好的轻节点快照，这是最快的方式。

• 利用 Toolkit 工具自行裁剪现有的全节点数据库：

  Bash

  java -jar Toolkit.jar db lite -o split -t snapshot -fn /path/to/fullnode/output-directory -ds /path/to/snapshot

  如果本地已有同步完整的全节点，可用此命令提取轻节点快照。参数细节参阅节点维护工具套件。

解压获取到的快照数据，并将其放置在 FullNode.jar 目录下的 output-directory 文件夹中。

启动轻节点

轻节点与全节点的启动方式相同，不需要额外的轻节点启动参数。请根据 CPU 架构选择对应的 JDK 和启动命令。以下以 16 GB 内存的主机为例：

# x86_64 / amd64：JDK 8
java -Xms9G -Xmx9G -XX:+UseConcMarkSweepGC -jar FullNode.jar -c config.conf

# ARM64 / aarch64：JDK 17
java -Xmx9G -XX:+UseZGC -jar FullNode.jar -c config.conf

长期运行时，请使用JVM 参数配置中对应架构的完整命令。

FullNode.jar 会自动识别轻节点快照的数据库结构，并以轻节点模式运行。

默认的 API 查询限制

默认情况下，轻节点拒绝查询快照区块高度（即最近 65,536 个区块）之前的历史数据：所有按区块 / 交易哈希，或按历史去中心化交易所交易，访问 /wallet/、/walletsolidity/、/walletpbft/ 的查询请求，都会被网关过滤，并收到报错：this API is closed because this node is a lite fullnode。具体过滤的 API 列表见 LiteFnQueryHttpFilter.java 和 LiteFnQueryGrpcInterceptor.java。

如果希望轻节点提供它启动同步之后累积的历史数据查询，可在 config.conf 中把下面的参数设为 true：

node.openHistoryQueryWhenLiteFN = true

注意，快照生成之前的历史区块数据并未保存在本节点磁盘上，因此无论这个参数怎么设，轻节点都无法提供那段时间之前的历史数据。

定期进行重新裁剪

轻节点运行起来后，累积新区块的速度与普通全节点一致。为保持磁盘轻量，建议定期用 Toolkit.jar 命令行工具的 lite 命令对节点数据库做二次裁剪（通常每月一次）。

日常运维

安全关闭节点

为避免底层数据库写损坏，请用以下命令优雅关闭：

kill -15 <pid>

维持节点在线

节点无法保证 100% 在线，但保持在线能减少重启后追赶最新区块的时间。运维建议：

1. 始终使用 kill -15 优雅关闭节点以保护数据完整性。
2. 重启时，从本地最新区块高度继续追赶。若离线过久，节点在追上最新高度前，无法正常响应外部实时 API 请求。

客户端升级

请关注客户端升级公告，在重大升级或治理提议生效前完成更新。客户端版本过旧，可能在升级提议激活后无法同步新区块。

基本的节点升级步骤如下：

1. 下载最新发布的 FullNode.jar 与 Toolkit.jar 包。
2. 使用 kill -15 安全关闭当前运行中的节点。
3. 替换对应的旧 JAR 包。
4. 重启节点进程。

作为超级代表（SR），升级出块主节点前，务必先把出块权限切换到备用节点。切勿在正在出块的主节点上直接做就地热升级。详细的升级与倒换规范，参阅超级代表 (SR) 最佳实践。

其他常用配置选项

使用 tcmalloc 优化内存分配

tcmalloc 能明显改善 JVM 原生内存分配的碎片化，并降低高并发查询下的系统延迟。装好后，在启动节点前加载环境变量即可启用。

libtcmalloc.so.4 的安装路径因 Linux 发行版和 CPU 架构而异。安装后请运行 ldconfig -p | awk '$1 == "libtcmalloc.so.4" {print $NF; exit}' 查询本机实际路径，并将输出路径填入 LD_PRELOAD；如果命令没有输出，请检查软件包是否已正确安装。下表中的路径仅为 x86_64 示例：

启动节点前，在当前 Shell 中设置以下环境变量：

# 将以下路径替换为上述命令输出的实际路径
export LD_PRELOAD="/usr/lib/x86_64-linux-gnu/libtcmalloc.so.4"
export TCMALLOC_RELEASE_RATE=10

随后在同一 Shell 中执行JVM 参数配置中对应架构的启动命令。

作为纯只读/查询节点运行（禁用 P2P 网络连接）

节点支持在关闭 P2P 发现和通信的情况下运行，只对本地提供离线数据查询。该模式很适合数据分析、只读归档服务或只读索引器后端。

目前禁用 P2P 的唯一方式是命令行传入 --p2p-disable true 参数（代码 CommonParameter.java 中已确认，没有对应的配置文件键）：

java -jar FullNode.jar -c config.conf --p2p-disable true

同时，为彻底阻止节点对外发起 P2P 连接，建议在 config.conf 中这样配置：

node.discovery.enable = false
node.active = []
node.passive = []

这样启动的节点仍提供 HTTP 和 gRPC 查询接口，但不再主动连接对等节点、也不再同步最新区块。

默认端口列表

主网默认的 config.conf 包含以下通信端口。如果在单台主机上运行多个节点，请确保这些端口不冲突：

⚠️

端口访问控制

除必需的 P2P 通信外，HTTP、gRPC、ZeroMQ 和备用节点端口应只向可信内网或经明确授权的客户端开放。使用防火墙或安全组限制来源地址；如需提供公网 API，应通过启用 TLS、身份验证和限流的可信网关转发，不要直接暴露节点端口。

启用历史余额查询功能

如果要用 API wallet/getaccountbalance 查询任意账户在任意历史高度的 TRX 余额，需做以下配置：

1. 在 config.conf 配置文件中开启该功能：

   Text

   storage {
     balance.history.lookup = true
   }

2. （可选）下载并使用包含历史余额数据的全节点快照，参见主网数据库快照。若不用带余额历史的快照，节点只能查询从开启该参数、完成同步以来各区块高度的余额，更早的历史数据无法追溯。

3. 正常启动节点。等节点同步追上网络高度后，历史余额 API 就会返回正常数据。

相关资源

• 节点概述——TRON 节点类型及如何选型
• 数据库快照——使用主网备份快照跳过冷同步
• 节点维护工具套件——数据库的转换、裁剪与备份维护
• TRON 私链——如何搭建隔离的私有开发测试链
• 成为超级代表——超级代表注册与竞选流程说明
• 超级代表配置——超级代表节点的高级 witness 权限代理配置
• 账户与密钥——TRON 账户与密钥模型基础