全部文档
当前文档
最近更新时间：2025-11-07 15:15:27
cp命令可用于将存储在KS3的文件复制到同Bucket的其他目录，或同区域的其他Bucket内。
以下示例均以Linux为例。
./ks3util cp cloud_url cloud_url
[--object-file <value>]
[-r, --recursive]
[-f, --force]
[-u, --update]
[--bigfile-threshold <value>]
[--part-size <value>]
[--only-current-dir]
[--storage-class <value>]
[--acl <value>]
[--meta <value>]
[--tagging <value>]
[--sse-algorithm <value>]
[--include <value>]
[--exclude <value>]
[--time-range <value>]
[-j, --jobs <value>]
[--parallel <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才会执行复制操作，否则会跳过该文件。 |
--bigfile-threshold | 开启大文件分块操作的阈值，大于等于该值的文件会进行分块，并且支持断点续传。格式为：值+单位。单位可选，支持的单位：B、KB、MB、GB、TB，默认单位为B（Byte）。默认值：100MB（104857600）。 |
--part-size | 分块大小，默认情况下根据文件大小自行计算合适的值。格式为：值+单位。单位可选，支持的单位：B、KB、MB、GB、TB，默认单位为B（Byte）。取值范围：5MB-5GB（5242880-5368709120）。 如果有特殊需求或者需要性能调优，可以设置该值。 |
--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。 |
--include | 包含对象匹配模式，满足匹配规则的文件将会被选中，如：*.jpg。 该选项可以出现多次，多个--include规则取并集。 |
--exclude | 不包含对象匹配模式，满足匹配规则的文件将会被排除，如：*.txt。 该选项可以出现多次，多个--exclude规则取并集。 |
--time-range | 时间段匹配模式，仅匹配最后修改时间在该时间段内的文件。时间段格式为：time1-time2，其中time1、time2需要填写UTC时间，格式为：yyyyMMddHHmmss。 详细请参考通用选项&过滤规则文档。 |
-j, --jobs | 多文件操作时的并发数，默认值：5，取值范围：1-10000。 1. 该参数决定有多少个文件并行复制。 2. 批量操作文件时适合调整该参数。 3. Util2.9.0版本默认值由3改为5。 |
--parallel | 单文件内部操作的并发任务数，取值范围：1-10000。 1. 默认KS3 Util会根据操作类型和文件大小自动决定，自动取值范围是1-12。 2. 该参数决定单个文件有多少个块并行复制。 3. 操作单个大文件时适合调整该参数。 4. 总并发数= jobs * parallel。 |
--checkpoint-dir | checkpoint目录的路径(默认值为:.ks3util_checkpoint)，断点续传时，操作失败KS3Util会自动创建该目录，并在该目录下记录checkpoint信息，操作成功会删除该目录。如果指定了该选项，请确保所指定的目录可以被删除。 |
--dry-run | 测试模式运行，不执行实际复制操作，用于验证流程的正确性。 |
--list-parallel | 扫描文件的并发数，默认值：1，取值范围：1-100。 |
--list-depth | 并行扫描的最大深度，超过此深度的目录将不再并行扫描，默认值：1，取值范围：1-100。 假设源目录为prefix/，而该目录存在以下结构： prefix/aa/ prefix/aa/1/、prefix/aa/2/ prefix/bb/ prefix/bb/1/、prefix/bb/2/ 值为 1 代表使用 delimiter=/ 扫描顶层（prefix/），获取到 prefix/aa/，prefix/bb/后，二者不再使用 delimiter=/ 进行扫描。 值为 2 代表获取到 prefix/aa/，prefix/bb/ 后，二者仍使用 delimiter=/ 进行扫描，再得到的结果不再使用 delimiter=/ 进行扫描。 |
除上述的功能参数，关于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当批量复制失败或需要增量复制时，可以使用--update（可缩写为-u）选项跳过已存在且最后修改时间晚于原文件的文件。
./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r -u仅复制当前目录下的文件，忽略子目录。
./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://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --time-range "20241106120000-20241110120000"示例五：按照文件列表复制。
使用准备：创建列表文件list.txt，假设文件列表为以下内容。
files/part01/file1
files/part01/file2Case1：复制list.txt中的文件。
./ks3util cp ks3://samplebucket/ --object-file list.txt ks3://samplebucket2/prefix/ -r复制后的文件在ks3中的路径为：ks3://samplebucket2/prefix/files/part01/file1、ks3://samplebucket2/prefix/files/part01/file2。
Case2：复制list.txt中的文件，去掉files/part01/前缀。
./ks3util cp ks3://samplebucket/files/part01/ --object-file list.txt ks3://samplebucket2/prefix/ -r复制后的文件在ks3中的路径为：ks3://samplebucket2/prefix/file1、ks3://samplebucket2/prefix/file2。
示例六：复制文件夹，测试模式运行。
./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纯净模式