백업 및 복원 CLI

Koneksi Secure Digital Storage Solution을 위해 개발된, 실시간 변경 감지 기능을 갖춘 자동 디렉토리 백업을 위한 명령줄 도구입니다.

완전한 사용 방법 가이드

앱 기능

• 실시간 모니터링: 지정된 디렉터리의 변경 사항을 자동으로 감지합니다.

• 단일 파일 백업: 필요에 따라 개별 파일을 백업합니다.

• 디렉토리 압축: 백업 전 전체 디렉터리를 tar.gz 아카이브로 압축합니다.

• 동시 백업: 여러 파일을 병렬로 효율적으로 백업합니다.

• 스마트 감지: 체크섬을 사용하여 실제로 변경된 파일만 백업합니다.

• 압축 지원: 저장 공간을 절약하기 위한 gzip/zlib 압축(선택 사항)

• 암호화 지원: 암호로 보호되는 안전한 백업을 위한 AES-256-GCM 암호화

• 대용량 파일 지원: 자동 압축 권장 기능을 통해 최대 2GB의 파일을 처리합니다.]

• 데이터베이스 추적: SQLite 데이터베이스가 모든 백업 기록 및 메타데이터를 추적합니다.

• 종합 보고: 각 백업 세션에 대한 상세 JSON 보고서를 생성합니다.

• 전체 복원 기능: 매니페스트 파일에서 백업된 파일을 복원합니다.

• 자동 추출: 복원 후 tar.gz 아카이브를 자동으로 추출합니다.

• 자동 복호화: 복원 후 암호화된 파일을 자동으로 복호화합니다.

• 구성 가능: 디렉터리, 제외 및 성능에 대한 유연한 구성

전제 조건

• Go 1.19 이상 (소스에서 빌드하려는 경우)

• 회원가입을 위한 유효한 이메일 주소

• 인터넷 연결

• 운영 체제: Linux, macOS 또는 Windows

설치

옵션 1: 소스에서 빌드

릴리스 페이지에서 해당 플랫폼에 맞는 최신 릴리스를 다운로드하세요.

# Clone the repository
git clone https://github.com/koneksi-tech/koneksi-backup-cli.git
cd koneksi-backup-cli

# Build the CLI
make build

# Or install globally
make install

옵션 2: 사전 빌드된 바이너리 다운로드

이미 검증된 Koneksi 계정이 있는 경우 4단계: 구성으로 이동하여 환경을 설정하세요. 그렇지 않은 경우 아래 단계에 따라 프로그래밍 방식 액세스를 위한 API 키를 등록, 검증 및 생성하세요.

1단계: 사용자 등록

먼저, Koneksi에 계정을 만들어야 합니다.

koneksi-backup auth register \
    --first-name "John" \
    --last-name "Doe" \
    --email "[e-mail]" \
    --password "StrongPassword123!"

예상 출력:

Registration successful!
User ID: usr_1234567890
Email: [e-mail]

중요: 귀하의 이메일로 인증 코드가 전송되었습니다.

다음 단계:
1. 이메일에서 인증 코드를 확인하세요.
2. 로그인: koneksi-backup auth login -e [e-mail] -p <비밀번호>
3. 확인: koneksi-backup auth verify <인증 코드> -t <액세스 토큰>

2단계: 계정 확인

이메일에서 6자리 인증 코드를 확인한 후, 다음을 수행하세요.

koneksi-backup auth verify "123456" -t "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

예상 출력:

Account verified successfully!
Email: [e-mail]
Verified: true

이제 다음을 사용하여 API 키를 생성할 수 있습니다:
  koneksi-backup auth create-key "My API Key" -t <your-access-token>

3단계: API 키 생성

API 키는 백업 서비스에 대한 프로그래밍 방식 액세스에 사용됩니다.

예상 출력:

API Key 'My Backup Service' created successfully!

Client ID:
id_rTFliuxFqbEpjb3NbMGZKm8yKqbA2gejqatMTNwcfE

클라이언트 시크릿 (저장해 주세요. 다시 표시되지 않습니다):
sk_KRZQQJg17Vp7A53YOIg3iwFuuCqaZ7g7ZbVMqK2U

koneksi-backup에서 이러한 자격 증명을 사용하려면:
  export KONEKSI_API_CLIENT_ID=<client-id>
  export KONEKSI_API_CLIENT_SECRET=<client-secret>

또는 구성 파일에 추가하세요 (~/.koneksi-backup/config.yaml)

중요: 클라이언트 ID와 클라이언트 비밀번호를 즉시 저장하세요. 클라이언트 비밀번호는 나중에 검색할 수 없습니다.

4단계: 구성

4.1 환경 변수 설정(빠른 시작)

export KONEKSI_API_CLIENT_ID="id_rTFliuxFqbEpjb3NbMGZKm8yKqbA2gejqatMTNwcfE"
export KONEKSI_API_CLIENT_SECRET="sk_KRZQQJg17Vp7A53YOIg3iwFuuCqaZ7g7ZbVMqK2U"

4.2 구성 파일 생성(권장)

# 구성 시작
koneksi-backup init

이렇게 하면 ~/.koneksi-backup/config.yaml이 생성됩니다. 자격 증명을 추가하려면 이 파일을 편집하세요.

api:
  base_url: "https://uat.koneksi.co.kr"
  client_id: "id_rTFliuxFqbEpjb3NbMGZKm8yKqbA2gejqatMTNwcfE"
  client_secret: "sk_KRZQQJg17Vp7A53YOIg3iwFuuCqaZ7g7ZbVMqK2U"
  directory_id: ""  # Leave empty to auto-create
  timeout: 30
  retry_count: 3

backup:
  directories:
    - "/home/john/documents"
    - "/home/john/projects"
  exclude_patterns:
    - "*.tmp"
    - "*.log"
    - ".git"
    - "node_modules"
  check_interval: 300
  max_file_size: 1073741824
  concurrent: 5
  compression:
    enabled: false
    level: 6
    format: "gzip"
  encryption:
    enabled: false
    password: ""  # Or use KONEKSI_BACKUP_ENCRYPTION_PASSWORD env var

5단계: 백업 수행

5.1 단일 파일의 일회성 백업

koneksi-backup backup /path/to/important-file.pdf

5.2 디렉토리 백업

koneksi-backup backup /home/john/documents

5.3 압축 아카이브로 디렉토리 백업

많은 파일이 있는 디렉토리를 더 빠르게 업로드하려면:

koneksi-backup backup /home/john/projects/my-app --compress-dir

5.4 연속 모니터링(데몬 모드)

디렉토리를 지속적으로 모니터링하려면 백업 서비스를 시작하세요.

koneksi-backup run

백업에 대한 예상 출력:

Starting backup of: /home/john/documents
Backing up file: report.pdf (size: 2458624 bytes)
Backing up file: presentation.pptx (size: 5242880 bytes)
Queued 15 files for backup
Waiting 20s for backups to complete...

Backup Report Summary
====================
Report ID: backup-20250115-143022
Duration: 18.5s
Total Files: 15
Successful: 15
Failed: 0
Total Size: 24.5 MB

6단계: 파일 복원

6.1 복원 매니페스트 만들기

먼저 백업 보고서를 찾으세요:

ls ./reports/

보고서에서 매니페스트를 만듭니다:

koneksi-backup manifest ./reports/backup-20250115-143022.json restore-manifest.json

6.2 파일 복원

koneksi-backup restore restore-manifest.json /home/john/restored-files

6.3 자동 추출로 복원

압축된 디렉토리를 백업한 경우:

koneksi-backup restore restore-manifest.json /home/john/restored-files --auto-extract

예상 출력:

Starting restore from manifest: restore-manifest.json
Target directory: /home/john/restored-files
Restoring: report.pdf (2.4 MB)
Restoring: presentation.pptx (5.0 MB)
Progress: 15/15 files

Restore completed:
- Total files: 15
- Restored: 15
- Failed: 0
- Duration: 12s

암호화

Koneksi Backup CLI는 클라우드에 업로드하기 전에 파일을 보호하기 위해 AES-256-GCM 암호화를 지원합니다. 이를 통해 민감한 데이터의 보안을 한층 강화할 수 있습니다.

암호화를 통한 백업

5.5 백업 중 파일 암호화

# 명령줄 비밀번호를 사용한 암호화 백업
koneksi-backup backup /path/to/sensitive-data --encrypt --encrypt-password "MySecretPass123"

# 환경 변수를 사용하여 암호화된 백업
export KONEKSI_BACKUP_ENCRYPTION_PASSWORD="MySecretPass123"
koneksi-backup backup /path/to/sensitive-data --encrypt

# 디렉토리에 대한 압축과 암호화 결합
koneksi-backup backup /home/john/confidential --compress-dir --encrypt --encrypt-password "MySecretPass123"

예상 출력:

Starting backup of: /home/john/confidential
Compressing directory before backup...
Directory compressed to /tmp/backup-123456.tar.gz (size: 5242880 bytes)
Encryption is enabled for this backup
Encrypting file before backup...
File encrypted (size: 5243904 bytes)
Backup completed successfully

복호화로 복원

6.4 파일 복원 및 암호 해독

# 명령줄 암호를 사용하여 복호화하여 복원
koneksi-backup restore restore-manifest.json /home/john/restored-files --decrypt --decrypt-password "MySecretPass123"

# 환경 변수를 사용하여 복호화하여 복원
export KONEKSI_BACKUP_ENCRYPTION_PASSWORD="MySecretPass123"
koneksi-backup restore restore-manifest.json /home/john/restored-files --decrypt

# 복호화와 추출을 결합합니다
koneksi-backup restore restore-manifest.json /home/john/restored-files --decrypt --auto-extract --decrypt-password "MySecretPass123"

예상 출력:

Starting restore from manifest: restore-manifest.json
Target directory: /home/john/restored-files
Restoring: confidential-data.tar.gz.enc (5.0 MB)
Progress: 1/1 files

Restore completed:
- Total files: 1
- Restored: 1
- Failed: 0
- Duration: 3s

Checking for encrypted files to decrypt...
Decrypting confidential-data.tar.gz.enc...
Decrypted and removed confidential-data.tar.gz.enc

Decrypted 1 file(s)

Checking for tar.gz files to extract...
Extracting confidential-data.tar.gz...
Extracted and removed confidential-data.tar.gz

Extracted 1 archive(s)

구성 기반 암호화

구성 파일에서 기본적으로 암호화를 활성화할 수 있습니다.

backup:
  encryption:
    enabled: true
    password: "MySecretPass123"  # Or leave empty and use env var

암호화를 위한 보안 모범 사례

1. 강력한 비밀번호: 길고 복잡한 문자가 혼합된 비밀번호를 사용하세요.

2. 비밀번호 저장소: 환경 변수 또는 안전한 비밀번호 관리자에 비밀번호를 저장하세요.

3. 비밀번호 커밋 금지: 버전 관리 시스템에 비밀번호를 커밋하지 마세요.

4. 비밀번호 순환: 보안 강화를 위해 암호화된 비밀번호를 정기적으로 변경하세요.

5. 비밀번호 백업: 암호화된 비밀번호를 안전하게 백업하세요.

예: 민감한 금융 데이터 암호화

# 암호화 비밀번호를 안전하게 설정하세요
export KONEKSI_BACKUP_ENCRYPTION_PASSWORD="$(openssl rand -base64 32)"
echo "Save this password securely: $KONEKSI_BACKUP_ENCRYPTION_PASSWORD"

# 암호화를 통한 재무 기록 백업
koneksi-backup backup ~/financial-records --compress-dir --encrypt

# 나중에 동일한 비밀번호로 복원하세요
koneksi-backup restore financial-manifest.json ~/restored-financials --decrypt --auto-extract

고급 기능

디렉토리 관리

모든 백업 디렉토리 나열

koneksi-backup dir list

새 디렉토리 생성

koneksi-backup dir create "Project Backups" -d "Backup directory for all projects"

대용량 파일 처리

100MB보다 큰 파일의 경우 항상 먼저 압축하세요.

# 대용량 파일 압축
gzip large-database.sql

# 백업압축 파일
koneksi-backup backup large-database.sql.gz

완전한 예시 워크플로우

등록에서 복원까지의 전체 예는 다음과 같습니다:

# Koneksi 인증 계정이 이미 있는 경우 1~3단계는 선택 사항입니다.

# 1. 등록하다
koneksi-backup auth register \
    --first-name "Jane" \
    --last-name "Smith" \
    --email "[e-mail]" \
    --password "SecurePass123!"

# 2. 로그인
koneksi-backup auth login \
    --email "[e-mail]" \
    --password "SecurePass123!"
# 액세스 토큰 복사

# 3. 계정 확인(이메일에서 코드 확인)
koneksi-backup auth verify "654321" -t "access-token-here"

# 4. API 키 생성
koneksi-backup auth create-key "Production Backup" -t "access-token-here"
# 클라이언트 ID와 비밀번호를 저장하세요

# 5. 설정하다
export KONEKSI_API_CLIENT_ID="your-client-id"
export KONEKSI_API_CLIENT_SECRET="your-client-secret"

# 6. 압축 및 암호화를 통해 중요한 파일을 백업하세요
export KONEKSI_BACKUP_ENCRYPTION_PASSWORD="SecureBackupPass456!"
koneksi-backup backup ~/important-docs --compress-dir --encrypt

# 7. 복원 매니페스트 생성
koneksi-backup manifest ./reports/backup-*.json my-restore.json

# 8. 복호화 및 추출을 통해 파일을 새 위치로 복원합니다.
koneksi-backup restore my-restore.json ~/restored-docs --decrypt --auto-extract

문제 해결

일반적인 문제 및 솔루션

인증 오류

# 자격 증명 테스트
koneksi-backup dir list

실패하면 환경 변수나 구성 파일에 유효한 자격 증명이 포함되어 있는지 확인하세요.

이메일 확인 문제

1. 스팸 폴더에서 인증 이메일을 확인하세요.

2. 유효한 이메일 도메인(gmail.com, outlook.com 등)을 사용하고 있는지 확인하세요.

3. 다시 로그인하여 새 인증 코드를 요청하세요.

대용량 파일 업로드 실패

# 구성에서 시간 초과를 늘리세요
api:
  timeout: 300  # 5 minutes

# 또는 먼저 파일을 압축하세요
gzip large-file.bin
koneksi-backup backup large-file.bin.gz

권한 거부 오류

백업하는 파일에 대한 읽기 권한이 있는지 확인하세요.

ls -la /path/to/backup/directory

디버그 모드

자세한 내용은 디버그 로깅을 실행하세요.

koneksi-backup backup /path/to/file --log-level debug

모범 사례

1. 정기 백업: 지속적인 보호를 위해 데몬 모드(koneksi-backup run)를 사용하세요.

2. 대용량 파일 압축: 백업 전 100MB 이상의 파일은 항상 압축하세요.

3. 민감한 데이터 암호화: 기밀 파일(금융, 개인, 비즈니스 데이터)에 암호화를 사용하세요.

4. 디렉토리 구성: 프로젝트별로 별도의 백업 디렉터리를 생성하세요.

5. 테스트 복원: 백업이 제대로 작동하는지 확인하기 위해 정기적으로 파일 복원을 테스트하세요.

6. 보안 자격 증명: API 키나 암호화된 비밀번호를 버전 관리 시스템에 커밋하지 마세요.

7. 모니터링 보고서: 백업 보고서에서 오류가 있는지 정기적으로 확인하세요.

8. 암호 관리: 암호화된 비밀번호에는 암호 관리자 또는 보안 저장소를 사용하세요.

도움 받기

• 기본 제공 도움말: koneksi-backup --help

• 명령어 도움말: koneksi-backup backup --help

• 문제 보고: https://github.com/koneksi-tech/koneksi-backup-cli/issues

• 문서: 자세한 구성 옵션은 README.md를 참조하세요.

다음 단계

이제 설정이 완료되었습니다:

1. 중요 디렉터리에 대한 자동 백업을 구성합니다.

2. 정기적인 백업 실행을 위한 Cron 작업을 설정합니다.

3. 다양한 유형의 데이터에 대한 백업 정책을 생성합니다.

4. 기존 백업 워크플로와 통합합니다.

추가 리소스

• GitHub 저장소: https://github.com/koneksi-tech/backup-restore

• 이슈 트래커: https://github.com/koneksi-tech/backup-restore/issues

• 릴리스: https://github.com/koneksi-tech/backup-restore/releases