Polkadot 노드 설치 가이드

Polkadot Relay Chain Full Node를 바이너리 다운로드, 소스 빌드, Snap, Docker 중 한 가지 방식으로 설치하는 방법입니다.
출처: Set Up a Node, Install Polkadot SDK.

목차

• 전제 조건
• Linux: 사전 빌드 바이너리
• Linux / macOS: 소스 빌드
• Linux: Snap
• Docker
• 실행 옵션 요약
• 동기화 확인
• Validator (별도 가이드)

전제 조건

• Rust: 소스 빌드 시 필수. curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 후 rustup default stable 등.
• 의존성: Install the necessary dependencies for the Polkadot SDK 참고 (Linux 패키지 등).
• Validator: 이 문서는 Full Node용. Validator는 Run a Validator 참고.

Linux: 사전 빌드 바이너리

1. paritytech/polkadot-sdk Releases에서 polkadot Linux 바이너리 다운로드.
   태그 예: polkadot-v1.20.0. asset 이름·다운로드 URL은 릴리스 페이지에서 확인.

# 예시 (버전·파일명은 릴리스에 맞게 변경)
wget https://github.com/paritytech/polkadot-sdk/releases/download/polkadot-v1.20.0/polkadot
chmod +x polkadot
./polkadot --version

1. 원하면 경로 지정: wget ... -O /var/lib/polkadot-data/polkadot 후 해당 경로에서 실행.

참고: cannot execute binary file: Exec format error 나오면 아키텍처/배포판 불일치. 소스 빌드 또는 Docker 사용.

Linux / macOS: 소스 빌드

빌드에 1시간 이상 걸릴 수 있습니다.

Rust 설정

macOS 예:

source ~/.cargo/env
rustup default stable
rustup update
rustup update nightly
rustup target add wasm32-unknown-unknown --toolchain nightly
rustup component add rust-src --toolchain stable-aarch64-apple-darwin   # 또는 해당 triple

Linux 예:

rustup default stable
rustup update
rustup update nightly
rustup target add wasm32-unknown-unknown --toolchain nightly
rustup target add wasm32-unknown-unknown --toolchain stable-x86_64-unknown-linux-gnu
rustup component add rust-src --toolchain stable-x86_64-unknown-linux-gnu

rustup show로 툴체인 확인.

클론 및 빌드

git clone https://github.com/paritytech/polkadot-sdk polkadot-sdk
cd polkadot-sdk
cargo build --release

실행 파일: ./target/release/polkadot. 이후 명령에서 polkadot 대신 ./target/release/polkadot 사용.

Linux: Snap

sudo apt update && sudo apt install snapd
sudo snap install polkadot
sudo snap set polkadot service-args="--name=MyName --chain=polkadot"
sudo snap start polkadot
snap logs polkadot -f

중지: sudo snap stop polkadot. 업데이트 시 서비스 유지: sudo snap set polkadot endure=true.

Docker

이미지: DockerHub parity/polkadot.
RPC·Prometheus를 호스트에서 쓰려면 --rpc-external, --prometheus-external 필요.

docker run -p 9944:9944 -p 9615:9615 parity/polkadot:v1.16.2 \
  --name "my-polkadot-node" --chain polkadot \
  --rpc-external --prometheus-external

Apple Silicon (M1/M2 등):

docker run --platform linux/amd64 -p 9944:9944 -p 9615:9615 parity/polkadot:v1.16.2 \
  --name "my-polkadot-node" --chain polkadot \
  --rpc-external --prometheus-external

버전은 DockerHub 태그에서 선택. 자세한 Docker 활용: docker/README.md.

실행 옵션 요약

• 기본 Pruned: polkadot --chain polkadot --name "MyNode"
• 커스텀 Pruned: --state-pruning 1000 --blocks-pruning archive 등.
• Archive: --state-pruning archive --blocks-pruning archive
• RPC 외부 노출: --rpc-external --rpc-cors all --rpc-methods safe
• Kusama: --chain kusama
• Telemetry: --telemetry-url 'wss://telemetry.polkadot.io/submit/ 0'
• 도움말: polkadot --help

동기화 확인

• 로그: Syncing, target=#... best: #... finalized #...
• Polkadot Telemetry — 노드 이름으로 검색. 동기화 완료 시 흰색으로 표시.
• Polkadot.js Apps — Development → ws://127.0.0.1:9944 연결.

동기화는 환경에 따라 수십 시간12일 걸릴 수 있습니다.

Validator (별도 가이드)

Validator는 키 생성(polkadot-keygen), 세션 키·온체인 등록 등 별도 절차가 필요합니다.
Full Node 가이드로는 Validator 설정을 할 수 없습니다.
반드시 Set Up a Validator를 따르세요.