全部文档
当前文档
最近更新时间：2026-08-05 17:12:33
该命令用于将本地文件目录或者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命令在-r被输入时也会在prefix后面加上字符 ’/’。
参数 | 说明 |
|---|---|
| 表示需要删除或者移走目的端存在而源端不存在的Object或者文件。 |
| 该选项表示从ks3同步到本地目录时，用于备份目的端文件的目录，不能是目的端目录的子目录，如果输入了 |
其他选项说明、sync命令用法和cp命令相同。
ks3util sync src_url dst_url
[-f, --force]
[-u, --update]
[--update-rule <value>]
[--sse-algorithm <value>]
[-j, --jobs <value>]
[--parallel <value>]
[--bandwidth-limit <value>]
[--delete]
[--backup-dir]
[--disable-crc64]
[--dry-run]
[--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 | 使用 可选值： 1：目标文件不存在则更新。 2：目标文件不存在或大小不相等则更新。 3：目标文件不存在或时间戳更旧则更新。 4：目标文件不存在或时间戳更旧或大小不相等则更新。 5：目标文件不存在或CRC64不一致则更新。 |
--sse-algorithm | 设置服务端加密算法，可选值：AES256、SM4。 |
-j, --jobs | 多文件操作时的并发数，表示有多少个文件并行传输。默认值：5，取值范围：1-10000。 1. 同步文件时，若带宽未跑满，可适当调大 2. 当 3. 避免同时调大 |
--parallel | 单文件内部操作的并发任务数，表示单个大文件有多少个块并行传输。取值范围：1-10000。 1. 默认根据文件大小自动调整，取值范围为 1-16。 2. 同步文件时，建议 |
--bandwidth-limit | 设置网络带宽限速，用于限制文件传输速度。例如：100MB 表示限速 100MB/s。
可选单位：B、KB、MB、GB。 |
--delete | 表示需要删除或者移走目的端存在而源端不存在的Object或者文件。 |
--backup-dir | 从ks3同步到本地目录时，用于备份目的端文件的目录，不能是目的端目录的子目录，如果输入了--delete，该选项必须输入。 |
--disable-crc64 | 关闭 CRC64 数据校验。默认情况下数据传输时自动开启 CRC64 校验以确保完整性。 |
--dry-run | 测试模式运行，不执行实际操作，用于验证流程的正确性。 |
--disable-temp-file | 下载文件时，将不再生成带 .temp 后缀的临时文件，而是直接创建并写入目标文件。该参数适用于将大量小文件下载至网络文件系统时速度较低的场景。 1. 启用该参数后，若任务中断或文件下载失败，会产生不完整的文件。 2. 启用该参数后，使用 3. 若关闭此参数并使用增量下载，将会依据最后修改时间跳过这些不完整的文件，因此请避免这样操作。 |
--list-parallel | 扫描文件的并发数，默认值：1，取值范围：1-100。 |
--list-depth | 并行扫描的最大目录深度，默认值：1，取值范围：1-100。该值影响扫描策略，值越大并行扫描的目录层级越深，但不影响最终扫描到的文件总数。 |
--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同步并指定加密算法。
./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纯净模式