全部文档
当前文档

热搜词推荐

云服务器 虚拟私有网络 边缘节点计算 对等连接

共搜索到 0 条结果

暂无内容

如果没有找到您期望的内容，请尝试其他搜索词

文档中心

对象存储(KS3)

查看更多结果
未找到含当前关键字的文档标题
页面目录
全部展开全部收起
未找到含该关键词的产品
文档中心 对象存储(KS3) 常用工具 工具汇总 KS3Util命令行工具 对象操作 下载文件（cp）

下载文件（cp）

最近更新时间：2026-08-05 17:12:33

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>]
[--bandwidth-limit <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

使用-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

表示仅操作当前目录下的文件，忽略子目录。

--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）

可选单位：B、KB、MB、GB。

--checkpoint-dir

断点续传信息存储目录，默认值为当前工作目录下的 .ks3util_checkpoint，大文件分块传输中断后可从中断点续传。

--disable-crc64

关闭 CRC64 数据校验。默认情况下数据传输时自动开启 CRC64 校验以确保完整性。

--dry-run

测试模式运行，不执行实际下载操作，用于验证流程的正确性。

--disable-temp-file

下载文件时，将不再生成带 .temp 后缀的临时文件，而是直接创建并写入目标文件。该参数适用于将大量小文件（KB 级别）下载至 NAS 时 TPS（每秒完成数）较低的场景。

1. 启用该参数后，若任务中断或文件下载失败，会产生不完整的文件。

2. 启用该参数后，使用 -u 进行增量下载时，将始终基于 CRC64 校验已下载的文件内容。

3. 若关闭此参数并使用增量下载，将会依据最后修改时间跳过这些不完整的文件，因此请避免这样操作。

--list-parallel

扫描文件的并发数，默认值：1，取值范围：1-100。

1. 下载大量小文件到NAS时，若下载TPS较低，可尝试适当调大该值。

2. 该参数仅对存在多层子目录的源目录有效。

--list-depth

并行扫描的最大目录深度，默认值：1，取值范围：1-100。该值影响扫描策略，值越大并行扫描的目录层级越深，但不影响最终扫描到的文件总数。

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

使用示例

  1. 下载单个文件。

    • 没有指定文件名，则使用原文件名保存到本地。

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

    • 若指定了文件名，使用指定的文件名保存到本地。

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

  2. 下载目录。

    • 下载目录下所有文件，包括子目录。

      ./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

  3. 按规则匹配文件名下载。

    • 使用--include和--exclude选项选择符合条件的文件下载。

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

  4. 下载指定列表中的文件。

    • 使用准备：创建列表文件list.txt，假设为以下内容。

      data/abc/file1
data/abc/test/file2

    • 下载samplebucket的data/abc/前缀下，且在list.txt列表中的文件到本地目录/root/abc/下。

      ./ks3util cp ks3://samplebucket/data/abc/ --object-file list.txt /root/abc/ -r

      下载后的文件在本地的路径为：/root/abc/file1、/root/abc/test/file2。

  5. 下载指定列表中的目录。

    • 使用准备：创建列表文件list.txt，假设为以下内容。

      data/abc/dir1/
data/abc/test/dir2/

      目录路径需要以/符号结尾。

    • 下载samplebucket的data/abc/前缀下，且在list.txt列表中的目录到本地/root/abc/目录下。

      ./ks3util cp ks3://samplebucket/data/abc/ --object-file list.txt /root/abc/ -r

      下载后的目录在本地的路径为：/root/abc/dir1/、/root/abc/test/dir2/。

  6. 下载文件夹，测试模式运行。

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

  7. 下载文件时，不生成临时文件，若本地已存在同名文件，则覆盖。

    ./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r -f --disable-temp-file

  8. 下载最后修改时间在指定范围的文件。

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

  9. 下载文件夹，设置扫描并发数为5，最大并发扫描深度为1。

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

文档导读
上一篇：上传文件（cp）
下一篇：复制文件（cp）
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈