BSC 노드 Docker 가이드

Docker를 사용하여 Binance Smart Chain (BSC) 풀노드를 실행하는 방법입니다.
공식 클라이언트는 Geth 포크인 bsc이며, BNB Chain에서 제공하는 Docker 이미지를 사용할 수 있습니다.

이 가이드는 개념과 기본 실행 예시를 제공하며, 반드시 최신 공식 문서를 함께 참고하세요.

공식 문서: Run BSC Nodes using Docker

전체 노드 가이드: Full Node

빠른 시작

1. Docker 설치

Ubuntu 예시:

sudo apt update
sudo apt install -y docker.io
sudo systemctl enable --now docker

2. BSC Docker 이미지 받기

공식 이미지는 GitHub Container Registry에 제공됩니다.

docker pull ghcr.io/bnb-chain/bsc:latest

버전 태그는 공식 문서·릴리스 노트를 참고해 운영 환경에 맞게 고정하는 것이 좋습니다.

3. 데이터·설정 디렉토리 준비

sudo mkdir -p /mnt/cryptocur-data/bsc/node
sudo mkdir -p /mnt/cryptocur-data/bsc/config

# 권한은 운영 환경에 맞게 조정
sudo chown -R $USER:$USER /mnt/cryptocur-data/bsc
sudo chmod -R 755 /mnt/cryptocur-data/bsc

/mnt/cryptocur-data/bsc/config 에는 genesis.json, config.toml 등 네트워크 설정 파일을 둡니다.
메인넷·테스트넷용 예시는 BNB Chain 공식 문서를 참고하세요.

4. 단일 `docker run` 예시

docker run -d --name bsc-node \
  -v /mnt/cryptocur-data/bsc/config:/bsc/config \
  -v /mnt/cryptocur-data/bsc/node:/bsc/node \
  -p 8545:8545 \  # HTTP-RPC (필요 시)
  -p 8546:8546 \  # WebSocket RPC (선택)
  -p 30311:30311 \  # P2P
  ghcr.io/bnb-chain/bsc:latest \
  --config /bsc/config/config.toml \
  --datadir /bsc/node

RPC 옵션(--http, --http.addr, --http.port, --ws, --ws.addr, --ws.port 등)은 운영 정책에 맞게 설정하세요.
보안상 RPC는 기본적으로 로컬에서만 열고, 외부 노출 시 프록시·방화벽·IP 제한을 꼭 적용해야 합니다.

docker-compose 예시

여러 옵션을 한 곳에서 관리하려면 docker-compose.yml을 만들어 사용할 수 있습니다.

version: '3.8'

services:
  bsc-node:
    image: ghcr.io/bnb-chain/bsc:latest
    container_name: bsc-node
    restart: unless-stopped
    volumes:
      - /mnt/cryptocur-data/bsc/config:/bsc/config
      - /mnt/cryptocur-data/bsc/node:/bsc/node
    ports:
      - "8545:8545"   # HTTP-RPC (선택)
      - "8546:8546"   # WebSocket RPC (선택)
      - "30311:30311" # P2P
    command: >
      --config /bsc/config/config.toml
      --datadir /bsc/node
      --http
      --http.addr 0.0.0.0
      --http.port 8545
      --http.api eth,net,web3
      --ws
      --ws.addr 0.0.0.0
      --ws.port 8546
      --ws.api eth,net,web3

실행:

docker-compose up -d
docker-compose logs -f

실제 운영 시 포트 노출·RPC API 목록·CORS·IP 제한을 반드시 조정하세요. 위 예시는 로컬 개발/테스트에 적합한 기본값입니다.

노드 상태 확인

컨테이너 내부에서 bsc(Geth 포크) CLI를 사용할 수 있습니다.

docker exec -it bsc-node /bin/sh

# 예: 동기화 상태, 블록 높이 확인
bsc attach http://127.0.0.1:8545 --exec 'eth.syncing'
bsc attach http://127.0.0.1:8545 --exec 'eth.blockNumber'

또는 외부에서 RPC로 직접 호출할 수 있습니다.

curl -X POST http://127.0.0.1:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

운영 팁

스냅샷 사용: 제네시스부터 동기화하면 시간이 오래 걸립니다. BNB Chain에서 제공하는 스냅샷 또는 신뢰할 수 있는 공급자의 스냅샷 사용을 고려하세요.
리소스 모니터링: docker stats bsc-node로 CPU·메모리·네트워크를 모니터링하세요.
로그: docker logs -f bsc-node 로 오류·경고를 수시로 확인합니다.
보안:
- RPC 포트는 가능하면 로컬 전용으로 두고, 외부 접근은 역프록시·VPN·방화벽으로 제어합니다.
- P2P 포트만 퍼블릭에 노출하는 구성을 권장합니다.

Localhost 설치

호스트에 직접 BSC 노드를 설치하는 방법은 ../localhost/README.md를 참고하세요.

BSC 노드 Docker 가이드

Docker를 사용하여 BSC (Binance Smart Chain) 노드를 실행하는 방법입니다.

빠른 시작

1. 환경 변수 설정 (선택사항)

# .env 파일 생성 (선택사항)
cat > .env << EOF
# 네트워크 모드: mainnet (기본값), testnet
MODE=mainnet

# BSC Geth P2P 포트
P2PPORT=30311

# 최대 피어 연결 수
MAXPEERS=50

# 동기화 모드: snap (기본값), full
SYNCMODE=snap
EOF

2. Docker Compose로 실행

# 이미지 빌드 및 컨테이너 시작
docker-compose up -d

# 로그 확인
docker-compose logs -f

# 컨테이너 상태 확인
docker-compose ps

3. 노드 상태 확인

# 동기화 상태 확인
docker-compose exec bsc ./geth attach --exec 'eth.syncing'

# 최신 블록 번호 확인
docker-compose exec bsc ./geth attach --exec 'eth.blockNumber'

# 피어 연결 수 확인
docker-compose exec bsc ./geth attach --exec 'net.peerCount'

# 체인 ID 확인 (56: mainnet, 97: testnet)
docker-compose exec bsc ./geth attach --exec 'eth.chainId()'

파일 구조

docker/
├── Dockerfile              # Docker 이미지 빌드 파일
├── docker-compose.yml      # Docker Compose 설정
├── launcher.sh             # BSC Geth 실행 스크립트
├── config.toml             # BSC 설정 파일 (선택사항)
└── README.md               # 이 파일

BSC 노드 구성

BSC Geth

공식 릴리스: https://github.com/bnb-chain/bsc/releases
버전: v1.4.15
역할: 트랜잭션 실행, 블록 검증, 상태 관리
합의: PoSA (Proof of Staked Authority)
포트:
- 30311: P2P 네트워크 (TCP/UDP)
- 8545: HTTP-RPC
- 8546: WebSocket-RPC

환경 변수

필수 변수

P2PPORT: BSC Geth P2P 포트 (기본값: 30311)

선택 변수

MODE: 네트워크 모드
- mainnet (기본값): BSC 메인넷 (Chain ID: 56)
- testnet: BSC 테스트넷 Chapel (Chain ID: 97)
MAXPEERS: 최대 피어 연결 수 (기본값: 50)
SYNCMODE: 동기화 모드
- snap (기본값): 빠른 동기화 (1-2일)
- full: 전체 동기화 (5-7일)

데이터 저장

블록체인 데이터 저장 위치는 환경에 따라 다릅니다.

Linux 서버 (프로덕션)

# 데이터 디렉토리 생성
sudo mkdir -p /mnt/cryptocur-data/bsc

# 권한 설정
sudo chown -R 1000:1000 /mnt/cryptocur-data/bsc
sudo chmod -R 755 /mnt/cryptocur-data/bsc

# .env 파일에 경로 설정
echo "DATA_DIR=/mnt/cryptocur-data/bsc" > .env

Mac/Windows (로컬 개발)

# 현재 디렉토리에 데이터 폴더 생성
mkdir -p bsc-data

# .env 파일에 경로 설정 (이미 기본값)
echo "DATA_DIR=./bsc-data" > .env

네트워크 모드

메인넷 (기본값)

docker-compose up -d
# 또는
MODE=mainnet docker-compose up -d

테스트넷 (Chapel)

MODE=testnet docker-compose up -d

스냅샷 사용 (빠른 동기화)

BSC는 공식 스냅샷을 제공하여 동기화 시간을 크게 단축할 수 있습니다.

스냅샷 다운로드

# 컨테이너 중지
docker-compose down

# 스냅샷 다운로드 (약 1.5TB, 시간 소요)
cd /mnt/cryptocur-data/bsc
wget https://pub-60d5.bscscan.com/mainnet/geth-20240101.tar.gz

# 압축 해제
tar -xzvf geth-20240101.tar.gz
rm geth-20240101.tar.gz

# 컨테이너 재시작
docker-compose up -d

참고: 최신 스냅샷은 BSC Snapshot Repository에서 확인하세요.

노드 관리

로그 확인

# 전체 로그
docker-compose logs -f

# 최근 100줄만
docker-compose logs --tail 100 -f

노드 중지

docker-compose stop

노드 재시작

docker-compose restart

노드 제거 (데이터 유지)

docker-compose down

노드 제거 (데이터 삭제)

docker-compose down -v
sudo rm -rf /mnt/cryptocur-data/bsc/*

RPC 사용

HTTP-RPC

# 로컬에서만 접근 가능 (보안)
curl -H "Content-Type: application/json" \
  -X POST \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://localhost:8545

WebSocket

# WebSocket 연결
wscat -c ws://localhost:8546

# 블록 구독
> {"jsonrpc":"2.0","method":"eth_subscribe","params":["newHeads"],"id":1}

보안 주의사항

포트 노출: RPC 포트는 localhost로만 노출되어 있습니다
방화벽: P2P 포트(30311)만 외부에 노출하세요
정기 업데이트: BSC Geth 최신 버전 유지
RPC 접근 제어: 필요한 경우 인증 추가

모니터링

동기화 진행률 확인

# 동기화 상태 (false면 완료)
docker exec bsc-node /opt/bsc/geth attach --exec 'eth.syncing'

# 현재 블록 vs 최신 블록
docker exec bsc-node /opt/bsc/geth attach --exec 'eth.blockNumber'

# 피어 수
docker exec bsc-node /opt/bsc/geth attach --exec 'net.peerCount'

리소스 사용량

# 컨테이너 리소스 사용량
docker stats bsc-node

# 디스크 사용량
du -sh /mnt/cryptocur-data/bsc

문제 해결

동기화가 느린 경우

피어 수 확인 (최소 10개 이상 권장)
디스크 I/O 확인 (SSD 권장)
스냅샷 사용 고려

피어 연결 문제

방화벽에서 P2P 포트 (30311) 개방 확인
--bootnodes 옵션으로 부트노드 명시

디스크 공간 부족

아카이브 모드가 아닌 경우 pruning 활성화
오래된 로그 파일 정리

추가 리소스

BSC 공식 문서
BSC GitHub
BscScan - 블록 익스플로러
BSC 포럼

BSC 노드 Docker 가이드

빠른 시작

1. Docker 설치

2. BSC Docker 이미지 받기

3. 데이터·설정 디렉토리 준비

4. 단일 docker run 예시

docker-compose 예시

노드 상태 확인

운영 팁

Localhost 설치

BSC 노드 Docker 가이드

빠른 시작

1. 환경 변수 설정 (선택사항)

2. Docker Compose로 실행

3. 노드 상태 확인

파일 구조

BSC 노드 구성

BSC Geth

환경 변수

필수 변수

선택 변수

데이터 저장

Linux 서버 (프로덕션)

Mac/Windows (로컬 개발)

네트워크 모드

메인넷 (기본값)

테스트넷 (Chapel)

스냅샷 사용 (빠른 동기화)

스냅샷 다운로드

노드 관리

로그 확인

노드 중지

노드 재시작

노드 제거 (데이터 유지)

노드 제거 (데이터 삭제)

RPC 사용

HTTP-RPC

WebSocket

보안 주의사항

모니터링

동기화 진행률 확인

리소스 사용량

문제 해결

동기화가 느린 경우

피어 연결 문제

디스크 공간 부족

추가 리소스

bsc 다른 챕터

4. 단일 `docker run` 예시