全部文档
当前文档
最近更新时间：2025-02-25 15:35:11
本文为您介绍KS3Util的通用选项参数和过滤规则示例。
表格中为ks3util的通用选项，可以在大部分命令中使用：
选项参数 | 说明 |
|---|---|
-c, --config-file | ks3util工具的配置文件路径，ks3util启动时从配置文件读取配置，在config命令中，ks3util将配置写入该文件。 |
-e, --endpoint | 设置Bucket所在地域的域名信息（该选项值会覆盖配置文件中的相应设置），支持HTTP和HTTPS访问。填写内容示例： |
-i, --access-key-id | 访问ks3使用的AccessKeyID（该选项值会覆盖配置文件中的相应设置）。 |
-k, --access-key-secret | 访问ks3使用的AccessKeySecret（该选项值会覆盖配置文件中的相应设置）。 |
-r, --recursive | 递归进行操作。对于支持该选项的命令，当指定该选项时，命令会对指定目录下所有符合条件的文件进行操作，否则只对指定的单个文件进行操作。 |
-f, --force | 强制操作，不进行询问提示。 |
--retry-times | 当错误发生时的重试次数，默认值：10，取值范围：1-500。 |
--loglevel | 日志级别，默认为off（该选项值会覆盖配置文件中的相应设置）。可选值：off | error | warn | info | debug。
|
--read-timeout | 表示客户端读超时的时间，单位为秒，缺省值为60。 |
--connect-timeout | 表示客户端连接超时的时间，单位为秒，缺省值为60。 |
--include | 包含对象匹配模式，满足匹配规则的文件将会被选中，如：*.jpg。  该选项可以出现多次，多个--include规则取并集。 |
--exclude | 不包含对象匹配模式，满足匹配规则的文件将会被排除，如：*.txt。 该选项可以出现多次，多个--exclude规则取并集。 |
-j, --jobs | 多文件操作时的并发数，默认值：5，取值范围：1-10000。 1. 该参数决定有多少个文件并行上传/下载/拷贝。 2. 批量操作文件时适合调整该参数。 3. Util2.9.0版本默认值由3改为5。 |
--parallel | 单文件内部操作的并发任务数，取值范围：1-10000。 1. 默认KS3 Util会根据操作类型和文件大小自动决定，自动取值范围是1-12。 2. 该参数决定单个文件有多少个块并行上传/下载/拷贝。 3. 操作单个大文件时适合调整该参数。 4. 总并发数= jobs * parallel。 |
-L, --language | 设置ks3util工具的语言。取值如下：EN：英文；CH（默认值）：中文。设置为CH时，请确保系统编码方式为UTF-8。 |
--object-file | 需对其进行操作的文件列表，每个objectKey为一行（不包含ks3://bucket/ 部分）。 |
--enable-regex | 匹配模式，指定该选项时，--include与--exclude将使用正则表达式匹配，若不指定该选项，则使用默认模式匹配。 |
--path-matching | 路径匹配，指定该选项时，--include与--exclude将对文件路径（ObjectKey）使用过滤规则，若不指定该选项，则对文件名（FileName）使用过滤规则。 |
--time-range | 时间段匹配模式，仅匹配最后修改时间在该时间段内的文件。时间段格式为：time1-time2，其中time1、time2需要填写UTC时间，格式为：yyyyMMddHHmmss。 1、time1-time2表示匹配最后修改时间大于等于time1且小于等于time2的所有文件。 2、*-time2表示匹配最后修改时间小于等于time2的所有文件。 3、time1-*表示匹配最后修改时间大于等于time1的所有文件。 |
--disable-endpoint-redirect | 禁用endpoint重定向，不会自动重定向到桶所在region对应的endpoint，始终使用配置中的endpoint。 |
--proxy | 指定代理服务器。配置值可以为以下几种：
配置这些环境变量后，将代理服务器选项的值设置为 |
用户可以使用--include或--exclude参数，根据文件的名称过滤文件。从2.7.0版本开始，支持根据文件路径过滤文件。为避免特殊字符的影响，建议将过滤规则使用双引号""包含。
从2.7.0版本开始，KS3Util修改了过滤规则的匹配流程，多个规则填写的顺序不会影响匹配结果，具体细节请参照以下文档。
*：匹配所有字符。例如："*.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的文件。
从2.7.0版本开始，该匹配模式将作为默认模式。
--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"。
2.7.0及以上版本支持两种匹配模式：默认模式和正则模式。命令中不添加额外参数时，遵循默认模式匹配，--include和--exclude填写的值需要符合默认模式的规则；当添加--enable-regex参数后，将使用正则模式匹配，此时--include和--exclude中需要填写标准的正则表达式。
若exclude存在，且只要有一个exclude匹配成功，文件被排除。
若exclude不存在，或所有exclude匹配失败，则由include决定匹配结果。
若include存在，且只要有一个include匹配成功，文件被选中。若所有include匹配失败，文件被排除。
若exclude和include都不存在，表示不过滤，文件被选中。
具体示例图如下：
1.根据文件名匹配
以下示例均采用默认匹配模式，例如指定生效的文件夹中包含名为file5.txt的文件，具体规则生效示例如下。
1.1单规则匹配示例
规则一：--exclude "*test*"
该规则的含义：排除所有文件名包含test的文件
先匹配--exclude规则，当规则匹配到--exclude "*test*"时，因为file5.txt不包含test，所以未被排除，则匹配的最终结果为file5.txt符合条件。
规则二：--exclude "*file*"
该规则的含义：排除所有文件名包含file的文件
先匹配--exclude规则，当规则匹配到--exclude "*file*"时，因为file5.txt包含file，所以被排除，则匹配的最终结果为file5.txt不符合条件。
规则三：--include "*test*"
该规则的含义：选中所有文件名包含test的文件
先匹配--exclude规则，发现无--exclude规则，再匹配--include规则，当规则匹配到--include "*test*"时，因为file5.txt不包含test，所以未被选中，则匹配的最终结果为file5.txt不符合条件。
规则四：--include "*file*"
该规则的含义：选中所有文件名包含file的文件
先匹配--exclude规则，发现无--exclude规则，再匹配--include规则，当规则匹配到--include "*file*"时，因为file5.txt包含file，所以被选中，则匹配的最终结果为file5.txt符合条件。
1.2多规则匹配示例
规则一：--include "*.txt" --exclude "*test*"
该规则的含义：排除所有文件名包含test的文件后，选中文件结尾是.txt的文件
先匹配--exclude规则，当规则匹配到--exclude "*test*"时，因为file5.txt不包含test，所以未被排除；再匹配--include规则，当规则匹配到--include "*.txt"时，因为file5.txt包含.txt，所以被选中，则匹配的最终结果为file5.txt符合条件。
规则二：--include "*.txt" --exclude "*file*"
该规则的含义：排除所有文件名包含file的文件后，选中文件结尾是.txt的文件
先匹配--exclude规则，当规则匹配到--exclude "*file*"时，因为file5.txt包含file，所以被排除，则匹配的最终结果为file5.txt不符合条件。
规则三：--include "*.txt" --exclude "*test*" --include "*abc*" --exclude "*.png"
该规则的含义：排除所有文件名包含test或后缀是.png的文件后，选中文件结尾是.txt或包含abc的文件
先匹配--exclude规则，当规则匹配到--exclude "*test*"时，因为file5.txt不包含test，所以未被排除，当规则匹配到--exclude "*.png"时，因为file5.txt不包含.png，所以未被排除；再匹配--include规则，当规则匹配到--include "*.txt"时，因为file5.txt包含.txt，所以被选中，则匹配的最终结果为file5.txt符合条件。
规则四：--include "*.txt" --exclude "*file*" --include "*abc*" --exclude "*.png"
该规则的含义：排除所有文件名包含file或后缀是.png的文件后，选中文件结尾是.txt或包含abc的文件
先匹配--exclude规则，当规则匹配到--exclude "*file*"时，因为file5.txt包含file，所以被排除，则匹配的最终结果为file5.txt不符合条件。
2.根据文件路径匹配
默认情况下，KS3Util的过滤规则匹配文件名，命令中填写--path-matching参数后，KS3Util的过滤规则将匹配文件路径。
在使用路径匹配时，推荐使用正则模式--enable-regex。
2.1 匹配单个文件示例
上传时，如本地文件的绝对路径为：/root/files/upload/abc.txt
规则一：--include ".*\.txt" --path-matching --enable-regex
该规则的含义：选中文件路径结尾是.txt的文件
因为/root/files/upload/abc.txt包含.txt，所以被选中，则匹配的最终结果为abc.txt符合条件。
规则二：--include ".*upload.*" --path-matching --enable-regex
该规则的含义：选中文件路径包含upload的文件
因为/root/files/upload/abc.txt包含upload，所以被选中，则匹配的最终结果为abc.txt符合条件。
下载时，如有KS3中文件的Key为：files/download/abc.txt
规则一：--include ".*\.txt" --path-matching --enable-regex
该规则的含义：选中文件路径结尾是.txt的文件
因为files/download/abc.txt包含.txt，所以被选中，则匹配的最终结果为abc.txt符合条件。
规则二：--include ".*download.*" --path-matching --enable-regex
该规则的含义：选中文件路径包含download的文件
因为files/download/abc.txt包含download，所以被选中，则匹配的最终结果为abc.txt符合条件。
2.2 匹配文件夹示例
上传示例：
假如在/root/test/目录下有1000个子目录，命名为part+序号，如：part0001、part1000，现需上传part0001-part0099的目录，可通过以下命令实现：
./ks3util cp /root/test/ ks3://bucket/prefix/ -r --include ".*/part00\d{2}/.*" --path-matching --enable-regex在过滤规则中：.*表示匹配任意个任意字符，/表示匹配一个路径分隔符，part00表示匹配part00字符串，\d{2}表示匹配两个数字，/表示匹配一个路径分隔符，.*表示匹配任意个任意字符。
--path-matching表示使用路径匹配模式，此时--include或--exclude匹配的是文件完整路径。
--enable-regex表示使用正则表达式匹配，此时--include或--exclude需填写正则表达式。
下载示例：
假如在bucket桶的prefix/test/目录下有若干个子目录，如：unfinished-xxx、completed-xxx，现需下载所有以unfinished-开头的子目录，可通过以下命令实现：
./ks3util cp ks3://bucket/prefix/test/ files/ -r --include ".*/unfinished-.*/.*" --path-matching --enable-regex在过滤规则中：.*表示匹配任意个任意字符，/表示匹配一个路径分隔符，unfinished-表示匹配unfinished-字符串，.*表示匹配任意个任意字符，/表示匹配一个路径分隔符，.*表示匹配任意个任意字符。
--path-matching表示使用路径匹配模式，此时--include或--exclude匹配的是对象完整的key。
--enable-regex表示使用正则表达式匹配，此时--include或--exclude需填写正则表达式。
3.时间段匹配示例
从2.9.0版本开始，KS3Util新增根据文件的最后修改时间匹配，具体生效规则请查看通用选项--time-range。
示例一：匹配最后修改时间在2024-11-06 12:00:00 到 2024-11-10 12:00:00 之间的文件（UTC时间）。
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --time-range "20241106120000-20241110120000"示例二：匹配最后修改时间在2024-11-06 12:00:00 到 2024-11-10 12:00:00 之间的文件（北京时间）。
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --time-range "20241106040000-20241110040000"示例三：匹配最后修改时间在2024-11-06 12:00:00 之前的文件（UTC时间）。
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --time-range "*-20241106120000"示例四：匹配最后修改时间在2024-11-06 12:00:00 之前的文件（北京时间）。
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --time-range "*-20241106040000"示例五：匹配最后修改时间在 2024-11-10 12:00:00 之后的文件（UTC时间）。
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --time-range "20241110120000-*"示例六：匹配最后修改时间在 2024-11-10 12:00:00 之后的文件（北京时间）。
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --time-range "20241110040000-*"纯净模式