S3-호환 CLI

익숙한 S3 명령어를 통해 파일과 디렉터리를 관리할 수 있는 명령줄 도구로, AWS S3 사용 경험이 있는 사용자들이 Koneksi 스토리지를 보다 쉽게 활용할 수 있도록 도와줍니다.

완전한 사용 방법 가이드

앱 기능

• S3 호환 명령: ls, cp, mv, rm, mb, rb와 같은 익숙한 명령을 사용하세요.

• 크로스 플랫폼 지원: Linux, macOS, Windows에서 작동합니다.

• 재귀 작업: 재귀적 디렉터리 업로드/다운로드 지원

• 진행률 표시: 파일 전송 중 시각적 피드백 제공

• 재시도 로직: 실패한 작업 자동 재시도

• 유연한 구성: 구성 파일 및 환경 변수 지원

작동 방식

CLI는 S3 개념을 Koneksi의 스토리지 모델로 변환합니다.

• 버킷 → 연결 디렉터리

• 객체 → 연결 파일

• S3 URI → 연결 경로(예: s3://bucket/key → 디렉터리/파일)

설치

전제 조건

• Go 1.23 이상(소스 빌드용)

• 유효한 Koneksi API 자격 증명(클라이언트 ID 및 클라이언트 비밀번호)

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

1. 릴리스 페이지를 방문하세요여기.

2. 귀하의 플랫폼에 적합한 바이너리를 다운로드하세요:

   1. Linux용 koneksi-s3-linux-amd64

   2. macOS(Intel)용 koneksi-s3-darwin-amd64

   3. macOS(Apple Silicon)용 koneksi-s3-darwin-arm64

   4. Windows용 koneksi-s3-windows-amd64.exe

3. 바이너리를 실행 가능하게 만듭니다(Linux/macOS):

chmod +x koneksi-s3-*

1. PATH에 있는 위치로 이동합니다.

sudo mv koneksi-s3-* /usr/local/bin/koneksi-s3

옵션 2: 소스에서 빌드

1. 저장소를 복제합니다.

git clone https://github.com/your-org/koneksi-s3-cli-standalone.git
cd koneksi-s3-cli-standalone

1. 바이너리를 빌드합니다.

make build

1. 시스템 전체에 설치:

sudo make install

옵션 3: 플랫폼별 빌드

특정 플랫폼에 맞춰 빌드:

# Linux
make build-linux

# macOS (Intel)
make build-darwin-amd64

# macOS (Apple Silicon)
make build-darwin-arm64

# Windows
make build-windows

# All platforms
make build-all

설정 또는 구성

구성 방법

CLI는 세 가지 구성 방법을 지원합니다(우선순위 순):

1. 환경 변수(가장 높은 우선순위)

2. 구성 파일

3. 명령줄 플래그(특정 옵션용)

구성을 설정하는 방법

방법 1: 구성 파일

~/.koneksi-s3.yaml에 구성 파일을 만듭니다.

# 필수 자격 증명
client_id: "your-client-id"
client_secret: "your-client-secret"

# 선택적 설정
directory_id: "default-directory-id"  # Default directory for operations
timeout: 30                          # Request timeout in seconds
retry_count: 3                       # Number of retries for failed requests
retry_wait_time: 1                   # Wait time between retries in seconds
retry_max_wait_time: 30              # Maximum wait time between retries

방법 2: 환경 변수

KONEKSI_ 접두사로 환경 변수를 설정합니다.

export KONEKSI_CLIENT_ID="your-client-id"
export KONEKSI_CLIENT_SECRET="your-client-secret"
export KONEKSI_DIRECTORY_ID="default-directory-id"
export KONEKSI_TIMEOUT=30
export KONEKSI_RETRY_COUNT=3

방식 3: 혼합 구성 방식

구성 방법을 혼합하여 사용할 수 있습니다. 예를 들어, 자격 증명은 구성 파일에 저장하되, 디렉터리 ID는 환경을 통해 재정의할 수 있습니다.

# ~/.koneksi-s3.yaml contains client_id and client_secret
export KONEKSI_DIRECTORY_ID="project-specific-directory"

구성 확인 중

버킷을 나열하여 구성을 테스트하세요.

koneksi-s3 ls

올바르게 구성한 경우 디렉토리 목록이 표시됩니다.

기본 사용법

S3 URI 형식 이해

CLI는 S3 스타일 URI를 사용하여 원격 위치를 참조합니다.

• s3://bucket-name/ - 버킷(디렉토리)을 참조합니다.

• s3://bucket-name/path/to/object - 객체(파일)를 참조합니다.

필수적인명령

버킷(디렉토리) 목록 나열

# 모든 버킷 나열
koneksi-s3 ls

# 출력 예:
# 2024-01-15 10:30:00 my-documents
# 2024-01-15 11:45:00 project-files
# 2024-01-15 12:00:00 backups

버킷에 있는 객체 나열

# 버킷에 있는 객체 나열
koneksi-s3 ls s3://my-documents/

# 접두사가 있는 객체 나열
koneksi-s3 ls s3://my-documents/reports/

# 출력 예:
# 2024-01-15 10:30:00    1024 file1.txt
# 2024-01-15 11:00:00    2048 file2.pdf
# 2024-01-15 11:30:00     512 reports/monthly.xlsx

파일 업로드

# 단일 파일 업로드
koneksi-s3 cp local-file.txt s3://my-documents/remote-file.txt

# 진행률 표시와 함께 업로드
koneksi-s3 cp large-file.zip s3://backups/

# 특정 경로에 업로드
koneksi-s3 cp report.pdf s3://my-documents/reports/2024/january.pdf

파일 다운로드

# 파일 다운로드
koneksi-s3 cp s3://my-documents/remote-file.txt local-file.txt

# 현재 디렉토리에 다운로드(원래 파일 이름 유지)
koneksi-s3 cp s3://my-documents/report.pdf .

# 새로운 이름으로 다운로드
koneksi-s3 cp s3://my-documents/old-name.txt new-name.txt

버킷 만들기 및 제거

# 새 버킷 만들기
koneksi-s3 mb s3://new-bucket/

# 빈 버킷 제거
koneksi-s3 rb s3://old-bucket/

# 비어 있지 않은 버킷을 강제로 제거합니다(신중하게 사용하세요!)
koneksi-s3 rb --force s3://old-bucket/

명령 참조

ls - 목록 명령

버킷이나 버킷에 있는 객체를 나열합니다.

통사론:

koneksi-s3 ls [s3://bucket[/prefix]]

예시들

# 모든 버킷 나열
koneksi-s3 ls

# 버킷의 루트 수준 나열
koneksi-s3 ls s3://my-bucket/

# 접두사가 있는 목록
koneksi-s3 ls s3://my-bucket/documents/2024/

# 재귀적 목록(지원되는 경우)
koneksi-s3 ls -r s3://my-bucket/

cp - 복사 명령

로컬 파일 시스템과 S3 간, 또는 S3 위치 간에 파일을 복사합니다.

통사론:

koneksi-s3 cp [options] <source> <destination>

옵션:

• -r, --recursive: 디렉터리를 재귀적으로 복사합니다.

• --dry-run: 실제로 복사하지 않고 복사될 내용을 표시합니다.

예시들

# 파일 업로드
koneksi-s3 cp file.txt s3://bucket/file.txt

# 파일 다운로드
koneksi-s3 cp s3://bucket/file.txt file.txt

# S3 위치 간 복사
koneksi-s3 cp s3://bucket1/file.txt s3://bucket2/file.txt

# 재귀적 업로드
koneksi-s3 cp -r local-folder/ s3://bucket/remote-folder/

# 재귀적 다운로드
koneksi-s3 cp -r s3://bucket/remote-folder/ local-folder/

# 작업을 미리 보기 위한 연습 실행
koneksi-s3 cp -r --dry-run local-folder/ s3://bucket/

mv - 이동 명령

로컬 파일 시스템과 S3 간, 또는 S3 내에서 파일을 이동하거나 이름을 바꿉니다.

통사론:

koneksi-s3 mv <source> <destination>

예시들

# 로컬 파일을 S3로 이동
koneksi-s3 mv file.txt s3://bucket/file.txt

# S3에서 로컬로 이동
koneksi-s3 mv s3://bucket/file.txt file.txt

# S3 내에서 이름 바꾸기
koneksi-s3 mv s3://bucket/old-name.txt s3://bucket/new-name.txt

# 버킷 간 이동
koneksi-s3 mv s3://bucket1/file.txt s3://bucket2/file.txt

rm - 명령 제거

S3에서 객체를 제거합니다.

통사론:

koneksi-s3 rm [options] s3://bucket/key

옵션:

• -r, --recursive: 객체를 재귀적으로 제거합니다.

• --dry-run: 실제로 제거하지 않고 제거될 항목을 표시합니다.

예시들

# 단일 객체 제거
koneksi-s3 rm s3://bucket/file.txt

# 확인 후 제거
koneksi-s3 rm s3://bucket/important-file.txt

# 재귀적으로 제거
koneksi-s3 rm -r s3://bucket/folder/

# 드라이런
koneksi-s3 rm -r --dry-run s3://bucket/folder/

mb - 버킷 명령 만들기

새로운 버킷(디렉토리)을 만듭니다.

통사론:

koneksi-s3 mb s3://bucket-name/

예시들

# 버킷 만들기
koneksi-s3 mb s3://my-new-bucket/

# 특정 이름으로 생성
koneksi-s3 mb s3://project-2024-data/

rb - 버킷 명령 제거

빈 양동이를 꺼내세요.

통사론:

koneksi-s3 rb [options] s3://bucket-name/

옵션:

• --force: 비어 있지 않은 버킷을 제거합니다.

예시들:

# 빈 버킷 제거
koneksi-s3 rb s3://old-bucket/

# 비어 있지 않은 버킷 강제 제거
koneksi-s3 rb --force s3://old-bucket/

고급 사용법

대용량 파일 작업

대용량 파일 업로드의 경우 CLI는 다음을 자동으로 처리합니다.

• 전송 중 진행률 표시

• 실패 시 자동 재시도

• 메모리 사용량을 최소화하는 효율적인 스트리밍

# 진행 상황을 담은 대용량 파일 업로드
koneksi-s3 cp large-dataset.zip s3://backups/datasets/

# CLI는 다음을 표시합니다:
# Uploading large-dataset.zip to s3://backups/datasets/
# Progress: [##########----------] 50% (512MB/1GB)

일괄 작업

여러 파일 업로드

# 모든 .txt 파일을 업로드하세요
for file in *.txt; do
    koneksi-s3 cp "$file" "s3://bucket/texts/$file"
done

# 디렉토리 구조 업로드
koneksi-s3 cp -r ./project/ s3://bucket/projects/2024/

여러 파일 다운로드

# 접두사가 포함된 모든 파일 다운로드
koneksi-s3 cp -r s3://bucket/reports/2024/ ./local-reports/

# 특정 패턴 다운로드(셸 사용)
for month in jan feb mar; do
    koneksi-s3 cp "s3://bucket/reports/2024/$month-report.pdf" .
done

스크립팅 및 자동화

백업 스크립트 예

#!/bin/bash
# backup-to-koneksi.sh

BACKUP_DATE=$(date +%Y%m%d)
BACKUP_BUCKET="s3://backups"

# 일일 백업 버킷 만들기
koneksi-s3 mb "$BACKUP_BUCKET/daily-$BACKUP_DATE/"

# 중요한 디렉터리 업로드
for dir in documents projects config; do
    echo "Backing up $dir..."
    koneksi-s3 cp -r "$HOME/$dir/" "$BACKUP_BUCKET/daily-$BACKUP_DATE/$dir/"
done

echo "Backup completed for $BACKUP_DATE"

동기화 스크립트 예제

#!/bin/bash
# sync-projects.sh

# 새 파일이나 수정된 ​​파일을 업로드하세요
find ./projects -type f -mtime -1 | while read file; do
    s3_path="s3://project-bucket/${file#./}"
    echo "Uploading $file to $s3_path"
    koneksi-s3 cp "$file" "$s3_path"
done

다양한 디렉토리 ID로 작업하기

특정 작업에 대한 기본 디렉토리 ID를 재정의합니다.

# 세션에 대한 디렉토리 ID 설정
export KONEKSI_DIRECTORY_ID="project-specific-id"

# 특정 디렉토리에 업로드
koneksi-s3 cp file.txt s3://bucket/file.txt

# 기본값으로 재설정
unset KONEKSI_DIRECTORY_ID

성능 최적화

병렬 업로드

# GNU Parallel을 사용하여 병렬로 파일 업로드
find . -name "*.jpg" | parallel -j 4 koneksi-s3 cp {} s3://images/{}

# 또는 xargs를 사용하여
find . -name "*.pdf" | xargs -P 4 -I {} koneksi-s3 cp {} s3://documents/{}

효율적인 재귀 연산

# 더 나은 성능을 위해 재귀 플래그를 사용하세요
koneksi-s3 cp -r large-directory/ s3://bucket/

# 개별 파일 업로드 대신
# 이렇게 하지 마세요 - 속도가 느려집니다:
find large-directory -type f -exec koneksi-s3 cp {} s3://bucket/{} \;

문제 해결 가이드

인증 오류

문제: "인증 실패" 또는 "잘못된 자격 증명"

솔루션:

1. 자격 증명이 올바르게 설정되었는지 확인하세요.

# 환경 변수 확인
echo $KONEKSI_CLIENT_ID
echo $KONEKSI_CLIENT_SECRET

# 구성 파일 확인
cat ~/.koneksi-s3.yaml

1. 자격 증명에 공백이 없는지 확인하세요.

2. Koneksi 시스템에서 자격 증명이 활성화되어 있는지 확인하세요.

연결 시간 초과

문제: "요청 시간 초과" 오류

솔루션:

1. 시간 초과 설정을 늘리세요:

export KONEKSI_TIMEOUT=60  # 60 seconds

1. 네트워크 연결을 확인하십시오.

# 테스트 API 엔드포인트
curl -I https://api.koneksi.com/health

1. 불안정한 연결에 재시도 구성을 사용하세요

파일 업로드 실패

문제: 대용량 파일 업로드 실패

솔루션:

1. 대용량 파일의 시간 초과를 늘리세요:

export KONEKSI_TIMEOUT=300  # 5 minutes

1. 임시 파일의 사용 가능한 디스크 공간을 확인하세요.

2. 파일 권한 확인

디렉토리/버킷을 찾을 수 없습니다

문제: "버킷을 찾을 수 없음" 오류

솔루션:

1. 사용 가능한 버킷을 나열하세요.

koneksi-s3 ls

1. 버킷 이름 철자를 확인하세요.

2. 디렉토리 ID가 올바른지 확인하세요:

echo $KONEKSI_DIRECTORY_ID

디버그 모드

문제 해결을 위해 자세한 출력을 활성화하세요.

# 디버그 환경 변수 설정(지원되는 경우)
export KONEKSI_DEBUG=true

# 자세한 출력으로 명령 실행
koneksi-s3 -v cp file.txt s3://bucket/

도움 받기

1. 기본 제공 도움말:

# 일반 도움말
koneksi-s3 --help

# 명령별 도움말
koneksi-s3 cp --help
koneksi-s3 ls --help

2. 버전 정보:

koneksi-s3 --version

빠른 참조

필수 명령 요약

# 모든 버킷 나열
koneksi-s3 ls

# 버킷 콘텐츠 나열
koneksi-s3 ls s3://bucket/

# 파일 업로드
koneksi-s3 cp file.txt s3://bucket/file.txt

# 파일 다운로드
koneksi-s3 cp s3://bucket/file.txt file.txt

# 디렉토리 업로드
koneksi-s3 cp -r folder/ s3://bucket/folder/

# 파일 이동/이름 바꾸기
koneksi-s3 mv s3://bucket/old.txt s3://bucket/new.txt

# 파일 삭제
koneksi-s3 rm s3://bucket/file.txt

# 버킷 만들기
koneksi-s3 mb s3://new-bucket/

# 버킷 삭제
koneksi-s3 rb s3://bucket/

구성 빠른 설정

# 구성 파일 생성
cat > ~/.koneksi-s3.yaml << EOF
client_id: "your-client-id"
client_secret: "your-client-secret"
directory_id: "your-directory-id"
timeout: 30
retry_count: 3
EOF

# 또는 환경 변수를 사용하십시오.
export KONEKSI_CLIENT_ID="your-client-id"
export KONEKSI_CLIENT_SECRET="your-client-secret"

일반적인 패턴

# 백업 패턴
koneksi-s3 cp -r /important/data/ s3://backups/$(date +%Y%m%d)/

# 아카이브 패턴
tar czf - /path/to/files | koneksi-s3 cp - s3://archives/backup.tar.gz

# 일괄 업로드 패턴
find . -name "*.log" -mtime -1 | while read f; do
    koneksi-s3 cp "$f" "s3://logs/$(basename "$f")"
done

# 패턴 다운로드 및 추출
koneksi-s3 cp s3://archives/data.tar.gz - | tar xzf -

팁과 모범 사례

1. 재귀 플래그 사용: 디렉터리 작업의 경우 성능 향상을 위해 항상 -r 플래그를 사용하십시오.

2. 접두사로 구성: S3 스타일 접두사를 사용하여 파일을 구성합니다(예: s3://bucket/year/month/day/).

3. 드라이 런으로 테스트: --dry-run 플래그를 사용하여 실행 전에 작업을 미리 봅니다.

4. 반복 작업 스크립팅: 일반적인 작업에 대한 셸 스크립트를 생성합니다.

5. 전송 모니터링: 대용량 전송의 경우 screen/tmux 세션에서 실행합니다.

6. 정기 백업: cron 작업을 사용하여 정기 백업을 예약합니다.

7. 보안 자격 증명: 버전 제어에 자격 증명을 커밋하지 않습니다.

추가 리소스

• GitHub 저장소: https://github.com/koneksi-tech/s3-cli

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

• 릴리스: https://github.com/koneksi-tech/s3-cli/issues