版本
当前版本:1.3
下载地址:ks3util
运行环境
Windows/Linux/macOS
支持架构:x86(32bit、64bit)、ARM(32bit、64bit)
建议使用JDK 1.6以上环境。
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)
curl http://ks3tools.ks3-cn-beijing.ksyuncs.com/tools/release/ks3Util/1.3/install.sh|bash
单击下载链接下载工具。
将工具解压。
打开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 --config d:/sample.conf
在第一次执行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的安装路径下自动生成sample.conf配置文件。
您也可以通过在命令行中指定–config 参数,来指定配置文件。例如,在list buckets时指定配置文件。
./ks3util ls -b --config d:/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操作时必填 |
ks3.movedest.sk | cp和multi-move操作时的目标账号SK。 | cp操作时必填 |
ks3.movedest.endpoint | cp和multi-move操作时的目标Bucket所在的endpoint。 | cp操作时必填 |
multipart.partsize | 分块上传时,设置分块的大小 | 否 |
help指令用于介绍ks3util各个命令的语法格式。
./ks3util help
输出
usage: ks3util <command> [ <args> ]
Commands are:
cp Batch upload/download/copy
help Display help information
ls List ks3 object keys
mb create bucket
mkdir create prefix
multi-change-meta Batch change user meta
mv Batch upload/download/mv
rm Rm Command to Multi delete ks3 keys
set-acl Batch set ks3 objects acl
See 'ks3util help <command>' for more information on a specific command.
如果要查看某个子命令的使用方式,可以执行ks3util help
./ks3util help ls
参数名称 | 是否必填 | 描述 |
---|---|---|
bucketName | 是 | Bucket名称 |
objectPrefix | 否 | Object名称前缀。当您要列举Bucket中指定前缀的Object时添加此项。 |
–config | 否 | 指定ks3util配置文件的路径。默认读取当前执行命令下的sample.conf文件 |
–exclude | 否 | 导出Object列表时,不导出包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。 |
–include | 否 | 导出Object列表时,仅导出包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。 |
–storage-class | 否 | 指定文件的存储类型 枚举值:STANDARD(标准存储)、STANDARD_IA(低频存储)、ARCHIVE(归档存储),默认跟随bucket存储类型。 |
–acl | 否 | 设置文件的ACL权限,枚举值:Private(私有),PublicRead(公共读),默认Private。 |
-f | 否 | 导出拷贝失败的Object列表文件 |
ls命令用于列举存储空间(Bucket)和对象(Object)。
./ks3util ls -b [--config config_file]
参数名称 | 是否必填 | 描述 |
---|---|---|
-b | 是 | 列举所有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
./ks3util ls ks3://bucketName/objectPrefix [--config config_file] [-d] [--exclude exclude_pattern] [--include include_pattern] [-key keys_file] [--marker] [--time_range] [-u urls_file]
参数名称 | 是否必填 | 描述 |
---|---|---|
-d | 否 | 返回当前目录下的文件(合并成一个目录形式输出)和子目录。 |
–marker | 否 | 列举名称字母排序在marker之后的Object。 |
-o | 否 | 导出文件的同时增加文件的属性信息。 |
–time-range | 否 | 列举lastmodified在规定时间内的文件,例如:“2021-01-01 00:00:00#2021-01-31 23:59:00” |
-url | 否 | 导出Object的共享URL列表到指定文件,共享URL根据用户配置的AccessKeyID和SecretKey生成,有效期为24小时。 |
-k | 否 | 导出Object名称到指定文件。 |
./ks3util ls ks3://bucketName/ -k objectKeys.txt
./ks3util ls ks3://bucketName/abc -k objectKeys.txt
./ks3util ls ks3://bucketName -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
./ks3util ls ks3://bucketName -k objectKeys.txt --marker objectMarker
./bin/ks3util ls ks3://bucketName -u keys.txt
./bin/ks3util ls ks3://bucketName --time-range "2021-10-10 00:00:00#2021-10-15 00:00:00" -k keys.txt
./bin/ks3util ls ks3://bucketName --exclude mp4 -k keys.txt
./bin/ks3util ls ks3://bucketName --include mp4 -k keys.txt
cp命令可以批量上传本地路径下的文件到KS3 bucket中。当上传的文件较大时,cp命令将自动使用分块上传和断点续传。
./ks3util cp LocalPath ks3://bucketName/objectPath [--acl acl] [--config_file] [--exclude exclude_pattern] <-f fail_keys_file> [-i upload_hidden_files] [--include include_pattern] [-r use_relative_path] [--storageclass storage_class] [--update|-u update_exist_files]
参数名称 | 是否必填 | 描述 |
---|---|---|
-i | 否 | 当前上传的文件是否移动隐藏文件,枚举值:yes,no(默认) |
-r | 否 | 当前上传的路径是否是相对路径,枚举值:yes,no |
-u,–update | 否 | 只有当目标文件不存在,或源文件的最后修改时间晚于目标文件时,ks3util才会执行上传操作。 |
-z | 否 | 是否将上传的的当前目录名称作为object名称前缀,枚举值:yes,no(默认)。 |
以Linux系统为例,将本地文件或文件夹上传至KS3中。您在实际使用中,请根据您的系统和使用环境修改对应参数。
本地文件:examplefile.txt(相对目录下的文件)
本地文件夹:LocalPath(相对目录下的文件夹)
目标Bucket:bucketName
目标Bucket指定目录:desPath
上传单个文件,如果不指定上传至KS3的文件名,则默认使用原文件名进行保存;如果指定文件名,则按照指定的文件名保存在KS3中。上传失败的文件列表输出到fail.txt。
./ks3util cp examplefile.txt ks3://bucketName/desPath/ -f fail.txt
./ks3util cp LocalPath/ ks3://bucketName/Path/ -u
cp命令可以将KS3 Bucket中的文件(Object)拷贝至其他Bucket。
./ks3util cp ks3_path ks3_path [--exclude exclude_pattern] <-f fail_keys_file> [--include include_pattern]
以Linux系统为例,在不同Bucket之间拷贝文件。您在实际使用中,请根据您的系统和使用环境修改对应参数。
源Bucket:bucketName1
源Bucket指定目录1:srcPath
源文件:examplefile.txt
目标Bucket:bucketName2
目标Bucket指定目录:desPath
复制单个文件,目标bucket中的文件名与源文件名相同,上传失败的文件列表输出到fail.txt。
./ks3util cp ks3://bucketName1/srcPath/examplefile.txt ks3://bucketName2/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
./ks3util cp ks3://bucketName1/srcPath/ ks3://bucketName2/desPath/
cp命令可以将KS3 bucket中的文件或文件夹,批量下载至本地。
./ks3util cp ks3://bucketName/objectPath LocalPath/ [--config config_file] [--exclude exclude_pattern] <-f fail_keys_file> [--include include_pattern]
以Linux系统为例,将KS3中的文件或文件夹下载至本地。您在实际使用中,请根据您的系统和使用环境修改对应参数。
目标Bucket:bucketName
目标Bucket指定目录:desPath
目标Bucket中的文件:examplefile.txt
本地文件夹:LocalPath(相对目录下的文件夹)
下载单个文件,如果不指定下载到本地的文件名,则默认使用原文件名进行保存;如果指定文件名,则按照指定的文件名保存在本地。下载失败的文件列表输出到fail.txt。
./ks3util cp ks3://bucketName/desPath/examplefile.txt LocalPath/ -f fail.txt
./ks3util cp ks3://bucketName/desPath/ LocalPath/ -f fail.txt
./ks3util cp ks3://bucketName/Path/ LocalPath/ --exclude txt
./ks3util cp ks3://bucketName/Path/ LocalPath/ --include txt
mv命令可以批量移动本地路径下的文件到KS3 bucket中,或者批量移动KS3中的对象到本地,或者在KS3 bucket之间移动对象,移动之后会删除源对象。当移动的文件较大时,mv命令将自动使用分块上传和断点续传。
参数名称 | 是否必填 | 描述 |
---|---|---|
-i | 否 | 当前上传的文件是否移动隐藏文件,枚举值:yes,no(默认) |
-r | 否 | 当前上传的路径是否是相对路径,枚举值:yes,no |
-u,–update | 否 | 只有当目标文件不存在,或源文件的最后修改时间晚于目标文件时,ks3util才会执行上传操作。 |
-z | 否 | 是否将上传的的当前目录名称作为object名称前缀,枚举值:yes,no(默认)。 |
以Linux系统为例,进行移动文件的操作。您在实际使用中,请根据您的系统和使用环境修改对应参数。
本地文件:examplefile.txt(相对目录下的文件)
本地文件夹:LocalPath(相对目录下的文件夹)
目标Bucket:bucketName
目标Bucket指定目录:desPath
移动单个文件到KS3,如果不指定移动至KS3的文件名,则默认使用原文件名进行保存;如果指定文件名,则按照指定的文件名保存在KS3中。移动失败的文件列表输出到fail.txt。
./ks3util mv examplefile.txt ks3://bucketName/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
./ks3util mv LocalPath/ ks3://bucketName/desPath/
./ks3util mv LocalPath/ ks3://bucketName/Path/ --acl PublicRead
./ks3util mv LocalPath/ ks3://bucketName/Path/ --exclude txt
./ks3util mv LocalPath/ ks3://bucketName/Path/ --include txt
./ks3util mv LocalPath/ ks3://bucketName/Path/ --storage-class STANDARD_IA
./ks3util mv LocalPath/ ks3://bucketName/Path/ -u
./ks3util mv ks3://bucketName/desPath/examplefile.txt LocalPath/
输出:下载后的文件路径。
[Download]File write to /home/user/ks3util-1.2.2/LocalPath/examplefile.txt
./ks3util mv ks3://bucketName/desPath/* LocalPath/
./ks3util mv ks3://bucketName1/srcPath/examplefile.txt ks3://bucketName2/desPath/
第一次移动对象时,需要配置目标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
./ks3util mv ks3://bucketName1/srcPath/* ks3://bucketName2/desPath/ -f fail.txt
rm命令用于删除存储空间桶(Bucket)或对象(Object)。
./ks3util rm ks3://bucketName[/objectPath] [-b] [--config] [-exclude] <-f> [--include] [-r]
参数名 | 是否必填 | 描述 |
---|---|---|
-b | 否 | 删除存储空间,删除前请先删除存储空间下的所有对象。 |
以Linux系统为例,删除KS3中的bucket或者object。您在实际使用中,请根据您的系统和使用环境修改对应参数。
文件:examplefile.txt
Bucket:bucketName
删除指定Bucket下的指定object
./ks3util rm ks3://bucketName/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
./ks3util rm ks3://bucketName/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
./ks3util rm ks3://bucketName -b -f fail.txt
multiChangeMeta命令用于批量修改对象元数据信息。
./ks3util multiChangeMeta ks3_path [--acl] [--config] <-f fail_Keys_file> <-i meta_info> <-m metaType> [--storage-class storage_class]
选项名称 | 是否必填 | 描述 |
---|---|---|
-i | 是 | 设置的元数据信息,格式为 key=value#key=value 使用utf-8编码,自定义的元素头将保存为以x-kss-meta开头。 |
-m | 是 | 操作类型,枚举值:add (新增元数据),rewrite (修改元数据)。 |
以Linux系统为例,修改KS3中对象的元数据信息。您在实际使用中,请根据您的系统和使用环境修改对应参数。
文件:examplefile.txt
Bucket:bucketName
对以prefix为开头的所有对象,新增自定义元数据
./ks3util multiChangeMeta ks3://bucketName/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
./ks3util multiChangeMeta ks3://bucketName/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://bucketName/prefix/ -f fail.txt -m rewrite -i yourMetaKey1=yourMetaValue11 --acl PublicRead --storage-class 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
set-acl 指令可以批量设置文件的权限ACL。
./ks3util set-acl ks3://bucketName/prefix --acl Private
选项名称 | 是否必填 | 描述 |
---|---|---|
–acl | 是 | 设置文件的ACL权限,枚举值:Private(私有),PublicRead(公共读),默认Private。 |
以Linux系统为例,修改KS3中对象的元数据信息。您在实际使用中,请根据您的系统和使用环境修改对应参数。
文件:examplefile.txt
Bucket:bucketName
设置单个文件的ACL权限。
./bin/ks3util set-acl ks3://bucketName/examplefile.txt --acl Private
批量设置prefix目录下的多个文件的ACL权限。
./bin/ks3util set-acl ks3://bucketName/prefix --acl Private
Mb命令用于创建一个桶。
./ks3util mb ks3://bucketName
mkdir命令用于创建一个桶。
./ks3util mkdir ks3://bucketName
KS3Util工具最大支持上传多大的文件?
KS3单个文件(对象)最大支持48.8TB。KS3Util上传大文件时,会自动进行切分,通过分块上传的方式上传大文件。
KS3Util工具传输大量文件时,如何提高传输速度?
可适当调整配置文件中的http.max.connections 参数值,来增加并发处理的线程数。
KS3Util工具可以同时管理多个账号的存储空间吗?
KS3Util配置文件中只能配置一个账号,如您需要管理不同账号下的存储空间,可以保存多个账号的配置文件,在执行KS3Util命令时,通过-c参数来指定不同的配置文件,从而达到切换账号的效果。例如
./bin/ks3util ls -b --config 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://bucketName/desPath -f fail.txt --exclude mp4
文档内容是否对您有帮助?
评价建议不能为空
非常感谢您的反馈,我们会继续努力做到更好!