> ## 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>

## 사용 가능한 네트워크

| 네트워크    | 체인 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="템플릿 저장소 복제">
    ```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 실행 클라이언트" icon="microchip">
    [Reth](https://github.com/paradigmxyz/reth) 기반. 트랜잭션 실행, 상태 관리를 처리하며 애플리케이션을 위한 JSON-RPC 엔드포인트를 제공합니다.
  </Card>

  <Card title="Plasma 옵저버 클라이언트" icon="satellite-dish">
    블록 생성이나 검증에 참여하지 않고 Plasma 합의 네트워크를 모니터링하는 가벼운 클라이언트입니다.
  </Card>
</CardGroup>

Docker Compose 설정은 JWT 시크릿 생성, 키 생성 및 데이터베이스 설정을 자동으로 처리하는 초기화 컨테이너와 함께 이러한 구성 요소를 조율합니다.

### 디렉터리 구조

각 네트워크 디렉터리는 동일한 레이아웃을 따릅니다:

```
{network}/
├── docker-compose/
│   ├── docker-compose.yml        # 서비스 정의
│   ├── .env                      # 이미지 버전 및 태그 (단일 소스)
│   ├── non-validator.toml        # 합의 구성
│   ├── enodes.txt                # 실행 부트스트랩 노드
│   ├── monitoring.yml            # 모니터링 스택
│   └── monitoring/               # Prometheus & Grafana 구성
└── shared/                       # 검증자 키 & 신원 (읽기 전용)
    ├── keys/                     # BLS12-381 검증자 공개 키
    └── identities/               # 검증자 신원 파일
```

## 설정 프로세스 설명

Docker Compose 파일은 순차적으로 실행되는 네 가지 서비스를 정의합니다:

<Steps>
  <Step title="OpenSSL 초기화">
    안전한 Engine API 통신을 위한 JWT 시크릿을 생성하고 노드의 네트워크 신원을 위한 secp256k1 키를 만듭니다. 이는 한 번만 생성되고 재시작 시에도 유지됩니다.
  </Step>

  <Step title="합의 데이터베이스 초기화">
    선택한 네트워크의 제네시스 구성으로 합의 데이터베이스를 초기화하고 노드용 피어 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)">
  | 섹션                            | 필드                                                                                           | 설명                  |
  | ----------------------------- | -------------------------------------------------------------------------------------------- | ------------------- |
  | *(최상위)*                       | `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`  | 실행 RPC | HTTP    | JSON-RPC API 엔드포인트 |
| `8551`  | 실행 인증  | HTTP    | Engine API (내부)    |
| `30303` | 실행 P2P | TCP/UDP | P2P 네트워킹           |
| `34070` | 합의 P2P | TCP     | 합의 네트워킹            |
| `35070` | 합의 API | HTTP    | 합의 상태/API 엔드포인트    |
| `9001`  | 메트릭    | HTTP    | Prometheus 메트릭     |

<Warning>
  **방화벽 요구 사항**: 실행 P2P를 위해 포트 `30303`(TCP/UDP)의 인바운드/아웃바운드를, 합의 P2P를 위해 포트 `34070`(TCP)의 인바운드를, Engine API를 위해 포트 `8551`의 내부 통신을 보장하세요. JSON-RPC 인터페이스(포트 `8545`)는 기본적으로 노출되며 — 프로덕션에서는 접근 제한을 고려하세요.
</Warning>

## 일반 작업

```bash theme={null}
cd {network}/docker-compose

docker compose up -d                              # 시작
docker compose -f monitoring.yml up -d            # 모니터링 시작
docker compose logs -f                            # 로그
docker compose down                               # 중지
docker compose -f monitoring.yml down             # 모니터링 중지
docker compose down -v && docker compose up -d    # 클린 재시작
```

## 노드 모니터링

노드가 운영되면 상태와 동기화 상태를 모니터링할 수 있습니다. 종합적인 모니터링 설정과 모범 사례는 [모니터링 가이드](../maintenance/monitoring)를 참조하세요.

<Tabs>
  <Tab title="상태 확인">
    ```bash theme={null}
    # 컨테이너 상태 확인
    docker compose ps

    # 실행 클라이언트 로그 보기
    docker compose logs -f plasma-execution

    # 합의 옵저버 클라이언트 로그 보기
    docker compose logs -f plasma-consensus
    ```
  </Tab>

  <Tab title="동기화 상태">
    ```bash theme={null}
    # 실행 클라이언트 동기화 상태 확인
    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                             |
    | ------ | ------------------------------- |
    | 실행 RPC | `http://localhost:8545`         |
    | 합의 API | `http://localhost:35070`        |
    | 메트릭    | `http://localhost:9001/metrics` |
  </Tab>
</Tabs>

노드는 즉시 동기화를 시작합니다. 초기 동기화는 네트워크 조건과 하드웨어 사양에 따라 수 분이 걸릴 수 있습니다.

## 데이터베이스 스냅샷

Plasma는 **mainnet**과 **testnet**에 대해 일일 데이터베이스 스냅샷을 게시합니다. 스냅샷은 제네시스부터 동기화하는 대신 새 노드를 몇 시간 안에 부트스트랩할 수 있게 해주며, 제네시스부터 동기화는 상당히 더 오래 걸릴 수 있습니다.

각 스냅샷에는 두 개의 파일 — 합의 계층 데이터베이스와 실행 계층 데이터베이스 — 이 포함되어 있으며, 요청자 지불 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)          |
| **액세스 모델** | 요청자 지불                      | 요청자 지불                      |
| **백업 주기**  | 일일                          | 매일 02:00 UTC                |
| **보존**     | 롤링 (오래된 백업은 자동으로 제거됨)       | 3일                          |

백업은 날짜 스탬프 폴더(`MM-DD-YY`)로 정리됩니다. 각 폴더에는 두 개의 파일이 포함됩니다:

| 파일                                              | 설명                             |
| ----------------------------------------------- | ------------------------------ |
| **합의 데이터베이스** (mainnet은 `.db`, testnet은 `.mdb`) | 전체 합의 계층 상태                    |
| **실행 데이터베이스** (`.tar.gz`)                       | Reth 실행 `data/` 디렉터리의 Tar 아카이브 |

### 스냅샷 다운로드

```bash theme={null}
# 대상 네트워크의 버킷 설정
BUCKET="plasma-mainnet-db-backups"   # 또는 "plasma-testnet-db-backups"

# 사용 가능한 스냅샷 목록
aws s3 ls "s3://${BUCKET}/" \
  --region us-east-2 \
  --request-payer requester

# 최신 스냅샷 다운로드
DATE="MM-DD-YY"   # 최신 날짜 폴더로 교체 (예: 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`를 사용합니다. 네트워크에 맞는 파일을 복사하세요.               |