Plasma Docs - Build on Plasma

非验证者节点通过监控共识客户端和服务应用请求，向 Plasma 网络提供 RPC 访问。本指南将介绍如何使用官方的 non-validator-templates 仓库进行部署。

前置条件

基本的 Linux 管理技能

已安装 Docker 与 Docker Compose

一台满足硬件要求的服务器

可用网络

网络	Chain ID	共识版本	执行层版本
mainnet	9745	0.15.0	Reth v1.8.3
testnet	9746	0.15.0	Reth v1.8.3
devnet	9747	0.15.0	Reth v1.8.3

所有网络均使用公共 plasma-consensus-public 镜像 —— 无需 GHCR 身份认证。

快速开始

安装 Docker

连接到你的服务器，并确保已安装 Docker 和 Docker Compose。

克隆 templates 仓库

git clone https://github.com/PlasmaLaboratories/non-validator-templates.git
cd non-validator-templates

启动节点

将 {network} 替换为 mainnet、testnet 或 devnet：

cd {network}/docker-compose
docker compose up -d

确认容器正在运行

docker compose ps
docker compose logs -f plasma-consensus

启动监控（可选）

docker compose -f monitoring.yml up -d

架构概览

你的非验证者节点由两个主要组件构成：

Plasma Execution Client

基于 Reth。处理交易执行、状态管理，并为应用提供 JSON-RPC 端点。

Plasma Observer Client

一个轻量级客户端，监控 Plasma 共识网络，但不参与区块生产或验证。

Docker Compose 设置会编排这些组件，并搭配自动处理 JWT 密钥生成、密钥生成和数据库初始化的初始化容器。

目录结构

每个网络目录采用相同的布局：

{network}/
├── docker-compose/
│   ├── docker-compose.yml        # Service definitions
│   ├── .env                      # Image versions and tags (source of truth)
│   ├── non-validator.toml        # Consensus configuration
│   ├── enodes.txt                # Execution bootstrap nodes
│   ├── monitoring.yml            # Monitoring stack
│   └── monitoring/               # Prometheus & Grafana configs
└── shared/                       # Validator keys & identities (read-only)
    ├── keys/                     # BLS12-381 validator public keys
    └── identities/               # Validator identity files

部署流程详解

Docker Compose 文件定义了四个按顺序运行的服务：

OpenSSL 初始化

为安全的 Engine API 通信生成 JWT 密钥，并为节点的网络身份生成 secp256k1 密钥。这些仅生成一次，并在重启后保持持久。

共识数据库初始化

使用所选网络的创世配置初始化共识数据库，并为节点生成 peer ID。

执行数据库初始化

使用创世状态初始化 Reth 执行数据库。

容器部署

初始化完成后，执行客户端和共识客户端启动。执行客户端（Reth） 先启动并暴露 JSON-RPC API 与 Engine API。共识观察者客户端 在执行客户端进入健康状态后启动，并连接到共识网络。

配置

所有版本号和镜像标签均定义在每个网络的 .env 文件中——这是软件版本的唯一可信来源。共识客户端通过 non-validator.toml 进行配置。

共识配置参考 (non-validator.toml)

区段	字段	描述
(top-level)	`engine_api_url`, `consensus_api_host`, `authrpc_jwtsecret`	执行引擎连接
`[persistence]`	`data_dir`	共识数据存储路径
`[network]`	`p2p_port`, `interval`, `timeout`, `identity_file_path`, `trusted_only`, `discovery.enabled`	P2P 网络与对等发现
`[api]`	`enabled`, `host`, `port`	共识 API 端点
`[validators.*]`	`validator_keystore_pk_file_path`, `identity_file_path`	验证者委员会
`[network.bootstrap_nodes.*]`	`api_host`, `p2p_port`, `peer_id`	共识引导对等节点

NAT / 外部地址

对于位于 NAT 后的节点，请配置外部地址，以便其他对等节点可以发现并连接到你的节点：

[network]
external_address = "node.example.com:34070"

--p2p.external-address node.example.com:34070

端口配置

端口	服务	协议	描述
`8545`	Execution RPC	HTTP	JSON-RPC API 端点
`8551`	Execution Auth	HTTP	Engine API（内部）
`30303`	Execution P2P	TCP/UDP	点对点网络
`34070`	Consensus P2P	TCP	共识网络
`35070`	Consensus API	HTTP	共识健康/API 端点
`9001`	Metrics	HTTP	Prometheus 指标

防火墙要求：请确保端口 30303（TCP/UDP）允许执行 P2P 的入站/出站，端口 34070（TCP）允许共识 P2P 的入站，以及端口 8551 用于 Engine API 的内部通信。端口 8545 上的 JSON-RPC 接口默认对外暴露——在生产环境中请考虑限制访问。

常见操作

cd {network}/docker-compose

docker compose up -d                              # Start
docker compose -f monitoring.yml up -d            # Start monitoring
docker compose logs -f                            # Logs
docker compose down                               # Stop
docker compose -f monitoring.yml down             # Stop monitoring
docker compose down -v && docker compose up -d    # Clean restart

监控你的节点

节点上线后，你可以监控其健康与同步状态。关于全面的监控设置与最佳实践，请参阅监控指南。

状态检查
同步状态
端点

# Check container status
docker compose ps

# View execution client logs
docker compose logs -f plasma-execution

# View consensus observer client logs
docker compose logs -f plasma-consensus

# Check execution client sync status
curl -s -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' \
  http://localhost:8545

端点	URL
Execution RPC	`http://localhost:8545`
Consensus API	`http://localhost:35070`
Metrics	`http://localhost:9001/metrics`

节点将立即开始同步。初始同步可能需要数分钟，具体取决于网络条件和硬件规格。

数据库快照

Plasma 为 mainnet 与 testnet 每日发布数据库快照。快照可让你在数小时内引导新节点，而不是从创世开始同步（后者可能耗时显著更长）。每个快照包含两个文件——共识层数据库和执行层数据库——上传到一个 requester-pays S3 存储桶。你需要一个 AWS 账户；将适用标准的 S3 数据传输费率。

快照前置条件

要求	详情
AWS 账户	通过 `aws configure` 或环境变量配置凭证
AWS CLI	推荐 v2（`aws --version`）
磁盘空间	Mainnet：约 400 GB 空闲 • Testnet：约 100 GB 空闲

从 us-east-2 出站的数据传输费率为前 10 TB/月约 $0.09/GB。从 同区域 的 EC2 实例传输是免费的——将节点运行在 us-east-2 是最具成本效益的选项。

快照存储桶

属性	Mainnet	Testnet
存储桶	`plasma-mainnet-db-backups`	`plasma-testnet-db-backups`
区域	`us-east-2` (Ohio)	`us-east-2` (Ohio)
访问模式	Requester-pays	Requester-pays
备份频率	每日	每日 02:00 UTC
保留	滚动（旧备份自动移除）	3 天

备份按带日期的文件夹组织（MM-DD-YY）。每个文件夹包含两个文件：

文件	描述
共识数据库（mainnet 上为 `.db`，testnet 上为 `.mdb`）	完整的共识层状态
执行数据库（`.tar.gz`）	Reth 执行层 `data/` 目录的 tar 归档

下载快照

# Set your target network's bucket
BUCKET="plasma-mainnet-db-backups"   # or "plasma-testnet-db-backups"

# List available snapshots
aws s3 ls "s3://${BUCKET}/" \
  --region us-east-2 \
  --request-payer requester

# Download the most recent snapshot
DATE="MM-DD-YY"   # replace with the latest date folder (e.g. 03-23-26)

aws s3 cp \
  "s3://${BUCKET}/${DATE}/" \
  ./backups/ \
  --recursive \
  --region us-east-2 \
  --request-payer requester

从快照恢复

停止节点

cd {network}/docker-compose
docker compose down

恢复共识数据库

将快照复制到共识数据目录：

# Mainnet (.db)
cp backups/consensus-backup-*.db /path/to/plasma-data-dir/

# Testnet (.mdb)
cp backups/consensus-backup-*.mdb /path/to/plasma-data-dir/

恢复执行数据库

将归档解压到执行数据目录：

tar -xzf backups/execution-backup-*.tar.gz -C /path/to/execution-data-dir/

重启节点

docker compose up -d

快照故障排查

问题	原因/解决方案
`Access Denied`	你必须在每个命令中包含 `--request-payer requester`。存储桶会拒绝不带该参数的请求。
`403 Forbidden`	AWS 凭证未配置。运行 `aws sts get-caller-identity` 验证你拥有有效会话。
存储桶列表为空	旧备份会被自动清理。如果桶看起来是空的，可能正处于备份周期中——请稍后再查看。
错误的文件扩展名	Mainnet 使用 `.db`；testnet 使用 `.mdb`。请确保为你的网络复制正确的文件。

设置与配置

维护

共识节点

非验证者节点部署

前置条件

可用网络

快速开始

架构概览

Plasma Execution Client

Plasma Observer Client

目录结构

部署流程详解

配置

NAT / 外部地址

端口配置

常见操作

监控你的节点

数据库快照

快照前置条件

快照存储桶

下载快照

从快照恢复

快照故障排查

​前置条件

​可用网络

​快速开始

​架构概览

Plasma Execution Client

Plasma Observer Client

​目录结构

​部署流程详解

​配置

​NAT / 外部地址

​端口配置

​常见操作

​监控你的节点

​数据库快照

​快照前置条件

​快照存储桶

​下载快照

​从快照恢复

​快照故障排查

前置条件

可用网络

快速开始

架构概览

目录结构

部署流程详解

配置

NAT / 外部地址

端口配置

常见操作

监控你的节点

数据库快照

快照前置条件

快照存储桶

下载快照

从快照恢复

快照故障排查