金山云-文档中心-同步目录（sync）

对象存储(KS3)

查看更多结果

未找到含当前关键字的文档标题

页面目录

全部展开全部收起

产品更新动态

未找到含该关键词的产品

文档中心

对象存储(KS3)

常用工具

工具汇总

KS3Util命令行工具

对象操作

同步目录（sync）

最近更新时间：2026-04-10 20:40:21



该命令用于将本地文件目录或者KS3 Prefix从源端同步到目的端。

不支持本地目录之间的同步。

sync命令和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`	该选项表示从ks3同步到本地目录时，用于备份目的端文件的目录，不能是目的端目录的子目录，如果输入了`--delete`，该选项必须输入。

其他选项说明、sync命令用法和cp命令相同。

命令格式

# 将本地目录同步到ks3 prefix
ks3util sync local_dir ks3://bucketname[/prefix] 
[-f, --force] 
[-u, --update]
[--update-rule <value>]
[--sse-algorithm <value>]
[-j, --jobs <value>]
[--parallel <value>]
[--delete] 
[--backup-dir]
[--disable-crc64]
[--dry-run]
[--recover <value>]
[--disable-temp-file]
[--list-parallel <value>]
[--list-depth <value>]
[--list-type <value>]
[--list-before-upload]
[--output-dir <value>]

参数说明

参数	说明
local_dir	本地目录。
bucketname	操作的桶名。
prefix	操作的对象前缀。
-f, --force	强制操作，不进行询问提示。
-u, --update	更新操作，只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，KS3Util才会执行上传操作。
--update-rule	使用`-u`选项进行增量操作时的更新规则，只有当目标文件满足指定规则时才会更新，否则文件会被跳过。默认值：3。可选值： 1：目标文件不存在则更新。 2：目标文件不存在或大小不相等则更新。 3：目标文件不存在或时间戳更旧则更新。 4：目标文件不存在或时间戳更旧或大小不相等则更新。 5：目标文件不存在或CRC64不一致则更新。
--sse-algorithm	设置服务端加密算法，可选值：AES256、SM4。
-j, --jobs	多文件操作时的并发数，表示有多少个文件并行传输。默认值：5，取值范围：1-10000。 1. 批量操作小文件时，可以适当调大该值，批量操作大文件时，建议先使用默认值。 2. 若未跑满预期带宽，则可适当增大该值；若出现传输超时报错，则需要适当减小该值。 3. 若该值设置的较大，建议同时将--parallel设置为较小的值（比如设置--parallel 1），以防止总并发过大。 4. 总并发计算公式= jobs * parallel。
--parallel	单文件内部操作的并发任务数，表示单个大文件有多少个块并行传输。取值范围：1-10000。 1. 默认根据文件大小取不同的值，自动取值范围为1-12。
--delete	表示需要删除或者移走目的端存在而源端不存在的Object或者文件。
--backup-dir	从ks3同步到本地目录时，用于备份目的端文件的目录，不能是目的端目录的子目录，如果输入了--delete，该选项必须输入。
--disable-crc64	关闭CRC64数据校验。默认情况下，KS3Util进行数据传输时都会打开CRC64校验。
--dry-run	测试模式运行，不执行实际操作，用于验证流程的正确性。
--recover	待恢复失败任务的任务ID。指定该选项时表示恢复失败的任务，此时不需要指定源地址和目标地址，待重传的文件会从失败结果清单中读取。
--disable-temp-file	下载文件时，将不再生成带 .temp 后缀的临时文件，而是直接创建并写入目标文件。该参数适用于将大量小文件下载至网络文件系统时速度较低的场景。 1. 启用该参数后，若任务中断或文件下载失败，会产生不完整的文件。 2. 启用该参数后，使用 `-u` 进行增量下载时，将始终基于 CRC64 校验已下载的文件内容。 3. 若关闭此参数并使用增量下载，将会依据最后修改时间跳过这些不完整的文件，因此请避免这样操作。
--list-parallel	扫描文件的并发数，默认值：1，取值范围：1-100。该参数适合在以下场景使用：下载大量小文件（MB级别以下）到网络文件系统时，下载的tps较慢。从网络文件系统上传大量文件时，扫描速度较慢。仅当源目录下存在子目录层级时，可尝试适当调大后重启任务。
--list-depth	并行扫描的最大深度，超过此深度的目录将不再并行扫描，默认值：1，取值范围：1-100。假设源目录为prefix/，而该目录存在以下结构： prefix/aa/ prefix/aa/1/、prefix/aa/2/ prefix/bb/ prefix/bb/1/、prefix/bb/2/ 值为 1 代表使用 delimiter=/ 扫描顶层（prefix/），获取到 prefix/aa/，prefix/bb/后，二者不再使用 delimiter=/ 进行扫描。值为 2 代表获取到 prefix/aa/，prefix/bb/ 后，二者仍使用 delimiter=/ 进行扫描，再得到的结果不再使用 delimiter=/ 进行扫描。
--list-type	上传时指定列举文件使用的方法。默认值：1，可选值：1｜2。当指定为其他值时，等效于1。
--list-before-upload	扫描完全部文件后再上传，只有上传目录时可以使用该选项。使用该选项时，KS3Util会先扫描全部文件并将路径保存在文本文件中，上传时会从该文件中读取待上传文件路径，不会再并行执行列举文件操作。
--output-dir	输出文件的保存目录，包含批量操作时生成的清单文件，扫描生成的文件列表。默认值：ks3util_output（工具当前执行目录的ks3util_output目录下）。

除上述的功能参数，关于Util支持的通用选项参数，详情请参考通用选项&过滤规则文档。

使用示例

示例一：从本地目录同步到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 ./test_dir ks3://samplebucket/test_sync/ -u -f --sse-algorithm AES256

示例二：从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

示例四：从本地目录同步到ks3，测试模式运行。

./ks3util sync ./test_dir ks3://samplebucket/test_sync/ -u -f --dry-run

示例五：从ks3同步到本地目录，不生成临时文件，若本地已存在同名文件，则覆盖。
```
./ks3util sync ks3://samplebucket/test_sync/ ./test_dir -u -f --disable-temp-file
```

示例六：通过任务ID恢复失败的任务。

./ks3util sync --recover fcab4805-ee1e-4d8f-b313-e0c4d8733266 -f

示例七：从ks3同步到本地目录，设置扫描并发数为5，最大并发扫描深度为1。
```
./ks3util sync ks3://samplebucket/test_sync/ ./test_dir -f --list-parallel 5 --list-depth 1
```

示例八：从本地目录同步到ks3，更换扫描文件的方式。

./ks3util sync ./test_dir ks3://samplebucket/test_sync/ -f --list-type 2

示例九：从本地目录同步到ks3，使用扫描完全部文件后再上传的方式。
```
./ks3util sync ./test_dir ks3://samplebucket/test_sync/ -f --list-before-upload
```

文档导读

上一篇：管理文件元信息（set-meta）

下一篇：解冻文件（restore）

纯净模式常规模式

纯净模式

点击可全屏预览文档内容