> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plasma.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 非验证者节点部署

> 使用 Docker Compose 部署和运行非验证者节点的完整指南。

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

## 前置条件

<Check>基本的 Linux 管理技能</Check>
<Check>已安装 Docker 与 Docker Compose</Check>
<Check>一台满足[硬件要求](./hardware-requirements)的服务器</Check>

## 可用网络

| 网络      | 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 身份认证。

## 快速开始

<Steps>
  <Step title="安装 Docker">
    连接到你的服务器，并确保已安装 **Docker** 和 **Docker Compose**。
  </Step>

  <Step title="克隆 templates 仓库">
    ```bash theme={null}
    git clone https://github.com/PlasmaLaboratories/non-validator-templates.git
    cd non-validator-templates
    ```
  </Step>

  <Step title="启动节点">
    将 `{network}` 替换为 `mainnet`、`testnet` 或 `devnet`：

    ```bash theme={null}
    cd {network}/docker-compose
    docker compose up -d
    ```
  </Step>

  <Step title="确认容器正在运行">
    ```bash theme={null}
    docker compose ps
    docker compose logs -f plasma-consensus
    ```
  </Step>

  <Step title="启动监控（可选）">
    ```bash theme={null}
    docker compose -f monitoring.yml up -d
    ```
  </Step>
</Steps>

## 架构概览

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

<CardGroup cols={2}>
  <Card title="Plasma Execution Client" icon="microchip">
    基于 [Reth](https://github.com/paradigmxyz/reth)。处理交易执行、状态管理，并为应用提供 JSON-RPC 端点。
  </Card>

  <Card title="Plasma Observer Client" icon="satellite-dish">
    一个轻量级客户端，监控 Plasma 共识网络，但不参与区块生产或验证。
  </Card>
</CardGroup>

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 文件定义了四个按顺序运行的服务：

<Steps>
  <Step title="OpenSSL 初始化">
    为安全的 Engine API 通信生成 JWT 密钥，并为节点的网络身份生成 secp256k1 密钥。这些仅生成一次，并在重启后保持持久。
  </Step>

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

  <Step title="执行数据库初始化">
    使用创世状态初始化 Reth 执行数据库。
  </Step>

  <Step title="容器部署">
    初始化完成后，执行客户端和共识客户端启动。**执行客户端（Reth）** 先启动并暴露 JSON-RPC API 与 Engine API。**共识观察者客户端** 在执行客户端进入健康状态后启动，并连接到共识网络。
  </Step>
</Steps>

## 配置

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

<Accordion title="共识配置参考 (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`                                                            | 共识引导对等节点    |
</Accordion>

### NAT / 外部地址

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

<CodeGroup>
  ```toml non-validator.toml theme={null}
  [network]
  external_address = "node.example.com:34070"
  ```

  ```bash CLI theme={null}
  --p2p.external-address node.example.com:34070
  ```
</CodeGroup>

### 端口配置

| 端口      | 服务             | 协议      | 描述              |
| ------- | -------------- | ------- | --------------- |
| `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 指标   |

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

## 常见操作

```bash theme={null}
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
```

## 监控你的节点

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

<Tabs>
  <Tab title="状态检查">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="同步状态">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="端点">
    | 端点            | URL                             |
    | ------------- | ------------------------------- |
    | Execution RPC | `http://localhost:8545`         |
    | Consensus API | `http://localhost:35070`        |
    | Metrics       | `http://localhost:9001/metrics` |
  </Tab>
</Tabs>

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

## 数据库快照

Plasma 为 **mainnet** 与 **testnet** 每日发布数据库快照。快照可让你在数小时内引导新节点，而不是从创世开始同步（后者可能耗时显著更长）。

每个快照包含两个文件——共识层数据库和执行层数据库——上传到一个 requester-pays S3 存储桶。你需要一个 AWS 账户；将适用标准的 S3 数据传输费率。

### 快照前置条件

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

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

### 快照存储桶

| 属性       | 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 归档 |

### 下载快照

```bash theme={null}
# 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
```

### 从快照恢复

<Steps>
  <Step title="停止节点">
    ```bash theme={null}
    cd {network}/docker-compose
    docker compose down
    ```
  </Step>

  <Step title="恢复共识数据库">
    将快照复制到共识数据目录：

    ```bash theme={null}
    # Mainnet (.db)
    cp backups/consensus-backup-*.db /path/to/plasma-data-dir/

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

  <Step title="恢复执行数据库">
    将归档解压到执行数据目录：

    ```bash theme={null}
    tar -xzf backups/execution-backup-*.tar.gz -C /path/to/execution-data-dir/
    ```
  </Step>

  <Step title="重启节点">
    ```bash theme={null}
    docker compose up -d
    ```
  </Step>
</Steps>

### 快照故障排查

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