Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

이 가이드는 업그레이드 절차 및 롤백 전략을 포함하여, Stable 노드의 업그레이드 프로세스를 다룹니다.

전체 버전 기록 및 업그레이드 세부 정보는 버전 기록을 참조하십시오.

업그레이드 유형

소프트 업그레이드 (구조적 변경 없음)

  • 언제든지 수행 가능
  • 하위 호환성 유지

하드 업그레이드 (구조적 변경)

  • 특정 높이에서 업그레이드 필요
  • 하위 호환성 없음

긴급 업그레이드

  • 주요 보안 수정 사항
  • 즉각적인 조치 필요
  • 체인 일시 중지 필요할 수 있음

v1.4.0 스토리지 마이그레이션

v1.4.0은 LevelDB 기반 상태 스토리지를 MemIAVL로 대체합니다. 이 업그레이드에는 일반적인 바이너리 교체 외에 데이터 마이그레이션이 필요합니다.

네트워크별 업그레이드 지침에 다른 방법이 명시되지 않는 한 로컬 스냅샷 내보내기 및 복원 기능을 사용하십시오. 벤치마킹 결과 표준 복원의 경우 평균 19.4초, 병렬 복원의 경우 약 2.6초의 유효성 검사기 다운타임이 측정되었습니다.

투표 권한의 최소 2/3가 온라인 상태를 유지하도록 라운드 로빈 순서로 유효성 검사기를 마이그레이션하십시오. 노드가 가장 오래 보관된 스냅샷보다 오래된 기록 쿼리에 응답해야 하는 경우 RocksDB 기반 VersionDB를 구성하십시오.

표준 업그레이드 절차

1단계: 준비

# 현재 버전 확인
stabled version --long
 
# 중요 데이터 백업
cp -r ~/.stabled/config ~/stable-backup-$(date +%Y%m%d)/
 
# 유효성 검사기만 해당: 유효성 검사기 상태 백업
cp ~/.stabled/data/priv_validator_state.json ~/stable-backup-$(date +%Y%m%d)/
 
# 디스크 공간 확인 (현재 데이터 크기의 2배 필요)
df -h ~/.stabled

2단계: 새 바이너리 다운로드

# v1.2.0-rc1 업그레이드 (2026년 1월 22일)
# 아키텍처 선택:
 
# Linux AMD64
BINARY_URL="https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.2.0-rc1-linux-amd64-testnet.tar.gz"
 
# 또는 Linux ARM64
BINARY_URL="https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.2.0-rc1-linux-arm64-testnet.tar.gz"
 
# 새 바이너리 다운로드
wget $BINARY_URL
 
# 임시 위치에 압축 해제
tar -xvzf stabled-1.2.0-rc1-linux-*.tar.gz -C /tmp/
 
# 새 버전 확인
/tmp/stabled version --long

3단계: 업그레이드 수행

소프트 업그레이드의 경우

# 노드 중지
sudo systemctl stop ${SERVICE_NAME}
 
# 현재 바이너리 백업
sudo mv /usr/bin/stabled /usr/bin/stabled.backup
 
# 새 바이너리 설치
sudo mv /tmp/stabled /usr/bin/stabled
sudo chmod +x /usr/bin/stabled
 
# 설치 확인
stabled version --long
 
# 노드 시작
sudo systemctl start ${SERVICE_NAME}
 
# 로그 모니터링
sudo journalctl -u ${SERVICE_NAME} -f

하드 업그레이드의 경우

# 업그레이드 높이 모니터링
while true; do
    HEIGHT=$(curl -s localhost:26657/status | jq -r '.result.sync_info.latest_block_height')
    echo "현재 높이: $HEIGHT"
    if [ $HEIGHT -ge $UPGRADE_HEIGHT ]; then
        break
    fi
    sleep 10
done
 
# 노드는 업그레이드 높이에서 자동으로 중지됩니다.
# 로그에서 중지 메시지 대기
sudo journalctl -u ${SERVICE_NAME} -f | grep "UPGRADE"
 
# 중지되면 업그레이드 수행
sudo systemctl stop ${SERVICE_NAME}
sudo mv /usr/bin/stabled /usr/bin/stabled.backup
sudo mv /tmp/stabled /usr/bin/stabled
 
# 새 바이너리로 시작
sudo systemctl start ${SERVICE_NAME}

4단계: 업그레이드 후 확인

# 노드 상태 확인
curl -s localhost:26657/status | jq '.result'
 
# 버전 확인
curl -s localhost:26657/status | jq '.result.node_info.version'
 
# 피어 확인
curl -s localhost:26657/net_info | jq '.result.n_peers'
 
# 동기화 상태 모니터링
watch -n 2 'curl -s localhost:26657/status | jq ".result.sync_info"'
 
# 오류 확인
sudo journalctl -u ${SERVICE_NAME} --since "10 minutes ago" | grep -i error

코스모바이저 설정 (자동 업그레이드)

코스모바이저는 조율된 업그레이드를 위한 업그레이드 프로세스를 자동화합니다.

설치

# 코스모바이저 설치
go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest
 
# 또는 바이너리 다운로드
wget https://github.com/cosmos/cosmos-sdk/releases/download/cosmovisor%2Fv1.7.0/cosmovisor-v1.7.0-linux-amd64.tar.gz
tar -xzf cosmovisor-v1.7.0-linux-amd64.tar.gz
sudo mv cosmovisor /usr/bin/

구성

# 환경 변수 설정
cat >> ~/.bashrc <<EOF
export DAEMON_NAME=stabled
export DAEMON_HOME=$HOME/.stabled
export DAEMON_RESTART_AFTER_UPGRADE=true
export DAEMON_ALLOW_DOWNLOAD_BINARIES=true
export UNSAFE_SKIP_BACKUP=false
EOF
 
source ~/.bashrc
 
# 디렉터리 구조 생성
mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin
mkdir -p $DAEMON_HOME/cosmovisor/upgrades
 
# 현재 바이너리를 제네시스에 복사
cp /usr/bin/stabled $DAEMON_HOME/cosmovisor/genesis/bin/
 
# systemd 서비스 생성
sudo tee /etc/systemd/system/cosmovisor.service > /dev/null <<EOF
[Unit]
Description=Cosmovisor 데몬
After=network-online.target
 
[Service]
Environment="DAEMON_NAME=stabled"
Environment="DAEMON_HOME=$HOME/.stabled"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=true"
User=$USER
ExecStart=/usr/bin/cosmovisor run start --chain-id stabletestnet_2201-1
Restart=always
RestartSec=3
LimitNOFILE=65535
 
[Install]
WantedBy=multi-user.target
EOF
 
# 활성화 및 시작
sudo systemctl daemon-reload
sudo systemctl enable cosmovisor
sudo systemctl start cosmovisor

코스모바이저를 사용한 업그레이드

# 각 업그레이드마다 디렉터리 생성 (제안서의 업그레이드 이름 사용)
mkdir -p $DAEMON_HOME/cosmovisor/upgrades/v1.2.0-rc1/bin
 
# 새 바이너리 배치
cp /path/to/new/stabled $DAEMON_HOME/cosmovisor/upgrades/v1.2.0-rc1/bin/
 
# 코스모바이저는 업그레이드 높이에서 자동으로 전환됩니다.

롤백

# 노드 중지
sudo systemctl stop ${SERVICE_NAME}
 
# 현재 상태 백업 (필요한 경우)
cp -r ~/.stabled/data ~/.stabled/data.failed
 
# 업그레이드 전 스냅샷에서 복원
cd ~/.stabled
rm -rf data/
tar -I lz4 -xf ~/snapshots/pre-upgrade-snapshot.tar.lz4
 
# 이전 바이너리 복원
sudo mv /usr/bin/stabled.backup /usr/bin/stabled
 
# 노드 시작
sudo systemctl start ${SERVICE_NAME}

비상 절차

# 체인이 예기치 않게 중지된 경우
# 1. Discord에서 지침 확인
# 2. 마지막으로 확인된 정상 높이에서 상태 내보내기
stabled export --height <last_good_height> > export.json
 
# 3. 조정된 재시작 지침 대기

다음 단계