文档中心

对象存储

请输入

tosutil

配置文件说明

tosutil 提供了很多配置参数，您可以通过 vim ~/.tosutilconfig 文件查看。本文介绍配置文件的详细说明。

注意

配置文件中还有部分较少使用的配置参数没有包含在上述列表中（如 skipCheckEmptyFolderForDownload、memoryEconomicalScanForUpload、faultTolerantMode），这些配置参数通常无需修改，保持默认值即可，如果需要详细了解这些参数的细节用法，请联系火山引擎 TOS 团队。

参数名	描述	建议值
endpoint	连接 TOS 的服务地址。	N/A
region	连接 TOS 的区域名称。	N/A
ak	永久或临时访问密钥中的 Access Key ID。为了保证密钥安全避免泄露，tosutil 会自动加密您的信息。	N/A
sk	永久或临时访问密钥中的 Secret Access Key。为了保证密钥安全避免泄露，tosutil 会自动加密您的信息。	N/A
token	临时访问密钥中的 Security Token，与临时Access Key 和 Secret Key 配套使用。	N/A
connectTimeout	建立连接的超时时间，单位：秒，默认为 30。	[5, 60]
socketTimeout	读写数据的超时时间，单位：秒，默认为 120。	[5, 120]
maxConnections	配置允许打开的最大连接数，默认为 1000。	N/A
maxRetryCount	请求的最大重试次数，默认为 10。说明当请求 TOS 服务端完成但获取到的 HTTP 状态码为 408、429、5XX 时，或者请求 TOS 服务发生超时错误时会选择性地进行退避重试。	[0, 10]
proxyUrl	访问 TOS 服务端时使用的 HTTP 代理地址。	N/A
useListType2	是否使用 ListObjectsType2 接口进行批量操作和列举对象。支持的值： true：使用 listobjectstype2。 false（默认）：使用 listobjects。	N/A
defaultSse	上传或复制对象时使用的默认的服务端加密算法，支持的值： aes256 kms	N/A
defaultSseKeyId	上传或复制对象且指定服务端加密算法为 kms 时，默认使用的 kms 密钥。	N/A
defaultBigfileThreshold	开启分片任务的阈值，如果待上传、下载或复制的文件大于该阈值，则采用分片任务的形式进行上传、下载或复制。单位：字节，默认为 100MB。说明支持带容量单位配置，例如，配置 1MB 代表 1048576 字节。	[50MB, max)
defaultPartSize	每个分片任务的段大小，单位：字节，默认为 auto。说明支持带容量单位配置，例如，配置 1MB 代表 1048576 字节。如果取值为 auto，此时 tosutil 会根据源文件大小自动设置每个分片任务的分片大小。	默认值。
defaultParallels	每个上传和复制分片任务的最大并发数，默认为 20。	根据客户端运行的机器环境配置，建议不超过 50。
defaultDownloadParallels	每个下载分片任务的最大并发数，默认为 5。	根据客户端运行的机器环境配置，建议不超过 50。
defaultJobs	批量任务的最大并发数，默认为 3。说明批量任务包含上传文件夹、下载文件夹、复制文件夹、批量删除对象等。	根据客户端运行的机器环境配置，建议不超过 1000。
defaultJobsCacheCount	批量任务队列的缓存大小，表示最大可以缓存的任务个数，默认为 1000000。说明缓存的任务个数越多，占用的内存资源越大，建议保持默认值，如果需要调整，请根据实际使用情况调整此参数值。	默认值。
rateLimitThreshold	上传/下载命令的流控阈值，单位：字节。默认为 0 ，表示不限流，最小值为 1KB。说明支持带容量单位配置，例如，配置 1MB 代表 1048576 字节。	大于 100KB。
utilLogPath	tosutil 日志文件的全路径，必须是一个文件名，默认为用户目录（macOS 或 Linux 下为 HOME 目录；Windows 下为 C:\Users<用户名>）的子文件夹 .tosutil_log 下的 tosutil.log 文件。说明如果该参数为空，则不会产生日志。该路径必须是一个文件，不能为文件夹。开启 tosutil 日志后，命令运行过程中产生的正常和异常的日志记录都会保存在 tosutil 日志文件中，可用于问题分析和定位。请保证运行命令的用户对该路径有读写权限。	默认值。
utilMaxLogSize	tosutil 日志文件大小，单位：字节，默认为 30MB。说明支持带容量单位配置，例如，配置 1MB 代表 1048576 字节。	[10MB, 100MB]
utilLogBackups	最大可保留 tosutil 日志的文件个数，默认为 10。	[3, 30]
utilLogLevel	tosutil 日志的级别，支持的值： DEBUG INFO WARN ERROR ，默认为 INFO。	N/A
sdkLogPath	TOS SDK 日志文件的全路径，必须是一个文件名，默认为用户目录（macOS 或 Linux 下为 HOME 目录；Windows 下为 C:\Users<用户名>）的子文件夹 .tosutil_log 下的 tossdk.log 文件。说明如果该参数为空，则不会产生日志；该路径必须是一个文件，不能为文件夹。	默认值。
sdkMaxLogSize	TOS SDK 日志文件大小，单位：字节，默认为 30MB。说明支持带容量单位配置，例如，配置 1MB 代表 1048576 字节。	[10MB, 100MB]
sdkLogBackups	最大可保留 TOS SDK 日志的文件个数，默认为 10。	[3, 30]
sdkLogLevel	SDK 日志的级别，支持的值： DEBUG 、INFO 、WARN和 ERROR ，默认为 WARN。	N/A
recordMaxLogSize	批量任务成功/失败/警告的结果清单文件大小，单位：字节，默认为 30 MB。说明支持带容量单位配置，例如，配置 1MB 代表 1048576 字节。	[10MB, 100MB]
recordBackups	批量任务最大可保留的成功或失败的结果清单文件个数，默认为 2048。	默认值。
humanReadableFormat	是否将列举对象结果和结果清单内容中的字节数转换为易读格式，取值说明如下： true（默认）：表示进行转换。 false：表示不进行转换。	N/A
showProgressBar	是否在控制台显示进度条，取值说明如下： true（默认）：在控制台显示进度条。 false：表示不在控制台显示进度条。	N/A
showStartTime	是否在控制台显示开始时间，取值说明如下： true（默认）：表示在控制台显示开始时间。 false：表示不在控制台显示开始时间。	N/A
helpLanguage	帮助文档的语种，支持的值如下： Chinese（默认） English	N/A
defaultOutputDir	批量任务结果清单文件的默认文件夹，默认为用户目录，说明如下： macOS 或 Linux ：为 HOME 目录。 Windows ：为 C:\Users\<用户名> 的子文件夹 .tosutil_output。说明批量任务均支持 -o 参数在每次运行时候重写该文件夹地址。	N/A
defaultCheckpointDir	断点续传文件的默认文件夹，，默认为用户目录，说明如下： macOS 或 Linux ：为 HOME 目录。 Windows ：为 C:\Users\<用户名> 的子文件夹 .tosutil_checkpoint。说明上传、下载或复制任务均支持 -cpd 参数在每次运行时重写该文件夹地址。	N/A
defaultTempFileDir	下载大文件时保存临时文件的文件夹，默认为空，代表会将大文件的临时文件生成到待下载大文件的同目录。	N/A
readBufferIoSize	上传数据的缓存大小。单位：字节，默认为 8192。说明可根据实际场景设置该值，上传大量小文件时，建议将该值设置较小；上传大文件时，可将该值设置较大。支持带容量单位配置，例如，配置 1MB 代表 1048576 字节。	[4096，65536]
writeBufferIoSize	下载数据的缓存大小，单位：字节，默认为 65536。说明可根据实际场景设置该值，如果待下载的文件较大，可将该值设置较大。支持带容量单位配置，例如，配置 1MB 代表 1048576 字节。	N/A
checkSourceChange	上传、下载或复制时，是否在上传、下载或复制完成后检测源文件或对象变化，取值说明如下： true：表示开启检测源文件或对象变化。 false（默认）：表示不开启检测源文件或对象变化。	N/A
fsyncForDownload	下载时是否强制同步内存（pagecache）数据到磁盘，取值说明如下： true：表示强制同步。 false（默认）：表示不强制同步。注意对数据可靠性要求极高的场景下可开启该参数；开启该参数后，会对下载性能产生较大影响，请谨慎使用。	N/A
defaultScanConcurrency	批量任务在列举源端数据时的并发数，仅在源端为 HNS 桶或本地文件目录时支持并发列举，默认为 3。	N/A
usePrefetchForDownload	下载对象时，使用并发预读模式顺序写本地文件，默认为 false。	N/A
forceOverwriteForDownload	在 Linux 或 macOS 操作系统上下载对象时，强制覆盖本地可执行文件（即使本地可执行文件正在运行），取值说明如下： true（默认）：表示强制覆盖。 false：表示不强制覆盖。	N/A
forceReadFileChecksumForDownload	执行 cp 命令下载对象时，在执行数据一致性校验时，是否在下载完成后再次读取一遍本地目标文件计算 CRC64 和源端对象进行比较，取值说明如下： true：表示需要读取本地目标文件。 false（默认）：表示不读取本地目标文件。	N/A
forceReadFileChecksumForUpload	执行 cp 命令上传对象时，在执行数据一致性校验时，是否在上传完成后再次读取一遍本地源文件计算 CRC64 和目标端对象进行比较，取值说明如下： true：表示需要读取本地源文件。 false（默认）：表示不读取本地源文件。	N/A
defaultVerifyChecksum	执行 cp 或 fcp 命令时，是否默认启用数据一致性校验机制，取值说明如下： true（默认）：表示启用数据一致性校验机制。 false：表示不启用数据一致性校验机制。	默认值
panicForSymbolicLinkCircle	上传时对于检测到软链接形成环后的处理方式，取值说明如下： true：表示产生 panic 异常。 false（默认）：表示仅记录错误。	N/A
fastFailThreshold	批量任务遇到 4XX 错误后快速失败的阈值，当发生超过该阈值的 4XX 错误后进入快速失败流程，所有未执行或正在扫描的任务会被中断。默认为 5。	N/A
useTempFileForDownloadSmallFile	下载小文件到本地时，是否使用写临时文件模式，为 true 时代表先写临时文件再重命名为最终文件，为 false 时代表直接写最终文件，默认值为 true。	N/A
skipWriteSucceedRecord	是否跳过批量任务成功结果清单文件的生成，为 true 时，代表执行批量任务时不生成成功的结果清单文件，默认值为 true。	N/A
scanLocalFolderByChunk	执行 cp 上传文件夹或 fcp 复制本地文件夹时，使用 chunk 模式读取本地文件夹中的文件，当本地文件夹中文件个数较多时建议设置为 true，默认值为 false。	N/A
abortHttpStatusForResumableTasks	分片上传、下载或复制任务快速中断的 HTTP 状态码，当某个分片子任务的 HTTP 状态码包含在该值范围内时，则会立即中断整个分段上传、下载或复制任务。默认值为：401、403、404、405、409。	N/A
additionalRetryHttpStatus	请求服务端非 2xx 时，额外的支持重试的 HTTP 状态码。默认值为：408。	N/A
additionalRetryEc	请求服务端非 2xx 时，额外的支持重试的 EC 码，优先级高于 additionalRetryHttpStatus。默认值为：0002-00000018	N/A
enablePprof	运行命令时，是否开启 pprof 服务。取值说明如下： true（默认）：表示开启 pprof 服务，端口号为 18888。 false：不开启 pprof 服务。
allowNoDelimiterForHns	使用 HNS 桶时，是否允许不带 delimiter 列举，取值说明如下： true：允许不带 delimiter 列举。 false（默认）：必须携带 delimiter 列举。	N/A
printMemUsageForMount	使用挂载命令时，是否需要在日志中记录内存申请 metrics，取值说明如下： true：在日志中记录内存申请 metrics。 false（默认）：不在日志中记录内存申请 metrics。	N/A
noTruncateForCreateNewFile	创建新文件时，是否使用 Truncate 参数指定文件大小，取值说明如下： true：创建新文件时，不使用 Truncate 参数指定文件大小。 false（默认）：创建新文件时，使用 Truncate 参数指定文件大小。	N/A

最近更新时间：2025.12.02 15:08:35

这个页面对您有帮助吗？

有用

无用