> ## Documentation Index
> Fetch the complete documentation index at: https://daehan-base.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 노드 문제 해결

> Base 노드를 설정하고 실행할 때 발생하는 일반적인 문제를 진단하고 해결하기 위한 가이드입니다.

이 가이드는 공식 [Base 노드 Docker 설정](https://github.com/base/node)을 사용하여 Base 노드를 설정하고 실행할 때 발생하는 일반적인 문제를 다루며 진단 및 해결 단계를 제공합니다.

## 일반적인 문제 해결 단계

특정 문제로 넘어가기 전에 일반적으로 도움이 되는 단계가 있습니다:

1. **컨테이너 로그 확인**: 일반적으로 가장 유익한 단계입니다. `docker compose logs -f <service_name>`을 사용하여 특정 컨테이너의 실시간 로그를 확인합니다.
   * L2 클라이언트 (Reth): `docker compose logs -f execution`
   * 롤업 노드: `docker compose logs -f node`. 오류, 경고 또는 반복되는 메시지를 확인합니다.

2. **컨테이너 상태 확인**: 관련 Docker 컨테이너가 실행 중인지 확인합니다: `docker compose ps`. 컨테이너가 자주 재시작되거나 종료된 경우 로그를 확인합니다.

3. **리소스 사용량 확인**: 서버의 CPU, RAM, 디스크 I/O, 네트워크 사용량을 모니터링합니다. 성능 문제는 종종 불충분한 리소스와 관련됩니다. `htop`, `iostat`, `iftop`과 같은 도구가 유용합니다.

4. **RPC 엔드포인트 확인**: `curl`을 사용하여 L2 클라이언트의 RPC 엔드포인트가 응답하는지 확인합니다([Base 노드 실행 > 노드 실행 확인](/base-chain/node-operators/run-a-base-node#verify-node-is-running) 참조). 또한 L1 엔드포인트가 올바르고 노드 서버에서 접근 가능한지 확인합니다.

5. **L1 노드 확인**: 구성된 L1 노드(실행 및 합의)가 완전히 동기화되고 건강하며 접근 가능한지 확인합니다. L1 노드의 문제는 L2 노드의 동기화를 방해합니다.

***

## 일반적인 문제와 해결책

### 설정 및 구성 문제

* **문제**: Docker 명령 실패 (`docker compose up ...`)
  * **확인**: Docker와 Docker Compose가 설치되고 Docker 데몬이 실행 중인가요?
  * **확인**: `docker-compose.yml`이 포함된 클론된 `node` 디렉토리에 있나요?
  * **확인**: 명령의 구문 오류(예: `NETWORK_ENV` 또는 `CLIENT` 오타).

* **문제**: 컨테이너 시작 실패, `.env` 파일 또는 환경 변수 관련 오류 표시.
  * **확인**: 올바른 `.env` 파일(`.env.mainnet` 또는 `.env.sepolia`)에서 L1 엔드포인트(`OP_NODE_L1_ETH_RPC`, `OP_NODE_L1_BEACON`)를 올바르게 구성했나요?
  * **확인**: 구성 또는 L1 노드에서 필요한 경우 `OP_NODE_L1_BEACON_ARCHIVER` 엔드포인트가 설정되어 있나요?
  * **확인**: L1 제공업체에 맞게 `OP_NODE_L1_RPC_KIND`가 올바르게 설정되어 있나요?
  * **확인**: (Reth) `.env` 파일에 `RETH_CHAIN`과 `RETH_SEQUENCER_HTTP`가 올바르게 설정되어 있나요?

* **문제**: `op-node`와 L2 클라이언트 간의 JWT 시크릿 또는 인증 관련 오류.
  * **확인**: 무엇을 하는지 알지 못하는 한 `OP_NODE_L2_ENGINE_AUTH` 변수나 JWT 파일 경로(`$OP_NODE_L2_ENGINE_AUTH`)를 수동으로 수정하지 않았는지 확인합니다. `docker-compose` 설정은 일반적으로 이를 자동으로 처리합니다.

* **문제**: 데이터 볼륨(`./reth-data`) 관련 권한 오류.
  * **확인**: `docker compose`를 실행하는 사용자가 `node` 저장소가 클론된 디렉토리에 쓰기 권한이 있는지 확인합니다. Docker는 `./reth-data`에 쓸 수 있어야 합니다. `sudo`로 Docker 명령을 실행하면 나중에 권한 문제가 발생할 수 있습니다; `docker` 그룹에 추가된 비루트 사용자로 실행해 보세요.

### 동기화 문제

* **문제**: 노드가 동기화를 시작하지 않거나 멈춘 것처럼 보임 (블록 높이가 증가하지 않음).
  * **확인**: `op-node` 로그. L1 엔드포인트 또는 L2 클라이언트에 연결하는 데 오류가 있나요?
  * **확인**: 실행 클라이언트 로그. 엔진 API(포트 `8551`)를 통해 `op-node`에 연결하거나 P2P 문제에 오류가 있나요?
  * **확인**: L1 노드 건강 및 동기화 상태. L1 노드가 접근 가능하고 완전히 동기화되어 있나요?
  * **확인**: 시스템 시간. 서버의 시계가 정확하게 동기화되어 있는지 확인합니다(`ntp` 또는 `chrony` 사용). 큰 시간 드리프트는 P2P 문제를 유발할 수 있습니다.

* **문제**: 동기화가 매우 느림.
  * **확인**: 하드웨어 사양. [노드 성능](/base-chain/node-operators/performance-tuning) 가이드에 설명된 권장 사양(특히 RAM과 **NVMe SSD**)을 충족하나요? 디스크 I/O가 종종 병목입니다.
  * **확인**: L1 노드 성능. L1 RPC 엔드포인트가 응답성이 있나요? 느린 L1 노드는 L2 동기화를 느리게 합니다.
  * **확인**: 네트워크 연결 품질 및 대역폭.
  * **확인**: `op-node` 및 L2 클라이언트 로그에서 성능 경고나 오류를 확인합니다.

* **문제**: `optimism_syncStatus`(포트 `7545`의 `op-node`)에서 큰 시간 차이나 오류 표시.
  * **조치**: 상태가 확인된 시간 주변에 롤업 노드와 L2 실행 클라이언트 모두의 로그를 확인하여 근본 원인(예: L1 연결 문제, L2 클라이언트 문제)을 파악합니다.

* **문제**: 트랜잭션 전송 시 `Error: nonce has already been used`.
  * **원인**: 노드가 아직 체인 헤드까지 완전히 동기화되지 않았습니다.
  * **조치**: 노드가 완전히 동기화될 때까지 기다립니다. `optimism_syncStatus` 또는 로그를 사용하여 진행 상황을 모니터링합니다.

### 성능 문제

* **문제**: 높은 CPU, RAM 또는 디스크 I/O 사용량.
  * **확인**: [노드 성능](/base-chain/node-operators/performance-tuning)의 권장 사항에 대한 하드웨어 사양. 필요하면 업그레이드합니다. 로컬 NVMe SSD가 매우 중요합니다.
  * **확인**: 특정 오류나 병목을 찾기 위해 클라이언트 로그를 검토합니다.

### 스냅샷 복원 문제

올바른 절차는 [스냅샷](/base-chain/node-operators/snapshots) 가이드를 참조하세요.

* **문제**: `wget` 명령 실패 또는 스냅샷 다운로드 손상.
  * **확인**: 네트워크 연결.
  * **확인**: 사용 가능한 디스크 공간.
  * **조치**: 다운로드를 재시도합니다. 다운로드 URL이 올바른지 확인합니다.

* **문제**: `tar` 추출 실패.
  * **확인**: 다운로드된 파일 무결성 (손상되었나요?).
  * **확인**: 사용 가능한 디스크 공간 (추출에는 다운로드보다 훨씬 많은 공간이 필요합니다).
  * **확인**: `tar` 명령 구문.

* **문제**: 스냅샷 복원 후 노드 시작 실패; 로그에 데이터베이스 오류 또는 파일 누락.
  * **확인**: 데이터 디렉토리를 수정하기 *전에* 노드를 중지(`docker compose down`)했나요?
  * **확인**: 스냅샷 데이터를 추출/이동하기 전에 기존 데이터 디렉토리의 *내용*(`./reth-data/*`)을 삭제했나요?
  * **확인**: 스냅샷 데이터가 올바르게 이동되었나요? 체인 데이터는 중첩된 하위 폴더(예: `./reth-data/reth/...`)가 아닌 `./reth-data` 내에 직접 있어야 합니다. 폴더 구조를 확인합니다.

* **문제**: 다운로드 또는 추출 중 디스크 공간 부족.
  * **조치**: 디스크 공간을 확보하거나 더 큰 볼륨을 프로비저닝합니다. 스토리지 공식을 기억하세요:
    ```
    (2 * 체인_크기 + 스냅샷_크기 + 20% 버퍼)
    ```

### 네트워킹 / 연결 문제

* **문제**: RPC/WS 연결 거부 (예: `localhost:8545`에 `curl` 실패).
  * **확인**: L2 클라이언트 컨테이너가 실행 중인가요(`docker compose ps`)?
  * **확인**: 올바른 포트를 사용하고 있나요(HTTP는 기본값 `8545`, WS는 `8546`)?
  * **확인**: L2 클라이언트 로그. RPC 서버 시작에 실패했나요?
  * **확인**: 외부 연결(Docker 네트워크 내에서)을 허용하기 위해 클라이언트 설정/엔트리포인트에서 `--http.addr`와 `--ws.addr` 플래그가 `0.0.0.0`으로 설정되어 있나요?

* **문제**: 노드의 피어 수가 낮음.
  * **확인**: P2P 포트 접근성. 호스트 또는 네트워크 방화벽에서 `30303`(TCP/UDP)과 `9222`(Reth discv5를 위한 TCP/UDP)가 차단되어 있지 않은지 확인합니다.
  * **확인**: P2P 오류에 대한 노드 로그.
  * **조치**: NAT 뒤에 있는 경우 `.env` 파일의 `ADDITIONAL_ARGS`를 통해 `--nat=extip:<your-ip>` 플래그를 구성합니다([고급 설정](/base-chain/node-operators/run-a-base-node#improving-peer-connectivity) 참조).

* **문제**: 로그에 포트 충돌 보고 또는 `docker compose up` 실패.
  * **확인**: 호스트에서 기본 포트(`8545`, `8546`, `8551`, `6060`, `7545`, `30303`)를 사용하는 다른 서비스가 실행 중인가요? 다음을 사용하세요:
    ```bash theme={null}
    sudo lsof -i -P -n | grep LISTEN
    sudo netstat -tulpn | grep LISTEN
    ```
  * **조치**: 충돌하는 서비스를 중지하거나 `docker-compose.yml`의 `ports` 섹션을 수정하고 필요한 경우 `.env` 파일에서 관련 환경 변수(`$RPC_PORT`, `$WS_PORT` 등)를 업데이트하여 Base 노드 컨테이너에서 사용하는 포트를 변경합니다.

***

## 추가 도움 받기

이 가이드를 따라도 여전히 문제가 있다면 커뮤니티에서 도움을 구하세요:

* **Discord**: [Base Discord](https://discord.gg/buildonbase)에 참여하여 `🛠｜node-operators` 채널에 설정, 문제, 관련 로그에 대한 세부 정보를 게시합니다.
* **GitHub**: [Base 노드 저장소 이슈](https://github.com/base/node/issues)를 확인하거나 버그로 의심되는 경우 새 이슈를 열어 보세요.