全部文档
当前文档
最近更新时间：2025-11-07 14:51:30
该命令用于将本地文件目录或者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后面加上字符’/’。
参数 | 说明 |
|---|---|
| 表示需要删除或者移走目的端存在而源端不存在的Object或者文件。 |
| 该选项表示从ks3同步到本地目录时，用于备份目的端文件的目录，不能是目的端目录的子目录，如果输入了 |
其他选项说明、sync命令用法和cp命令相同。
# 将本地目录同步到ks3 prefix
ks3util sync local_dir ks3://bucketname[/prefix]
[-f]
[-u]
[--sse-algorithm <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才会执行上传操作。 |
--sse-algorithm | 设置服务端加密算法，可选值：AES256。 |
--delete | 表示需要删除或者移走目的端存在而源端不存在的Object或者文件。 |
--backup-dir | 从ks3同步到本地目录时，用于备份目的端文件的目录，不能是目的端目录的子目录，如果输入了--delete，该选项必须输入。 |
--disable-crc64 | 关闭CRC64数据校验。默认情况下，KS3Util进行数据传输时都会打开CRC64校验。 |
--dry-run | 测试模式运行，不执行实际操作，用于验证流程的正确性。 |
--recover | 待恢复失败任务的任务ID。指定该选项时表示恢复失败的任务，此时不需要指定源地址和目标地址，待重传的文件会从失败结果清单中读取。 |
--disable-temp-file | 下载文件时，将不再生成带 .temp 后缀的临时文件，而是直接创建并写入目标文件。该参数适用于将大量小文件（KB 级别）下载至 NAS 网络存储时 TPS（每秒完成数）较低的场景。 1. 启用该参数后，若任务中断或文件下载失败，会产生不完整的文件。 2. 启用该参数后，使用 3. 若关闭此参数并使用增量下载，将会依据最后修改时间跳过这些不完整的文件，因此请避免这样操作。 |
--list-parallel | 扫描文件的并发数，默认值：1，取值范围：1-100。 |
--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纯净模式