金山云-文档中心-复制文件（cp）

cp命令可用于将存储在KS3的文件复制到同Bucket的其他目录，或其他Bucket内。

以下示例均以Linux为例。

命令格式

./ks3util cp cloud_url cloud_url 
[--object-file <value>]
[-r, --recursive] 
[-f, --force] 
[-u, --update]
[--update-rule <value>]
[--bigfile-threshold <value>]
[--part-size <value>]
[--only-current-dir]
[--storage-class <value>]
[--acl <value>]
[--meta <value>]
[--tagging <value>]
[--sse-algorithm <value>]
[--copy-mode <value>]
[--include <value>]
[--exclude <value>]
[--time-range <value>]
[-j, --jobs <value>]
[--parallel <value>]
[--bandwidth-limit <value>]
[--checkpoint-dir <value>]
[--dry-run]
[--list-parallel <value>]
[--list-depth <value>]

参数说明

参数	说明
cloud_url	KS3文件路径，格式为ks3://bucketname/objectname。
--object-file	需复制的文件列表，内容为文件完整的key，不同key之间以换行分隔。
-r, --recursive	递归进行操作。当指定该选项时，会对源存储空间下所有符合条件的对象进行操作，否则只对路径指定的单个对象进行操作。
-f, --force	强制操作，不进行询问提示。当目标文件已存在，且没有使用-u选项时，会覆盖目标文件（即所有文件重传）。
-u, --update	更新操作，只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，KS3Util才会执行复制操作，否则会跳过该文件。
--update-rule	使用`-u`选项进行增量操作时的更新规则，只有当目标文件满足指定规则时才会更新，否则文件会被跳过。默认值：3。可选值： 1：目标文件不存在则更新。 2：目标文件不存在或大小不相等则更新。 3：目标文件不存在或时间戳更旧则更新。 4：目标文件不存在或时间戳更旧或大小不相等则更新。 5：目标文件不存在或CRC64不一致则更新。
--bigfile-threshold	开启大文件分块操作的阈值，大于等于该值的文件会进行分块。格式：值+单位默认值：100MB（104857600）默认单位：B（Byte）可选单位：B、KB、MB、GB、TB。
--part-size	分块大小，默认情况下将根据文件大小自动计算合适的值。格式：值+单位默认单位：B（Byte）取值范围：5MB-5GB（5242880-5368709120） 1. 可选单位：B、KB、MB、GB。 2. 如果有特殊需求或需要性能调优，可以设置该值。
--only-current-dir	表示仅操作当前目录下的文件，忽略子目录。
--storage-class	设置对象的存储类型，可选值：STANDARD、STANDARD_IA、ARCHIVE。若未指定，则与源文件保持一致。
--acl	设置对象的访问权限，可选值：private、public-read。若未指定，则与源文件保持一致。
--meta	设置对象的元数据，格式为：header:value#header:value（多组值之间以#分隔），例如：Cache-Control:no-cache#Content-Encoding:gzip。若未指定，则与源文件保持一致。
--tagging	设置对象的标签，格式为："TagA=A&TagB=B"（多个标签以&分隔），例如："tag1=value1&tag2=value2"。若未指定，则与源文件保持一致。该选项的值需要使用双引号包含。
--sse-algorithm	设置服务端加密算法，可选值：AES256、SM4。
--copy-mode	对象复制模式，默认值：1。可选值： 1：服务端复制，适合同区域复制。 2：客户端复制，适合跨区域复制，该模式需要分别配置源和目标桶的域名。
--include	包含对象匹配模式，满足匹配规则的文件将会被选中，如：*.jpg。该选项可以出现多次，多个--include规则取并集。
--exclude	不包含对象匹配模式，满足匹配规则的文件将会被排除，如：*.txt。该选项可以出现多次，多个--exclude规则取并集。
--time-range	时间段匹配模式，仅匹配最后修改时间在该时间段内的文件。时间段格式为：time1-time2，其中time1、time2需要填写UTC时间，格式为：yyyyMMddHHmmss。详细请参考通用选项&过滤规则文档。
-j, --jobs	多文件操作时的并发数，表示有多少个文件并行传输。默认值：5，取值范围：1-10000。 1. 批量复制时，若带宽未跑满，可适当调大`-j`。 2. 当`-j`的值较大时（如 50 以上），建议将`--parallel`设为较小值（如 1）。 3. 避免同时调大`-j`与`--parallel`，以防止并发过高导致传输超时。
--parallel	单文件内部操作的并发任务数，表示单个大文件有多少个块并行传输。取值范围：1-10000。 1. 默认根据文件大小自动调整，取值范围为 1-16。 2. 单文件复制时，若带宽未跑满，可适当调大`--parallel`。 3. 批量复制时，建议`--parallel`保持默认值或设置为 1。
--bandwidth-limit	设置网络带宽限速，用于限制文件跨区域复制速度。例如：100MB 表示限速 100MB/s。格式：值+单位默认值：无（不限速）默认单位：B（Byte） 1. 可选单位：B、KB、MB、GB。 2. 该参数不会限制同区域复制文件的速度。
--checkpoint-dir	断点续传信息存储目录，默认值为当前工作目录下的 .ks3util_checkpoint，大文件分块传输中断后可从中断点续传。
--dry-run	测试模式运行，不执行实际复制操作，用于验证流程的正确性。
--list-parallel	扫描文件的并发数，默认值：1，取值范围：1-100。
--list-depth	并行扫描的最大目录深度，默认值：1，取值范围：1-100。该值影响扫描策略，值越大并行扫描的目录层级越深，但不影响最终扫描到的文件总数。

除上述的功能参数，关于Util支持的通用选项参数，详情请参考通用选项&过滤规则文档。

使用示例

复制单个文件。

如果没有指定目标文件名，则使用原文件名保存。

./ks3util cp ks3://samplebucket/src-prefix/sample.txt ks3://samplebucket/dst-prefix/

若指定了目标文件名，则使用指定的文件名保存。

./ks3util cp ks3://samplebucket/src-prefix/sample.txt ks3://samplebucket/dst-prefix/sample-file.txt

复制单个文件并为目标文件指定加密算法。

./ks3util cp ks3://samplebucket/src-prefix/sample.txt ks3://samplebucket/dst-prefix/ --sse-algorithm AES256

按目录复制。
- 复制目录下所有文件，包括子目录。
```
./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r
```
- 复制目录下所有文件，并跳过已存在的文件。
  当批量复制失败或需要增量复制时，可以使用-u选项跳过已存在且最后修改时间晚于源文件的文件。
```
./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r -u
```
- 复制目录下所有文件，并设置更新规则为5（目标文件不存在或CRC64不一致则更新）。
```
./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r -u --update-rule 5
```
- 仅复制当前目录下的文件，忽略子目录。
```
./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --only-current-dir
```

按条件复制。

使用--include和--exclude选项复制符合匹配规则的文件。

./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --include *.jpg --exclude *screenshot*

修改目标文件读写权限ACL。

./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --acl public-read

修改目标文件的存储类型。

./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --storage-class STANDARD_IA

修改目标文件标签。

./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --tagging "a=1&b=2"

修改文件meta。

./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --meta Cache-Control:no-cache#X-Kss-Meta-A:1

跨区域复制文件夹。

./ks3util cp ks3://samplebucket1/src-prefix/ ks3://samplebucket2/dst-prefix/ -r -u --copy-mode 2

跨区域复制时，您需要为源和目标桶配置访问域名，并将其添加到配置文件内容的末尾，格式如下所示：

[Bucket-Endpoint]
samplebucket1=ks3-cn-beijing.ksyuncs.com
samplebucket2=ks3-cn-shanghai.ksyuncs.com

复制最后修改时间在指定范围的文件。

./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --time-range "20241106120000-20241110120000"

复制指定列表中的文件。
- 使用准备：创建列表文件list.txt，假设为以下内容。
```
data/abc/file1
data/abc/test/file2
```
- 复制samplebucket的data/abc/前缀下，且在list.txt列表中的文件到samplebucket2的prefix/前缀下。
```
./ks3util cp ks3://samplebucket/data/abc/ --object-file list.txt ks3://samplebucket2/prefix/ -r
```
  复制后的文件在ks3中的路径为：ks3://samplebucket2/prefix/file1、ks3://samplebucket2/prefix/test/file2。
复制指定列表中的目录。
- 使用准备：创建列表文件list.txt，假设为以下内容。
```
data/abc/dir1/
data/abc/test/dir2/
```
  目录路径需要以/符号结尾。
- 复制samplebucket的data/abc/前缀下，且在list.txt列表中的目录到samplebucket2的prefix/前缀下。
```
./ks3util cp ks3://samplebucket/data/abc/ --object-file list.txt ks3://samplebucket2/prefix/ -r
```
  复制后的目录在ks3中的路径为：ks3://samplebucket2/prefix/dir1/、ks3://samplebucket2/prefix/test/dir2/。

复制文件夹，测试模式运行。

./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --dry-run

复制文件夹，设置扫描并发数为5，最大并发扫描深度为1。

./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r -f --list-parallel 5 --list-depth 1