使用 tosutil 实现 NAS 与 TOS 数据迁移的最佳实践--文件存储 NAS-火山引擎

文档中心

导航

使用 tosutil 实现 NAS 与 TOS 数据迁移的最佳实践

最近更新时间：2025.04.17 14:54:54首次发布时间：2025.04.17 14:54:54

概述

在跨存储系统的数据流转过程中，文件存储 NAS 提供了高效的解决方案，使用官方命令行工具 tosutil 可对存储内的数据进行导入导出，实现数据在文件存储 NAS 与对象存储 TOS 之间的高效流动。

安装与初始化

tosutil 命令行工具同时支持 Windows、Linux 及 macOS 三大系统，您可以根据实际环境下载和安装合适的版本。
在进行文件存储的数据导入与导出之前，您需要先进行 tosutil 工具的安装与初始化。详细下载与安装过程请参见 tosutil 工具下载与安装，初始化过程请参见 tosutil 初始化。

命令格式

基本格式

Linux/macOS 系统

Windows 系统

./tosutil [command] [args...] [options...]

参数	说明
[command]	需要运行的命令，例如 ls、cp、rm 等，更多命令请见常用命令。
[args...]	运行命令的基本参数，一般为必选，可能存在多个参数，以空格分隔。更多基本参数请见常见基本参数。
[options...]	运行命令的可选参数。当存在多个参数时，以 - 开头作为参数名，以 = 分隔作为参数值，例如 -limit=100。更多可选参数请见通用可选参数。注意当可选参数为布尔类型时，支持仅以 - 开头（不带 = ），表示取值为 true。

常用命令

tosutil 工具常见的命令如下所示。

类型	命令	描述
常用命令	ls	列举桶、列举桶内对象或列举桶内分片导出任务。
	mkdir	创建文件夹。
	du	计算桶内对象和分片的大小和数量。
	mb	根据指定的桶名和参数创建一个新桶。
	cp	导出文件或文件夹。
	setmeta	设置对象元数据。
	stat	查询桶属性或查询对象属性。
	rm	删除桶、删除对象或删除分片导出任务。
	share	为需要分享的对象创建授权码，并通过授权码列举或下载对象。
	set-acl	设置桶或对象的预定义访问策略。
	mount	将存储桶挂载为本地文件系统目录。
辅助命令	config	查看配置文件路径，并更新配置文件中的关键配置信息。
	help	查看命令帮助。
	probe	测试导出速率。
	netdig	支持一键式网络诊断。注意该命令仅支持 Linux 和 macOS。
	hash	计算文件哈希值。
	fcp	复制本地文件或文件夹。
	clear	删除指定文件夹下的断点记录文件，并尽力执行云端清理工作。
	version	查看版本号。
	ping	测量网络延迟。
	connect	计算网络连接耗时。
	traceroute	抓取网络路径。
	curl	发送 HTTP 请求。

常见基本参数

参数	说明
cloud_url	表示 TOS 上的路径，格式为 tos://bucket/[prefix]，其中 prefix 为可选，代表对象名或对象名前缀。
file_url	代表文件路径。
folder_url	代表文件夹路径。

通用可选参数

除部分特殊的辅助命令外，所有命令均可包含可选参数，可选参数说明如下。

参数	说明
-e	代表执行本次命令所使用的 TOS 服务端的 Endpoint。
-re	代表执行本次命令所使用的 TOS 服务端的 Region。
-i	代表执行本次命令所使用的 Access Key ID。说明匿名访问 TOS 时，无需指定 Access Key ID，设置参数为 -i= 即可。
-k	代表执行本次命令所使用的 Secret Access Key 。说明匿名访问 TOS 时，无需指定 Secret Access Key，设置参数为 -k= 即可。
-t	代表执行本次命令所使用的 Security Token，使用临时 AccessKey 时需要。说明匿名访问 TOS 时，无需指定 Security Token，设置参数为 -t= 即可。
-conf	代表执行本次命令所使用的配置文件路径。

注意

当您的命令同时设置了 -conf 和 -e/-re/-i/-k/-t 参数时，-conf 参数仍有效，但该路径下配置文件中的 Access key、Secret key 等参数不生效，以运行命令时指定的 -e/-re/-i/-k/-t 参数优先。

数据导入和导出

您可以通过 cp 命令从 NAS 导出文件到 TOS 或从 TOS 导入对象到 NAS。

命令语法

Linux/macOS 系统

Windows 系统

导出单个文件

./tosutil cp file_url tos://bucket[/key] [-dryRun] [-link] [-u] [-vchecksum] [-p=1] [-threshold=52428800] [-ps=auto] [-cpd=xxx] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-sse=xxx] [-sseKeyId=xxx] [-contentType=xxx] [-contentDisposition=xxx] [-contentEncoding=xxx] [-contentLanguage=xxx] [-cacheControl=xxx] [-expires=xxx] [-arcDir=xxx] [-fr] [-o=xxx] [-bt=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]

导入单个文件

./tosutil cp tos://bucket/key file_url|folder_url [-dryRun] [-tempFileDir=xxx] [-u] [-vchecksum] [-p=1] [-threshold=104857600] [-ps=auto] [-cpd=xxx] [-versionId=xxx] [-fr] [-o=xxx] [-bt=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]

导出文件夹

./tosutil cp folder_url tos://bucket[/prefix] -r [-dryRun] [-link] [-u] [-vchecksum] [-flat] [-j=1] [-p=1] [-threshold=104857600] [-nfj=1] [-ps=auto] [-cpd=xxx] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-sse=xxx] [-sseKeyId=xxx] [-contentType=xxx] [-contentDisposition=xxx] [-contentEncoding=xxx] [-contentLanguage=xxx] [-cacheControl=xxx] [-expires=xxx] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-at] [-ddo] [-dmf] [-arcDir=xxx] [-o=xxx] [-bt=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]

导出文件列表

./tosutil cp file1_url,folder1_url|filelist_url tos://bucket[/prefix] -msm=1 [-r] [-dryRun] [-link] [-u] [-vchecksum] [-flat] [-j=1] [-p=1] [-threshold=104857600] [-nfj=1] [-ps=auto] [-cpd=xxx] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-sse=xxx] [-sseKeyId=xxx] [-contentType=xxx] [-contentDisposition=xxx] [-contentEncoding=xxx] [-contentLanguage=xxx] [-cacheControl=xxx] [-expires=xxx] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-at] [-ddo] [-dmf] [-arcDir=xxx] [-o=xxx] [-bt=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]

批量导入文件

./tosutil cp tos://bucket[/prefix] folder_url -r [-dryRun] [-tempFileDir=xxx] [-u] [-vchecksum] [-flat] [-j=1] [-p=1] [-threshold=104857600] [-nfj=1] [-ps=auto] [-cpd=xxx] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-dmf] [-o=xxx] [-bt=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]

导出单个文件

tosutil cp file_url tos://bucket[/key] [-dryRun] [-link] [-u] [-vchecksum] [-p=1] [-threshold=52428800] [-ps=auto] [-cpd=xxx] [-acl=xxx] [-meta=aaa:bbb#ccc:ddd] [-sse=xxx] [-sseKeyId=xxx] [-contentType=xxx] [-contentDisposition=xxx] [-contentEncoding=xxx] [-contentLanguage=xxx] [-cacheControl=xxx] [-expires=xxx] [-arcDir=xxx] [-fr] [-o=xxx] [-bt=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]

导入单个文件

tosutil cp tos://bucket/key file_url|folder_url [-dryRun] [-tempFileDir=xxx] [-u] [-vchecksum] [-p=1] [-threshold=104857600] [-ps=auto] [-cpd=xxx] [-versionId=xxx] [-fr] [-o=xxx] [-bt=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]

导出文件夹

tosutil cp folder_url tos://bucket[/prefix] -r [-dryRun] [-link] [-u] [-vchecksum] [-flat] [-j=1] [-p=1] [-threshold=104857600] [-nfj=1] [-ps=auto] [-cpd=xxx] [-acl=xxx] [-meta=aaa:bbb#ccc:ddd] [-sse=xxx] [-sseKeyId=xxx] [-contentType=xxx] [-contentDisposition=xxx] [-contentEncoding=xxx] [-contentLanguage=xxx] [-cacheControl=xxx] [-expires=xxx] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-at] [-ddo] [-dmf] [-arcDir=xxx] [-o=xxx] [-bt=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]

导出文件列表

tosutil cp file1_url,folder1_url|filelist_url tos://bucket[/prefix] -msm=1 [-r] [-dryRun] [-link] [-u] [-vchecksum] [-flat] [-j=1] [-p=1] [-threshold=104857600] [-nfj=1] [-ps=auto] [-cpd=xxx] [-acl=xxx] [-meta=aaa:bbb#ccc:ddd] [-sse=xxx] [-sseKeyId=xxx] [-contentType=xxx] [-contentDisposition=xxx] [-contentEncoding=xxx] [-contentLanguage=xxx] [-cacheControl=xxx] [-expires=xxx] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-at] [-ddo] [-dmf] [-arcDir=xxx] [-o=xxx] [-bt=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]

批量导入文件

tosutil cp tos://bucket[/prefix] folder_url -r [-dryRun] [-tempFileDir=xxx] [-u] [-vchecksum] [-flat] [-j=1] [-p=1] [-threshold=104857600] [-nfj=1] [-ps=auto] [-cpd=xxx] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-dmf] [-o=xxx] [-bt=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]

数据导出

导出单个文件

以下命令用于将 /NAS/export 文件夹中的 file1 文件导出至 bucketname 存储桶，导出后文件名为 object。

命令

./tosutil cp /NAS/export/file1  tos://bucketname/object

Start at 2022-10-27 10:49:12.407874 +0000 UTC
 
 
Parallel:      1                   Jobs:          5                   
Threshold:     100.00MB            PartSize:      auto                
VerifyChecksum: false                         
CheckpointDir: /.tosutil_checkpoint
 
[-------------------------------------------] 100.00% ?/s 50.50KB/50.50KB 162ms
 
Upload successfully, 50.50KB, n/a, /NAS/export/file1 --> tos://bucketname/object, cost [164], status [200], request id [2643485a6228acbb635a6228-ac1173a1-1oo0Rk-PuO-cb-tos-bj-3]

导出文件夹

以下命令用于将 /NAS/export 文件夹中的所有文件导出至 bucketname 存储桶，导出后文件夹命名为 cpfile。
说明
该命令会导出文件夹本身，导出后所有的文件仍在 cpfile 文件夹内。

命令

./tosutil cp /NAS/export  tos://bucketname/cpfile -r

Start at 2022-10-27 10:50:43.872787 +0000 UTC
 
 
Parallel:      1                   Jobs:          5                   
Threshold:     100.00MB            PartSize:      auto                
VerifyChecksum: false                         
CheckpointDir: /Users/.tosutil_checkpoint
OutputDir: /Users/.tosutil_output
 
[----------------------------] 100.00% tps:0.00 ?/s 4/4 181.45KB/181.45KB 183ms
Succeed count is:   4         Failed count is:    0         
Succeed bytes is:   181.45KB  
Metrics [max cost:178 ms, min cost:103 ms, average cost:143.75 ms, average tps:21.62]
 
Task id is: 34c8480e-55e5-11ed-806b-aa665a3c7f26

数据导入

导入单个文件

以下命令用于将 bucketname 存储桶内的 object1.png 对象，导入至 /NAS/import 文件夹。

命令

./tosutil cp tos://bucketname/object1.png /NAS/import

Start at 2022-10-27 10:56:20.611282 +0000 UTC
 
 
Parallel:      1                   Jobs:          5                   
Threshold:     100.00MB            PartSize:      auto                
VerifyChecksum: false                         
CheckpointDir: /.tosutil_checkpoint
TempFileDir:               
 
[-------------------------------------------] 100.00% ?/s 55.98KB/55.98KB 106ms
 
Download successfully, 55.98KB, n/a, tos://bucketname/object1.png --> /Downloads/TOS/tosutil/object1.png, cost [106], status [200], request id [5c81485a63d4b1d7635a63d4-ac17b21f-1oo0Ye-GO-cb-tos-bj]

批量导入文件

以下命令用于将 bucketname 存储桶内的前缀为 object 的对象，导入至 /NAS/import 文件夹。

命令

./tosutil cp tos://bucketname/object /NAS/import -r

Start at 2022-10-27 10:56:35.434563 +0000 UTC
 
 
Parallel:      1                   Jobs:          5                   
Threshold:     100.00MB            PartSize:      auto                
VerifyChecksum: false                         
CheckpointDir: /Users/.tosutil_checkpoint
OutputDir: /Users/.tosutil_output
TempFileDir:               
 
[----------------------] 100.00% tps:51.09 3.02MB/s 4/4 238.21KB/238.21KB 278ms
Succeed count is:   4         Failed count is:    0         
Succeed bytes is:   238.21KB  
Metrics [max cost:216 ms, min cost:163 ms, average cost:191.50 ms, average tps:14.23]
 
Task id is: 0653482e-55e6-11ed-afb8-aa665a3c7f26

参数说明

通用可选参数的说明，请参见通用可选参数。

参数名	参数类型	描述
file_url	String	需要导入或导出文件的路径。说明如果您需要导入或导出文件列表，可在命令中添加多个 `file_url`，以英文逗号（,）分隔。
folder_url	String	需要导入或导出的文件夹路径，需要 `-r` 参数配合使用。
bucket	String	桶名。
key	String	对象名。
prefix	String	批量操作时的对象名前缀。
-r	Bool	执行批量导入、导出或复制操作。
-dryRun	Bool	测试模式运行，不执行实际的导入、导出或复制操作。
-link	Bool	导出软链接文件或文件夹指向的真实路径。
-msm	Enum	开启多文件或文件夹导出模式，说明如下： `-msm=1`：代表导出路径是一组文件或文件夹列表，以英文逗号（,）分隔。 `-msm=2`：代表导出路径是一个包含文件或文件夹列表的清单文件。注意如果文件或文件夹名本身包含英文逗号，请不要使用 `-msm=1` 的模式。如果没有设置 `-r` 参数，则列表中的文件夹不会被导出。
-tempFileDir	String	分片导入时保存临时文件的文件夹，默认为配置文件中的 `defaultTempFileDir`。说明如果 `-tempFileDir` 参数为空，则分片导入时生成的临时文件的存储路径默认与待导入文件的存储路径一致，并且文件名称以 `.tos.temp` 结尾。由于导入时生成的临时文件会保存在该目录，请确保运行 tosutil 的用户对该路径有写权限。该路径的可用空间需要大于待导入对象的大小。
-recover	String	待恢复导入、导出或复制文件任务的结果清单文件任务 ID。
-u	Bool	增量导入、导出或复制文件，设置该参数后，会比较源端和目标端，建议您在以下情况下使用：目标端不存在。目标端与源端的文件大小不一致。目标端的最后修改时间早于源端的最后修改时间时执行对应的操作。
-vchecksum	Bool	导入、导出或复制文件时通过 CRC64 算法验证数据一致性。
-flat	Bool	导入、导出或复制文件时不包含相对父目录。
-j	Integer	批量任务的最大并发数，默认为配置文件中的 `defaultJobs`，默认值为 3。
-p	Integer	每个分片任务的最大并发数，默认为配置文件中的 `defaultParallels`，默认值为 1。
-threshold	Integer	开启分片任务的阈值，单位为字节，默认为配置文件中的 `defaultBigfileThreshold`。说明支持带容量单位配置，例如，配置 1MB 代表 1048576 字节。
-nfj	Integer	批量任务的处理普通文件或对象（非分片任务）的最大并发数。当设置该参数后，`-j` 参数设置的并发数会分为两部分，普通文件的并发数为 `nfj`，分片任务的并发数为 `j-nfj`。仅在批量操作时生效。
-ps	Integer/String	每个分片任务的段大小，单位为字节，默认为配置文件中的 `defaultPartSize`。说明支持带容量单位配置，例如，配置 1MB 代表 1048576 字节。
-cpd	String	生成断点记录文件的文件夹，默认为配置文件中的 `defaultCheckpointDir`。
-versionId	String	导入或复制单个对象的版本号。
-acl	String	导出或复制文件时可指定的预定义访问策略。支持的值如下： `private` `public-read` `public-read-write` `authenticated-read` `bucket-owner-read` `bucket-owner-full-control` `bucket-owner-entrusted`
-sc	Enum	导出文件时可指定的对象存储类型，取值说明如下： `STANDARD`：标准存储，默认值。 `IA`：低频访问存储。 `ARCHIVE_FR`：归档闪回存储。 `ARCHIVE`：归档存储。 `COLD_ARCHIVE`：冷归档存储。 `DEEP_COLD_ARCHIVE`：深度冷归档存储。说明当前华北2（北京）和华东2（上海）支持冷归档存储，华南1（广州）处于邀测状态，如您需要在华南1（广州）使用冷归档存储，请联系客户经理。当前仅华北2（北京）、华东2（上海）、华南1（广州）支持深度冷归档，且都处于邀测状态，如您需要使用该存储类型，请联系客户经理。
-meta	String	导出或复制文件时可指定的自定义元数据。
-sse	String	导出、复制文件时使用的服务端加密算法，支持的值： aes256 kms 默认为配置文件中的 defaultSse。
-sseKeyId	String	导出、复制文件且指定服务端加密算法为 kms 时，使用的 kms 密钥，默认为配置文件中的 defaultSseKeyId。
-contentType	String	导出、复制文件时设置文件的 Content-Type。
-contentDisposition	String	导出、复制文件时设置文件的 Content-Disposition。
-contentEncoding	String	导出、复制文件时设置文件的 Content-Encoding。
-contentLanguage	String	导出、复制文件时设置文件的 Content-Language。
-cacheControl	String	导出、复制文件时设置文件的 Cache-Control。
-expires	String	导出、复制文件时设置文件的 Expires，格式为：YYYYMMDDHHmmSS。
-include	String	导入、导出或复制文件时对包含文件的名称匹配模式，支持以下字符： `?` ：匹配单个任意字符。 `` ：匹配多个任意字符。 `#` ：作为分隔符。例如 `-include=.png#*.txt` 表示匹配所有以 `.png` 和 `.txt` 结尾的文件。说明为了避免因操作系统转义特殊符号的导致的解析失败等问题，建议您使用引号设置名称匹配模式。名称匹配模式只在导出文件夹或文件列表时生效。名称匹配模式在文件全路径生效（包含文件名和文件目录）。
-exclude	String	导入、导出或复制文件时对不包含文件的名称匹配模式，支持以下字符： `?` ：匹配单个任意字符。 `` ：匹配多个任意字符。 `#` ：作为分隔符。例如 `-exclude=.png#*.txt` 表示匹配所有以 `.png` 和 `.txt` 结尾的文件。说明为了避免因操作系统转义特殊符号导致的解析失败等问题，建议您使用引号设置名称匹配模式。名称匹配模式只在导出文件夹或文件列表时生效。名称匹配模式在文件全路径生效（包含文件名和文件目录）。
-timeRange	String	导入、导出或复制文件时文件最后修改时间的时间段匹配模式，格式为：`YYYYMMDDHHmmSS-YYYYMMDDHHmmSS`。
-at	Bool	导出文件夹中文件的最后访问时间满足 `-timeRange` 参数的文件列表。
-ddo	Bool	导出时文件夹本身不会作为单独一个对象导出。
-dmf	Bool	设置名称匹配模式 `-include/-exclude` 和时间段匹配模式 `-timeRange` 对文件夹不生效。
-marker	String	批量导入时指定文件的开始位置。
-arcDir	String	导出文件成功后的归档文件夹。
-fr	Bool	操作单个文件时生成结果清单文件。
-o	String	生成结果清单文件的文件夹，默认为配置文件中的 `defaultOutputDir`。
-bt	String	存储桶的类型。取值说明如下： `fns`：扁平桶。 `hns`：分层桶。如果未指定存储桶的类型，则默认从桶元数据获取存储桶的类型。

性能优化建议

tosutil 支持通过 -j 及 -p 参数调整并发数。当您批量导出或导入大文件时，实际并发数为 -j 乘以 -p 参数。调整建议如下：

资源不充足场景

当网络、内存等资源不充足的场景下，建议您不要设置过高的并发数，避免因资源占满导致的性能下降或失败等问题。您可以根据实际资源情况，先设置一个较低的并发数，然后逐渐增大参数，直至调整至一个较优的设置。

提升整体执行的 QPS 和带宽
- 导出小文件：需要设置较高的并发数提升 QPS。
- 导出大文件：避免并发数过高导致带宽抢占造成性能衰减。

您可以通过 -nfj 参数和 -j 参数分别控制非分片任务和分片任务的并发数。例如设置 -j=100，-nfj=80，表示总并发数为 100，当执行非分片任务（一般是小文件）时，最大的并发数为 80；当执行分片任务（一般是大文件）时，最大的并发数为 20。

公网运行场景

由于公网网络不稳定以及客户端带宽较低等因素，容易导致导出缓慢且失败等问题，您可以参考以下建议调整参数：

调大配置文件中的 maxRetryCount 参数，通过不断重试错误解决公网网络不稳定的问题。
如果客户端带宽有限，您需要合理减少 -j 和 -p 参数，避免因并发过高导致客户端超带宽，进而出现断流失败等情况。
合理调整 -ps 参数，降低分片大小，有利于提高单个分片复制的成功率。

注意

在海量小文件场景中，如果您设置了较高的 -j，导致 TPS 超过 1000，您需要同步上调 maxConnections 参数，更多信息，请参见配置文件说明。