更新时间:2024-12-11 GMT+08:00

配置参数说明

通过配置文件.obsutilconfig,您可以设置obsutil中的各项配置参数。

配置文件格式:

endpoint=<value>
ak=<value>
sk=<value>
token=<value>
endpointCrr=<value>
akCrr=<value>
skCrr=<value>
tokenCrr=<value>
connectTimeout=<value>
socketTimeout=<value>
maxRetryCount=<value>
maxConnections=<value>
defaultBigfileThreshold=<value>
defaultPartSize=<value>
defaultParallels=<value>
defaultJobs=<value>
defaultJobsCacheCount=<value>
rateLimitThreshold=<value>
sdkLogBackups=<value>
sdkLogLevel=<value>
sdkLogPath=<value>
sdkMaxLogSize=<value>
utilLogBackups=<value>
utilLogLevel=<value>
utilLogPath=<value>
utilMaxLogSize=<value>
writeBufferIoSize=<value>
readBufferIoSize=<value>
recordMaxLogSize=<value>
recordBackups=<value>
humanReadableFormat=<value>
showProgressBar=<value>
showStartTime=<value>
helpLanguage=<value>
defaultTempFileDir=<value>
checkSourceChange=<value>
skipCheckEmptyFolder=<value>
fsyncForDownload=<value>
memoryEconomicalScanForUpload=<value>
forceOverwriteForDownload=<value>
panicForSymbolicLinkCircle=<value>
autoChooseSecurityProvider=<value>
fastFailThreshold=<value>
abortHttpStatusForResumableTasks=<value>
showBytesForCopy=<value>
proxyUrl=<value>
faultTolerantMode=<value>

各参数的详细描述如表1所示。

表1 obsutil配置文件参数说明

参数

约束

描述

建议值

endpoint

必选

连接OBS的服务地址。可包含协议类型、域名、端口号(可选)。示例:https://your-endpoint:443。(出于安全性考虑,建议使用https协议,443端口号可以省略)

例如,访问区域为中国-香港,则实际的OBS服务地址为:https://obs.ap-southeast-1.myhuaweicloud.com。

说明:
  • 您可以从这里查看OBS当前开通的服务地址和区域信息。
  • 如果配置的服务地址不带协议,则默认使用HTTPS协议。

N/A

ak

可选

访问密钥中的AK。当配置了autoChooseSecurityProvider为true时可选。

说明:
  • 您可以从这里进入访问密钥管理界面;
  • 第一次运行obsutil后,工具会对AK进行加密以保护密钥安全。

N/A

sk

可选

访问密钥中的SK。当配置了autoChooseSecurityProvider为true时可选。

说明:
  • 您可以从这里进入访问密钥管理界面;
  • 第一次运行obsutil后,工具会对SK进行加密以保护密钥安全。

N/A

token

可选

安全令牌,为空表示不设置安全令牌。当使用临时AK,SK访问的时候必须要带token。

N/A

endpointCrr

可选

客户端跨区域复制模式时,源桶的OBS的服务地址。可包含协议类型、域名、端口号。示例:https://your-endpoint:443。(出于安全性考虑,建议使用https协议,443端口号可以省略)

说明:
  • 您可以从这里查看OBS当前开通的服务地址和区域信息。
  • 如果配置的服务地址不带协议,则默认使用HTTPS协议。

N/A

akCrr

可选

客户端跨区域复制模式时,源桶使用的访问密钥中的AK。

N/A

skCrr

可选

客户端跨区域复制模式时,源桶使用的访问密钥中的SK。

N/A

tokenCrr

可选

客户端跨区域复制模式时,源桶使用的安全令牌,为空表示不设置安全令牌。当使用临时访问密钥访问的时候必须要带此参数。

N/A

connectTimeout

可选

建立HTTP/HTTPS连接的超时时间,单位:秒,默认为30。

[5, 120]

socketTimeout

可选

读写数据的超时时间,单位:秒,默认为310。

[5, 600]

maxRetryCount

可选

请求的最大重试次数,默认为3。

说明:

当请求OBS服务完成但获取到的HTTP状态码为408、5XX时,或者请求OBS服务发生超时错误时会进行重试。

[0, 5]

maxConnections

可选

配置允许打开的最大HTTP连接数。默认为1000。

N/A

defaultBigfileThreshold

可选

开启分段任务的阈值,如果待上传/下载/复制的文件大于该阈值,则采用分段任务的形式进行上传/下载/复制。单位:字节,默认为50MB。

说明:

支持带容量单位配置,例如,配置1MB代表1048576字节。

至少大于5MB

defaultPartSize

可选

每个分段任务的段大小,单位:字节,默认为auto。

说明:
  • 对于分段上传和分段复制取值范围是100KB~5GB;
  • 对于分段下载取值范围无限制;
  • 支持带容量单位配置,例如,配置1MB代表1048576字节;
  • 如果值为auto,此时obsutil会根据源文件/对象大小自动设置每个分段任务的段大小。

[9MB, 100MB]

defaultParallels

可选

每个分段任务的最大并发数,默认为5。

可参照obsutil性能调优最佳实践进行配置

defaultJobs

可选

批量任务的最大并发数,默认为5。

说明:

批量任务包含上传文件夹、下载文件夹、复制文件夹、批量恢复对象、批量删除对象等。

[1, 50]

defaultJobsCacheCount

可选

批量任务队列的缓存大小,表示最大可以缓存的任务个数,默认为1000000。

说明:

缓存的任务个数越多,占用的内存资源越大,建议根据实际使用情况调整此参数值。

默认

rateLimitThreshold

可选

上传/下载命令的流控阈值,单位:字节/秒,默认为0表示不限流,最小值为10KB。

说明:

支持带容量单位配置,例如,配置1MB代表1048576字节。

大于100KB

sdkLogBackups

可选

最大可保留SDK日志的文件个数,默认为10。

N/A

sdkLogLevel

可选

SDK日志的级别,支持的值:

  • DEBUG
  • INFO
  • WARN
  • ERROR

默认为WARN。

N/A

sdkLogPath

可选

SDK日志文件的全路径,必须是一个文件名,默认为用户目录(macOS/Linux下为HOME目录;Windows下为C:\Users\<用户名>)的子文件夹.obsutil_log下的obssdk.log文件。

说明:
  • 如果该参数为空,则不会产生日志;
  • 该路径必须是一个文件,不能为文件夹;
  • 开启SDK日志后,请求OBS服务的正常/异常的日志记录都会保存在SDK日志文件中,可用于问题分析和定位;
  • 请保证运行命令的用户对该路径有读写权限。
须知:

同一个用户如果开启多个obsutil进程同时运行时,可能导致日志文件并发写失败或日志内容丢失的问题,请在运行命令时加上-config参数为每个进程配置独立的配置文件。

N/A

sdkMaxLogSize

可选

SDK日志文件大小,单位:字节,默认为30MB。

说明:

支持带容量单位配置,例如,配置1MB代表1048576字节。

[10MB, 100MB]

utilLogBackups

可选

最大可保留obsutil日志的文件个数,默认为10。

N/A

utilLogLevel

可选

obsutil日志的级别,支持的值:

  • DEBUG
  • INFO
  • WARN
  • ERROR

默认为INFO。

N/A

utilLogPath

可选

obsutil日志文件的全路径,必须是一个文件名,默认为用户目录(macOS/Linux下为HOME目录;Windows下为C:\Users\<用户名>)的子文件夹.obsutil_log下的obsutil.log文件。

说明:
  • 如果该参数为空,则不会产生日志;
  • 该路径必须是一个文件,不能为文件夹;
  • 开启obsutil日志后,命令运行过程中产生的正常/异常的日志记录都会保存在obsutil日志文件中,可用于问题分析和定位;
  • 请保证运行命令的用户对该路径有读写权限。
须知:

同一个用户如果开启多个obsutil进程同时运行时,可能导致日志文件并发写失败的问题,请在运行命令时加上-config参数为每个进程配置独立的配置文件。

N/A

utilMaxLogSize

可选

obsutil日志文件大小,单位:字节,默认为30MB。

说明:

支持带容量单位配置,例如,配置1MB代表1048576字节。

[10MB, 100MB]

writeBufferIoSize

可选

下载数据的缓存大小,单位:字节,默认为65536。

说明:
  • 可根据实际场景设置该值,如果待下载的文件较大,可将该值设置较大;
  • 支持带容量单位配置,例如,配置1MB代表1048576字节。

N/A

readBufferIoSize

可选

上传数据的缓存大小,单位:字节,默认为8192。

说明:
  • 可根据实际场景设置该值,上传大量小文件时,建议将该值设置较小;上传大文件时,可将该值设置较大;
  • 支持带容量单位配置,例如,配置1MB代表1048576字节。

[4096, 65536]

recordMaxLogSize

可选

批量任务成功/失败/警告的结果清单文件大小,单位:字节,默认为30MB。

说明:

支持带容量单位配置,例如,配置1MB代表1048576字节。

[5MB, 100MB]

recordBackups

可选

批量任务最大可保留的成功或失败的结果清单文件个数,默认为1024。

N/A

humanReadableFormat

可选

是否将列举对象结果和结果清单内容中的字节数转换为易读格式,为true时表示进行转换,默认为true。

N/A

showProgressBar

可选

是否在控制台显示进度条,为true时表示显示进度条,默认为true。

N/A

showStartTime

可选

是否在控制台显示开始时间,为true时表示显示,默认为true。

N/A

helpLanguage

可选

帮助文档的语种,当前完成国际化的语种类型:

  • Chinese
  • English

默认为English。

N/A

defaultTempFileDir

可选

下载时保存临时文件的文件夹,

默认为用户目录(macOS/Linux下为HOME目录;Windows下为C:\Users\<用户名>)的子文件夹.obsutil_tempfile。

说明:
  • 由于分段下载时生成的临时文件会保存在该目录,请确保运行obsutil的用户对该路径有写权限;
  • 该路径的可用空间需要大于待下载对象的大小。

N/A

checkSourceChange

可选

上传/下载/复制时,是否检测源文件/对象变化,为true时表示开启。

N/A

skipCheckEmptyFolder

可选

下载时是否跳过检查OBS服务端的空文件夹,为true时表示跳过检查,默认为false。

须知:

配置该参数为true,可能导致下载到本地后的目录结构与云端不一致。

N/A

fsyncForDownload

可选

下载时是否强制同步内存数据到磁盘,为true时表示需要强制同步,默认为false。

说明:
  • 对数据可靠性要求极高的场景下可开启该参数;
  • 开启该参数后,会对下载性能产生较大影响,请谨慎使用。

N/A

memoryEconomicalScanForUpload

可选

上传文件夹时,是否使用内存占用更少的扫描方式,为true时表示使用,默认为true。

N/A

forceOverwriteForDownload

可选

在linux/macOs操作系统上下载对象时,强制覆盖本地可执行文件(即使本地可执行文件正在运行),为true时表示进行强制覆盖,默认为true。

N/A

panicForSymbolicLinkCircle

可选

上传时对于检测到软链接形成环后的处理方式,为false时代表仅记录错误,为true时代表产生panic异常,默认为false。

N/A

autoChooseSecurityProvider

可选

是否依次从配置文件、环境变量、ecs接口获取访问密钥自动获取访问密钥,默认为false。

说明:

该参数的更多细节请参考为obsutil配置自动获取访问密钥

N/A

fastFailThreshold

可选

批量任务遇到4XX错误后快速失败的阈值,当发生超过该阈值的4XX错误后进入快速失败流程,所有未执行或正在扫描的任务会被中断。默认为5。

说明:

快速失败机制的目的是进行批量任务时,避免产生过多的流量,如果希望尽早启动快速失败,可将该值配置为0或-1,表示一旦遇到4XX错误则立即进入快速失败流程。

N/A

abortHttpStatusForResumableTasks

可选

分段上传/下载/复制任务快速中断的HTTP状态码,当某个分段子任务的HTTP状态码包含在该值范围内时,则会立即中断整个分段上传/下载/复制任务。默认值为:401,403,404,405,409。

说明:
  • 可包含多个HTTP状态码,并以逗号分隔,例如:401,403,404;
  • 必须是4XX的HTTP状态码,其他状态码将被忽略。

默认

showBytesForCopy

可选

桶间复制对象时进度条是否以字节方式显示速率,默认为false。

N/A

proxyUrl

可选

HTTP代理配置,示例:http://username:password@your-proxy:8080。

说明:
  • HTTP代理的格式一般为http://[用户名:密码@]代理服务器地址:端口号,其中用户名密码非必选。
  • 如果proxyUrl参数和系统环境变量的优先级规则为:proxyUrl > HTTPS_PROXY > HTTP_PROXY。
  • 用户名和密码里面不能出现“:”和“@”,否则解析用户名密码会出错。

N/A

faultTolerantMode

可选

是否忽略读操作引发的panic,默认为false,表示不忽略。

N/A

  • 建议值为N/A的表示需要根据实际情况进行设置;
  • 建议指定sdkLogPath和utilLogPath开启SDK日志和obsutil日志;
  • defaultBigfileThreshold、defaultPartSize、rateLimitThreshold、sdkMaxLogSize、utilMaxLogSize、recordMaxLogSize、readBufferIoSize、writeBufferIoSize支持带容量单位配置,例如,配置1MB代表1048576字节。