파일 동기화 업/다운로드 또는 복사 - sync
마지막 업데이트 시간:2025-11-19 15:52:40
sync 명령어는 파일을 동기화 업로드, 다운로드 또는 복사에 사용되며 cp 명령어와의 차이점은 sync 명령어는 먼저 같은 이름의 파일의 crc64를 비교하고 crc64 값이 같으면 전송하지 않는다는 것입니다.
주의:
파일 업로드 명령어를 사용하려면 권한 정책 설정 시 action을
cos:HeadBucket,cos:GetBucket,cos:HeadObject,cos:InitiateMultipartUpload,cos:UploadPart,cos:CompleteMultipartUpload,cos:ListMultipartUploads,cos:ListParts으로 지정해야 합니다.파일 다운로드 명령어를 사용하려면 권한 정책 설정 시 action을
cos:HeadBucket,cos:GetBucket,cos:HeadObject,cos:GetObject으로 지정해야 합니다. 파일 복사 명령어를 사용하려면 권한 정책 설정 시 대상 객체 action을
cos:GetBucket, cos:HeadObject, cos:InitiateMultipartUpload, cos:PutObject, cos:CompleteMultipartUpload, 소스 객체 action을 cos:HeadBucket, cos:GetBucket, cos:HeadObject, cos:GetObject으로 지정해야 합니다.명령어 형식
./coscli sync <source_path> <destination_path> [flag]
sync 명령은 다음 매개변수를 포함합니다.
매개변수 포맷 | 매개변수 용도 | 예시 |
source_path | 소스 파일 경로. 로컬 경로 또는 COS 파일 경로일 수 있습니다. COS 경로는 구성 매개변수에 있는 버킷 별칭 또는 버킷 이름을 사용하여 액세스하는 것을 지원합니다. 버킷 이름을 사용하여 액세스하는 경우 추가로 endpoint flag가 포함되어야 합니다. | 로컬 경로: ~/example.txt 버킷 별칭을 사용하여 COS 파일 경로를 지정: cos://bucketalias/example.txt 버킷 이름을 사용하여 COS 파일 경로를 지정: cos://examplebucket-1250000000/example.txt |
destination_path | 대상 파일 경로. 로컬 경로 또는 COS 파일 경로일 수 있습니다. COS 경로는 구성 매개변수에 있는 버킷 별칭 또는 버킷 이름을 사용하여 액세스하는 것을 지원합니다. 버킷 이름을 사용하여 액세스하는 경우 추가로 endpoint flag가 필요합니다. | 로컬 경로: ~/example.txt 버킷 별칭을 사용하여 COS 파일 경로를 지정: cos://bucketalias/example.txt 버킷 이름을 사용하여 COS 파일 경로를 지정: cos://examplebucket-1250000000/example.txt |
sync 명령어에는 다음과 같은 flag 옵션이 포함됩니다.
flag 약칭 | flag 전체 명칭 | flag 용도 |
없음 | --include | 특정 패턴이 포함된 파일(v1.0.4 이전 버전: 업로드 시 로컬 파일명만 필터링, v1.0.4 이후: 전체 경로 필터링) 예를 들어, ./test 아래의 모든 파일을 COS에 업로드해야 하며, ./test 아래에는 aaa 폴더가 포함되어 있고, aaa 폴더 아래에는 1.txt 파일이 포함되어 있습니다. 1.0.4 이전 버전은 aaa/1.txt와 일치합니다. 1.0.4 및 이후 버전은 ./test/aaa/1.txt와 일치합니다. |
없음 | --exclude | 특정 패턴이 제외된 파일(v1.0.4 이전 버전: 업로드 시 로컬 파일명만 필터링, v1.0.4 이후: 전체 경로 필터링) 예를 들어, ./test 아래의 모든 파일을 COS에 업로드해야 하며, ./test 아래에는 aaa 폴더가 포함되어 있고, aaa 폴더 아래에는 1.txt 파일이 포함되어 있습니다. 1.0.4 이전 버전은 aaa/1.txt와 일치합니다. 1.0.4 및 이후 버전은 ./test/aaa/1.txt와 일치합니다. |
-r | --recursive | 폴더의 모든 파일 재귀적 순회 여부 |
없음 | --storage-class | |
없음 | --part-size | 파일 파트 크기(기본 32MB, 최대 5GB 지원). 파일 크기에 따른 자동 파트 분할을 설정하려면 0을 입력하세요. |
없음 | --thread-num | 동시 스레드 수(기본값: 5) |
없음 | --rate-limiting | 단일 링크 속도 제한(0.1 - 100MB/s) |
없음 | --snapshot-path | 업로드 또는 다운로드하는 파일을 저장할 때의 스냅샷 정보가 있는 목록을 지정합니다. 다음에 파일을 업로드 또는 다운로드할 때, coscli는 지정 목록의 스냅샷 정보를 읽어 증량 업로드 또는 다운로드를 수행합니다. 본 옵션은 목록 파일 동기화를 가속화하는 데 사용됩니다. |
없음 | --meta | 파일의 메타 정보를 업로드합니다. 일부 HTTP 표준 속성(HTTP Header) 및 x-cos-meta-로 시작하는 사용자 정의 메타데이터(User Meta)를 포함합니다. 파일 메타 정보 포맷은 header:value#header:value이고, 예시는 Expires:2022-10-12T00:00:00.000Z#Cache-Control:no-cache#Content-Encoding:gzip#x-cos-meta-x:x입니다. |
없음 | --routines | 파일 간 동시 업로드 또는 다운로드 스레드의 파일 수를 지정하며, 기본값은 3입니다. |
없음 | --fail-output | 이 옵션은 업로드 또는 다운로드가 실패할 때 파일의 오류 출력을 활성화할지 여부를 결정합니다(기본값은 true, 활성화). 활성화되면 실패한 파일 전송은 지정된 목록(지정하지 않은 경우 기본값은 ./coscli_output임)에 기록됩니다. 비활성화되면 실패한 파일의 수만 콘솔로 출력됩니다. |
없음 | --fail-output-path | 이 옵션은 업로드 또는 다운로드 실패를 기록하는 파일의 오류 출력 폴더를 지정하는 데 사용됩니다. 사용자 정의 폴더 경로를 제공함으로써 오류 출력 폴더의 위치 및 이름을 제어할 수 있다. 이 옵션을 설정하지 않은 경우 기본 오류 로그 폴더 ./coscli_output를 사용합니다. |
없음 | --retry-num | 빈도 제한 재시도 횟수(기본값은 0, 재시도하지 않음). 1-10회 선택 가능. 여러 대의 컴퓨터가 동시에 동일한 COS 목록에서 다운로드 작업을 실행하는 경우, 이 매개변수를 지정하여 재시도함으로써 빈도 제한 오류를 피할 수 있습니다. |
없음 | --err-retry-num | 오류 재시도 횟수(기본값은 5임). 1-10회로 지정하거나 0으로 설정하여 재시도하지 않음을 나타냅니다. |
없음 | --err-retry-interval | 재시도 간격( --err-retry-num를 1-10로 지정할 때에만 사용 가능). 1-10초의 재시도 간격을 지정하며, 지정하지 않거나 0으로 설정한 경우 매번 재시도 간격은 1-10초 내에서 무작위로 선택됩니다. |
없음 | --only-current-dir | 현재 목록의 파일만 업로드하고 하위 목록 및 그 내용을 무시할지 여부(기본값은 false, 무시하지 않음). |
없음 | --disable-all-symlink | 업로드 시 모든 심볼릭 링크의 하위 파일 및 심볼릭 링크의 하위 목록을 무시할지 여부(기본값은 true, 업로드하지 않음). 현재 Linux 및 MacOS 시스템에서만 지원됩니다. |
없음 | --enable-symlink-dir | 심볼링 링크의 하위 목록 업로드할지 여부(기본값은 false, 업로드하지 않음). 현재 Linux 및 MacOS 시스템에서만 지원됩니다. |
없음 | --disable-crc64 | CRC64 데이터 검증 비활성화 여부 (기본값은 false, 검증 활성화). |
없음 | --delete | 지정된 타겟 경로에 있는 임의의 기타 파일을 삭제하고 이번 동기화된 파일만 유지(기본값은 false, 삭제하지 않음) 실수로 데이터가 삭제되는 것을 방지하기 위해 --delete 옵션을 사용하기 전에 버전 제어를 활성화하는 것이 좋습니다. |
없음 | --backup-dir | 타겟측에서 이미 삭제되었지만 소스측에 존재하지 않는 파일을 저장하기 위해 삭제된 파일의 백업을 동기화합니다(다운로드할 때에만 유효하고 --delete=true 시 필히 지정). 업로드 및 버킷 복제는 버전 제어를 사용하여 실수로 삭제되는 데이터를 복구하시기 바랍니다. |
없음 | --force | 확인 알림이 없는 강제 작업 (기본값은 false). |
없음 | --disable-checksum | 기본값은 true이며, 샤드 crc64만 검증합니다. false로 설정하면 전체 파일의 crc64를 검증합니다. (coscli V1.0.6 및 이전 버전은 기본값이 false임) |
없음 | --process-log | 프로세스 로그를 활성화할지 여부. 기본값: true(활성화) |
없음 | --process-log-path | 해당 옵션은 프로세스 로그를 저장하기 위한 전용 출력 폴더를 지정하는 데 사용됩니다. 로그에는 파일 업로드 또는 다운로드와 관련된 정보(오류 로그, 정상 실행 로그, 재시도 등)가 기록됩니다. 사용자 정의 폴더 경로를 제공하여 로그 출력 폴더의 위치와 이름을 제어할 수 있습니다. 이 옵션을 설정하지 않으면 기본 로그 폴더(coscli_output)가 사용됩니다. |
없음 | --update | 수정 시간이 더 최신인 파일만 전 |
없음 | --ignore-existing | 존재하지 않는 파일만 전송 |
없음 | --skip-dir | 기본값은 false이며, true로 설정하면 폴더 전송을 건너뜁니다. |
없음 | --acl | 파일의 ACL 설정, 예: private, public-read |
없음 | --grant-read | 피승인자에게 객체 읽기 권한을 부여합니다. 형식은 id="[OwnerUin]"입니다(예: id="100000000001"). 반각 쉼표(,)를 사용하여 여러 피승인자를 구분할 수 있습니다(예: id="100000000001",id="100000000002"). |
없음 | --grant-read-acp | 피승인자에게 객체의 접근 제어 목록(ACL) 읽기 권한을 부여합니다. 형식은 id="[OwnerUin]"입니다(예: id="100000000001"). 반각 쉼표(,)를 사용하여 여러 피승인자를 구분할 수 있습니다(예: id="100000000001",id="100000000002"). |
없음 | --grant-write-acp | 피승인자에게 객체의 접근 제어 목록(ACL) 쓰기 권한을 부여합니다. 형식은 id="[OwnerUin]"입니다(예: id="100000000001"). 반각 쉼표(,)를 사용하여 여러 피승인자를 구분할 수 있습니다(예: id="100000000001",id="100000000002"). |
없음 | --grant-full-control | 피승인자에게 객체 작업 관련 모든 권한을 부여합니다. 형식은 id="[OwnerUin]"입니다(예: id="100000000001"). 반각 쉼표(,)를 사용하여 여러 피승인자를 구분할 수 있습니다(예: id="100000000001",id="100000000002"). |
없음 | --tags | 객체의 태그 집합. 최대 10개의 태그 설정 가능(예: --tags="Key1=Value1&Key2=Value2"). |
없음 | --forbid-overwrite | 버전 관리가 활성화되지 않은 버킷에 파일을 업로드할 때, 동일한 이름의 객체 덮어쓰기 금지 여부 지정. false로 지정하면 동일한 이름의 Object를 기본적으로 덮어씁니다. true로 지정하면 동일한 이름의 Object를 덮어쓰는 것이 금지됩니다. 버킷의 버전 관리 상태가 활성화됨이나 일시 중지됨일 경우 x-cos-forbid-overwrite 요청 헤더 설정이 무효화되며, 동일한 이름의 객체를 덮어쓰는 것이 허용됩니다. |
없음 | --encryption-type | 서버 측 암호화 방식(SSE-COS/SSE-C). |
없음 | --server-side-encryption | 서버 측 암호화 알고리즘, AES256, cos/kms 지원. SSE-COS 또는 SSE-KMS를 사용할 때 이 필드는 필수 항목입니다. |
없음 | --sse-customer-algo | 서버 측 암호화 알고리즘, AES256 지원. SSE-C를 사용할 때 이 필드는 필수 항목입니다. |
없음 | --sse-customer-key | 서버 측 암호화 키의 Base64 인코딩. 예: MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNERUY=. SSE-C를 사용할 때 이 필드는 필수 항목입니다. |
없음 | --sse-customer-key-md5 | 서버 측 암호화 키의 MD5 해시 값, Base64 인코딩 사용. 예: U5L61r7jcwdNvT7frmUG8g==. SSE-C를 사용할 때 이 필드는 필수 항목입니다. |
없음 | --check-point | 중단 지점에서 재개할지 여부. 기본값: true(중단 지점에서 재개 활성화) |
설명：
sync 명령어는 대용량 파일을 업로드 및 다운로드할 때 동시 업로드/다운로드를 자동으로 활성화합니다.
파일이
--part-size보다 큰 경우 COSCLI는 먼저 파일을 --part-size로 나눈 다음 --thread-num 스레드를 사용하여 업/다운로드 작업을 동시 실행합니다.각 스레드는 링크를 점검합니다. 각 링크에 대해
--rate-limiting 매개변수를 사용하여 단일 링크의 속도를 제한할 수 있습니다. 동시 업/다운로드가 활성화된 경우 총 속도는 --thread- num * --rate-limiting입니다.파일을 파트로 업로드/다운로드할 때 기본적으로 중간 지점 재개가 활성화됩니다.
--include 및 --exclude는 표준 정규식 구문을 지원하므로, 파일 특정 조건 필터링에 사용할 수 있습니다.zsh를 사용할 때 pattern 문자열의 양쪽 끝에 큰따옴표를 넣어야 할 수도 있습니다.
snapshot-path를 마이그레이션할 목록 또는 그 하위 목록으로 설정하지 마십시오.
./coscli sync ~/test/ cos://bucket1/example/ -r --include ".*\\.txt$" --snapshot-path=/path/snapshot-path --meta=x-cos-meta-a:a#ContentType:text#Expires:2022-10-12T00:00:00.000Z
사용자가 sync 명령을 사용할 때 PUT 요청 비용이 발생하는 것 외에 다음의 두 가지 경우에 클라우드에 있는 파일에 대해 HEAD 요청이 있으므로 추가 비용이 발생하게 됩니다.
지정 스냅샷 목록을 추가하지 않은 매개변수(
--snapshot-path``)는 HEAD 요청 비용이 발생하게 됩니다.지정 스냅샷 목록 매개변수(
--snapshot-path``)를 추가하고 스냅샷 목록을 처음 생성하는 경우 HEAD 요청 비용이 발생하게 됩니다. 처음 생성한 스냅샷 목록이 아니면 추가 요청 비용이 발생하지 않습니다.이 명령의 기타 범용 옵션(예: 버킷 전환, 사용자 계정 전환 등)에 대해서는 범용 옵션 문서를 참고하시기 바랍니다.
작업 예시
파일 동기화 업로드
./coscli sync ~/example.txt cos://bucket1/example.txt
파일 동기화 다운로드
./coscli sync cos://bucket1/example.txt ~/example.txt
버킷 내 파일 동기화 복사
./coscli sync cos://bucket1/example.txt cos://bucket1/example_copy.txt
버킷 간 파일 동기화 복사
./coscli sync cos://bucket1/example.txt cos://bucket2/example_copy.txt
피드백