Skip to main content

Documentation Index

Fetch the complete documentation index at: https://daehan-base.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

이 가이드는 공식 Base 노드 Docker 설정을 사용하여 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 노드 실행 > 노드 실행 확인 참조). 또한 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 문제를 유발할 수 있습니다.
  • 문제: 동기화가 매우 느림.
    • 확인: 하드웨어 사양. 노드 성능 가이드에 설명된 권장 사양(특히 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 사용량.
    • 확인: 노드 성능의 권장 사항에 대한 하드웨어 사양. 필요하면 업그레이드합니다. 로컬 NVMe SSD가 매우 중요합니다.
    • 확인: 특정 오류나 병목을 찾기 위해 클라이언트 로그를 검토합니다.

​
스냅샷 복원 문제

올바른 절차는 스냅샷 가이드를 참조하세요.
  • 문제: 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> 플래그를 구성합니다(고급 설정 참조).
  • 문제: 로그에 포트 충돌 보고 또는 docker compose up 실패.
    • 확인: 호스트에서 기본 포트(8545, 8546, 8551, 6060, 7545, 30303)를 사용하는 다른 서비스가 실행 중인가요? 다음을 사용하세요: 
      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에 참여하여 🛠｜node-operators 채널에 설정, 문제, 관련 로그에 대한 세부 정보를 게시합니다.
  • GitHub: Base 노드 저장소 이슈를 확인하거나 버그로 의심되는 경우 새 이슈를 열어 보세요.