全部文档
当前文档
最近更新时间：2026-04-10 20:40:21
cp命令可以用于将存储于KS3的文件下载到本地。
以下示例均以Linux为例。
./ks3util cp cloud_url file_url
[--object-file <value>]
[-r, --recursive]
[-f, --force]
[-u, --update]
[--update-rule <value>]
[--bigfile-threshold <value>]
[--part-size <value>]
[--include <value>]
[--exclude <value>]
[--time-range <value>]
[-j, --jobs <value>]
[--parallel <value>]
[--checkpoint-dir <value>]
[--disable-crc64]
[--dry-run]
[--disable-temp-file]
[--list-parallel <value>]
[--list-depth <value>]参数 | 说明 |
|---|---|
file_url | 本地文件或目录路径。 |
cloud_url | KS3文件路径，格式为ks3://bucketname/objectname。 |
--object-file | 需下载的文件列表，内容为文件完整的key，不同key之间以换行分隔。 |
-r, --recursive | 递归进行操作。当指定该选项时，会对存储空间下所有符合条件的对象进行操作，否则只对路径指定的定的单个对象进行操作。 |
-f, --force | 强制操作，不进行询问提示。当目标文件已存在，且没有使用-u选项时，会覆盖目标文件（即所有文件重传）。 |
-u, --update | 更新操作，只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，KS3Util才会执行下载操作，否则会跳过该文件。 |
--update-rule | 使用 可选值： 1：目标文件不存在则更新。 2：目标文件不存在或大小不相等则更新。 3：目标文件不存在或时间戳更旧则更新。 4：目标文件不存在或时间戳更旧或大小不相等则更新。 5：目标文件不存在或CRC64不一致则更新。 |
--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 | 表示仅操作当前目录下的文件，忽略子目录。 |
--include | 包含对象匹配模式，满足匹配规则的文件将会被选中，如：*.jpg。 该选项可以出现多次，多个--include规则取并集。 |
--exclude | 不包含对象匹配模式，满足匹配规则的文件将会被排除，如：*.txt。 该选项可以出现多次，多个--exclude规则取并集。 |
--time-range | 时间段匹配模式，仅匹配最后修改时间在该时间段内的文件。时间段格式为：time1-time2，其中time1、time2需要填写UTC时间，格式为：yyyyMMddHHmmss。 详细请参考通用选项&过滤规则文档。 |
-j, --jobs | 多文件操作时的并发数，表示有多少个文件并行传输。默认值：5，取值范围：1-10000。 1. 批量下载小文件时，可以适当调大该值，批量下载大文件时，建议先使用默认值。 2. 若未跑满预期带宽，则可适当增大该值；若出现传输超时报错，则需要适当减小该值。 3. 若该值设置的较大，建议同时将--parallel设置为较小的值（比如设置--parallel 1），以防止总并发过大。 4. 总并发计算公式= jobs * parallel。 |
--parallel | 单文件内部操作的并发任务数，表示单个大文件有多少个块并行传输。取值范围：1-10000。 1. 默认根据文件大小取不同的值，自动取值范围为1-12。 2. 下载单个大文件时，若传输速度未跑满预期带宽，可适当上调该值。 |
--checkpoint-dir | checkpoint目录的路径(默认值为:.ks3util_checkpoint)，断点续传时，操作失败KS3Util会自动创建该目录，并在该目录下记录checkpoint信息，操作成功会删除该目录。如果指定了该选项，请确保所指定的目录可以被删除。 |
--disable-crc64 | 关闭CRC64数据校验。默认情况下，KS3Util进行数据传输时都会打开CRC64校验。 |
--dry-run | 测试模式运行，不执行实际下载操作，用于验证流程的正确性。 |
--disable-temp-file | 下载文件时，将不再生成带 .temp 后缀的临时文件，而是直接创建并写入目标文件。该参数适用于将大量小文件（KB 级别）下载至 NAS 网络存储时 TPS（每秒完成数）较低的场景。 1. 启用该参数后，若任务中断或文件下载失败，会产生不完整的文件。 2. 启用该参数后，使用 3. 若关闭此参数并使用增量下载，将会依据最后修改时间跳过这些不完整的文件，因此请避免这样操作。 |
--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 local-dir/若指定了文件名，使用指定的文件名保存到本地。
./ks3util cp ks3://samplebucket/src-prefix/sample.txt local-dir/sample-file.txt示例二：下载目录。
下载目录下所有文件，包括子目录。
./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r下载目录下所有文件，并跳过已存在的文件。
当批量下载失败或需要增量下载时，可以使用-u选项跳过已存在且最后修改时间晚于源文件的文件。
./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r -u下载目录下所有文件，并设置更新规则为5（目标文件不存在或CRC64不一致则更新）。
./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r -u --update-rule 5仅下载当前目录下的文件，忽略子目录。
./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r --only-current-dir示例三：按规则匹配文件名下载
使用–include和–exclude选项选择符合条件的文件下载。
./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r --include *.jpg --exclude *screenshot*示例四：下载文件列表
使用准备：创建列表文件list.txt，假设文件列表为以下内容。
files/part01/file1
files/part01/file2Case1：下载samplebucket根目录下，且在list.txt文件列表中的文件到本地目录/root/abc/下。
./ks3util cp ks3://samplebucket/ --object-file list.txt /root/abc/ -r下载后的文件在本地的路径为：/root/abc/files/part01/file1、/root/abc/files/part01/file2。
Case2：下载samplebucket的files/part01/前缀下，且在list.txt文件列表中的文件到本地目录/root/abc/下。
./ks3util cp ks3://samplebucket/files/part01/ --object-file list.txt /root/abc/ -r下载后的文件在本地的路径为：/root/abc/file1、/root/abc/file2。
示例五：下载文件夹，测试模式运行。
./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r --dry-run示例六：下载文件时，不生成临时文件，若本地已存在同名文件，则覆盖。
./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r -f --disable-temp-file示例七：下载最后修改时间在指定范围的文件。
./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r --time-range "20241106120000-20241110120000"示例八：下载文件夹，设置扫描并发数为5，最大并发扫描深度为1。
./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r -f --list-parallel 5 --list-depth 1纯净模式