版本历史
| 版本号 | 修改内容 | 时间 |
|---|---|---|
| ks3util-1.2.3-dist | 增加移动对象功能 |
2021年10月27日 |
| ks3util-1.2.2-dist | 支持上传对象指定存储类型 |
2021年9月1日 |
| ks3util-1.2.1-dist | 支持按本地目录结构上传 | 2021年6月8日 |
| ks3util-1.2.0-dist(beta) | 1：省略配置文件，启动根据提示输入配置信息生成文件 2：将所有指令格式进行统一重构 3：整合get, put,multi-move指令到cp指令（上传下载复制）支持多文件，过滤器以及不同账号桶下的迁移复制操作 4：增加cp指令显示指定路径下各个目录大小 5：ls,du命令列举优化控制台输出信息 |
2020年12月30日 |
| ks3util-1.1.3-dist | 修复了批量复制的Bug | 2019年5月21日 |
| ks3util-1.1.2-dist | List命令增加了显示文件大小、文件MD5值的可选项 | 2018年1月29日 |
| ks3util-1.1.1-dist | 增加了Bucket统计容量的功能 | 2017年6月7日 |
| ks3util-1.1.0-dist | 包括功能：List、上传、下载、批量下载、批量删除、批量设置ACL | 2017年6月2日 |
一、介绍
KS3Util工具是KS3为用户提供的命令行工具，方便用户实现对象的批量上传、下载、查询、复制、设置元数据等操作。
二、功能列表
三、运行环境
用户系统需要具备JDK 1.8以上环境。
Windows安装JDK方法参考：环境安装与配置-WIN7下JDK安装与配置。安装完成后，在命令提示符下，执行java –version，来确认是否安装成功。
c:\>java -version
java version "1.8.0_301"
Java(TM) SE Runtime Environment (build 1.8.0_301-b09)
Java HotSpot(TM) Client VM (build 25.301-b09, mixed mode)
Linux安装JDK方法参考：环境安装与配置-Linux下JDK安装与配置。安装完成后，在终端下执行java -version，来确认是否安装成功。
#java -version
java version "1.8.0_301"
Java(TM) SE Runtime Environment (build 1.8.0_301-b09)
Java HotSpot(TM) Client VM (build 25.301-b09, mixed mode)
四. 安装
1. Linux系统
- 下载KS3Util（以ks3util 1.2.3版本为例）。
wget https://ks3tools-online.ks3-cn-beijing.ksyuncs.com/tools/beta/ks3util-1.2.3-dist.zip
- 解压文件。
unzip ks3util-{VERSION}-dist.zip
- 修改文件执行权限。
cd ks3util-{VERSION}
chmod 755 bin/ks3util
- 使用交互方式生成配置文件。
在第一次执行ks3util命令时，可通过交互方式设置访问KS3时所需要的域名Endpoint，Access Key ID和Access Secret Key。例如，第一次执行list buckets操作时，会提示输入配置信息。
./bin/ks3util ls -b
输出：
请输入AK
AKLTYS2***********
请输入SK
OE23G***********
请输入ENDPOINT
ks3-cn-beijing.ksyuncs.com
配置之后，默认在KS3Util的安装路径下自动生成sample.conf配置文件。您也可以在命令行中指定-c参数，来指定配置文件。例如，在list buckets时指定配置文件。
./bin/ks3util ls -b -c /home/ks3util-1.2.2/sample.conf
2. Windows系统
-
单击下载链接下载工具。
-
将工具解压。
打开CMD命令提示符工具，进入KS3Util的安装目录。在第一次执行ks3util命令时，可通过交互方式设置访问KS3时所需要的域名Endpoint，Access Key ID和Access Secret Key。例如，第一次执行list buckets操作时，会提示输入配置信息。
ks3util ls -b
输出：
请输入AK
AKLTYS2***********
请输入SK
OE23G***********
请输入ENDPOINT
ks3-cn-beijing.ksyuncs.com
配置之后，默认在KS3Util的安装路径下自动生成bin/sample.conf配置文件。
您也可以通过在命令行中指定-c 参数，来指定配置文件。例如，在list buckets时指定配置文件。
ks3util ls -b -c d:/sample.conf
五、 常用命令
以下以Linux系统为例，说明工具的常用命令使用方法。
ks3util文件在bin目录下。
1. 查看工具支持的命令
描述
help指令用于介绍ks3util各个命令的语法格式。
命令格式
./ks3util help
输出
usage: ks3util <command> [ <args> ]
Commands are:
cp Batch upload/download/copy
du Calculate sum of object size
get Download a file from ks3
help Display help information
ls List ks3 object keys
multi-change-meta Batch change user meta
multi-del Multi delete ks3 keys
multi-get Batch download
multi-move Batch move from one bucket to another
multiChangeMeta Batch change user meta
put Upload a file to ks3
rm Rm Command to Multi delete ks3 keys
set-acl Batch set ks3 objects acl
setAcl Batch set ks3 objects acl
toUrl Get urls
See 'ks3util help <command>' for more information on a specific command.
其中get,put,multi-del,set-acl,multi-move,multi-get,multi-change-meta,toUrl 命令是旧版本命令，建议您使用新版本命令。
如果要查看某个子命令的使用方式，可以执行ks3util help
./ks3util help ls
2. 列举存储空间
描述
ls命令用于列举存储空间（Bucket）和对象（Object）。
2.1. 列举存储空间
命令格式
./ks3util ls -b [-c config_file]
常用参数
| 参数名称 | 描述 |
|---|---|
| -b | 列举所有Bucket |
| -c | 指定ks3util配置文件的路径 |
使用示例
- 列举Bucket
./ks3util ls -b
输出：包括bucket名称、创建时间、所在地域、存储类型和数量。
========================= Buckets List =========================
CreationTime Region StorageClass BucketName
------------------- -------- ------------ ---------------------
2020-08-19 14:45:38 BEIJING NORMAL uptooz-test
2020-09-01 15:31:22 BEIJING NORMAL bucket-1
------------------- -------- ------------ ---------------------
Bucket Number is:2
2.2. 列举对象
命令格式
./ks3util ls ks3://bucketName[/objectPrefix] [-c config_file] [-d] [-exclude exclude_pattern] [-include include_pattern] [-k keys_file] [-m marker] [-o] [-T time_range] [-u urls_file]
常用参数
| 参数名称 | 描述 |
|---|---|
| bucketName | Bucket名称 |
| objectPrefix | Object名称前缀。当您要列举Bucket中指定前缀的Object时添加此项。 |
| -c | 指定ks3util配置文件的路径。 |
| -d | 返回当前目录下的文件（合并成一个目录形式输出）和子目录。 |
| -exclude | 导出Object列表时，不导出包含指定名称的Object（模糊匹配），多个Object名称用英文逗号分隔。 |
| -include | 导出Object列表时，仅导出包含指定名称的Object（模糊匹配），多个Object名称用英文逗号分隔。 |
| -k | 导出Object名称到指定文件。 |
| -m | 列举名称字母排序在marker之后的Object。 |
| -o | 导出文件的同时增加文件的属性信息。 |
| -T | 列举lastmodified在规定时间内的文件，例如：“2021-01-01 00:00:00#2021-01-31 23:59:00” |
| -u | 导出Object的共享URL列表到指定文件。共享URL根据用户配置的AccessKeyID和SecretKey生成。 |
使用示例
- 列举指定Bucket下所有的Object。
./ks3util ls ks3://examplebucket/ -k objectKeys.txt
- 列举指定Bucket下所有以”abc/”开头的Object。
./ks3util ls ks3://examplebucket/abc -k objectKeys.txt
- 列举指定Bucket下所有目录
./ks3util ls ks3://examplebucket -d
输出：目录名称、包含的对象个数、目录总大小
============= Object List =============
PrefixDir ContainsNum TotalSize
------------------ ----------- ---------
目录文件集合 3 13.99 MB
testDir 209 280.23 MB
------------------ ----------- ---------
Direction Number is:2
total num 212 个
total size 308517940 Bytes, 294.23 MB
- 列举Object时指定marker参数，列举出指定marker之后的对象。
./ks3util ls ks3://examplebucket -k objectKeys.txt -m objectMarker
- 导出object URL列表到指定文件
./bin/ks3util ls ks3://examplebucket -u keys.txt
- 导出文件的同时增加文件的属性信息，包括文件的ETag，文件大小和最后修改时间。
./bin/ks3util ls ks3://examplebucket -o -k keys.txt
- 导出lastmodified在规定时间内的文件，例如：“2021-10-10 00:00:00#2021-10-15 00:00:00”
./bin/ks3util ls ks3://examplebucket -T "2021-10-10 00:00:00#2021-10-15 00:00:00" -k keys.txt
- 导出object列表时，不导出名称中包含mp4的object。
./bin/ks3util ls ks3://examplebucket -exclude mp4 -k keys.txt
- 导出object列表时，仅导出名称中包含mp4的object。
./bin/ks3util ls ks3://examplebucket -include mp4 -k keys.txt
3. 对象上传
描述
cp命令可以批量上传本地路径下的文件到KS3 bucket中。当上传的文件较大时，cp命令将自动使用分块上传和断点续传。
命令格式
./ks3util cp LocalPath ks3://bucketName/objectPath [-a|--acl acl] [-c config_file] [-exclude exclude_pattern] <-f fail_keys_file> [-i upload_hidden_files] [-include include_pattern] [-r use_relative_path] [-s|--storageclass storage_class] [--update|-u update_exist_files] [-z use_last_dir_name]
常用参数
| 参数名称 | 描述 |
|---|---|
| LocalPath | 本地文件路径。例如Linux系统文件路径/localPath/examplefile.txt，Windows系统文件路径D:\localPath\examplefile.txt。也可以配置为本地目录，表示上传目录下的文件。 |
| bucketName | Bucket名称。 |
| objectPath | 将Object上传到Bucket指定路径下。 |
| -a | 设置文件的ACL权限，枚举值：Private（私有），PublicRead（公共读），默认Private。 |
| -c | 指定ks3util配置文件的路径。 |
| -exclude | 不上传包含指定名称的Object（模糊匹配），多个Object名称用英文逗号分隔。 |
| -f | 导出上传失败的Object列表文件。 |
| -i | 是否上传隐藏文件，枚举值：yes，no（默认） |
| -include | 仅上传包含指定名称的Object（模糊匹配），多个Object名称用英文逗号分隔。 |
| -r | 路径是否是相对路径，枚举值：yes，no |
| -s | 指定文件的存储类型 枚举值：STANDARD（标准存储）、STANDARD_IA（低频存储）、ARCHIVE（归档存储），默认跟随bucket存储类型。 |
| -u | 上传时如bucket中已有同名文件存在的处理方式，枚举值： 0（根据最后修改时间判断是否重传，新文件覆盖旧文件），1（最后修改时间或文件大小判断是否重传），2（全部覆盖），3（全部跳过），默认是0。 |
| -z | 是否将文件所在的当前目录名称作为object名称前缀，枚举值：yes（默认），no。 |
使用示例
以Linux系统为例，将本地文件或文件夹上传至KS3中。您在实际使用中，请根据您的系统和使用环境修改对应参数。
-
本地文件：examplefile.txt（相对目录下的文件）
-
本地文件夹：LocalPath（相对目录下的文件夹）
-
目标Bucket：examplebucket
-
目标Bucket指定目录：desPath
-
上传单个文件，如果不指定上传至KS3的文件名，则默认使用原文件名进行保存；如果指定文件名，则按照指定的文件名保存在KS3中。上传失败的文件列表输出到fail.txt。
./ks3util cp examplefile.txt ks3://examplebucket/desPath/ -f fail.txt
输出：包括上传的文件名称，文件个数，文件大小，重复文件个数，失败文件个数，上传时长等信息。
[Upload] SUCCESS objectKey:examplefile.txt storageClass:STANDARD [success:1/total:1]
[Upload DONE]totalKeys=1,filterFetchNum=0,SuccessTotalNum=1,SuccessFileSize=6,repeatNum=0,failedNum=0 cost=87
- 上传文件夹和文件夹下的所有文件（包括子文件夹和子文件夹中的文件）。上传失败的文件列表输出到fail.txt。
./ks3util cp LocalPath/ ks3://examplebucket/desPath/ -f fail.txt
输出：包括上传的文件名称，文件个数，文件大小，重复文件个数，失败文件个数，上传时长等信息。
[Upload] SUCCESS objectKey:LocalPath/s3util-1.2.2/LocalPath/ storageClass:STANDARD [success:1/total:1]
[Upload] SUCCESS objectKey:LocalPath/s3util-1.2.2/LocalPath/subPath/ storageClass:STANDARD [success:2/total:2]
[Upload] SUCCESS objectKey:LocalPath/s3util-1.2.2/LocalPath/subPath/33.txt storageClass:STANDARD [success:3/total:3]
[Upload] SUCCESS objectKey:LocalPath/s3util-1.2.2/LocalPath/abc.txt storageClass:STANDARD [success:4/total:4]
[Upload] SUCCESS objectKey:LocalPath/s3util-1.2.2/LocalPath/111.txt storageClass:STANDARD [success:5/total:5]
[Upload DONE]totalKeys=5,filterFetchNum=0,SuccessTotalNum=5,SuccessFileSize=8192,repeatNum=0,failedNum=0 cost=425
- 上传本地文件时，指定文件权限为公有读。
./ks3util cp LocalPath/ ks3://examplebucket/Path/ -f fail.txt -a PublicRead
- 上传本地文件时，不上传名称中包含txt的object。
./ks3util cp LocalPath/ ks3://examplebucket/Path/ -f fail.txt -exclude txt
- 上传本地文件时，仅上传名称中包含txt的object。
./ks3util cp LocalPath/ ks3://examplebucket/Path/ -f fail.txt -include txt
- 上传本地文件时，使用绝对路径方式指定本地路径。
./ks3util cp /home/user/LocalPath/ ks3://examplebucket/Path/ -f fail.txt -r no
- 上传本地文件时，设置文件存储类型为低频存储。
./ks3util cp LocalPath/ ks3://examplebucket/Path/ -f fail.txt -s STANDARD_IA
- 上传本地文件时，如KS3 bucket中已有同名文件存在，则全部覆盖。
./ks3util cp LocalPath/ ks3://examplebucket/Path/ -f fail.txt -u 2
- 上传本地文件时，不将文件所在的当前目录名称作为object名称前缀
./ks3util cp LocalPath/ ks3://examplebucket/Path/ -f fail.txt -z no
4. 对象复制
描述
cp命令可以将KS3 Bucket中的文件（Object）拷贝至其他Bucket。
命令格式
./ks3util cp ks3_path ks3_path [-exclude exclude_pattern] <-f fail_keys_file> [-include include_pattern] [-r retry_times]
常用选项
您可以在使用cp命令时附加如下选项指定列举模式及列举的内容：
| 选项名称 | 描述 |
|---|---|
| ks3_path | 分别填写KS3源文件和目标文件路径。格式为ks3://bucketname/objectname。例如，将目标存储空间examplebucket下的源文件srcobject.txt拷贝到存储空间examplebucket2下的目标文件destobject.txt，则源文件路径填写为ks3://examplebucket/srcobject.txt，目标文件路径填写为ks3://examplebucket2/destobject.txt。 |
| -c | 指定ks3util配置文件的路径。 |
| -f | 导出拷贝失败的Object列表文件 |
| -r | 失败重试次数 |
| -include | 仅拷贝包含指定名称的Object（模糊匹配），多个Object名称用英文逗号分隔。 |
| -exclude | 不拷贝包含指定名称的Object（模糊匹配），多个Object名称用英文逗号分隔。 |
使用示例
以Linux系统为例，在不同Bucket之间拷贝文件。您在实际使用中，请根据您的系统和使用环境修改对应参数。
-
源Bucket：examplebucket1
-
源Bucket指定目录1：srcPath
-
源文件：examplefile.txt
-
目标Bucket：examplebucket2
-
目标Bucket指定目录：desPath
-
复制单个文件，目标bucket中的文件名与源文件名相同，上传失败的文件列表输出到fail.txt。
./ks3util cp ks3://examplebucket1/srcPath/examplefile.txt ks3://examplebucket2/desPath/ -f fail.txt
第一次复制对象时，需要配置目标bucket对应的域名Endpoint，Access Key ID和Access Secret Key。配置之后，ks3util默认将配置信息保存在sample.conf配置文件。
配置完成后可以拷贝对象，并输出拷贝的文件名称，文件个数等信息。
复制
请输入目标账户AK
AKLTYS2***********
请输入目标账户SK
OE23G***********
请输入目标账号ENDPOINT
ks3-cn-beijing-internal.ksyuncs.com
[Copy] SUCCESS examplefile.txt[success:1/total:1]
[Copy] DONE,totalKeys=1,SuccessTotalNum=1,filterFetchNum=0,repeatNum=0,failedNum=0
- 批量复制多个文件，将examplebucket1中srcPath目录下的文件批量拷贝到examplebucket2的desPath目录下。
./ks3util cp ks3://examplebucket1/srcPath/ ks3://examplebucket2/desPath/ -f fail.txt
5. 对象下载
描述
cp命令可以将KS3 bucket中的文件或文件夹，批量下载至本地。
命令格式
./ks3util cp ks3://bucketName/objectPath LocalPath/ [-c config_file] [-exclude exclude_pattern] <-f fail_keys_file> [-include include_pattern]
常用参数
| 参数名称 | 描述 |
|---|---|
| LocalPath | 本地文件路径。例如Linux系统文件路径localPath/，Windows系统文件路径D:\localPath。 |
| bucketName | Bucket名称 |
| -c | 指定ks3util配置文件的路径。 |
| -exclude | 不下载包含指定名称的Object（模糊匹配），多个Object名称用英文逗号分隔。 |
| -f | 导出下载失败的Object列表文件 |
| -include | 仅下载包含指定名称的Object（模糊匹配），多个Object名称用英文逗号分隔。 |
使用示例
以Linux系统为例，将KS3中的文件或文件夹下载至本地。您在实际使用中，请根据您的系统和使用环境修改对应参数。
-
目标Bucket：examplebucket
-
目标Bucket指定目录：desPath
-
目标Bucket中的文件：examplefile.txt
-
本地文件夹：LocalPath（相对目录下的文件夹）
-
下载单个文件，如果不指定下载到本地的文件名，则默认使用原文件名进行保存；如果指定文件名，则按照指定的文件名保存在本地。下载失败的文件列表输出到fail.txt。
./ks3util cp ks3://examplebucket/desPath/examplefile.txt LocalPath/ -f fail.txt
输出：下载后的文件路径。
[Download]File write to /home/user/ks3util-1.2.2/LocalPath/examplefile.txt
- 下载文件夹和文件夹下的所有文件（包括子文件夹和子文件夹中的文件）。下载失败的文件列表输出到fail.txt。
./ks3util cp ks3://examplebucket/desPath/ LocalPath/ -f fail.txt
输出：包括下载后的文件路径。
[Download]OK LocalPath/desPath/examplefile.txt[success:1/total:1]
[Download] DONE,totalKeys=1,filterFetchNum=1,SuccessTotalNum=1,findRepeatNum=0,failKeys=0
- 下载文件时，不下载名称中包含txt的object。
./ks3util cp ks3://examplebucket/Path/ LocalPath/ -f fail.txt -exclude txt
- 下载本地文件时，仅下载名称中包含txt的object。
./ks3util cp ks3://examplebucket/Path/ LocalPath/ -f fail.txt -include txt
6. 移动对象
描述
mv命令可以批量移动本地路径下的文件到KS3 bucket中，或者批量移动KS3中的对象到本地，或者在KS3 bucket之间移动对象，移动之后会删除源对象。当移动的文件较大时，mv命令将自动使用分块上传和断点续传。
命令格式
移动本地路径下的文件到KS3 bucket
./ks3util mv LocalPath ks3://bucketName/objectPath [-a|--acl acl] [-c config_file] [-exclude exclude_pattern] <-f fail_keys_file> [-i upload_hidden_files] [-include include_pattern] [-r use_relative_path] [-s|--storageclass storage_class] [--update|-u update_exist_files] [-z use_last_dir_name]
移动KS3中的对象到本地
./ks3util mv ks3://bucketName/objectPath LocalPath/ [-c config_file] [-exclude exclude_pattern] <-f fail_keys_file> [-include include_pattern]
在KS3 bucket之间移动对象
./ks3util mv ks3_path ks3_path [-exclude exclude_pattern] <-f fail_keys_file> [-include include_pattern]
常用参数
| 参数名称 | 描述 |
|---|---|
| LocalPath | 本地文件路径。例如Linux系统文件路径/localPath/examplefile.txt，Windows系统文件路径D:\localPath\examplefile.txt。也可以配置为本地目录，表示移动目录下的文件。 |
| bucketName | Bucket名称。 |
| objectPath | 将Object移动到Bucket指定路径下。 |
| -a | 设置文件的ACL权限，枚举值：Private（私有），PublicRead（公共读），默认Private。 |
| -c | 指定ks3util配置文件的路径。 |
| -exclude | 不移动包含指定名称的Object（模糊匹配），多个Object名称用英文逗号分隔。 |
| -f | 导出移动失败的Object列表文件。 |
| -i | 是否移动隐藏文件，枚举值：yes，no（默认） |
| -include | 仅移动包含指定名称的Object（模糊匹配），多个Object名称用英文逗号分隔。 |
| -r | 路径是否是相对路径，枚举值：yes，no |
| -s | 指定文件的存储类型 枚举值：STANDARD（标准存储）、STANDARD_IA（低频存储）、ARCHIVE（归档存储），默认跟随bucket存储类型。 |
| -u | 移动时如bucket中已有同名文件存在的处理方式，枚举值： 0（根据最后修改时间判断是否重传，新文件覆盖旧文件），1（最后修改时间或文件大小判断是否重传），2（全部覆盖），3（全部跳过），默认是0。 |
| -z | 是否将文件所在的当前目录名称作为object名称前缀，枚举值：yes（默认），no。 |
使用示例
以Linux系统为例，进行移动文件的操作。您在实际使用中，请根据您的系统和使用环境修改对应参数。
-
本地文件：examplefile.txt（相对目录下的文件）
-
本地文件夹：LocalPath（相对目录下的文件夹）
-
目标Bucket：examplebucket
-
目标Bucket指定目录：desPath
-
移动单个文件到KS3，如果不指定移动至KS3的文件名，则默认使用原文件名进行保存；如果指定文件名，则按照指定的文件名保存在KS3中。移动失败的文件列表输出到fail.txt。
./ks3util mv examplefile.txt ks3://examplebucket/desPath/ -f fail.txt
输出：包括移动的文件名称，文件个数，文件大小，重复文件个数，失败文件个数，上传时长等信息。
[Upload] SUCCESS objectKey:des/sample.conf storageClass:STANDARD [success:1/total:1]
[Upload DONE]totalKeys=1,filterFetchNum=0,SuccessTotalNum=1,SuccessFileSize=0,repeatNum=0,failedNum=1 cost=2082
- 移动文件夹和文件夹下的所有文件到KS3（包括子文件夹和子文件夹中的文件）到KS3。移动失败的文件列表输出到fail.txt。
./ks3util mv LocalPath/ ks3://examplebucket/desPath/ -f fail.txt
- 移动本地文件到KS3时，指定文件权限为公有读。
./ks3util mv LocalPath/ ks3://examplebucket/Path/ -f fail.txt -a PublicRead
- 移动本地文件到KS3时，不移动名称中包含txt的object。
./ks3util mv LocalPath/ ks3://examplebucket/Path/ -f fail.txt -exclude txt
- 移动本地文件到KS3时，仅移动名称中包含txt的object。
./ks3util mv LocalPath/ ks3://examplebucket/Path/ -f fail.txt -include txt
- 移动本地文件到KS3时，使用绝对路径方式指定本地路径。
./ks3util mv /home/user/LocalPath/ ks3://examplebucket/Path/ -f fail.txt -r no
- 移动本地文件到KS3时，设置文件存储类型为低频存储。
./ks3util mv LocalPath/ ks3://examplebucket/Path/ -f fail.txt -s STANDARD_IA
- 移动本地文件到KS3时，如KS3 bucket中已有同名文件存在，则全部覆盖。
./ks3util mv LocalPath/ ks3://examplebucket/Path/ -f fail.txt -u 2
- 移动本地文件到KS3时，不将文件所在的当前目录名称作为object名称前缀
./ks3util mv /home/user/LocalPath/ ks3://examplebucket/Path/ -f fail.txt -z no
- 从KS3移动单个文件到本地，如果不指定下载到本地的文件名，则默认使用原文件名进行保存；如果指定文件名，则按照指定的文件名保存在本地。移动失败的文件列表输出到fail.txt。
./ks3util mv ks3://examplebucket/desPath/examplefile.txt LocalPath/ -f fail.txt
输出：下载后的文件路径。
[Download]File write to /home/user/ks3util-1.2.2/LocalPath/examplefile.txt
- 从KS3移动文件夹和文件夹下的所有文件（包括子文件夹和子文件夹中的文件）到本地。移动失败的文件列表输出到fail.txt。
./ks3util mv ks3://examplebucket/desPath/* LocalPath/ -f fail.txt
- 在KS3之间移动单个文件，目标bucket中的文件名与源文件名相同，移动失败的文件列表输出到fail.txt。
./ks3util mv ks3://examplebucket1/srcPath/examplefile.txt ks3://examplebucket2/desPath/ -f fail.txt
第一次移动对象时，需要配置目标bucket对应的域名Endpoint，Access Key ID和Access Secret Key。配置之后，ks3util默认将配置信息保存在sample.conf配置文件。
配置完成后可以移动对象，并输出移动的文件名称，文件个数等信息。
请输入目标账户AK
AKLTYS2***********
请输入目标账号SK
OE23G**********
请输入目标账号ENDPOINT
ks3-cn-beijing.ksyuncs.com
[Move] SUCCESS examplefile.txt[success:1/total:1]
[Move] DONE,totalKeys=1,SuccessTotalNum=1,filterFetchNum=0,repeatNum=0,failedNum=0
- 批量移动多个文件，将examplebucket1中srcPath目录下的文件批量移动到examplebucket2的desPath目录下。
./ks3util mv ks3://examplebucket1/srcPath/* ks3://examplebucket2/desPath/ -f fail.txt
7. 删除存储空间或对象
描述
rm命令用于删除存储空间桶（Bucket）或对象（Object）。
命令格式
./ks3util rm ks3://bucketName[/objectPath] [-b] [-c] [-exclude] [-f] [-include] [-r]
常用参数
| 参数名 | 描述 |
|---|---|
| bucketName | bucket名称 |
| objectPath | 删除指定路径下的对象 |
| -b | 删除存储空间，删除前请先删除存储空间下的所有对象。 |
| -c | 指定ks3util配置文件的路径。 |
| -exclude | 不删除包含指定名称的Object（模糊匹配），多个Object名称用英文逗号分隔。 |
| -f | 导出删除失败的Object列表文件。 |
| -include | 仅删除包含指定名称的Object（模糊匹配），多个Object名称用英文逗号分隔。 |
| -r | 失败重试次数 |
使用示例
以Linux系统为例，删除KS3中的bucket或者object。您在实际使用中，请根据您的系统和使用环境修改对应参数。
-
文件：examplefile.txt
-
Bucket：examplebucket
-
删除指定Bucket下的指定object
./ks3util rm ks3://examplebucket/Path/examplefile.txt -f fail.txt
输出：包括删除的对象名称，对象个数，删除时长等信息。
[RM]delete Success :Path/examplefile.txt
[RM]Done：totalKeys=1, deleted =1,filter Intercepts=0, failKeys=0 ,cost=326 ms，Check log for more information
- 删除指定Bucket下某目录中所有文件
./ks3util rm ks3://examplebucket/Path/ -f fail.txt
输出：包括删除的对象名称，对象个数，删除时长等信息。
[RM]delete Success :Path/3.txt
[RM]delete Success :Path/1.txt
[RM]delete Success :Path/2.txt
[RM]delete Success :Path/
[RM]Done：totalKeys=4, deleted =4,filter Intercepts=0, failKeys=0 ,cost=362 ms，Check log for more information
- 删除空的Bucket
./ks3util rm ks3://examplebucket -b -f fail.txt
8. 修改元数据
描述
multiChangeMeta命令用于批量修改对象元数据信息。
./ks3util multiChangeMeta ks3_path [-a acl] [-c] [-f fail_Keys_file] [-i meta_info] [-m metaType] [-s storage_class]
常用参数
| 选项名称 | 描述 |
|---|---|
| ks3_path | 可以修改单个对象的元数据信息，格式为ks3://bucketname/objectname。也可以批量修改对象的元数据信息，格式为ks3://examplebucket/prefix/。 |
| -a | 设置文件的ACL权限，枚举值：Private（私有），PublicRead（公共读），默认Private。 |
| -c | 指定ks3util配置文件的路径。 |
| -f | 导出修改失败的Object列表文件。 |
| -i | 设置的元数据信息，格式为 key=value#key=value 使用utf-8编码，自定义的元素头将保存为以x-kss-meta开头。 |
| -m | 操作类型，枚举值：add （新增元数据），rewrite （修改元数据）。 |
| -s | 指定文件的存储类型 枚举值：STANDARD（标准存储）、STANDARD_IA（低频存储）、ARCHIVE（归档存储），默认跟随bucket存储类型。 |
使用示例
以Linux系统为例，修改KS3中对象的元数据信息。您在实际使用中，请根据您的系统和使用环境修改对应参数。
-
文件：examplefile.txt
-
Bucket：examplebucket
-
对以prefix为开头的所有对象，新增自定义元数据
./ks3util multiChangeMeta ks3://examplebucket/prefix/ -f fail.txt -m add -i yourMetaKey1=yourMetaValue1#yourMetaKey2=yourMetaValue2
输出以下信息，包括各个对象的元数据。
{x-kss-metadata-directive=REPLACE, ETag=d41d8cd98f00b204e9800998ecf8427e, Ctime=Fri, 15 Oct 2021 08:02:09 GMT, x-kss-acl=public-read, Last-Modified=Fri Oct 15 16:02:09 CST 2021, x-kss-meta-yourMetaKey2=yourMetaValue2, Content-Length=0, x-kss-meta-yourMetaKey1=yourMetaValue1,Content-Type=application/octet-stream, Content-MD5=1B2M2Y8AsgTpgAmY7PhCfg==}
{x-kss-metadata-directive=REPLACE, ETag=bbb8aae57c104cda40c93843ad5e6db8, Ctime=Fri, 15 Oct 2021 08:02:20 GMT, x-kss-acl=public-read, Last-Modified=Fri Oct 15 16:02:20 CST 2021, x-kss-meta-yourMetaKey2=yourMetaValue2, Content-Length=9, x-kss-meta-yourMetaKey1=yourMetaValue1, Content-Type=text/plain, Content-MD5=u7iq5XwQTNpAyThDrV5tuA==}
success key = prefix/
success key = prefix/1.txt
All files change meta success,totalKeys=2,filterFetchKeys=0,failKeys=0
- 对以prefix为开头的所有对象，修改自定义元数据
./ks3util multiChangeMeta ks3://examplebucket/prefix/ -f fail.txt -m rewrite -i yourMetaKey1=yourMetaValue11
输出以下信息，包括各个对象的元数据。
{x-kss-metadata-directive=REPLACE, ETag=d41d8cd98f00b204e9800998ecf8427e, Ctime=Fri, 15 Oct 2021 08:02:09 GMT, x-kss-acl=public-read, Last-Modified=Fri Oct 15 16:02:55 CST 2021, Content-Length=0, x-kss-meta-yourMetaKey1=yourMetaValue11, Content-Type=application/octet-stream, Content-MD5=1B2M2Y8AsgTpgAmY7PhCfg==}
{x-kss-metadata-directive=REPLACE, ETag=bbb8aae57c104cda40c93843ad5e6db8, Ctime=Fri, 15 Oct 2021 08:02:20 GMT, x-kss-acl=public-read, Last-Modified=Fri Oct 15 16:02:55 CST 2021, Content-Length=9, x-kss-meta-yourMetaKey1=yourMetaValue11, Content-Type=text/plain, Content-MD5=u7iq5XwQTNpAyThDrV5tuA==}
success key = prefix/
success key = prefix/1.txt
All files change meta success,totalKeys=2,filterFetchKeys=0,failKeys=0
- 修改单个对象的自定义元数据，并设置访问权限为公有读，存储类型为低频。
./ks3util multiChangeMeta ks3://examplebucket/prefix/ -f fail.txt -m rewrite -i yourMetaKey1=yourMetaValue11 -a PublicRead -s STANDARD_IA
输出以下信息，包括各个对象的元数据。
{x-kss-metadata-directive=REPLACE, x-kss-storage-class=STANDARD_IA, ETag=bbb8aae57c104cda40c93843ad5e6db8, Ctime=Fri, 15 Oct 2021 08:02:20 GMT, x-kss-acl=public-read, Last-Modified=Fri Oct 15 17:33:48 CST 2021, Content-Length=9, x-kss-meta-yourMetaKey1=yourMetaValue11, Content-Type=text/plain, Content-MD5=u7iq5XwQTNpAyThDrV5tuA==}
{x-kss-metadata-directive=REPLACE, x-kss-storage-class=STANDARD_IA, ETag=d41d8cd98f00b204e9800998ecf8427e, Ctime=Fri, 15 Oct 2021 08:02:09 GMT, x-kss-acl=public-read, Last-Modified=Fri Oct 15 17:33:48 CST 2021, Content-Length=0, x-kss-meta-yourMetaKey1=yourMetaValue11, Content-Type=application/octet-stream, Content-MD5=1B2M2Y8AsgTpgAmY7PhCfg==}
success key = prefix/1.txt
success key = prefix/
All files change meta success,totalKeys=2,filterFetchKeys=0,failKeys=0
9. 设置ACL
描述
setAcl指令可以批量设置文件的权限ACL。
命令格式
./ks3util setAcl ks3_path <-a> [-c] [-exclude exclude_pattern] [-include include_pattern]
常用参数
| 选项名称 | 描述 |
|---|---|
| ks3_path | 可以设置单个对象的ACL，格式为ks3://bucketname/objectname。也可以批量设置对象的元数据信息，格式为ks3://examplebucket/prefix/。 |
| -a | 设置文件的ACL权限，枚举值：Private（私有），PublicRead（公共读），默认Private。 |
| -c | 指定ks3util配置文件的路径。 |
| -exclude | 不设置包含指定名称的Object（模糊匹配），多个Object名称用英文逗号分隔。 |
| -include | 仅设置包含指定名称的Object（模糊匹配），多个Object名称用英文逗号分隔。 |
使用示例
以Linux系统为例，修改KS3中对象的元数据信息。您在实际使用中，请根据您的系统和使用环境修改对应参数。
-
文件：examplefile.txt
-
Bucket：examplebucket
-
设置单个文件的ACL权限。
./bin/ks3util setAcl ks3://examplebucket/examplefile.txt -a Private
批量设置prefix目录下的多个文件的ACL权限。
./bin/ks3util setAcl ks3://examplebucket/prefix -a Private
10. 计算对象总大小
描述
du命令用于计算对象（Object）总大小。
命令格式
./ks3util du ks3://bucketName[/objectPath] [-c] [-exclude] [-f] [-include] [-r]
常用参数
| 参数名称 | 描述 |
|---|---|
| bucketName | Bucket名称 |
| objectPath | 统计objectPath下的所有对象大小，如果不填写，则统计Bucket中的所有对象大小。 |
| -c | 指定ks3util配置文件的路径。 |
| -exclude | 不统计包含指定名称的Object（模糊匹配），多个Object名称用英文逗号分隔。 |
| -include | 仅统计包含指定名称的Object（模糊匹配），多个Object名称用英文逗号分隔。 |
| -m | 列举名称字母排序在marker之后的Object。 |
使用示例
以Linux系统为例，统计KS3 Bucket中的对象大小。您在实际使用中，请根据您的系统和使用环境修改对应参数。
-
Bucket：examplebucket
-
Bucket指定目录：desPath
-
统计Bucket中desPath目录下的所有对象大小
./ks3util du ks3://examplebucket/desPath
输出：包括统计的对象个数，对象总大小，统计时长等信息。
list 17 object, cost 581 ms
total num 17 个
total size 14672097 Bytes, 13.99 MB
六、配置文件
1.2.0之后的版本，可在第一次执行KS3Util命令时以交互方式填写配置信息，KS3Util将生成sample.conf配置文件，无需用户手动填写配置文件。用户可以手动修改配置文件中的参数，各参数含义如下。
| 字段 | 说明 | 是否必填 |
|---|---|---|
| ks3.ak | 账户AK，参考获取AK/SK。 | 是 |
| ks3.sk | 账户SK，参考获取AK/SK。 | 是 |
| ks3.endpoint | bucket所在region的endpoint，对应列表参看官方文档。 | 是 |
| http.conn.timeout | http连接超时，默认为10000ms，一般不需要更改。 | 否 |
| http.so.timeout | http通讯超时，默认为10000ms，一般不需要更改。 | 否 |
| http.max.connections | http连接数，默认值:100。 | 否 |
| async.queuesize | 批量处理时的队列长度，默认:200，该值越大内存使用率越大。 | 否 |
| async.max.threads | 批量处理时最大并发数，默认:100。 | 否 |
| async.core.threads | 批量处理时最小并发数，默认:4。 | 否 |
| ks3.movedest.ak | cp和multi-move操作时的目标账号AK。 | cp 和 multi-move操作时必填 |
| ks3.movedest.sk | cp和multi-move操作时的目标账号SK。 | cp 和 multi-move操作时必填 |
| ks3.movedest.endpoint | cp和multi-move操作时的目标Bucket所在的endpoint。 | cp 和 multi-move操作时必填 |
七、 常见问题
-
KS3Util工具上传同名文件时，会覆盖还是跳过？
KS3Util工具上传文件时，可以设置-u参数，取值为：0（根据最后修改时间判断是否重传，新文件覆盖旧文件），1（根据最后修改时间或文件大小判断是否重传），2（全部覆盖），3（全部跳过），默认是0。您可以根据实际需要设置参数值。 -
KS3Util工具最大支持上传多大的文件？
KS3单个文件（对象）最大支持48.8TB。KS3Util上传大文件时，会自动进行切分，通过分块上传的方式上传大文件。 -
KS3Util工具传输大量文件时，如何提高传输速度？
可适当调整配置文件中的http.max.connections 参数值，来增加并发处理的线程数。 -
KS3Util工具可以同时管理多个账号的存储空间吗？
KS3Util配置文件中只能配置一个账号，如您需要管理不同账号下的存储空间，可以保存多个账号的配置文件，在执行KS3Util命令时，通过-c参数来指定不同的配置文件，从而达到切换账号的效果。例如
./bin/ks3util ls -b -c user1_config.conf
-
KS3Util工具执行异常时，如何排查问题？
KS3Util工具在执行操作时，会记录日志，目录是KS3Util的安装路径/logs，您可以通过日志初步排查问题，或者将错误日志发送给我们排查。 -
配置文件中的Access Key ID和Access Secret Key都填写正确，但是执行KS3Util命令失败，是什么原因？
请检查安装KS3Util工具的服务器时间是否正确，如果与标准时间相差15分钟以上，将无法执行操作。 -
KS3Util工具上传文件时，如何排除某些目录或某些文件？
上传文件时，可以通过-exclude参数来排除某些目录和文件。例如，要上传LocalPath/中的目录和文件，并排除mp4目录下的文件，和文件名中包含mp4的文件。
./ks3util cp LocalPath/ ks3://examplebucket/desPath -f fail.txt -exclude mp4
文档内容是否对您有帮助？
根本没帮助
文档较差
文档一般
文档不错
文档很好
在文档使用中是否遇到以下问题
内容不全，不深入
内容更新不及时
描述不清晰，比较混乱
系统或功能太复杂，缺乏足够的引导
内容冗长
更多建议
0/200
评价建议不能为空
提交成功！
非常感谢您的反馈，我们会继续努力做到更好！