KS3Util命令行工具

最近更新时间:2021-03-01 18:00:15

查看PDF

版本历史

版本号 修改内容 时间
ks3util-1.1.0-dist 包括功能:List、上传、下载、批量下载、批量删除、批量设置ACL 2017年6月2日
ks3util-1.1.1-dist 增加了Bucket统计容量的功能 2017年6月7日
ks3util-1.1.2-dist List命令增加了显示文件大小、文件MD5值的可选项 2018年1月29日
ks3util-1.1.3-dist 修复了批量复制的Bug 2019年5月21日
ks3util-1.2.0-dist(beta) 1:省略配置文件,启动根据提示输入配置信息生成文件
2:将所有指令格式进行统一重构
3:整合get, put,multi-move指令到cp指令(上传下载复制)支持多文件,过滤器以及不同账号桶下的迁移复制操作
4:增加cp指令显示指定路径下各个目录大小
5:ls,du命令列举优化控制台输出信息
2020年12月30日

一、介绍

KS3Util命令行工具为用户提供一个方便的,以命令行方式管理KS3数据的途径。KS3Util提供的功能包括:列出Bucket下所有Object、上传、下载、批量下载、批量删除、批量设置ACL。

二、功能列表

旧版本指令 (v1.1.0 - v1.1.4)

三、运行环境

用户系统需要具备jdk 1.6/1.7/1.8 环境,建议使用Oracle版本JDK

Windows安装jdk1.7

方法参考:环境安装与配置-WIN7下JDK安装与配置

安装完成后,在命令提示符下,执行java –version,来确认是否安装成功
。如下所示,即安装成功

Linux安装jdk1.7

方法参考:环境安装与配置-Linux下JDK安装与配置

安装完成后,在终端下执行java -version,来确认是否安装成功

如下所示,即安装成功

image.png

四、 使用方式

假设work_dir=/your_dir/ 配置文件中请填写绝对路径

1. 解压文件

unzip ks3util-{VERSION}-dist.zip -d ${work_dir}
cd ${work_dir}/ks3util-{VERSION}
chmod 755 bin/ks3util
#运行help命令,查看支持的功能
./bin/ks3util help

2. 填写配置文件xxx.conf

(1.2.0版本起,填写配置文件为非必要步骤)

  • 根据${work_dir}下解压后的sample.conf,创建用户自己新的任务配置文件xxx.conf
  • 如果把配置文件放在用户目录并且命名为.ks3utilconfig(~/.ks3utilconfig),则不需要在命令行中指定配置文件
  • 配置文件中,字段具体含义如下
字段 说明 是否必填
ks3.ak 账户AK,使用KS3控制台生成
ks3.sk 账户SK,使用KS3控制台生成
ks3.endpoint bucket所在region的endpoint,对应列表参看官方文档
ks3.protocol 协议:http|https,默认为http协议
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 批量处理时最小并发数,默认:CPU核数
ks3.movedest.ak multi-move操作时的目标账号AK multi-move操作时必填
ks3.movedest.sk multi-move操作时的目标账号SK multi-move操作时必填
ks3.movedest.endpoint multi-move操作时的目标Bucket所在的endpoint multi-move操作时必填
multipart.threads 批量复制时分块上传的并发数,默认值:50 multi-move操作时选填

3. 命令格式说明

usage: ks3util <command> [ <args> ]

Commands are:
    help         Display help information
    du           Calculate sum of object size
    ls           List ks3 object keys  
    cp           contain functions of upload to      
                 ks3, download a file from ks3, 
                 copy between ks3 buckets
                 (1.2.0 and above) 
    rm           Delete objects in the bucket
    setAcl       Batch set ks3 objects acl
    multiChangeMeta    Batch change metadata   

outdated:Commands are:
    get          Download a file from ks3
    put          Upload a file to ks3
    multi-del    Multi delete ks3 keys
    set-acl      set the ks3 object acl
    multi-move   Batch move from one bucket to another
    multi-get    Batch get objects from a bucket
    multi-change-meta    Batch change metadata
   
   
See 'ks3util help <command>' for more information on a specific command.

五、 命令合集

1. 查看工具支持的命令

描述

help指令用于介绍ks3util各个命令的语法格式。

命令格式

NAME
        ks3util help - Display help information
SYNOPSIS
        ks3util help [ -c <config_file> ] [ {-h | --help} ] [--] [ <command>... ]
OPTIONS
        -c <config_file>
            set ks3/http/asyc properties
        -h, --help
            Display help information
        --
            This option can be used to separate command-line options from the
            list of arguments (useful when arguments might be mistaken for
            command-line options)
        <command>

2. 列举存储空间和对象

描述

ls命令用于列举存储空间(Bucket)、对象(Object)。

命令格式

./ks3util ls [-b]  [ks3://bucket[/prefix]] [-k] [-d] ] [-marker] [-o] [-u] 

常用选项

您可以在使用ls命令时附加如下选项指定列举模式及列举的内容:

选项名称 描述
-k 输入该值时会导出一份objectKey列表文件
-d 返回当前目录下的文件和子目录,而非递归显示所有子目录下的所有Object。
-marker 列举Buckets时的marker,或列举objects或Multipart Uploads时的key marker。
-u 输入该值时会导出一份url列表文件
-o 会在objectKey列表文件输出文件的基础上增加文件信息

使用示例

  • 列举Bucket

    ./ks3util ls -b
    
    ========================= 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:3
                      
    
  • 列举指定Bucket下所有的Object (目前数据可能多 请到输出的文本查看)

    ./ks3util ls ks3://bucket1 -k objectKeys.txt      
    
  • 列举指定Bucket下所有目录

    ./ks3util ls ks3://bucket1 -d
    =========================== Object Dir List===========================
    LastModifiedTime     Size(B)  StorageClass  ObjectName                                                                                                                                                                                                  
    -------------------  -------  ------------  --------------------------------------------
    2020-09-25 13:48:09  0      	STANDARD     	prefix/    
    2020-09-25 13:48:09	 0     	  STANDARD    	prefix/path1/path2/                                                                                                                                              
    2020-09-25 13:48:09  0     		STANDARD      prefix/path1/path2/path3/     
    
    Dir Number is:3
    

3. 对象上传

描述

cp命令用于上传本地路径文件夹下内容到KS3桶路径下 失败的文件写入false.txt文本中 可设置过滤条件(如不下载以.mp4结尾的文件)
【其他源路径填写规则相同】

命令格式

./ks3util cp LocalPath/  ks3://bucketName/Path/ -f false.txt -exclude *.mp4

常用选项

您可以在使用cp命令时附加如下选项指定列举模式及列举的内容:

选项名称 描述 是否必填
-f 导出传输失败的objectKey列表文件
-a 文件的权限,值:Private/ PublicRead
-r 失败重试次数
-include 文件名称白名单,多个用英文逗号分隔。
-exclude 文件名称黑名单,多个用英文逗号分隔。

4. 对象复制

描述

cp命令用于本地上传,KS3下载,KS3桶之间复制对象(Object)

命令格式

./ks3util cp   { ks3_path | local_path }    { ks3_path | local_path  }  -f<fail_keys> -include<include_files> -exclude<don't include files>  -r <retry_times>

常用选项

您可以在使用cp命令时附加如下选项指定列举模式及列举的内容:

选项名称 描述 是否必填
-f 导出传输失败的objectKey列表文件
-r 失败重试次数
-include 文件名称白名单,多个用英文逗号分隔。
-exclude 文件名称黑名单,多个用英文逗号分隔。

使用示例

(需要填写目标桶的相关AKSK和Endpoint)

复制KS3桶中的内容到另一个拥有权限的桶路径下 同时过滤掉某些特定文件

./ks3util cp ks3://bucketName1/path1/ ks3://bucketName2/path2/ -f false.txt -include *.pdf


复制
----------校验复制目标信息----------
【Copy】 objectKey moved: cos/Android.mdsuccess
【Copy】 objectKey moved: cos/COMMIT_EDITMSGsuccess
【Copy】 objectKey moved: cos/HEADsuccess
【Copy】 objectKey moved: cos/JAVA-SDK.mdsuccess
【Copy】 Move done,totalKeys=4,failKeys=0
All files copy over,totalKeys=4,filterFetchNum=0,SuccessTotalNum=4,repeatNum=0,failedNum=0

5. 对象下载

描述

cp命令支持下载KS3桶路径下的文件本地路径文件夹下内容 失败的文件写入false.txt文本中 可设置过滤条件(如只下载以.pdf结尾的文件)

命令格式

./ks3util cp ks3://bucketName/path/ LocalPath/ -f false.txt -include *.pdf
 

常用选项

您可以在使用cp命令时附加如下选项指定列举模式及列举的内容:

选项名称 描述 是否必填
-f 导出传输失败的objectKey列表文件
-r 失败重试次数
-include 文件名称白名单,多个用英文逗号分隔。
-exclude 文件名称黑名单,多个用英文逗号分隔。

6. 文件删除

描述

rm命令用于删除存储空间桶(Bucket)、对象(Object)。 支持过滤操作

命令格式

./ks3util rm  ks3://bucket[/prefix]] [-f] [-b] [-r] [-include] [-exclude]

常用选项

您可以在使用rm命令时附加如下选项指定列举模式及列举的内容:

选项名称 描述 是否必填
-f 输入该值时会导出一份objectKey列表文件
-b 删除一个空桶 (非空会报错)
-r 失败重试次数
-include 文件名称白名单,多个用英文逗号分隔。
-exclude 文件名称黑名单,多个用英文逗号分隔。

使用示例

  • 删除指定Bucket下指定的object

    ./ks3util rm ks3://bucket1/Path/key
    
    delete successed :Path/key
    find 1 object, deleted 1 object,cost 442 ms
    finish multi-del command,totalKeys=1,filter Intercepts=0, failKeys=0 ,Check log for more information     
    
  • 删除指定Bucket下某目录中所有文件

    ./ks3util rm ks3://bucket1/dir/ 
    
    delete successed :dir/1
    delete successed :dir/2
    delete successed :dir/3
    delete successed :dir/4
    delete successed :dir/5
    find 38 object, deleted 38 object,cost 643 ms
    finish multi-del command,totalKeys=38,filter Intercepts=0, failKeys=0 ,Check log for more information
    
  • 删除空的Bucket

    ./ks3util rm ks3://bucket/ -b
    
    deleteBucket  finish
                      
    

7. 修改元数据

描述

multiChangeMeta命令用于批量修改元数据

命令格式

./ks3util multiChangeMeta {-b | --bucket} <bucket_name> [ -c <config_file> ]  [ -m <metaType> ] [ -i <meta_info> ] [ {-h | --help} ] [ -k <key_file> ] [ -f <failKeys_file> ]

常用选项

您可以在使用multiChangeMeta命令时附加如下选项指定列举模式及列举的内容:

选项名称 描述 是否必填
-m 值:add \rewrite 新增或修改元数据
-f 将删除失败的objectkey保存到文件中
-i 设置的元数据信息 格式为 key=value#key=value 使用utf-8编码 key使用x-kss-meta开头
-a 值:Private \ PublicRead

使用示例

  • 下载指定key文件到本地某文件夹路径下
  ./ks3util multiChangeMeta ks3://bucketName/prefix/ -f fail.txt -m add -i x-kss-meta-xxx=xxx
  
    All files change meta success,totalKeys=9,filterFetchKeys=0,failKeys=0

8. 设置ACL

描述

setAcl指令为指定文件设置ACL。 使用新的方式填写配置文件以及bucket 。 支持文件过滤器

命令格式

./ks3util setAcl -a <acl_str>  <ks3Bucket>  -include<>

常用选项

您可以在使用setAcl命令时附加如下选项指定列举模式及列举的内容:

选项名称 描述 是否必填
ks3Bukcet 目标桶的名称 (需要以/结尾)
-a 值:Private | PublicRead
-include 文件名称白名单,多个用英文逗号分隔。
-exclude 文件名称黑名单,多个用英文逗号分隔。

使用示例

  • 批量设置 把目标桶bucketName下包含的所有key 的acl 状态设置成 PublicRead 桶名需要以/为结尾分割

    ./ks3util  setAcl ks3://bucketName/ -a PublicRead
    
    【批量设置ACL】
    finish setAcl command,totalNum=116,filterFetchNum=0,failNum=0,Check log for more information
    

旧版本指令(v1.1.0-v1.1.4)

1. 对象上传

描述

put命令用于上传本地文件至KS3,如果上传的文件大于20MB,会自动启用分块上传,每个分块20MB。

命令格式

./ks3util put [ {-a | --acl} <acl> ] {-b | --bucket} <bucket_name>
                [ -c <config_file> ] [ {-h | --help} ] [--] <local_file> <ks3_key>...

常用选项

您可以在使用put命令时附加如下选项指定列举模式及列举的内容:

选项名称 描述 是否必填
-c 配置文件
-b 用户桶的名称
-a 文件的权限,值:Private | PublicRead 否(默认: Private)
--(local_key) 下载到本地的文件名
--(ks3_key) ks3上的objectkey全名称

使用示例

  • 上传本地指定文件LocalPath/1.txtKS3桶下具体存放在samplePath文件夹下以 2.txt 文本存储 单个文件大小超过20MB,分块上传

    ./ks3util put -b bucketName -c sample.conf -- LocalPath/1.txt samplePath/2.txt
    
    Init multipart upload,UploadId=e953c688ef204801bb0771f9bcd3e8f9
    PartNum:3,upload success
    PartNum:1,upload success
    PartNum:2,upload success
    samplePath/2.txt upload success
    

2. 对象下载

描述

get命令用于下载指定文件。

ks3util get - Download a file from ks3

命令格式

./ks3util get {-b | --bucket} <bucket_name> [ -c <config_file> ]  [ {-h | --help} ] [--] <ks3_key> <local_key>...

常用选项

您可以在使用get命令时附加如下选项指定列举模式及列举的内容:

选项名称 描述 是否必填
-c 配置文件
-b 用户桶的名称
--(ks3_key) ks3上的objectkey全名称
--(local_key) 下载到本地的文件名

使用示例

  • 下载指定key文件到本地某文件夹路径下

    ./ks3util get bucketName -c sample.conf -- key1 LocalPath/
    
    File write to LocalPath/key1
    
  • 下载指定key文件到本地 自定义文件名存储(下载key1文件以key2名字文件存储)

    ./ks3util get bucketName -c sample.conf -- key1 LocalPath/key2
    
    File write to key2/key2
    

3. 批量下载

描述

批量下载指定文件,支持文件过滤器。(由于新版中ls命令无法导出key文本 建议使用新的cp命令)

ks3util multi-get - Batch download

命令格式

./ks3util multi-get -b <bucket_name> [ -c <config_file> ] -f <fail_keys>  [ {-h | --help} ] -k <ks3_keys> [ -p <skip_line_num> ] -s <save_dirs>   [ -include <files_include> ]  [ -exclude <files_exclude> ] 

常用选项

您可以在使用multi-get命令时附加如下选项指定列举模式及列举的内容:

选项名称 描述 是否必填
-c 配置文件
-b 用户桶的名称
-f 将删除失败的objectkey保存到文件中
-k 包含objectkey的文件,每行一个objectkey
-s 下载至本地的文件夹目录,多个目录以“,”分隔
-p 跳过ks3_keys文件中的前N行不执行
-include 文件名称白名单,多个用英文逗号分隔
-exclude 文件名称黑名单,多个用英文逗号分隔

使用示例

  • 把list.txt中的路径key批量下载到本地路径 localPath/ 中 失败的key写入false.txt中

    ./ks3util multi-get bucketName -c sample.conf  -f false.txt -k list.txt -s localPath/ 
    
    ......
    ......
    All files download success,totalKeys=13,skipKeys=0,successKeys=13,failKeys=0
    
  • 把list.txt中的路径key批量随机下载到本地路径 localPath/1/,localPath/2/ 两个文件夹中, 失败的key写入false.txt中 跳过前9行不下载 从第十行key开始下载 , 且只下载.pdf 后缀的文件

    ./ks3util multi-get bucketName -c sample.conf  -f false.txt -k list.txt -s localPath/1/, localPath/2/ -p 10 -include *.pdf 
    
    
    1,skip,Maven/2019年多家公司整理的350道Java面试题手册.pdf
    2,skip,xxx.pdf
    3,skip,xxx.pdf
    4,skip,xxx.pdf
    5,skip,xxx.pdf
    6,skip,xxx.pdf
    7,skip,xxx.pdf
    8,skip,xxx.pdf
    9,skip,xxx.pdf
    14,xxx.pdf
    15,xxx.pdf
    --------
    111,xxx.pdf
    All files download success,totalKeys=115,skipKeys=10,successKeys=88,failKeys=18
    

4. 对象删除

描述

删除某个bucket下指定文件。
(由于新版中ls命令无法导出key文本 建议使用新的rm命令)

 ks3util multi-del - Multi delete ks3 keys

命令格式

./ks3util multi-del -b <bucket_name> [ -c <config_file> ] -f <fail_keys>  [ {-h | --help} ] -k <ks3_keys>

常用选项

您可以在使用multi-del命令时附加如下选项指定列举模式及列举的内容:

选项名称 描述 是否必填
-c 配置文件
-b 用户桶的名称
-f 将删除失败的objectkey保存到文件中
-k 包含objectkey的文件,每行一个objectkey
-include 文件名称白名单,多个用英文逗号分隔
-exclude 文件名称黑名单,多个用英文逗号分隔

使用示例

  • 把list.txt中的路径key批量删除 失败的key写入false.txt中

    ./ks3util multi-del bucketName -c sample.conf  -f false.txt -k list.txt
    
    finish multi-del commond,totalKeys=13,failKeys=6
    

5. 对象转移

描述

一个bucket的指定文件复制到另一个bucket,两个bucket可以在不同的region。

使用这个功能,conf文件中需要加入三个参数:

 ks3util multi-move - Batch move frome one bucket to another

命令格式

./ ks3util multi-move -b <src_bucket_name> -B <dst_bucket_name> [ -c <config_file> ] -f <fail_keys> [ {-h | --help} ] -k <ks3_keys>  [ -p <ks3Parts> ]

常用选项

您可以在使用 multi-move命令时附加如下选项指定列举模式及列举的内容:

选项名称 描述 是否必填
-c 配置文件
-b 源桶的名称
-B 目标桶的名称
-f 将删除失败的objectkey保存到文件中
-k 包含objectkey的文件,每行一个objectkey
-p 复制失败的ks3Parts保存到文件中

使用示例

  • 把list.txt中 存在在bucketName桶下的文件key 批量复制到bucketName2桶下

    ./ks3util multi-move -b bucketName -B bucketName2  -c sample.conf  -f false.txt -k list.txt
    
    objkey moved: xxx.pdf
    objkey moved: xxx.txt
    -------------------
    objkey moved: xxx.md
    objkey moved: xxx.xmind
    Move done,totalKeys=115,failKeys=0
    

6. 修改元数据

描述

multi-change-meta命令用于批量修改元数据

ks3util multi-change-meta - Batch change user meta

命令格式

./ks3util multi-change-meta {-b | --bucket} <bucket_name> [ -c <config_file> ]  [ -m <metaType> ] [ -i <meta_info> ] [ {-h | --help} ] [ -k <key_file> ] [ -f <failKeys_file> ]

使用示例

  • 修改指定key文件中的key元数据

    ./ks3util multi-change-meta -b bucketName -c sample.conf -f fail.txt  -k keys.txt -m add -i x-kss-meta-xxx=xxx
    
    1,aws/1.jpg
    All files change meta success,totalKeys=1,skipKeys=0,failKeys=0
    

7. 设置ACL

描述

set-acl指令为指定文件设置ACL。

ks3util set-acl - Batch set ks3 objects acl

命令格式

./ks3util set-acl -a <acl_str> -b <bucket_name> [ -c <config_file> ]  [ {-h | --help} ] -k <ks3_keys>

常用选项

您可以在使用multi-change-meta命令时附加如下选项指定列举模式及列举的内容:

选项名称 描述 是否必填
-c 配置文件
-b 用户桶的名称
-k 包含objectkey的文件,每行一个objectkey
-m 值:add \rewrite 新增或修改元数据
-f 将删除失败的objectkey保存到文件中
-a 值:Private \ PublicRead
-i 设置的元数据信息 格式为 key=value#key=value 使用utf-8编码 key使用x-kss-meta开头
-p 跳过n行key文件中的数据

常用选项

您可以在使用set-acl命令时附加如下选项指定列举模式及列举的内容:

选项名称 描述 是否必填
-c 配置文件
-b 目标桶的名称
-B 源桶的名称
-k 包含objectkey的文件,每行一个objectkey
-a 值:Private | PublicRead
-f 是否使用源桶中key的acl值(从源桶复制过来的可以使用yes)

使用示例

  • 批量设置 把目标桶bucketName下在list.txt文本下包含的所有key的acl 状态设置成 PublicRead

    ./ks3util  set-acl -b bucketName -k list.txt -a PublicRead -f false.txt -f no -c default.conf
    
    finish set-acl command,totalNum=115,failNum=0
    

六、 日志和运行情况

会在命令执行目录下创建logs目录,如有问题请将info.log,warn.log,error.log发给ks3售前(后)咨询

文档内容是否对您有帮助?

根本没帮助
文档较差
文档一般
文档不错
文档很好

在文档使用中是否遇到以下问题

  • 内容不全,不深入
  • 内容更新不及时
  • 描述不清晰,比较混乱
  • 系统或功能太复杂,缺乏足够的引导
  • 内容冗长

更多建议

0/200

评价建议不能为空

提交成功!

非常感谢您的反馈,我们会继续努力做到更好!