ks3util 支持在Windows、Linux、macOS系统上通过命令行方式管理KS3数据。
版本和运行环境
-
版本
- 当前版本：2.2.1
-
运行环境
- Windows、Linux、macOS
- 支持架构：x86(64bit)、ARM(64bit)
安装与配置
在Windows上安装
-
根据操作系统及架构下载对应版本，假设下载的文件为
D:\Downloads\ks3util.exe。 -
打开cmd，执行以下命令切换到目标文件夹。
cd D:\Donwloads\ -
运行以下命令，验证是否已成功安装ks3util。
.\ks3util.exe如果终端输出ks3util所有支持的命令，表明已经成功安装ks3util。
-
运行以下命令，生成ks3util配置文件。
.\ks3util.exe config根据提示输入相应信息即可，当执行ks3util其他命令时就可以使用
-c选项指定该配置文件。
在Linux、macOS上安装
-
根据操作系统及架构下载对应版本，假设下载的文件为
~/Downloads/ks3util。 -
运行以下命令修改文件执行权限。
cd ~/Downloads/ chmod 755 ks3util -
运行以下命令，验证是否已成功安装ks3util。
./ks3util如果终端输出ks3util所有支持的命令，表明已经成功安装ks3util。
-
运行以下命令，生成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命令不同之处如下：
-
当输入
--delete选项时，该命令会自动删除目的端存在而源端不存在的object或者移走本地文件。如果目的端是ks3，则会删除多余的object；如果目的端是本地文件，则会移走本地多余的文件。警告：在没有完全搞清楚sync命令的行为之前，请慎用
--delete -
sync强制是以recursive方式遍历文件或者object的，所以不用输入-r --recursive。
-
当源端是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命令进行修改设置。
文档内容是否对您有帮助？
根本没帮助
文档较差
文档一般
文档不错
文档很好
在文档使用中是否遇到以下问题
更多建议
评价建议不能为空
提交成功！
非常感谢您的反馈，我们会继续努力做到更好！