KS3 Util命令行工具

最近更新时间:2023-05-15 10:01:55

查看PDF

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

版本和运行环境

  • 版本

    • 当前版本:2.2.1
  • 运行环境

    • 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。
--limited-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。
--limited-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信息,操作成功会删除该目录。如果指定了该选项,请确保所指定的目录可以被删除。

使用示例

  • 上传单个文件
    上传文件时,如果dest_prefix以/结尾,则object key为dest_prefix + 原文件名,否则object key为dest_prefix。

    # 例1: 上传后的对象为ks3://samplebucket/abc/sample.txt
    ./ks3util cp /home/sample.txt ks3://samplebucket/abc/
    
    # 例2: 上传后的对象为ks3://samplebucket/abc
    ./ks3util cp /home/sample.txt ks3://samplebucket/abc
    
  • 上传文件夹
    将文件夹(包括子文件夹)内的文件上传至KS3指定路径。使用-r选项时,如果指定路径不以/结尾,则会自动加上/。

    # 例1: 假设有以下文件
    # /home/logs/a.log
    # /home/logs/bak/b.log
    # 上传后的文件为
    # ks3://samplebucket/my-files/a.log
    # ks3://samplebucket/my-files/bak/a.log
    
    ./ks3util cp /home/logs/ ks3://samplebucket/my-files/ -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 --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 cp 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 cp 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 cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --include *.jpg --exclude *screenshot*
    
  • 修改文件读写权限ACL

    ./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --acl public-read
    
  • 修改文件读存储类型

    ./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --storage-class STANDARD_IA
    
  • 修改文件标签

    ./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --tagging "a=1&b=2"
    
  • 修改文件meta

    ./ks3util cp 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-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-Meta-A:1
    
    • 给指定前缀的所有文件设置meta
    ./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#X-Kss-Meta-A:1 -r
    
    • 给匹配条件的所有文件设置meta,--include--exclude的用法参见通用选项
    ./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#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-Meta-A:1 -u
    
    • 给指定前缀的所有文件更新meta
    ./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#X-Kss-Meta-A:1 -r -u
    
    • 给匹配条件的所有文件更新meta,--include--exclude的用法参见通用选项
    ./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#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。创建的bucket的地域为配置文件或选项中指定的endpoint所在的地域。

命令格式

./ks3util mb ks3://bucketname [--acl <value>] [--bucket-type <value>]

参数及选项说明如下:

配置项 说明
bucketname 目标Bucket名称。
--acl Bucket的读写权限,取值:private(默认),public-read,public-read-write
--bucket-type Bucket的存储类型,取值:NORMAL(默认),ARCHIVE

使用示例

  • 仅创建bucket

    ./ks3util mb ks3://samplebucket
    
  • 创建bucket并指定读写权限、存储类型

    ./ks3util mb ks3://samplebucket --acl public-read --bucket-type 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*
    

cat(输出到标准输出流)

cat命令可以将ks3的object内容输出到标准输出流,object内容是文本格式比较好。

命令格式

ks3util cat ks3://bucketname/objectKey

参数说明如下:

配置项 说明
bucketname 操作的桶名
objectKey 操作的对象名

使用示例

  • 输出到标准输出

    ks3util cat ks3://samplebucket/ks3log_samplebucket_2023_01_01.log
    
  • 与管道一起使用(Linux,MacOS)

    ks3util cat ks3://samplebucket/ks3log_samplebucket_2023_01_01.log | grep 'REST.DELETE.OBJECT'
    

rcat(流式上传)

rcat命令用于流式上传文件,需与管道配合使用,如果ks3上已存在同名文件,则会覆盖。

命令格式

ks3util rcat ks3://bucketname/objectKey 
[-f, --force]
[\-\-acl <acl>] 
[\-\-meta <meta>] 
[\-\-tagging <tagging>] 
[-j, --jobs <job-num>] 
[\-\-part-size <part-size>]

参数及选项说明如下:

配置项 说明
bucketname 操作的桶名
objectKey 操作的对象名
--acl acl信息的配置。
--meta 设置object的meta为header:value#header:value
,如:Cache-Control:no-cache#Content-Encoding:gzip
--tagging 设置object的tagging,取值格式如"TagA=A&TagB=B"
,注意:需要使用双引号。
--storage-class 对象的存储类型,取值:STANDARD,STANDARD_IA,ARCHIVE
-j, --jobs 多文件操作时的并发任务数,默认值:3,取值范围:1-10000
--part-size 分片大小,单位为Byte,默认情况下ks3util根据文件大小自行计算合适的分片大小值。如果有特殊需求或者需要性能调优,可以设置该值,取值范围:1-9223372036854775807(Byte)

使用示例

  • 流式上传文件

    grep 'REST.DELETE.OBJECT' ks3log_samplebucket_2023_01_01.log | ks3util rcat ks3://samplebucket/delete-object.log
    
  • 流式上传文件并设置ACL等

    grep 'REST.DELETE.OBJECT' ks3log_samplebucket_2023_01_01.log | ks3util rcat ks3://samplebucket/delete-object.log --acl public-read --storage-class STANDARD_IA --meta Content-Type:text/plain#X-Kss-Meta-belongs:kevin --tagging "log-file=true&test-file=true" -j 10 --part-size 5242880
    

sync(同步目录)

该命令用于将本地文件目录或者ks3 prefix从源端同步到目的端。

不支持本地目录之间的同步

该命令和cp命令类似:支持从本地文件系统上传文件到ks3,从ks3下载object到本地文件系统,在ks3上进行object拷贝;用于源端和目的端数据同步。

sync命令和cp命令不同之处如下:

  1. 当输入--delete选项时,该命令会自动删除目的端存在而源端不存在的object或者移走本地文件。如果目的端是ks3,则会删除多余的object;如果目的端是本地文件,则会移走本地多余的文件。

    警告:在没有完全搞清楚sync命令的行为之前,请慎用--delete

  2. sync强制是以recursive方式遍历文件或者object的,所以不用输入-r --recursive。

  3. 当源端是ks3://bucket/prefix,sync命令会自动在prefix后面加上字符 ‘/’,但是cp命令不会。当目的端是ks3://bucket/prefix,sync命令会在prefix后面加上字符 ‘/’;cp命令在–recursive被输入时也会在prefix后面加上字符’/’。

--delete选项
表示需要删除或者移走目的端存在而源端不存在的object或者文件。

--backup-dir选项
该选项表示用于备份目的端文件的目录,不能是目的端目录的子目录,如果输入了--delete,该选项必须输入。

其他选项说明、用法和cp命令相同。

命令格式

# 将本地目录同步到ks3 prefix
ks3util sync local_dir ks3://bucketname[/prefix] 
[-f] 
[-u] 
[--delete] 
[--backup-dir]

参数及选项说明如下:

配置项 说明
local_dir 本地目录
bucketname 操作的桶名
prefix 操作的对象前缀
-f, --force 强制操作,不进行询问提示。
-u, --update 更新操作,只有当目标文件不存在,或源文件的最后修改时间晚于目标文件时,ks3util才会执行上传操作。
--delete 表示需要删除或者移走目的端存在而源端不存在的object或者文件。
--backup-dir 用于备份目的端文件的目录,不能是目的端目录的子目录,如果输入了–delete,该选项必须输入。

使用示例

  • 从本地目录同步到ks3

    ks3util sync ./test_dir ks3://samplebucket/test_sync/ -u -f
    
    # 同步并删除ks3上多余的文件
    ks3util sync ./test_dir ks3://samplebucket/test_sync/ -u -f --delete
    
  • 从ks3同步到本地目录

    ks3util sync ks3://samplebucket/test_sync/ ./test_dir -u -f
    
    # 同步并移动本地目录多余的文件到./backup目录
    ks3util sync ks3://samplebucket/test_sync/ ./test_dir -u -f --delete --backup-dir ./backup
    
  • 从ks3同步到ks3

    ks3util sync ks3://samplebucket/test_sync/ ks3://samplebucket/test_sync_2/ -u -f
    
    # 同步并删除目的端上多余的文件
    ks3util sync ks3://samplebucket/test_sync/ ks3://samplebucket/test_sync_2/ -u -f --delete
    

set-storage-class(设置存储类型)

该命令用于设置指定objects的存储类型信息。

命令格式

ks3util set-storage-class ks3://bucketname/object-key <storage-class> 
[-r] 
[-f] 
[--include <patten>]
[--exclude <patten>]

参数及选项说明如下:

配置项 说明
-r, --recursive 递归进行操作
-f, --force 强制操作,不进行询问提示
--include 包含对象匹配模式,如:*.jpg
--exclude 不包含对象匹配模式,如:*.txt

使用示例

  • 设置单个文件的存储类型

    ks3util set-storage-class ks3://samplebucket/test-file STANDARD_IA
    
  • 批量设置文件的存储类型

    ks3util set-storage-class ks3://samplebucket/logs/ STANDARD_IA -r -f
    

set-tag(设置标签)

该命令可设置、更新、删除指定objects的tagging信息。

注意:tagging的key和value区分大小写。

命令格式

ks3util set-tag ks3://bucketname[/prefix] <tagging> [-r] [f]
[--update] 
[--delete] 
[--include <patten>]
[--exclude <patten>]
[-j, --jobs <num>]

参数及选项说明如下:

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

使用示例

  • 设置标签
    如果用户未指定--update选项和--delete选项,ks3util会设置指定objects的tagging为用户输入的"tag=value&tag=value"。

    • 设置单个文件的标签

      ks3util set-tag ks3://samplebucket/test-files/sample.txt "belongs=kevin&test-file=true"
      
    • 设置指定前缀的所有文件的标签

      ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r
      
    • 设置匹配条件的文件的标签,--include--exclude的用法参见通用选项

      ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r --include *.log --exclude tom-*
      
  • 更新标签
    如果用户设置--update选项,ks3util会更新指定objects的指定tagging为输入的value值,其中value可以为空,指定objects的其他tagging信息不会改变。此时不支持--delete选项。

    • 更新单个文件的标签

      ks3util set-tag ks3://samplebucket/test-files/sample.txt "belongs=kevin&test-file=true" --update
      
    • 更新指定前缀的所有文件的标签

      ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r --update 
      
    • 更新匹配条件的文件的标签,--include--exclude的用法参见通用选项

      ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r --include *.log --exclude tom-* --update
      
  • 删除标签
    如果用户设置--delete选项,ks3util会删除所有标签。此时不支持--update选项。

    • 删除单个文件的标签

      ks3util set-tag ks3://samplebucket/test-files/sample.txt "belongs=kevin&test-file=true"
      
    • 删除指定前缀的所有文件的标签

      ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r --delete
      
    • 删除匹配条件的文件的标签,--include--exclude的用法参见通用选项

      ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r --include *.log --exclude tom-* --delete
      

sign (生成上传或者下载链接)

sign命令用于该命令签名用户指定的cloud_url,生成经过签名的url可供第三方用户访问object。

命令格式

./ks3util sign ks3://bucketname[/prefix]
[-r, --recursive]
[-f, --force]
[--include <value>]
[--exclude <value>]
[--timeout <value>]
[--sign-method <value>]

参数及选项说明如下:

配置项 说明
bucketname 操作的桶名
prefix 操作的对象的前缀
-r, --recursive 递归进行操作。对于支持该选项的命令,当指定该选项时,命令会对目录下所有符合条件的文件进行操作,否则只对指定的单个文件进行操作。
-f, --force 强制操作,不进行询问提示。
--include 包含对象匹配模式,如:*.jpg
--exclude 不包含对象匹配模式,如:*.txt
--timeout 外链过期时间,默认值:10(单位秒)
--sign-method 生成下载链接或者上传链接,默认值:get,可选值为 get 、put
  • 生成下载链接,单个签名默认 ‘GET’

    ./ks3util sign ks3://samplebucket/src-prefix/sample.txt
    
  • 过期时间为签名时间+timeout时间。60秒后签名过期

    ./ks3util sign ks3://samplebucket/src-prefix/sample.txt --timeout 60 
    
  • 生成上传链接

    ./ks3util sign ks3://samplebucket/src-prefix/ -r --sign-method=PUT  
    
  • 批量签名目录

    ./ks3util sign ks3://samplebucket/src-prefix/ -r 
    
  • 批量给符合匹配规则的文件签名,--include--exclude的用法参见通用选项

    ./ks3util sign ks3://samplebucket/src-prefix -r --include *.txt
    

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命令进行修改设置。

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

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

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

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

更多建议

0/200

评价建议不能为空

提交成功!

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

问题反馈