Solana 노드 트러블슈팅
Solana 검증자·RPC 노드 운영 시 자주 겪는 문제와 확인 방법입니다.
상세 내용은 Solana Validator 문서를 참고하세요.
목차
시작 실패
"Address already in use" / 포트 충돌
증상: validator 기동 시 포트 바인딩 오류.
확인:
# RPC 포트(기본 8899)
ss -tlnp | grep 8899
# 동적 포트 범위(예: 8000-8020)
ss -ulnp | grep -E '800[0-9]|8020'
조치: 기존 solana-validator 프로세스를 종료하거나, --rpc-port, --dynamic-port-range를 다른 값으로 변경하세요.
키페이어·권한 오류
증상: --identity 또는 --vote-account 키 파일을 찾을 수 없거나 권한 오류.
확인:
ls -la /path/to/validator-keypair.json
# 실행 사용자(sol 등)가 읽기 가능해야 함
조치: 경로가 맞는지 확인하고, 파일 소유자·권한을 실행 사용자에 맞추세요.
시스템 한도 (nofile 등)
증상: "too many open files" 유사 메시지.
조치: Setup a Validator - System Tuning에 따라 sysctl·limits 설정을 적용하고, 재로그인 또는 재부팅 후 다시 실행하세요.
동기화·Ledger 문제
Ledger 디스크 부족
증상: Ledger 디렉터리 디스크가 가득 참.
조치:
- RPC 노드라면
--limit-ledger-size로 보관 블록 수를 제한하세요. - 오래된 Ledger 데이터 정리 여부는 공식 문서·릴리스 노트를 참고하세요.
WAL 복구
증상: 재시작 시 WAL 손상으로 인한 오류.
조치: --wal-recovery-mode skip_any_corrupted_record 옵션으로 손상된 레코드만 건너뛰고 기동할 수 있습니다. 데이터 무결성이 중요하면 스냅샷·백업에서 복구를 검토하세요.
RPC 응답 없음
RPC 포트 미개방
확인:
curl -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}' \
http://127.0.0.1:8899
조치: --rpc-bind-address 0.0.0.0으로 바인드했는지, 방화벽에서 8899(또는 사용 중인 RPC 포트)를 허용하는지 확인하세요.
노드가 아직 동기화 중
증상: getHealth는 오지만 getSlot 등이 예상과 다르거나 지연됨.
조치: 로그에서 동기화 진행 상황을 확인하고, 네트워크·디스크 성능을 점검하세요.
디스크·리소스
Accounts / Ledger I/O
증상: CPU는 여유 있는데 동기화가 느리거나 RPC 지연.
조치: Ledger와 Accounts를 서로 다른 NVMe에 두었는지 확인하고, Requirements의 디스크 권장 사양을 참고하세요.
메모리 부족 (account-index)
증상: --account-index 사용 시 OOM 또는 스왑 과다 사용.
조치: RAM 512 GB 이상 권장. 인덱스 종류를 줄이거나, 메모리 증설 후 다시 시도하세요.
네트워크·포트
피어 연결 부족
증상: 로그에 피어 수가 적거나, 동기화가 진행되지 않음.
확인:
--entrypoint,--expected-genesis-hash,--known-validator가 해당 클러스터와 일치하는지 확인.- Available Clusters의 예시와 비교.
조치: 방화벽에서 8000-10000 TCP/UDP(또는 --dynamic-port-range로 지정한 범위)가 열려 있는지 확인하세요. NAT 뒤에 두는 것은 권장하지 않습니다.
포트 포워딩
필수: 8000-10000 TCP/UDP (또는 사용 중인 동적 포트 범위) 인바운드·아웃바운드 허용.
선택: RPC 공개 시 8899(HTTP), 8900(WebSocket) TCP.