Harbor 단일 서버 장애 복구 백업부터 완전 재구축까지 단계별 해결법

Harbor 단일 서버 장애 복구 완벽 가이드

🚨 Harbor 단일 서버 장애의 현실

Harbor를 이중화 없이 단일 서버로 운영하는 것은 단일 장애점(SPOF)을 만드는 것과 같습니다. 장애 발생 시 즉각적인 무중단 복구는 불가능하며, 복구 완료까지 모든 컨테이너 이미지 배포가 중단됩니다.

🔍 1단계: 장애 원인 진단

장애 유형별 진단 방법

하드웨어 장애

# 시스템 상태 확인
dmesg | grep -i error
journalctl -xe
df -h  # 디스크 용량 확인
free -h  # 메모리 사용량 확인
top  # CPU 사용률 확인

네트워크 장애

# 네트워크 연결 상태 확인
ping 8.8.8.8
netstat -tlnp | grep :443
ss -tlnp | grep harbor
curl -k https://harbor.example.com/api/v2.0/systeminfo

Harbor 서비스 장애

# Harbor 컨테이너 상태 확인
docker-compose ps
docker logs harbor-core
docker logs harbor-db
docker logs harbor-redis

# Harbor 로그 확인
tail -f /var/log/harbor/core.log
tail -f /var/log/harbor/registry.log
tail -f /var/log/harbor/postgresql.log

장애 심각도 분류

심각도	증상	복구 방법
Level 1	서비스 일시 중단	컨테이너 재시작
Level 2	설정 파일 손상	설정 복구 + 서비스 재시작
Level 3	데이터베이스 손상	DB 백업 복원
Level 4	전체 시스템 장애	완전 재구축 + 백업 복원

🔧 2단계: 서비스 복구 절차

Level 1: 간단한 서비스 재시작

# Harbor 서비스 재시작
cd /opt/harbor
docker-compose down
docker-compose up -d

# 특정 컨테이너만 재시작
docker-compose restart harbor-core
docker-compose restart harbor-db

Level 2: 설정 파일 복구

# 설정 파일 백업에서 복구
cp /backup/harbor.yml /opt/harbor/harbor.yml
cd /opt/harbor
./prepare
docker-compose down
docker-compose up -d

Level 3: 데이터베이스 복구

# PostgreSQL 컨테이너 중지
docker-compose stop harbor-db

# 데이터베이스 볼륨 백업에서 복구
docker run --rm -v harbor_harbor-db:/source -v /backup:/backup alpine \
    sh -c "cd /source && tar -xzf /backup/harbor-db-backup.tar.gz"

# 서비스 재시작
docker-compose up -d

💾 3단계: 백업 데이터 복구

Harbor 백업 구성 요소

1. 데이터베이스 백업

# PostgreSQL 백업 생성
docker exec harbor-db pg_dump -U postgres -d postgres > harbor-db-backup.sql

# PostgreSQL 백업 복원
docker exec -i harbor-db psql -U postgres -d postgres < harbor-db-backup.sql

2. 이미지 저장소 백업

# 이미지 데이터 백업 (기본 경로)
tar -czf harbor-registry-backup.tar.gz /data/registry/

# 이미지 데이터 복원
cd /
tar -xzf harbor-registry-backup.tar.gz

3. 설정 파일 백업

# 설정 파일 백업
cp /opt/harbor/harbor.yml /backup/
cp -r /opt/harbor/common /backup/

# 설정 파일 복원
cp /backup/harbor.yml /opt/harbor/
cp -r /backup/common /opt/harbor/

완전 복구 스크립트 예시

#!/bin/bash
# Harbor 완전 복구 스크립트

BACKUP_DIR="/backup/harbor"
HARBOR_DIR="/opt/harbor"
DATA_DIR="/data"

echo "Harbor 복구 시작..."

# 1. 기존 Harbor 서비스 중지
cd $HARBOR_DIR
docker-compose down

# 2. 설정 파일 복원
echo "설정 파일 복원 중..."
cp $BACKUP_DIR/harbor.yml $HARBOR_DIR/
cp -r $BACKUP_DIR/common $HARBOR_DIR/

# 3. 데이터베이스 복원
echo "데이터베이스 복원 중..."
docker run --rm -v harbor_harbor-db:/target -v $BACKUP_DIR:/backup alpine \
    sh -c "cd /target && tar -xzf /backup/harbor-db-backup.tar.gz"

# 4. 이미지 저장소 복원
echo "이미지 저장소 복원 중..."
cd /
tar -xzf $BACKUP_DIR/harbor-registry-backup.tar.gz

# 5. Harbor 서비스 재시작
echo "Harbor 서비스 시작 중..."
cd $HARBOR_DIR
./prepare
docker-compose up -d

# 6. 서비스 상태 확인
echo "서비스 상태 확인 중..."
sleep 30
docker-compose ps
curl -k https://localhost/api/v2.0/systeminfo

echo "Harbor 복구 완료!"

🏗️ 4단계: 신규 서버 이전

새로운 서버 구축 절차

1. 시스템 준비

# Docker 및 Docker Compose 설치
curl -fsSL https://get.docker.com | sh
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

2. Harbor 설치

# Harbor 다운로드 및 설치
wget https://github.com/goharbor/harbor/releases/latest/download/harbor-offline-installer-v2.x.x.tgz
tar -xzf harbor-offline-installer-v2.x.x.tgz
cd harbor

3. 백업 데이터 복원

# 백업 데이터를 새 서버로 복사
scp -r /backup/harbor/ new-server:/backup/

# 복구 스크립트 실행
./harbor-recovery.sh

4. DNS 업데이트

# DNS 레코드 업데이트 (예: Route 53)
aws route53 change-resource-record-sets \
    --hosted-zone-id Z123456789 \
    --change-batch '{
        "Changes": [{
            "Action": "UPSERT",
            "ResourceRecordSet": {
                "Name": "harbor.example.com",
                "Type": "A",
                "TTL": 300,
                "ResourceRecords": [{"Value": "NEW_SERVER_IP"}]
            }
        }]
    }'

⏱️ 복구 시간 예상

복구 시간 영향 요소

요소	복구 시간 영향
백업 주기	1일 백업 → 최대 1일 데이터 손실
데이터 용량	1TB 데이터 → 약 2-4시간 복구
서버 성능	SSD vs HDD → 3-5배 시간 차이
네트워크 대역폭	복구 데이터 전송 속도
자동화 수준	수동 vs 스크립트 → 5-10배 시간 차이

복구 시간 시나리오

gantt
    title Harbor 복구 시간 시나리오
    dateFormat X
    axisFormat %H:%M
    
    section Level 1 (서비스 재시작)
    장애 감지        :0, 5m
    서비스 재시작    :5m, 10m
    상태 확인        :10m, 15m
    
    section Level 2 (설정 복구)
    장애 감지        :0, 10m
    설정 복구        :10m, 30m
    서비스 재시작    :30m, 45m
    상태 확인        :45m, 60m
    
    section Level 3 (DB 복구)
    장애 감지        :0, 15m
    백업 데이터 준비  :15m, 45m
    DB 복원          :45m, 120m
    서비스 재시작    :120m, 135m
    상태 확인        :135m, 150m
    
    section Level 4 (완전 재구축)
    장애 감지        :0, 30m
    새 서버 준비     :30m, 120m
    Harbor 설치      :120m, 180m
    데이터 복원      :180m, 360m
    DNS 업데이트     :360m, 390m
    최종 확인        :390m, 420m

 장애 예방 및 대응 체계

모니터링 설정

# Harbor 모니터링 설정 예시
version: '3.8'
services:
  harbor-monitor:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
      - '--web.console.libraries=/usr/share/prometheus/console_libraries'

자동 백업 스크립트

#!/bin/bash
# 자동 백업 스크립트 (cron으로 실행)

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/harbor_$DATE"
mkdir -p $BACKUP_DIR

# 데이터베이스 백업
docker exec harbor-db pg_dump -U postgres -d postgres > $BACKUP_DIR/harbor-db.sql

# 이미지 저장소 백업
tar -czf $BACKUP_DIR/harbor-registry.tar.gz /data/registry/

# 설정 파일 백업
cp /opt/harbor/harbor.yml $BACKUP_DIR/
cp -r /opt/harbor/common $BACKUP_DIR/

# 7일 이상 된 백업 삭제
find /backup -name "harbor_*" -type d -mtime +7 -exec rm -rf {} \;

결론: 단일 서버 운영의 한계

Harbor 단일 서버 운영 시 장애 복구는 백업 데이터에 완전히 의존하며, 다음과 같은 한계가 있습니다:

한계점

• 서비스 중단 불가피: 복구 완료까지 모든 서비스 중단
• 데이터 손실 가능성: 백업 주기만큼 데이터 손실 발생
• 복구 시간 불확실: 장애 규모에 따라 수십 분~수 시간 소요
• 수동 개입 필요: 대부분의 복구 과정이 수동 작업

개선 방안

1. 정기적인 백업 자동화 (최소 일 1회)
2. 복구 절차 문서화 및 정기적인 복구 훈련
3. 모니터링 시스템 구축으로 조기 장애 감지
4. 가능한 빠른 시일 내 이중화 구성 검토

결론: 단일 서버 운영은 비용 효율적이지만, 비즈니스 연속성 측면에서는 큰 리스크입니다.
중요한 운영 환경에서는 반드시 이중화 구성을 고려해야 합니다.