对象存储(KS3)

      文档中心 对象存储(KS3) 测试与工具 工具 KS3Util命令行工具

      KS3Util命令行工具

      最近更新时间：2021-05-08 17:27:59

      查看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操作时选填
      multipart.partsize 上传文件过大时可以客户自行添加下该配置项，修改分块上传参数：分块上传块大小 ，单位为Byte 否
      bigFile.threshold 上传文件过大时可以客户自行添加下该配置项，修改分块上传参数：分块上传文件大小阈值，大于该值使用分块上传 ，单位为Byte 否

      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 - Batch change user meta

      命令格式

      ./ks3util multiChangeMeta { ks3_path }  [ -m <metaType> ] [ -i <meta_info> ] [ {-h | --help} ] [ -f <failKeys_file> ] [ -s <storage_type> ] [ -a <acl> ]

      使用示例

      • 修改指定桶下路径中文件的元素头 修改失败的放入fail.txt文件中，可同时修改访问权限（使用-a参数）以及存储类型（使用-s参数）
       # 修改桶 bucketName 中 prefix 目录下的文件头元素 新增两个元素头：key为yourMetaKey1，yourMetaKey2，value为yourMetaValue1，yourMetaValue2
  ./ks3util multiChangeMeta ks3://bucketName/prefix/ -f fail.txt -m add -i yourMetaKey1=yourMetaValue1#yourMetaKey2=yourMetaValue2
  
 # 修改桶 bucketName 中 prefix 目录下的文件头元素 修改原有的两个元素头：key为yourMetaKey1，value为yourMetaValue1
  ./ks3util multiChangeMeta ks3://bucketName/prefix/ -f fail.txt -m rewrite -i yourMetaKey1=yourMetaValue1
  
 # 修改桶 bucketName 中 prefix 目录下的文件头元素 修改原有的两个元素头：key为yourMetaKey1，value为yourMetaValue1 同时设置ACL为公开：且存储类型设置为低频
 ./ks3util multiChangeMeta ks3://bucketName/prefix/ -f fail.txt -m rewrite -i yourMetaKey1=yourMetaValue1 -a PublicRead -s STANDARD_IA
  
    All files change meta success,totalKeys=9,filterFetchKeys=0,failKeys=0

      常用选项

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

      选项名称 描述 是否必填
      -m 值：add \rewrite 新增或修改元数据 是
      -f 将删除失败的objectkey保存到文件中 是
      -i 设置的元数据信息 格式为 key=value#key=value 使用utf-8编码 自定义的元素头将保存为x-kss-meta开头 是
      -a 文件访问权限ACL 值：Private \ PublicRead 否
      -s 文件存储类型 值：STANDARD \ STANDARD_IA \ ARCHIVE 否

      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.txt 到KS3桶下具体存放在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售前(后)咨询

      上一篇：KS3-import数据迁移工具
      下一篇：KS3可视化签名工具

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

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

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

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

      更多建议

      0/200

      评价建议不能为空

      提交成功！

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

      问题反馈