KS3Util 新版命令行工具

ks3util2.0支持在Windows、Linux、macOS系统上通过命令行方式管理KS3数据。

版本和运行环境

• 版本

  • 当前版本：2.1.0

• 运行环境

  • Windows、Linux、macOS
  • 支持架构：x86(64bit)、ARM(64bit)

• 点击下载

安装与配置

在Windows上安装

1. 根据操作系统及架构下载对应版本，假设下载的文件为`D:\Downloads\ks3util.exe

2. 打开cmd，执行以下命令切换到目标文件夹

   cd D:\Donwloads\
   

3. 运行以下命令，验证是否已成功安装ks3util。

   .\ks3util.exe
   

   如果终端输出ks3util所有支持的命令，表明已经成功安装ks3util。

4. 运行以下命令，生成ks3util配置文件。

   .\ks3util.exe config
   

   根据提示输入相应信息即可，当执行ks3util其他命令时就可以使用-c选项指定该配置文件。

在Linux、macOS上安装

1. 根据操作系统及架构下载对应版本，假设下载的文件为~/Downloads/ks3util

2. 运行以下命令修改文件执行权限。

   cd ~/Downloads/
   chmod 755 ks3util
   

3. 运行以下命令，验证是否已成功安装ks3util。

   ./ks3util
   

   如果终端输出ks3util所有支持的命令，表明已经成功安装ks3util。

4. 运行以下命令，生成ks3util配置文件。

   ./ks3util config
   

   根据提示输入相应信息即可，当使用ks3util其他命令时就可以使用-c选项指定该配置文件。

通用选项

以下为ks3util的通用选项，可以在大部分命令中使用：

选项	说明
-c, --config-file	ks3util工具的配置文件路径，ks3util启动时从配置文件读取配置，在config命令中，ks3util将配置写入该文件。
-e, --endpoint	ks3util工具的基本endpoint配置（该选项值会覆盖配置文件中的相应设置），注意其必须为一个二级域名，例如：ks3-cn-beijing.ksyuncs.com。
-i, --access-key-id	访问ks3使用的AccessKeyID（该选项值会覆盖配置文件中的相应设置）。
-k, --access-key-secret	访问ks3使用的AccessKeySecret（该选项值会覆盖配置文件中的相应设置）。
-r, --recursive	递归进行操作。对于支持该选项的命令，当指定该选项时，命令会对指定目录下所有符合条件的文件进行操作，否则只对指定的单个文件进行操作。
-f, --force	强制操作，不进行询问提示。
--retry-times	当错误发生时的重试次数，默认值：10，取值范围：1-500
--loglevel	日志级别，默认为空,表示不输出日志文件,可选值为:info | debug, info输出提示信息日志, debug输出详细信息日志(包括http请求和响应信息)
--read-timeout	表示客户端读超时的时间，单位为秒, 缺省值为1200
--connect-timeout	表示客户端连接超时的时间，单位为秒, 缺省值为120
--include	包含对象匹配模式，如：*.jpg
--exclude	不包含对象匹配模式，如：*.txt
-j, --jobs	多文件操作时的并发任务数，默认值：3，取值范围：1-10000
--parallel	单文件内部操作的并发任务数，取值范围：1-10000, 默认将由ks3util根据操作类型和文件大小自行决定。
-L, --language	设置ks3util工具的语言。取值如下：EN：英文；CH（默认值）：中文。设置为CH时，请确保您的系统编码方式为UTF-8。

--include和--exclude

--include和--exclude规则支持以下格式：

• *：匹配所有字符。例如：*.txt表示匹配所有TXT格式的文件。
• ?：匹配单个字符。例如：file?.txt表示匹配file+任意一个字符的txt文件，如：file2.txt。
• [sequence]：匹配sequence的任意字符，例如：abc[1-5].jpg表示匹配文件名为abc1.jpg~abc5.jpg的文件。
• [!sequence]：匹配不在sequence的任意字符，例如：abc[!1-5].jpg表示匹配文件名不为abc1.jpg~abc5.jpg的文件。

--include和--exclude可以出现多次。每个文件从左到右逐一运用每个规则，直至最后才能最终确定匹配的结果。例如指定生效的文件夹中包含名为file5.txt的文件，匹配不同的规则产生的结果如下。

• 规则一：--include *file* --exclude \*.txt，当规则匹配到--include *file*，匹配的结果为file5.txt符合条件；当规则继续匹配到--exclude *.txt时，因file5.txt文件名包含.txt，所以被排除；则匹配的最终结果为file5.txt不符合条件。

• 规则二：--exclude *.txt --include *file*，当规则匹配到--exclude *.txt，匹配的结果为file5.txt不符合条件；当规则继续匹配到--include *file*，因file5.txt文件名包含file，所以符合条件；则匹配的最终结果为file5.txt符合条件。

• 规则三：--include *file* --exclude *.txt --include file?.txt ，当规则匹配到--include *file*，匹配的结果为file5.txt符合条件；当规则继续匹配到--exclude *.txt时，因file5.txt文件名包含.txt，所以被排除；当规则最后匹配到--include file?.txt时，因file5.txt符合条件，所以被包含；则匹配的最终结果为file5.txt符合条件。

注意：规则不支持带目录的格式，例如：--include /usr/*/test/*.jpg。

常用命令

本文档的例子如无特别说明，均假设在Linux系统，下载的KS3Util工具的文件名为ks3util。

help（帮助信息）

help命令用来获取命令的帮助信息，当您不清楚某个命令的用法时，建议您使用help命令获取该命令的帮助信息。

• 命令格式

  ./ks3util help [command]
  

• 使用示例

  • 获取ks3util支持的所有命令

    ./ks3util help
    

  • 查看所有选项信息

    ./ks3util help -h
    

  • 查看某个命令的帮助信息，如：cp命令

    ./ks3util help cp
    

config（创建配置文件）

config命令用于创建配置文件，存储KS3访问信息，在使用其他命令时添加-c选项，ks3util将通过指定的配置来访问KS3。

• 命令格式
  该命令有交互式和非交互式两种用法。交互式用法为用户根据提示输入相应信息，命令结束时生成配置文件。非交互式则需要通过选项来指定需要的配置项。相比非交互式用法，交互式用法具有更高的安全性。

  如果您使用命令时输入了除-L, --languange和-c, --config-file以外的任意选项，则进入非交互式模式，所有的配置项需通过选项来指定。

  ./ks3util config 
  [-e, --endpoint <value>] 
  [-i, --access-key-id <value>] 
  [-k, --access-key-secret <value>] 
  [-L, --language <value>] 
  [--output-dir <value>] 
  [-c, --config-file <value>]
  

  各选项说明如下：

  选项	说明
  -e, --endpoint	ks3util工具的基本endpoint配置（该选项值会覆盖配置文件中的相应设置），注意其必须为一个二级域名，如：ks3-cn-beijing.ksyuncs.com
  -i, --access-key-id	访问ks3使用的AccessKeyID（该选项值会覆盖配置文件中的相应设置）。
  -k, --access-key-secret	访问ks3使用的AccessKeySecret（该选项值会覆盖配置文件中的相应设置）。
  -L, --language	指定语言。CH（默认值）：中文。EN：英文。设置为CH时，请确保您的系统编码方式为UTF-8。
  --output-dir	指定输出文件所在的目录，输出文件目前包含：cp命令批量拷贝文件出错时所产生的report文件。默认值为：当前目录下的ks3util_output目录。
  -c, --config-file	ks3util工具的配置文件路径，ks3util启动时从配置文件读取配置，在config命令中，ks3util将配置写入该文件。

• 使用示例

  • 交互式用法

    ./ks3util config
    该命令创建将一个配置文件，在其中存储配置信息。
    
    请输入配置文件名,文件名可以带路径(默认为：/home/user/.ks3utilconfig，回车将使用默认配置文件。如果用户设置为其它文件，在使用命令时需要将--config-file选项设置为该文件）：my_ks3util.conf
    对于下述配置，回车将跳过相关配置项的设置，配置项的具体含义，请使用"help config"命令查看。
    请输入语言(CH/EN，默认为：CH，该配置项将在此次config命令成功结束后生效)：CH
    请输入endpoint：ks3-cn-beijing.ksyuncs.com
    请输入accessKeyID：my-access-key-id
    请输入accessKeySecret：my-access-key-secret
    

  • 非交互式用法

    ./ks3util config -e ks3-cn-beijing.ksyuncs.com -i my-access-key-id -k my-access-key-secret -L CH -c my_ks3util.conf
    

  • 编辑配置文件
    对于已经生成的配置文件，您也可以通过直接修改配置文件来修改KS3访问信息。ks3util工具的配置文件格式如下：

    [Credentials]
        language = CH
        endpoint = ks3-cn-beijing.ksyuncs.com
        accessKeyID = your_key_id
        accessKeySecret = your_key_secret
        outputDir = your_output_dir
    

ls（列举资源）

您可以使用ls命令列举当前账号下的存储空间（Bucket）、对象（Object）和碎片（Part）信息。

列举Bucket

• 命令格式

  ./ks3util ls [-s, --short-format] [--limited-num <value>]
  

  各选项说明如下：

  选项	说明
  -s, --short-format	显示精简格式，如果未指定该选项，默认显示长格式。
  --limited-num	返回结果的最大个数。

• 使用示例

  • 列举所有Bucket

    ./ks3util ls
    

    以下输出结果表明已成功列举当前账号下所有Bucket，包括Bucket名称、创建时间、所在地域、存储类型、数量等信息。

    CreationTime                             Region     StorageClass    BucketName
    2021-12-02 17:03:21.811 +0800 CST        BEIJING    NORMAL          ks3://sampleBucket1
    2022-08-15 16:02:43.007 +0800 CST        SHANGHAI   ARCHIVE         ks3://sampleBucket2
    Bucket Number is: 2
    
    0.112480(s) elapsed
    

  • 以精简模式列举所有Bucket

    ./ks3util ls -s
    

    以下输出结果表明已成功列举出所有Bucket，仅包含Bucket名称及Bucket数量。

    ks3://sampleBucket1
    ks3://sampleBucket2
    ks3://sampleBucket3
    Bucket Number is: 3
    
    0.083726(s) elapsed
    

列举Object

• 命令格式

  ./ks3util ls ks3://bucketname[/prefix] 
  [-s, --short-format] 
  [-d, --directory] 
  [--limited-num <value>] 
  [--marker <value>] 
  [--include <value>] 
  [--exclude <value>]
  

  参数及选项说明如下：

  配置项	说明
  bucketname	目标桶名称。
  prefix	目标Object前缀，当列举目标Bucket中指定前缀的Object时添加此项。
  -s, --short-format	显示精简格式，如果未指定该选项，默认显示长格式。
  -d, --directory	返回当前目录下的文件和子目录，而非递归显示所有子目录下的所有object。
  --limit-num	返回结果的最大个数。
  --marker	列举名称字母排序在marker之后的Object。
  --include	包含对象匹配模式，如：*.jpg
  --exclude	不包含对象匹配模式，如：*.txt

• 使用示例

  • 列举sampleBucket中的所有文件

    ./ks3util ls ks3://sampleBucket
    

  • 列举sampleBucket中前缀为abc的所有文件

    ./ks3util ls ks3://sampleBucket/abc
    

  • 列举sampleBucket中所有后缀名为.jpg的文件

    ./ks3util ls ks3://sampleBucket --include *.jpg
    

  • 仅列举sampleBucket根目录下所有Object和子目录

    ./ks3util ls ks3://sampleBucket -d
    

列举碎片

• 命令格式

  ./ks3util ls ks3://bucketname[/prefix] -m 
  [-s, --short-format] 
  [-d, --directory] 
  [--limited-num <value>] 
  [--marker <value>] 
  [--include <value>] 
  [--exclude <value>]
  

  参数及选项说明如下：

  配置项	说明
  bucketname	目标桶名称。
  prefix	列举指定前缀下的Part。
  -m, --multipart	列举Part。
  -s, --short-format	显示精简格式，如果未指定该选项，默认显示长格式。
  -d, --directory	返回当前目录下的文件和子目录，而非递归显示所有子目录下的所有Part。
  --limit-num	返回结果的最大个数。
  --marker	列举名称字母排序在marker之后的Part。
  --include	包含对象匹配模式，如：*.jpg
  --exclude	不包含对象匹配模式，如：*.txt

• 使用示例

  • 列举sampleBucket中所有的Part

    ./ks3util ls ks3://sampleBucket -m 
    

  • 列举sampleBucket中前缀为abc的所有Part

    ./ks3util ls ks3://sampleBucket/abc -m 
    

  • 列举sampleBucket中后缀为.jpg的所有Part

    ./ks3util ls ks3://sampleBucket -m --include *.jpg
    

cp（上传、下载、复制文件）

cp命令用于上传、下载、复制文件。

上传文件

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

• 命令格式

  ./ks3util cp file_url cloud_url 
  [-r, --recursive] 
  [-f, --force] 
  [-u, --update]
  [--bigfile-threshold <value>]
  [--part-size <value>]
  [--only-current-dir]
  [--acl <value>]
  [--meta <value>]
  [--tagging <value>]
  [--include <value>]
  [--exclude <value>]
  [-j, --jobs <value>]
  [--parallel <value>]
  [--checkpoint-dir <value>]
  

  参数及选项说明如下：

  配置项	说明
  file_url	本地文件或目录路径
  cloud_url	KS3文件路径，格式为ks3://bucketname/objectname
  -r, --recursive	递归进行操作。对于支持该选项的命令，当指定该选项时，命令会对目录下所有符合条件的文件进行操作，否则只对file_url中指定的单个文件进行操作。
  -f, --force	强制操作，不进行询问提示。
  -u, --update	更新操作，只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，ks3util才会执行上传操作。
  --bigfile-threshold	开启大文件断点续传的文件大小阈值，单位为Byte，默认值:104857600(100M)，取值范围：0-9223372036854775807(Byte)
  --part-size	分片大小，单位为Byte，默认情况下ks3util根据文件大小自行计算合适的分片大小值。如果有特殊需求或者需要性能调优，可以设置该值，取值范围：1-9223372036854775807(Byte)
  --only-current-dir	表示仅操作当前目录下的文件, 忽略子目录
  --acl	acl信息的配置。
  --meta	设置object的meta为[header:value#header:value…]，如：Cache-Control:no-cache#Content-Encoding:gzip
  --tagging	设置object的tagging，取值格式如["TagA=A&TagB=B..."]，注意：需要使用双引号。
  --include	包含对象匹配模式，如：*.jpg
  --exclude	不包含对象匹配模式，如：*.txt
  -j, --jobs	多文件操作时的并发任务数，默认值：3，取值范围：1-10000
  --parallel	单文件内部操作的并发任务数，取值范围：1-10000, 默认将由ks3util根据操作类型和文件大小自行决定。
  --checkpoint-dir	checkpoint目录的路径(默认值为:.ks3util_checkpoint)，断点续传时，操作失败ks3util会自动创建该目录，并在该目录下记录checkpoint信息，操作成功会删除该目录。如果指定了该选项，请确保所指定的目录可以被删除。

• 使用示例

  • 上传单个文件
    上传文件时，如果没有指定上传到KS3的文件名，则使用原文件名；如果指定了文件名，则使用指定的文件名。

    ./ks3util cp sample.txt ks3://samplebucket/dest_prefix/
    

  • 上传文件夹内的文件
    将文件夹（包括子文件夹）内的文件上传至KS3指定路径。

    ./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r 
    

  • 上传文件夹及文件夹内的文件
    将文件夹本身以及文件夹（包括子文件夹）内的文件上传至KS3指定路径。

    ./ks3util cp local_dir ks3://samplebucket/dest_prefix/local_dir/ -r 
    

  • 仅上传当前目录下的文件，忽略子目录下的文件

    ./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 --meta X-Kss-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"
    

  • 上传符合条件的文件
    批量上传时，如果指定--include和--exclude选项，ks3util会上传符合指定条件的文件。--include和--exclude的说明请参见通用选项。

    ./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --include *.mp4
    

下载文件

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

• 命令格式

  ./ks3util cp cloud_url file_url
  [-r, --recursive] 
  [-f, --force] 
  [-u, --update]
  [--bigfile-threshold <value>]
  [--part-size <value>]
  [--include <value>]
  [--exclude <value>]
  [-j, --jobs <value>]
  [--parallel <value>]
  [--checkpoint-dir <value>]
  

  参数及选项说明如下：

  配置项	说明
  file_url	本地文件或目录路径
  cloud_url	KS3文件路径，格式为ks3://bucketname/objectname
  -r, --recursive	递归进行操作。对于支持该选项的命令，当指定该选项时，命令会对目录下所有符合条件的文件进行操作，否则只对file_url中指定的单个文件进行操作。
  -f, --force	强制操作，不进行询问提示。
  -u, --update	更新操作，只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，ks3util才会执行上传操作。
  --bigfile-threshold	开启大文件断点续传的文件大小阈值，默认值:100M，取值范围：0B-9223372036854775807B
  --part-size	分片大小，单位为Byte，默认情况下ks3util根据文件大小自行计算合适的分片大小值。如果有特殊需求或者需要性能调优，可以设置该值，取值范围：1-9223372036854775807(Byte)
  --only-current-dir	表示仅操作当前目录下的文件, 忽略子目录
  --include	包含对象匹配模式，如：*.jpg
  --exclude	不包含对象匹配模式，如：*.txt
  -j, --jobs	多文件操作时的并发任务数，默认值：3，取值范围：1-10000
  --parallel	单文件内部操作的并发任务数，取值范围：1-10000, 默认将由ks3util根据操作类型和文件大小自行决定。
  --checkpoint-dir	checkpoint目录的路径(默认值为:.ks3util_checkpoint)，断点续传时，操作失败ks3util会自动创建该目录，并在该目录下记录checkpoint信息，操作成功会删除该目录。如果指定了该选项，请确保所指定的目录可以被删除。

• 使用示例

  • 下载单个文件
    没有指定文件名，则使用原文件名保存到本地。

    ./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选项选择符合条件的文件下载。--include和--exclude选项的用法参见通用选项。

    ./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r --include *.jpg --exclude *screenshot*
    

复制文件

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

• 命令格式

  ./ks3util cp file_url cloud_url 
  [-r, --recursive] 
  [-f, --force] 
  [-u, --update]
  [--bigfile-threshold <value>]
  [--part-size <value>]
  [--only-current-dir]
  [--acl <value>]
  [--meta <value>]
  [--tagging <value>]
  [--include <value>]
  [--exclude <value>]
  [-j, --jobs <value>]
  [--parallel <value>]
  [--checkpoint-dir <value>]
  

  参数及选项说明如下：

  配置项	说明
  file_url	本地文件或目录路径
  cloud_url	KS3文件路径，格式为ks3://bucketname/objectname
  -r, --recursive	递归进行操作。对于支持该选项的命令，当指定该选项时，命令会对目录下所有符合条件的文件进行操作，否则只对file_url中指定的单个文件进行操作。
  -f, --force	强制操作，不进行询问提示。
  -u, --update	更新操作，只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，ks3util才会执行上传操作。
  --bigfile-threshold	开启大文件断点续传的文件大小阈值，默认值:100M，取值范围：0B-9223372036854775807B
  --part-size	分片大小，单位为Byte，默认情况下ks3util根据文件大小自行计算合适的分片大小值。如果有特殊需求或者需要性能调优，可以设置该值，取值范围：1-9223372036854775807(Byte)
  --only-current-dir	表示仅操作当前目录下的文件, 忽略子目录
  --acl	acl信息的配置。
  --meta	设置object的meta为[header:value#header:value…]，如：Cache-Control:no-cache#Content-Encoding:gzip
  --tagging	设置object的tagging，取值格式如["TagA=A&TagB=B..."]，注意：需要使用双引号。
  --include	包含对象匹配模式，如：*.jpg
  --exclude	不包含对象匹配模式，如：*.txt
  -j, --jobs	多文件操作时的并发任务数，默认值：3，取值范围：1-10000
  --parallel	单文件内部操作的并发任务数，取值范围：1-10000, 默认将由ks3util根据操作类型和文件大小自行决定。
  --checkpoint-dir	checkpoint目录的路径(默认值为:.ks3util_checkpoint)，断点续传时，操作失败ks3util会自动创建该目录，并在该目录下记录checkpoint信息，操作成功会删除该目录。如果指定了该选项，请确保所指定的目录可以被删除。

• 使用示例

  • 复制单个文件
    如果没有指定目标文件名，则使用原文件名保存

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

    如果指定了目标文件名，则使用指定的文件名保存

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

  • 按目录复制
    复制目录下所有文件，包括子目录

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

    当批量复制失败或需要增量复制时，可以使用--update（可缩写为-u）选项跳过已存在且最后修改时间晚于原文件的文件。

    ./ks3util ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r -u
    

    仅复制当前目录下的文件，忽略子目录

    ./ks3util ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --only-current-dir
    

  • 按条件复制
    使用--include和--exclude选项复制符合匹配规则的文件，--include和--exclude选项的使用方法参见通用选项

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

  • 修改文件读写权限ACL

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

  • 修改文件读存储类型

    ./ks3util ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --meta X-Kss-Meta-Storage-Class:STANDARD_IA
    

  • 修改文件标签

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

  • 修改文件meta

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

rm（删除）

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

• 命令格式

  ./ks3util rm ks3://bucketname[/prefix]
  [-r, --recursive] 
  [-f, --force] 
  [-b, --bucket]
  [-m, --multipart]
  [--include <value>]
  [--exclude <value>]
  

  参数及选项说明如下：

  配置项	说明
  bucketname	操作的桶名
  prefix	操作的对象的前缀
  -r, --recursive	递归进行操作。对于支持该选项的命令，当指定该选项时，命令会对目录下所有符合条件的文件进行操作，否则只对file_url中指定的单个文件进行操作。
  -f, --force	强制操作，不进行询问提示。
  -b, --bucket	对bucket进行操作，该选项用于确认操作作用于bucket
  -m, --multipart	指定操作的对象为bucket中未完成的Multipart事件，而非默认情况下的object。
  --include	包含对象匹配模式，如：*.jpg
  --exclude	不包含对象匹配模式，如：*.txt

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

删除文件

• 删除单个文件

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

• 批量删除文件
  删除指定前缀的文件

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

  按匹配条件删除，--include和--exclude选择的用法参见通用选项

  ./ks3util rm ks3://samplebucket/src-prefix/ -r --include *screenshot* --exclude *important*
  

删除碎片

• 删除单个文件未完成的Multipart事件产生的Part

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

• 批量删除Part
  删除指定前缀的所有文件未完成的Multipart事件产生的Part

  ./ks3util rm ks3://samplebucket/src-prefix/ -m -r
  

  删除匹配条件的文件未完成的Multipart事件产生的Part，--include和--exclude选择的用法参见通用选项

  ./ks3util rm ks3://samplebucket/src-prefix/ -m -r --include *screenshot* --exclude *important*
  

删除桶

• 删除空桶
  删除桶前请确保桶内文件和未完成的Multipart事件产生的Part，自定义域名、空间策略、区域复制等已删除。

  ./ks3util rm ks3://samplebucket -b
  

• 删除所有文件然后删除桶

  ./ks3util rm ks3://samplebucket -b -r 
  

set-acl（设置或修改ACL）

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

• 命令格式

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

  参数及选项说明如下：

  配置项	说明
  bucketname	操作的桶名
  prefix	操作的对象的前缀
  acl	读写权限ACL，可选值：private, public-read
  -r, --recursive	递归进行操作。对于支持该选项的命令，当指定该选项时，命令会对目录下所有符合条件的文件进行操作，否则只对指定的单个文件进行操作。
  -f, --force	强制操作，不进行询问提示。
  -b, --bucket	对bucket进行操作，该选项用于确认操作作用于bucket
  --include	包含对象匹配模式，如：*.jpg
  --exclude	不包含对象匹配模式，如：*.txt
  -j, --jobs	多文件操作时的并发任务数，默认值：3，取值范围：1-10000

• 使用示例

  • 给bucket设置acl

    ./ks3util set-acl ks3://samplebucket private -b
    

  • 给单个文件设置acl

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

  • 批量设置acl
    批量给指定前缀的文件设置acl

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

    批量给符合匹配规则的文件设置acl，--include和--exclude的用法参见通用选项

    ./ks3util set-acl ks3://samplebucket/src-prefix/ private -r --include *screenshot* --exclude *important*
    

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>]
  [-j, --jobs]
  

  参数及选项说明如下：

  配置项	说明
  bucketname	操作的桶名
  prefix	操作的对象的前缀
  meta	文件元信息，格式：header:value#header:value。header不区分大小写，但value区分大小写。
  -r, --recursive	递归进行操作。对于支持该选项的命令，当指定该选项时，命令会对目录下所有符合条件的文件进行操作，否则只对指定的单个文件进行操作。
  -f, --force	强制操作，不进行询问提示。
  -u, --update	更新操作。
  --delete	删除指定的元信息
  --include	包含对象匹配模式，如：*.jpg
  --exclude	不包含对象匹配模式，如：*.txt
  -j, --jobs	多文件操作时的并发任务数，默认值：3，取值范围：1-10000

  可选的header列表如下：

  • Expires
  • Content-Type
  • Cache-Control
  • Content-Encoding
  • Content-Disposition
  • X-Kss-Storage-Class
  • 以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-Storage-Class:STANDARD#X-Kss-Meta-A:1
    

    给指定前缀的所有文件设置meta

    ./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#X-Kss-Storage-Class:STANDARD#X-Kss-Meta-A:1 -r
    

    给匹配条件的所有文件设置meta，--include和--exclude的用法参见通用选项

    ./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#X-Kss-Storage-Class:STANDARD#X-Kss-Meta-A:1 -r --include *.jpg --exclude screenshot*
    

  • 更新文件meta

    如果用户设置--update选项，ks3util会更新指定objects的指定header为输入的value值，其中value可以为空，value为空时，表示保留原有的value值。未指定的header的value值不会改变。此时不支持--delete选项。

    给单个文件更新meta

    ./ks3util set-meta ks3://samplebucket/src-prefix/sample.txt Cache-Control:no-cache#X-Kss-Storage-Class:STANDARD#X-Kss-Meta-A:1 -u
    

    给指定前缀的所有文件更新meta

    ./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#X-Kss-Storage-Class:STANDARD#X-Kss-Meta-A:1 -r -u
    

    给匹配条件的所有文件更新meta，--include和--exclude的用法参见通用选项

    ./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#X-Kss-Storage-Class:STANDARD#X-Kss-Meta-A:1 -r -u --include *.jpg --exclude screenshot*
    

  • 删除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 -r --delete
    

    给匹配条件的所有文件删除meta，--include和--exclude的用法参见通用选项

    ./ks3util set-meta ks3://samplebucket/src-prefix/ X-Kss-Meta-A -r --delete --include *.jpg --exclude screenshot*
    

stat（查看Bucket或Object信息）

stat命令用于查看指定存储空间（Bucket）或者对象（Object）的相关信息。例如，您可以通过该命令查看Bucket的存储类型、Object元信息等 。

• 命令格式

  ./ks3util stat ks3://objectname[/objectname]
  

  参数及选项说明如下：

  配置项	说明
  bucketname	目标Bucket名称。
  objectname	目标Object名称。

• 使用示例

  • 查看bucket的信息

    ./ks3util stat ks3://samplebucket
    

  • 查看object的信息

    ./ks3util stat ks3://samplebucket/objectname
    

mb（创建Bucket）

存储空间（Bucket）是用于存储对象（Object）的容器。在上传任意类型的Object前，您需要先创建Bucket。mb命令用于创建Bucket。

• 命令格式

  ./ks3util mb ks3://bucketname [--acl <value>] [--storage-class <value>]
  

  参数及选项说明如下：

  配置项	说明
  bucketname	目标Bucket名称。
  --acl	Bucket的读写权限，取值：private（默认）, public-read, public-read-write
  --storage-class	Bucket的存储类型，取值：STANDARD（默认）, ARCHIVE

• 使用示例
  仅创建bucket

  ./ks3util mb ks3://samplebucket
  

  创建的bucket的地域为配置文件或选项中指定的endpoint所在的地域。

  创建bucket并指定读写权限、存储类型

  ./ks3util mb ks3://samplebucket --acl public-read --storage-class ARCHIVE
  

mkdir（创建目录）

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

• 命令格式

  ./ks3util mkdir ks3://bucketname/dir_name
  

  参数说明如下：

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

• 使用示例

  • 创建单级目录

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

  • 创建多级目录

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

  如果误删除了subdir/目录，且上一级目录sampledir/下文件个数为0，则sampledir/目录也会被自动移除。

restore（解冻）

restore命令用于在bucket中解冻文件。

• 命令格式

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

  参数及选项说明如下：

  配置项	说明
  bucketname	操作的桶名
  prefix	操作的对象的前缀
  -r, --recursive	递归进行操作。对于支持该选项的命令，当指定该选项时，命令会对目录下所有符合条件的文件进行操作，否则只对指定的单个文件进行操作。
  -f, --force	强制操作，不进行询问提示。
  --include	包含对象匹配模式，如：*.jpg
  --exclude	不包含对象匹配模式，如：*.txt
  -j, --jobs	多文件操作时的并发任务数，默认值：3，取值范围：1-10000

• 使用示例

  • 给单个文件解冻

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

  • 批量给指定前缀的文件解冻

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

    批量给符合匹配规则的文件解冻，--include和--exclude的用法参见通用选项

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

update（更新版本）

update命令用于ks3util更新版本。该命令会联网检查是否有新版本，如果有新版本，则询问是否进行更新；如果指定了--force选项，则不询问。

• 命令格式

  ./ks3util update [-f, --force]
  

  选项说明如下：

  选项	说明
  -f, --force	强制操作，不进行询问提示。

• 使用示例

  ./ks3util update
  当前版本为：1.0.0，最新版本为：2.0.0
  确定更新版本(y or N)? y
  更新成功!
  

常见问题

1. 上传、下载速度没有达到预期

当ks3util自行设置的默认并发数达不到用户的性能要求时，您可以自行调整这两个选项来升降性能。默认情况下，ks3util会根据文件大小来计算parallel个数。当批量上传大文件时，实际的并发数为jobs个数乘以parallel个数。

当服务器在网络、内存、CPU等资源不是特别大的情况下，建议将并发数调整到100以下。如果网络、内存、CPU等资源没有占满，可以适当增加并发数。

由于线程间资源切换及抢夺等原因，如果并发数过大，ks3util上传性能可能会下降。此外，并发数过大还可能产生EOF错误。所以请根据实际的机器情况调整-j, --jobs和--parallel选项的数值。如果要进行压测，可在一开始时调低这两项数值，然后逐渐调大直至找到最优值。

2. 使用ls命令查看Bucket内已无文件，但删除Bucket时报错

原因分析：Bucket上仍关联其他资源

解决方案：首先使用ls命令查看是否仍有未完成的Multipart事件产生的Part，命令：ls ks3://bucketname -m，如果有则需要删除，命令：rm ks3://bucketname -m -r；登录对象存储控制台，查看该Bucket是否存在自定义域名、空间策略、区域复制等配置，如果有则需要删除；然后重试删除桶。

3. 使用cp复制桶之间的数据时,需要注意的事项

原因分析：copy接口不能复制增量的meta

解决方案：需要在复制完成后再次调用set-meta or set-acl命令进行修改设置