金山云-文档中心-对象操作

对象存储(KS3)

查看更多结果

未找到含当前关键字的文档标题

页面目录

全部展开全部收起

产品更新动态

未找到含该关键词的产品

文档中心

对象存储(KS3)

常用工具

工具汇总

KS3Util命令行工具

对象操作

最近更新时间：2025-02-25 15:35:54

概述

本文以 Linux系统为例，介绍使用 KS3Util工具的对象操作的命令和相关示例。

上传文件（cp）

cp命令可以用于将本地文件上传至KS3。

命令格式

./ks3util cp file_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>]
[--include <value>]
[--exclude <value>]
[--time-range <value>]
[-j, --jobs <value>]
[--parallel <value>]
[--checkpoint-dir <value>]
[--disable-crc64]
[--enable-symlink-dir]
[--cycle-symlink-check]
[--dry-run]

参数说明

参数	说明
file_url	本地文件或目录路径。
cloud_url	KS3文件路径，格式为ks3://bucketname/objectname。
--object-file	需上传的文件列表，内容为本地文件的绝对路径，不同文件路径之间以换行分隔。
-r, --recursive	递归进行操作。当指定该选项时，会对目录下所有符合条件的文件进行操作，否则只对路径指定的定的单个文件进行操作。
-f, --force	强制操作，不进行询问提示。当目标文件已存在，且没有使用-u选项时，会覆盖目标文件（即所有文件重传）。
-u, --update	更新操作，只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，KS3Util才会执行上传操作，否则会跳过该文件。
--bigfile-threshold	开启大文件断点续传的文件大小阈值，单位为Byte，默认值:104857600(100M)，取值范围：0-5368709120(Byte)。
--part-size	分片大小，单位为Byte，默认情况下KS3Util根据文件大小自行计算合适的分片大小值。如果有特殊需求或者需要性能调优，可以设置该值，取值范围：1-5368709120(Byte)。
--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"。该选项的值需要使用双引号包含。
--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)，断点续传时，操作失败KS3Utill会自动创建该目录，并在该目录下记录checkpoint信息，操作成功会删除该目录。如果指定了该选项，请确保所指定的目录可以被删除。
--disable-crc64	关闭CRC64数据校验。默认情况下，KS3Util进行数据传输时都会打开CRC64校验。
--enable-symlink-dir	表示允许上传软链接子目录指向的源文件。使用该参数请确保软链接无循环嵌套情况，否则可能存在数据循环上传风险。可通过`--cycle-symlink-check`参数进行上传前的软链接循环嵌套检测。
--cycle-symlink-check	表示上传之前进行软链接循环检测。
--dry-run	测试模式运行，不执行实际上传操作，用于验证流程的正确性。

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

使用示例

示例一：上传单文件，上传文件时，如果dest_prefix以/结尾，则objectKey为dest_prefix + 原文件名，否则objectKey为dest_prefix。

# 例1: 上传后的对象为ks3://samplebucket/abc/sample.txt
./ks3util cp /home/sample.txt ks3://samplebucket/abc/

# 例2: 上传后的对象为ks3://samplebucket/abc
./ks3util cp /home/sample.txt ks3://samplebucket/abc

示例二：上传文件夹，将文件夹（包括子文件夹）内的文件上传至KS3指定路径。使用-r选项时，如果指定路径不以/结尾，则会自动加上/。
```
# 例1: 假设有以下文件
# /home/logs/a.log
# /home/logs/bak/b.log
# 上传后的文件为
# ks3://samplebucket/my-files/a.log
# ks3://samplebucket/my-files/bak/b.log

./ks3util cp /home/logs/ ks3://samplebucket/my-files/ -r
```
1. 如果需要保留文件夹名，则指定路径需以文件夹名结尾。
2. 当文件夹内存在软链接子目录时，默认会把软链接子目录当成一个空文件上传，不会上传软链接子目录对应的源文件。KS3Util提供了--enable-symlink-dir参数支持上传软链接子目录指向的源文件。

示例三：上传文件夹，上传软链接子目录指向的源文件。

./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --enable-symlink-dir

示例四：上传文件夹，上传软链接子目录指向的源文件，且在上传之前进行软链接循环嵌套风险检测。
```
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --enable-symlink-dir --cycle-symlink-check
```
示例五：仅上传当前目录下的文件，忽略子目录下的文件。
```
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --only-current-dir
```
示例六：上传文件夹内的文件，并跳过已存在的文件。
批量上传失败重传时，可以指定--update（可缩写为-u）选项跳过已经上传成功的文件，实现增量上传。
```
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r -u
```

示例七：上传文件并指定读写权限ACL。

./ks3util cp sample.txt ks3://samplebucket/sample.txt --acl private

示例八：上传文件并指定存储类型。

./ks3util cp sample.txt ks3://samplebucket/sample.txt --storage-class STANDARD

示例九：上传文件并指定meta。

./ks3util cp sample.txt ks3://samplebucket/sample.txt --meta Content-Type:text/plain#Cache-Control:no-cache#X-Kss-Meta-A:a

示例十：上传文件并指定标签tagging。

./ks3util cp sample.txt ks3://samplebucket/sample.txt --tagging "a=1&b=2"

示例十一：上传符合条件的文件。
- 上传文件夹中，文件后缀包含.txt的文件。
```
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --include "*.txt"
```
  上传文件夹时，如果指定--include和--exclude选项，KS3Util会上传符合指定条件的文件。
- 上传文件夹中，文件后缀包含.txt的文件，使用正则匹配模式。
```
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --enable-regex --include ".*\.txt"
```
- 上传文件夹中，文件路径包含20240626的文件，使用正则匹配模式。
```
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --enable-regex --path-matching --include ".*20240626.*"
```
- 上传文件夹中，文件后缀包含.png，但排除文件名中有temp的文件，使用正则匹配模式。
```
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --enable-regex --include ".*\.png" --exclude ".*temp.*"
```
- 上传文件夹中，文件路径包含20240626，但排除文件后缀为.txt的文件，使用正则匹配模式。
```
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --enable-regex --path-matching --include ".*20240626.*" --exclude ".*\.txt"
```
示例十二：上传文件列表的文件。
- 使用准备：创建列表文件list.txt，假设文件列表为以下内容。
```
/root/abc/file1
/root/abc/file2
```
- Case1：上传list.txt中的文件。
```
./ks3util cp / --object-file list.txt ks3://samplebucket/prefix/ -r
```
  上传后的文件在ks3中的路径为：ks3://samplebucket/prefix/root/abc/file1、ks3://samplebucket/prefix/root/abc/file2。
- Case2：上传list.txt中的文件，去掉/root/abc/前缀。
```
./ks3util cp /root/abc/ --object-file list.txt ks3://samplebucket/prefix/ -r
```
  上传后的文件在ks3中的路径为：ks3://samplebucket/prefix/file1、ks3://samplebucket/prefix/file2。

示例十三：上传文件夹，测试模式运行。

./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --dry-run

示例十四：上传最后修改时间在指定范围的文件。

./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --time-range "20241106120000-20241110120000"

下载文件（cp）

cp命令可以用于将存储于KS3的文件下载到本地。

命令格式

./ks3util cp cloud_url file_url
[--object-file <value>]
[-r, --recursive] 
[-f, --force] 
[-u, --update]
[--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]

参数说明

参数	说明
file_url	本地文件或目录路径。
cloud_url	KS3文件路径，格式为ks3://bucketname/objectname。
--object-file	需下载的文件列表，内容为文件完整的key，不同key之间以换行分隔。
-r, --recursive	递归进行操作。当指定该选项时，会对存储空间下所有符合条件的对象进行操作，否则只对路径指定的定的单个对象进行操作。
-f, --force	强制操作，不进行询问提示。当目标文件已存在，且没有使用-u选项时，会覆盖目标文件（即所有文件重传）。
-u, --update	更新操作，只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，KS3Util才会执行下载操作，否则会跳过该文件。
--bigfile-threshold	开启大文件断点续传的文件大小阈值，单位为Byte，默认值:104857600(100M)，取值范围：0-5368709120(Byte)。
--part-size	分片大小，单位为Byte，默认情况下KS3Util根据文件大小自行计算合适的分片大小值。如果有特殊需求或者需要性能调优，可以设置该值，取值范围：1-5368709120(Byte)。
--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. 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信息，操作成功会删除该目录。如果指定了该选项，请确保所指定的目录可以被删除。
--disable-crc64	关闭CRC64数据校验。默认情况下，KS3Util进行数据传输时都会打开CRC64校验。
--dry-run	测试模式运行，不执行实际下载操作，用于验证流程的正确性。
--disable-temp-file	下载文件时不创建临时文件，而是直接下载为目标文件。若将文件下载到NAS遇到下载速度瓶颈，可尝试使用该选项。若使用该选项，执行过程中请不要中断任务，假如任务中断后需要重新执行，建议与-f参数一起使用，请勿与`-u`选项一起使用。 1. 任务中断会导致正在下载的文件未下载完成，由于不生成临时文件，若使用`-u`选项这些文件会被直接跳过，导致与ks3中文件不一致，因此请勿与`-u`选项一起使用。 2. 任务中断后重新执行，与`-f`选项时一起使用时，若目标文件已存在则会强制覆盖，即重新下载所有文件，可以保证文件一致性，推荐与该参数一起使用。缺点是已下载的文件也会被重新下载，造成额外的开销。

除上述的功能参数，关于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
```
  当批量下载失败或需要增量下载文件时，可以通过指定--update（可缩写为-u）选项选择跳过已经成功下载的文件。如果本地与KS3没有同名文件，或本地同名文件的最后修改时间早于KS3文件，KS3Util会下载该文件。如果本地已有同名文件，且文件的最后修改时间晚于KS3内文件时，KS3Util会跳过该文件。
```
./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r -u
```
- 仅下载当前目录下的文件，忽略子目录。
```
./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/file2
```
- Case1：下载list.txt中的文件。
```
./ks3util cp ks3://samplebucket/ --object-file list.txt /root/abc/ -r
```
  下载后的文件在本地的路径为：/root/abc/files/part01/file1、/root/abc/files/part01/file2。
- Case2：下载list.txt中的文件，去掉files/part01/前缀。
```
./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"

复制文件（cp）

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

命令格式

./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>]
[--include <value>]
[--exclude <value>]
[--time-range <value>]
[-j, --jobs <value>]
[--parallel <value>]
[--checkpoint-dir <value>]
[--dry-run]

参数说明

参数	说明
cloud_url	KS3文件路径，格式为ks3://bucketname/objectname。
--object-file	需复制的文件列表，内容为文件完整的key，不同key之间以换行分隔。
-r, --recursive	递归进行操作。当指定该选项时，会对源存储空间下所有符合条件的对象进行操作，否则只对路径指定的定的单个对象进行操作。
-f, --force	强制操作，不进行询问提示。当目标文件已存在，且没有使用-u选项时，会覆盖目标文件（即所有文件重传）。
-u, --update	更新操作，只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，KS3Util才会执行复制操作，否则会跳过该文件。
--bigfile-threshold	开启大文件断点续传的文件大小阈值，单位为Byte，默认值:104857600(100M)，取值范围：0-5368709120(Byte)。
--part-size	分片大小，单位为Byte，默认情况下KS3Util根据文件大小自行计算合适的分片大小值。如果有特殊需求或者需要性能调优，可以设置该值，取值范围：1-5368709120(Byte)。
--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"。若未指定，则与源文件保持一致。该选项的值需要使用双引号包含。
--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	测试模式运行，不执行实际复制操作，用于验证流程的正确性。

除上述的功能参数，关于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/ 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/file2
```
- Case1：复制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

追加上传（append）

append命令用于在已上传的追加类型文件（Appendable Object）末尾直接追加内容。当对象不存在时，使用该命令会创建新对象。

命令格式

./ks3util append local_file ks3://bucketname/objectname
[--meta <value>]

参数说明

参数	说明
local_file	本地文件完整路径。
bucketname	目标Bucket名称。
objectname	目标Object名称。追加上传时可直接将本地文件名称保留为Object名称，也可以自定义上传至Bucket后的Object名称。
--meta	设置Object的meta信息。仅支持在首次追加上传时附加此选项，例如--meta "x-kss-acl:public-read#x-kss-meta-key1:value1"。 Object的meta信息配置完成后，您可以通过set-meta（管理文件元信息）命令修改Object的meta信息。

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

使用示例

将本地文件sample.txt首次追加上传至目标存储空间samplebucket，并设置meta信息。

./ks3util append sample.txt ks3://samplebucket/sampleobject.txt --meta "x-kss-acl:public-read#x-kss-meta-key1:value1"

以下输出结果表明sample.txt已追加上传至目标Bucket，此时文件大小为25.28MB。

Succeed: The local file size: 25.28MB, The object original size: 0.00B, The object new size: 25.28MB

平均速度：3.32MB/s

7.799511(s) elapsed

在sampleobject.txt文件末尾追加文件sample2.txt的内容。
```
./ks3util append sample2.txt ks3://samplebucket/sampleobject.txt
```
以下输出结果已在sampleobject.txt文件后追加了内容，此时文件大小为55.74MB。
```
Succeed: The local file size: 30.46MB, The object original size: 25.28MB, The object new size: 55.74MB

平均速度：3.37MB/s

9.230269(s) elapsed
```
如果需要在sampleobject.txt文件末尾多次追加内容，请替换示例中的待追加上传文件再执行命令。

列举碎片（listpart）

listpart命令用于列举未完成分块上传的Object包含的碎片（Part）信息。

命令格式

./ks3util listpart ks3://bucketname/objectname uploadId

参数说明

参数	说明
bucketname	目标桶名称。
objectname	未完成分块上传操作的对象名称。
uploadId	初始化Multipart Upload事件时返回的KS3服务器创建的全局唯一的Upload ID，用于标识本次Multipart Upload事件。您可以通过Upload ID进行Multipart Upload的中止或查询等操作。

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

使用示例

列举目标存储空间examplebucket下未完成分块上传的文件exampleobject.txt包含的碎片信息。

./ks3util listpart ks3://examplebucket/exampleobject 655d52aa954e4ea1b7556fad6247****

以下返回结果表明已成功获取exampleobject文件的碎片对应的Number、ETag值、碎片大小、碎片的最后修改时间等信息。

PartNumber       Etag           Size(Byte)        LastModifyTime
3                         ***            5242880           2024-01-04 14:24:14
4                         ***            5242880           2024-01-04 14:24:19
5                         ***            5242880           2024-01-04 14:24:14
7                         ***            5242880           2024-01-04 14:24:34
total part count: 4      total part size(MB): 20

0.202618(s) elapsed

删除文件/碎片（rm）

rm用于删除存储在KS3存储桶内的文件或者碎片。

删除后无法恢复，请谨慎操作！

命令格式

./ks3util rm ks3://bucketname[/prefix]
[-r, --recursive] 
[-f, --force] 
[-b, --bucket]
[-m, --multipart]
[-a, --all-type]
[--include <value>]
[--exclude <value>]
[--time-range <value>]
[--only-current-dir]
[--retention]
[--retention-id <value>]

参数说明

参数	说明
bucketname	操作的桶名。
prefix	操作的对象的前缀。
-r, --recursive	递归进行操作。当指定该选项时，会对存储空间下所有符合条件的对象进行操作，否则只对路径指定的定的单个对象进行操作。
-f, --force	强制操作，不进行询问提示。
-b, --bucket	对Bucket进行操作，该选项用于确认操作作用于Bucket。
-m, --multipart	指定操作的对象为Bucket中未完成的Multipart事件，而非默认情况下的Object。
-a, --all-type	指定操作的对象为Bucket中符合prefix条件的Object和未完成的Multipart事件。
--include	包含对象匹配模式，满足匹配规则的文件将会被选中，如：*.jpg。该选项可以出现多次，多个--include规则取并集。
--exclude	不包含对象匹配模式，满足匹配规则的文件将会被排除，如：*.txt。该选项可以出现多次，多个--exclude规则取并集。。
--time-range	时间段匹配模式，仅匹配最后修改时间在该时间段内的文件。时间段格式为：time1-time2，其中time1、time2需要填写UTC时间，格式为：yyyyMMddHHmmss。详细请参考通用选项&过滤规则文档。
--only-current-dir	表示仅操作当前目录下的文件，忽略子目录。
--retention	表示删除回收站中全部版本的对象。
--retention-id	指定回收站内被删除对象的retentionId，表示删除指定版本的对象。该参数不支持与--retention同时使用。

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

使用示例

a.删除文件

示例一：删除单个文件。

./ks3util rm ks3://samplebucket/src-prefix/sample.txt

示例二：批量删除文件。
- 删除指定前缀的文件。
```
./ks3util rm ks3://samplebucket/src-prefix/ -r
```
- 按匹配条件删除。
```
./ks3util rm ks3://samplebucket/src-prefix/ -r --include *screenshot* --exclude *important*
```
- 按指定列表文件进行删除。
```
./ks3util rm ks3://samplebucket/ --object-file object_keys_file
```
  注：object_keys_file为本地.txt文件的路径，文件内填写指定Object列表，每个objectKey为一行（不包含ks3://bucket/ 部分）。
示例三：删除指定目录下的文件，不递归子目录。
```
./ks3util rm ks3://samplebucket/abc/ -r --only-current-dir
```

示例四：删除回收站内文件。

指定文件的指定版本。

./ks3util rm ks3://bucketname/sample.txt --retention-id xxxxxx

指定文件的全部版本。

./ks3util rm ks3://bucketname/sample.txt --retention

删除回收站内指定前缀的所有文件的所有版本。
```
./ks3util rm ks3://bucketname/abc --retention -r
```

删除最后修改时间在指定范围的文件。

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

b.删除碎片

示例一：删除单文件碎片。
- 删除单个文件未完成的Multipart事件产生的Part。
```
./ks3util rm ks3://samplebucket/src-prefix/sample.txt -m
```
- 删除单个文件、以及未完成的Multipart事件所产生的Part。
```
./ks3util rm ks3://samplebucket/src-prefix/sample.txt -a
```
示例二：删除指定前缀文件碎片。
- 删除指定前缀的所有文件未完成的Multipart事件产生的Part。
```
./ks3util rm ks3://samplebucket/src-prefix/ -m -r
```
- 删除指定前缀的所有文件、以及未完成的Multipart事件所产生的Part。
```
./ks3util rm ks3://samplebucket/src-prefix/ -a -r
```
- 删除匹配条件的文件未完成的Multipart事件产生的Part。
```
./ks3util rm ks3://samplebucket/src-prefix/ -m -r --include *screenshot* --exclude *important*
```
- 删除匹配条件的文件、以及未完成的Multipart事件产生的Part。
```
./ks3util rm ks3://samplebucket/src-prefix/ -a -r --include *screenshot* --exclude *important*
```

移动文件（mv）

mv命令可用于将存储在KS3的文件移动到同Bucket的其他目录，或同区域的其他Bucket内。

命令格式

./ks3util mv 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>]
[--include <value>]
[--exclude <value>]
[--time-range <value>]
[-j, --jobs <value>]
[--parallel <value>]
[--checkpoint-dir <value>]
[--dry-run]

参数说明

参数	说明
cloud_url	KS3文件路径，格式为ks3://bucketname/objectname。
--object-file	需移动的文件列表，内容为文件完整的key，不同key之间以换行分隔。
-r, --recursive	递归进行操作。当指定该选项时，会对源存储空间下所有符合条件的对象进行操作，否则只对路径指定的定的单个对象进行操作。
-f, --force	强制操作，不进行询问提示。当目标文件已存在，且没有使用-u选项时，会覆盖目标文件（即所有文件重传）。
-u, --update	更新操作，只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，KS3Util才会执行移动操作，否则会跳过该文件。
--bigfile-threshold	开启大文件断点续传的文件大小阈值，单位为Byte，默认值:104857600(100M)，取值范围：0-5368709120(Byte)。
--part-size	分片大小，单位为Byte，默认情况下KS3Util根据文件大小自行计算合适的分片大小值。如果有特殊需求或者需要性能调优，可以设置该值，取值范围：1-5368709120(Byte)。
--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"。若未指定，则与源文件保持一致。该选项的值需要使用双引号包含。
--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	测试模式运行，不执行实际移动操作，用于验证流程的正确性。

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

使用示例

示例一：移动单个文件。

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

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

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

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

示例二：按目录移动。
- 移动目录下所有文件，包括子目录。
```
./ks3util mv ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r
```
- 当批量移动失败或需要增量移动时，可以使用--update（可缩写为-u）选项跳过已存在且最后修改时间晚于原文件的文件。
```
./ks3util mv ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r -u
```
- 仅移动当前目录下的文件，忽略子目录。
```
./ks3util mv ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --only-current-dir
```

示例三：按条件移动。

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

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

移动文件并修改文件读写权限ACL。

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

移动文件并修改文件读存储类型。

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

移动文件并修改文件标签。

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

移动文件并修改文件meta。

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

示例四：移动最后修改时间在指定范围的文件。

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

示例五：按照文件列表移动。
- 使用准备：创建列表文件list.txt，假设文件列表为以下内容。
```
files/part01/file1
files/part01/file2
```
- Case1：移动list.txt中的文件。
```
./ks3util mv 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 mv ks3://samplebucket/files/part01/ --object-file list.txt ks3://samplebucket2/prefix/ -r
```
  移动后的文件在ks3中的路径为：ks3://samplebucket2/prefix/file1、ks3://samplebucket2/prefix/file2。

示例六：移动文件夹，测试模式运行。

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

创建目录（mkdir）

mkdir命令用于在Bucket中创建目录。

命令格式

./ks3util mkdir ks3://bucketname/dir_name

参数说明

参数	说明
bucketname	目标Bucket名称。
dir_name	创建的目录名称。目录名称须以正斜线（/）结尾。若未添加正斜线（/），KS3Util会在目录末尾自动添加。

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

使用示例

创建单级目录。

./ks3util mkdir ks3://samplebucket/sampledir/

创建多级目录。
```
./ks3util mkdir ks3://samplebucket/sampledir/subdir/
```
如果删除了subdir/目录，且上一级目录sampledir/下文件个数为0，则sampledir/目录也会被自动移除。

设置ACL规则（set-acl）

set-acl命令用于设置Object的读写权限ACL。

命令格式

./ks3util set-acl ks3://bucketname[/prefix] <acl>
[-r, --recursive]
[-f, --force]
[-b, --bucket]
[--include <value>]
[--exclude <value>]
[--time-range <value>]
[-j, --jobs]

参数说明

参数	说明
bucketname	操作的桶名。
prefix	操作的对象的前缀。
acl	读写权限ACL，可选值：private，public-read。
-r, --recursive	递归进行操作。当指定该选项时，会对存储空间下所有符合条件的对象进行操作，否则只对路径指定的定的单个对象进行操作。
-f, --force	强制操作，不进行询问提示。
-b, --bucket	对Bucket进行操作，该选项用于确认操作作用于Bucket。
--include	包含对象匹配模式，满足匹配规则的文件将会被选中，如：*.jpg。该选项可以出现多次，多个--include规则取并集。
--exclude	不包含对象匹配模式，满足匹配规则的文件将会被排除，如：*.txt。该选项可以出现多次，多个--exclude规则取并集。
--time-range	时间段匹配模式，仅匹配最后修改时间在该时间段内的文件。时间段格式为：time1-time2，其中time1、time2需要填写UTC时间，格式为：yyyyMMddHHmmss。详细请参考通用选项&过滤规则文档。
-j, --jobs	多文件操作时的并发任务数，默认值：5，取值范围：1-10000。 Util2.9.0版本默认值由3改为5。

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

使用示例

示例一：给单个文件设置acl。

./ks3util set-acl ks3://samplebucket/src-prefix/sample.txt private

示例二：批量设置acl。
- 批量给指定前缀的文件设置acl。
```
./ks3util set-acl ks3://samplebucket/src-prefix/ private -r
```
- 批量给符合匹配规则的文件设置acl。
```
./ks3util set-acl ks3://samplebucket/src-prefix/ private -r --include *screenshot* --exclude *important*
```
- 批量给指定列表文件设置acl。
```
./ks3util set-acl ks3://samplebucket/ public-read --object-file object_keys_file
```
  object_keys_file为本地.txt文件的路径，文件内填写指定Object列表，每个objectKey为一行（不包含ks3://bucket/ 部分）。

示例三：批量给最后修改时间在指定范围的文件设置acl。

./ks3util set-acl ks3://samplebucket/src-prefix/ private -r --time-range "20241106120000-20241110120000"

管理文件元信息（set-meta）

文件元信息是对文件（Object）的属性描述，包括HTTP标准属性（HTTP Header）和用户自定义元数据（User Meta）两种。其中，HTTP Header可用于自定义HTTP请求的策略，用户自定义元数据可用于标识文件的用途或属性等。可以通过set-meta命令为已上传的文件（Object）设置、修改或者删除文件元信息。

命令格式

./ks3util set-meta ks3://bucketname[/prefix] <meta>
[-r, --recursive]
[-f, --force]
[-u, --update]
[--delete]
[--include <value>]
[--exclude <value>]
[--time-range <value>]
[-j, --jobs]

参数说明

参数	说明
bucketname	操作的桶名。
prefix	操作的对象的前缀。
meta	文件元信息，格式：header:value#header:value。header不区分大小写，但value区分大小写。
-r, --recursive	递归进行操作。当指定该选项时，会对存储空间下所有符合条件的对象进行操作，否则只对路径指定的定的单个对象进行操作。
-f, --force	强制操作，不进行询问提示。
-u, --update	更新操作。
--delete	删除指定的元信息。
--include	包含对象匹配模式，满足匹配规则的文件将会被选中，如：*.jpg。该选项可以出现多次，多个--include规则取并集。
--exclude	不包含对象匹配模式，满足匹配规则的文件将会被排除，如：*.txt。该选项可以出现多次，多个--exclude规则取并集。
--time-range	时间段匹配模式，仅匹配最后修改时间在该时间段内的文件。时间段格式为：time1-time2，其中time1、time2需要填写UTC时间，格式为：yyyyMMddHHmmss。详细请参考通用选项&过滤规则文档。
-j, --jobs	多文件操作时的并发任务数，默认值：5，取值范围：1-10000。 Util2.9.0版本默认值由3改为5。

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

可选的header列表如下：

Expires

Content-Type

Cache-Control

Content-Encoding

Content-Disposition

以X-Kss-Meta-开头的header（不区分大小写）

使用示例

示例一：设置全量值meta。
如果用户未指定 --update选项和 --delete选项，KS3Util会设置指定Objects的meta为用户输入的[header:value#header:value…]。
当缺失某个meta信息时，相当于删除meta信息（对于不可删除的headers，即：不以X-Kss-Meta-开头的headers，其值不会改变）。
- 给单个文件设置meta。
```
./ks3util set-meta ks3://samplebucket/src-prefix/sample.txt Cache-Control:no-cache#X-Kss-Meta-A:1
```
- 给指定前缀的所有文件设置meta。
```
./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#X-Kss-Meta-A:1 -r
```
- 给匹配条件的所有文件设置meta。
```
./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#X-Kss-Meta-A:1 -r --include *.jpg --exclude screenshot*
```
- 给指定列表文件设置meta。
```
./ks3util set-meta ks3://samplebucket/ Cache-Control:no-cache#X-Kss-Meta-A --object-file object_keys_file
```
  object_keys_file为本地.txt文件的路径，文件内填写指定Object列表，每个objectKey为一行（不包含ks3://bucket/ 部分）。
- 给最后修改时间在指定范围的文件设置meta。
```
./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#X-Kss-Meta-A:1 -r --time-range "20241106120000-20241110120000"
```
示例二：更新文件meta。
如果用户设置--update选项，KS3Util会更新指定Objects的指定header为输入的value值，value值不可以为空。未指定的header的value值不会改变。此时不支持--delete选项。
- 给单个文件更新meta。
```
./ks3util set-meta ks3://samplebucket/src-prefix/sample.txt Cache-Control:no-cache#X-Kss-Meta-A:1 -u
```
- 给指定前缀的所有文件更新meta。
```
./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#X-Kss-Meta-A:1 -r -u
```
- 给匹配条件的所有文件更新meta。
```
./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#X-Kss-Meta-A:1 -r -u --include *.jpg --exclude screenshot*
```
- 给指定列表文件更新meta。
```
./ks3util set-meta ks3://samplebucket/ Cache-Control:no-cache#X-Kss-Meta-A --object-file object_keys_file -u
```
  object_keys_file为本地.txt文件的路径，文件内填写指定Object列表，每个objectKey为一行（不包含ks3://bucket/ 部分）。
- 给最后修改时间在指定范围的文件更新meta。
```
./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#X-Kss-Meta-A:1 -r -u --time-range "20241106120000-20241110120000"
```
示例三：删除meta。
如果用户设置--delete选项，KS3Util会删除指定Objects的指定header（不用指定value值，指定了的value值都会被忽略；对于不可删除的headers，即：不以X-Kss-Meta-开头的headers，该选项不起作用）。此时不支持--update选项。
- 单个文件删除meta。
```
./ks3util set-meta ks3://samplebucket/src-prefix/sample.txt X-Kss-Meta-A --delete
```
- 给指定前缀的所有文件删除meta。
```
./ks3util set-meta ks3://samplebucket/src-prefix/ X-Kss-Meta-A --delete
```
- 给匹配条件的所有文件删除meta。
```
./ks3util set-meta ks3://samplebucket/src-prefix/ X-Kss-Meta-A -r --delete --include *.jpg --exclude screenshot*
```
- 给指定列表文件删除meta。
```
./ks3util set-meta ks3://samplebucket/ X-Kss-Meta-A --object-file object_keys_file --delete
```
  object_keys_file为本地.txt文件的路径，文件内填写指定Object列表，每个objectKey为一行（不包含ks3://bucket/ 部分）。
- 给最后修改时间在指定范围的文件删除meta。
```
./ks3util set-meta ks3://samplebucket/src-prefix/ X-Kss-Meta-A --delete --time-range "20241106120000-20241110120000"
```

同步目录（sync）

该命令用于将本地文件目录或者ks3 prefix从源端同步到目的端。

不支持本地目录之间的同步。

该命令和cp命令类似：支持从本地文件系统上传文件到ks3，从ks3下载Object到本地文件系统，在ks3上进行Object拷贝；用于源端和目的端数据同步。

sync命令和cp命令不同之处如下：

当输入--delete选项时，该命令会自动删除目的端存在而源端不存在的Object或者移走本地文件。如果目的端是ks3，则会删除多余的Object；如果目的端是本地文件，则会移走本地多余的文件。
警告：在没有完全搞清楚sync命令的行为之前，请慎用--delete
sync强制是以recursive方式遍历文件或者Object的，所以不用输入-r --recursive。
当源端是ks3://bucket/prefix，sync命令会自动在prefix后面加上字符 ‘/’，但是cp命令不会。当目的端是ks3://bucket/prefix，sync命令会在prefix后面加上字符 ‘/’；cp命令在–recursive被输入时也会在prefix后面加上字符’/’。

--delete选项
表示需要删除或者移走目的端存在而源端不存在的Object或者文件。

--backup-dir选项
该选项表示从ks3同步到本地目录时，用于备份目的端文件的目录，不能是目的端目录的子目录，如果输入了--delete，该选项必须输入。

其他选项说明、用法和cp命令相同。

命令格式

# 将本地目录同步到ks3 prefix
ks3util sync local_dir ks3://bucketname[/prefix] 
[-f] 
[-u] 
[--delete] 
[--backup-dir]
[--disable-crc64]
[--dry-run]
[--disable-temp-file]

参数说明

参数	说明
local_dir	本地目录。
bucketname	操作的桶名。
prefix	操作的对象前缀。
-f, --force	强制操作，不进行询问提示。
-u, --update	更新操作，只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，KS3Util才会执行上传操作。
--delete	表示需要删除或者移走目的端存在而源端不存在的Object或者文件。
--backup-dir	从ks3同步到本地目录时，用于备份目的端文件的目录，不能是目的端目录的子目录，如果输入了--delete，该选项必须输入。
--disable-crc64	关闭CRC64数据校验。默认情况下，KS3Util进行数据传输时都会打开CRC64校验。
--dry-run	测试模式运行，不执行实际操作，用于验证流程的正确性。
--disable-temp-file	下载文件时不创建临时文件，而是直接下载为目标文件。若将文件下载到NAS遇到下载速度瓶颈，可尝试使用该选项。若使用该选项，执行过程中请不要中断任务，假如任务中断后需要重新执行，建议与`-f`参数一起使用，请勿与`-u`选项一起使用。 1. 任务中断会导致正在下载的文件未下载完成，由于不生成临时文件，若使用`-u`选项这些文件会被直接跳过，导致与ks3中文件不一致。因此请勿与-u选项一起使用。 2. 任务中断后重新执行，与`-f`选项时一起使用时，若目标文件已存在则会强制覆盖，即重新下载所有文件，可以保证文件一致性，推荐与该参数一起使用。缺点是已下载的文件也会被重新下载，造成额外的开销。

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

使用示例

示例一：从本地目录同步到ks3。

./ks3util sync ./test_dir ks3://samplebucket/test_sync/ -u -f

# 同步并删除ks3上多余的文件
./ks3util sync ./test_dir ks3://samplebucket/test_sync/ -u -f --delete

示例二：从ks3同步到本地目录。

./ks3util sync ks3://samplebucket/test_sync/ ./test_dir -u -f

# 同步并移动本地目录多余的文件到./backup目录
./ks3util sync ks3://samplebucket/test_sync/ ./test_dir -u -f --delete --backup-dir ./backup

示例三：从ks3同步到ks3。

./ks3util sync ks3://samplebucket/test_sync/ ks3://samplebucket/test_sync_2/ -u -f

# 同步并删除目的端上多余的文件
./ks3util sync ks3://samplebucket/test_sync/ ks3://samplebucket/test_sync_2/ -u -f --delete

示例四：从本地目录同步到ks3，测试模式运行。

./ks3util sync ./test_dir ks3://samplebucket/test_sync/ -u -f --dry-run

示例五：从ks3同步到本地目录，不生成临时文件，若本地已存在同名文件，则覆盖。
```
./ks3util sync ks3://samplebucket/test_sync/ ./test_dir -u -f --disable-temp-file
```

解冻文件（restore）

restore命令用于解冻归档存储类型的文件。有关解冻规则的更多详情请参见文档：Restore Object。

命令格式

./ks3util restore ks3://bucketname[/prefix]
[-r, --recursive]
[-f, --force]
[--include <value>]
[--exclude <value>]
[--time-range <value>]
[-j, --jobs]
[--days <value>]

参数说明

参数	说明
bucketname	操作的桶名。
prefix	操作的对象的前缀。
-r, --recursive	递归进行操作。当指定该选项时，会对存储空间下所有符合条件的对象进行操作，否则只对路径指定的定的单个对象进行操作。
-f, --force	强制操作，不进行询问提示。
--include	包含对象匹配模式，满足匹配规则的文件将会被选中，如：*.jpg。该选项可以出现多次，多个--include规则取并集。
--exclude	不包含对象匹配模式，满足匹配规则的文件将会被排除，如：*.txt。该选项可以出现多次，多个-exclude规则取并集。
--time-range	时间段匹配模式，仅匹配最后修改时间在该时间段内的文件。时间段格式为：time1-time2，其中time1、time2需要填写UTC时间，格式为：yyyyMMddHHmmss。详细请参考通用选项&过滤规则文档。
-j, --jobs	多文件操作时的并发任务数，默认值：5，取值范围：1-10000。 Util2.9.0版本默认值由3改为5。
--days	表示解冻归档存储类型对象持续时间，当不加该参数时，表示解冻时间为1天。单位：天，默认值：1，取值范围：1-7。

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

使用示例

示例一：给单个文件解冻，并设置解冻天数为7天。

./ks3util restore ks3://samplebucket/src-prefix/sample.txt --days 7

示例二：批量给指定前缀的文件解冻，并设置解冻天数为7天。
```
./ks3util restore ks3://samplebucket/src-prefix/ -r --days 7
```

示例三：批量给符合匹配规则的文件解冻。

./ks3util restore ks3://samplebucket/src-prefix/  -r  --days 7 --include *screenshot* --exclude *important*

示例四：批量给最后修改时间在指定范围的文件解冻。

./ks3util restore ks3://samplebucket/src-prefix/ -r --days 7 --time-range "20241106120000-20241110120000"

示例五：给指定列表文件解冻。
```
./ks3util restore ks3://samplebucket/ --object-file object_keys_file
```
object_keys_file为本地.txt文件的路径，文件内填写指定Object列表，每个objectKey为一行（不包含ks3://bucket/ 部分）。

设置文件存储类型（set-stroage-class）

该命令用于设置指定Objects的存储类型信息。

命令格式

./ks3util set-storage-class ks3://bucketname/object-key <storage-class> 
[-r] 
[-f] 
[--include <patten>]
[--exclude <patten>]
[--time-range <value>]

参数说明

参数	说明
-r, --recursive	递归进行操作。当指定该选项时，会对存储空间下所有符合条件的对象进行操作，否则只对路径指定的定的单个对象进行操作。
-f, --force	强制操作，不进行询问提示。
--include	包含对象匹配模式，满足匹配规则的文件将会被选中，如：*.jpg。该选项可以出现多次，多个--include规则取并集。
--exclude	不包含对象匹配模式，满足匹配规则的文件将会被排除，如：*.txt。该选项可以出现多次，多个--exclude规则取并集。
--time-range	时间段匹配模式，仅匹配最后修改时间在该时间段内的文件。时间段格式为：time1-time2，其中time1、time2需要填写UTC时间，格式为：yyyyMMddHHmmss。详细请参考通用选项&过滤规则文档。

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

使用示例

示例一：设置单个文件的存储类型。

./ks3util set-storage-class ks3://samplebucket/test-file STANDARD_IA

示例二：批量设置文件的存储类型。

./ks3util set-storage-class ks3://samplebucket/logs/ STANDARD_IA -r -f

示例三：批量设置最后修改时间在指定范围的文件的存储类型。

./ks3util set-storage-class ks3://samplebucket/logs/ STANDARD_IA -r -f --time-range "20241106120000-20241110120000"

示例四：设置指定列表文件的存储类型。
```
./ks3util set-storage-class ks3://samplebucket/ STANDARD_IA --object-file object_keys_file -f
```
object_keys_file为本地.txt文件的路径，文件内填写指定Object列表，每个objectKey为一行（不包含ks3://bucket/ 部分）。

查看文件信息（stat）

stat命令用于查看指定对象（Object）的相关信息，可以通过该命令查看Object元信息。

命令格式

./ks3util stat ks3://bucketname/objectname

参数说明

参数	说明
bucketname	目标Bucket名称。
objectname	目标Object名称。

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

使用示例

示例一：查看Object的信息。

./ks3util stat ks3://samplebucket/objectname

响应内容如下：

ACL                                         : private
Accept-Ranges                       : bytes
Content-Length                      : 10240
Content-Md5                          : t4oxPaDQPOIUDtXulemwgw==
Content-Type                          : application/octet-stream
Content-Encoding                   :
Content-Disposition                :
Cache-Control                         :
Expires                                     :
Etag                                         : b78a313da0d03ce2140ed5ee95e9b083
Last-Modified                          : Fri, 22 Nov 2024 07:03:42 GMT
X-Kss-Checksum-Crc64ecma  : 7168165721704423945
Owner                                      : 123456
X-Kss-Storage-Class                : STANDARD
X-Kss-Tagging-Count              :
X-Kss-Server-Side-Encryption :

0.211489(s) elapsed

对象标签（set-tag）

该命令可设置、更新、删除指定Objects的tagging信息。

tagging的key和value区分大小写。

命令格式

./ks3util set-tag ks3://bucketname[/prefix] <tagging> [-r] [f]
[--update] 
[--delete] 
[--include <patten>]
[--exclude <patten>]
[--time-range <value>]
[-j, --jobs <num>]

参数说明

参数	说明
bucketname	操作的桶名。
prefix	操作的对象的名称或前缀。
-r, --recursive	递归进行操作。当指定该选项时，会对存储空间下所有符合条件的对象进行操作，否则只对路径指定的定的单个对象进行操作。
-f, --force	强制操作，不进行询问提示。
-u, --update	更新操作。
--delete	删除所有tagging。
--include	包含对象匹配模式，满足匹配规则的文件将会被选中，如：*.jpg。该选项可以出现多次，多个--include规则取并集。
--exclude	不包含对象匹配模式，满足匹配规则的文件将会被排除，如：*.txt。该选项可以出现多次，多个--exclude规则取并集。
--time-range	时间段匹配模式，仅匹配最后修改时间在该时间段内的文件。时间段格式为：time1-time2，其中time1、time2需要填写UTC时间，格式为：yyyyMMddHHmmss。详细请参考通用选项&过滤规则文档。
-j, --jobs	多文件操作时的并发任务数，默认值：5，取值范围：1-10000。 Util2.9.0版本默认值由3改为5。

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

使用示例

示例一：设置标签。
如果用户未指定--update选项和--delete选项，KS3Util会设置指定Objects的tagging为用户输入的"tag=value&tag=value"。
- 设置单个文件的标签。
```
./ks3util set-tag ks3://samplebucket/test-files/sample.txt "belongs=kevin&test-file=true"
```
- 设置指定前缀的所有文件的标签。
```
./ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r
```
- 设置匹配条件的文件的标签。
```
./ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r --include *.log --exclude tom-*
```
- 设置最后修改时间在指定范围的文件的标签。
```
./ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r --time-range "20241106120000-20241110120000"
```
- 设置指定列表文件的标签。
```
./ks3util set-tag ks3://samplebucket/ "belongs=kevin&test-file=true" --object-file object_keys_file
```
  object_keys_file为本地.txt文件的路径，文件内填写指定Object列表，每个objectKey为一行（不包含ks3://bucket/ 部分）。
示例二：更新标签。
如果用户设置--update选项，KS3Util会更新指定Objects的指定tagging为输入的value值，value值不可以为空，指定Objects的其他tagging信息不会改变。此时不支持--delete选项。
- 更新单个文件的标签。
```
./ks3util set-tag ks3://samplebucket/test-files/sample.txt "belongs=kevin&test-file=true" --update
```
- 更新指定前缀的所有文件的标签。
```
./ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r --update 
```
- 更新匹配条件的文件的标签。
```
./ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r --include *.log --exclude tom-* --update
```
- 更新最后修改时间在指定范围的文件的标签。
```
./ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r --update --time-range "20241106120000-20241110120000"
```
- 更新指定列表文件的标签。
```
./ks3util set-tag ks3://samplebucket/ "belongs=kevin&test-file=true" --object-file object_keys_file --update
```
  object_keys_file为本地.txt文件的路径，文件内填写指定Object列表，每个objectKey为一行（不包含ks3://bucket/ 部分）。
示例三：删除标签。
如果用户设置--delete选项，KS3Util会删除所有标签。此时不支持--update选项。
- 删除单个文件的标签。
```
./ks3util set-tag ks3://samplebucket/test-files/sample.txt  --delete
```
- 删除指定前缀的所有文件的标签。
```
./ks3util set-tag ks3://samplebucket/test-files/ -r --delete
```
- 删除匹配条件的文件的标签。
```
./ks3util set-tag ks3://samplebucket/test-files/  -r --include *.log --exclude tom-* --delete
```
- 删除最后修改时间在指定范围的文件的标签。
```
./ks3util set-tag ks3://samplebucket/test-files/ -r --delete --time-range "20241106120000-20241110120000"
```
- 删除指定列表文件的标签。
```
./ks3util set-tag ks3://samplebucket/  --object-file object_keys_file --delete
```
  object_keys_file为本地.txt文件的路径，文件内填写指定Object列表，每个objectKey为一行（不包含ks3://bucket/ 部分）。

标准输出流（cat）

cat命令可以将ks3的Object内容输出到标准输出流，Object内容是文本格式比较好。

命令格式

ks3util cat ks3://bucketname/objectKey

参数说明

参数	说明
bucketname	操作的桶名。
objectKey	操作的对象名。

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

使用示例

输出到标准输出。

ks3util cat ks3://samplebucket/ks3log_samplebucket_2023_01_01.log

与管道一起使用（Linux、MacOS）。

ks3util cat ks3://samplebucket/ks3log_samplebucket_2023_01_01.log | grep 'REST.DELETE.OBJECT'

流式上传（rcat）

rcat命令用于流式上传文件，需与管道配合使用，如果ks3上已存在同名文件，则会覆盖。

命令格式

./ks3util rcat ks3://bucketname/objectKey 
[--storage-class <value>]
[--acl <acl>] 
[--meta <meta>] 
[--tagging <tagging>] 
[-j, --jobs <job-num>] 
[--part-size <part-size>]
[--disable-crc64]

参数说明

参数	说明
bucketname	操作的桶名
objectKey	操作的对象名。
--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"。该选项的值需要使用双引号包含。
-j, --jobs	多文件操作时的并发任务数，默认值：5，取值范围：1-10000。 Util2.9.0版本默认值由3改为5。
--part-size	分片大小，单位为Byte，默认情况下KS3Util根据文件大小自行计算合适的分片大小值。如果有特殊需求或者需要性能调优，可以设置该值，取值范围：1-5368709120(Byte)。
--disable-crc64	关闭CRC64数据校验。默认情况下，KS3Util进行数据传输时都会打开CRC64校验。

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

使用示例

流式上传文件。

grep 'REST.DELETE.OBJECT' ks3log_samplebucket_2023_01_01.log | ks3util rcat ks3://samplebucket/delete-object.log

流式上传文件并设置ACL等。

grep 'REST.DELETE.OBJECT' ks3log_samplebucket_2023_01_01.log | ks3util rcat ks3://samplebucket/delete-object.log --acl public-read --storage-class STANDARD_IA --meta Content-Type:text/plain#X-Kss-Meta-belongs:kevin --tagging "log-file=true&test-file=true" -j 10 --part-size 5242880

生成上传或者下载链接（sign）

sign命令用于该命令签名用户指定的cloud_url，生成经过签名的url可供第三方用户访问Object。

命令格式

./ks3util sign ks3://bucketname[/prefix]
[-r, --recursive]
[-f, --force]
[--include <value>]
[--exclude <value>]
[--timeout <value>]
[--sign-method <value>]
[--network-type <value>]

参数说明

参数	说明
bucketname	操作的桶名。
prefix	操作的对象的前缀。
-r, --recursive	递归进行操作。当指定该选项时，会对存储空间下所有符合条件的对象进行操作，否则只对路径指定的定的单个对象进行操作。
-f, --force	强制操作，不进行询问提示。
--include	包含对象匹配模式，满足匹配规则的文件将会被选中，如：*.jpg。该选项可以出现多次，多个--include规则取并集。
--exclude	不包含对象匹配模式，满足匹配规则的文件将会被排除，如：*.txt。该选项可以出现多次，多个--exclude规则取并集。
--timeout	外链过期时间，默认值：10(单位秒) 。
--sign-method	生成下载链接或者上传链接，默认值：get，可选值为 get 、put。
--network-type	生成指定网络类型的链接，默认值：无，可选值：internal 、external。internal表示生成内网链接，external表示生成外网链接。

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

使用示例

生成下载链接，单个签名默认 ‘GET’。

./ks3util sign ks3://samplebucket/src-prefix/sample.txt

过期时间为签名时间+timeout时间。60秒后签名过期。

./ks3util sign ks3://samplebucket/src-prefix/sample.txt --timeout 60

生成上传链接。

./ks3util sign ks3://samplebucket/src-prefix/ -r --sign-method=PUT

批量签名目录。

./ks3util sign ks3://samplebucket/src-prefix/ -r

批量给符合匹配规则的文件签名。

./ks3util sign ks3://samplebucket/src-prefix -r --include *.txt

生成内网链接。

./ks3util sign ks3://samplebucket/src-prefix/sample.txt --network-type internal

生成外网链接。

./ks3util sign ks3://samplebucket/src-prefix/sample.txt --network-type external

恢复回收站内文件（recover）

recover命令用于恢复Bucket回收站中的文件。有关恢复规则的更多详情请参见文档：Recover Object。

命令格式

./ks3util recover ks3://bucketname[/prefix]
[-r, --recursive]
[-f, --force]
[--retention-id <value>]
[--retention-overwrite]
[--include <value>]
[--exclude <value>]
[-j, --jobs]

参数说明

配置项	说明
bucketname	操作的桶名。
prefix	操作的对象的前缀。
-r, --recursive	递归进行操作。当指定该选项时，会恢复存储空间下所有符合条件的对象为最近的版本，否则只恢复路径指定的单个对象为最近的版本。该选项不能与--retention-id同时使用。
--retention-id	指定被恢复Object的删除ID。当不带该选项时，默认只恢复最新的一个版本。
--retention-overwrite	从回收站内被恢复的Object在Bucket中存在同名Object时，是否支持覆盖。当取值为true时表示覆盖，Bucket内被覆盖的Object会进入回收站。
--include	包含对象匹配模式，满足匹配规则的文件将会被选中，如：*.jpg。该选项可以出现多次，多个--include规则取并集。
--exclude	不包含对象匹配模式，满足匹配规则的文件将会被排除，如：*.txt。该选项可以出现多次，多个--exclude规则取并集。
-j, --jobs	多文件操作时的并发任务数，默认值：5，取值范围：1-10000。

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

使用示例

示例一：恢复单个文件为最近版本。
```
./ks3util recover ks3://samplebucket/sample.txt
```

示例二：恢复单个文件为指定版本。

./ks3util recover ks3://samplebucket/sample.txt --retention-id xxxxxx

示例三：恢复单个文件为最近版本，若Bucket中存在同名文件时强制覆盖。
```
./ks3util recover ks3://samplebucket/sample.txt --retention-overwrite
```
示例四：恢复指定前缀下文件为最近版本。
```
./ks3util recover ks3://samplebucket/src-prefix/ -r
```
示例五：恢复指定前缀下文件为最近版本，若Bucket中存在同名文件时强制覆盖。
```
./ks3util recover ks3://samplebucket/src-prefix/ -r --retention-overwrite
```

上一篇：桶操作

下一篇：辅助命令

纯净模式常规模式

纯净模式

点击可全屏预览文档内容