上传文件（cp）
最近更新时间：2026-06-24 17:15:36
cp命令可以用于将本地文件上传至KS3。
以下示例均以Linux为例。
命令格式
./ks3util cp file_url cloud_url
[--object-file <value>]
[-r, --recursive]
[-f, --force]
[-u, --update]
[--update-rule <value>]
[--bigfile-threshold <value>]
[--part-size <value>]
[--only-current-dir]
[--storage-class <value>]
[--acl <value>]
[--meta <value>]
[--tagging <value>]
[--sse-algorithm <value>]
[--include <value>]
[--exclude <value>]
[--time-range <value>]
[-j, --jobs <value>]
[--parallel <value>]
[--checkpoint-dir <value>]
[--disable-crc64]
[--enable-symlink-dir]
[--cycle-symlink-check]
[--dry-run]
[--list-parallel <value>]
[--list-type <value>]
[--list-before-upload]
[--output-dir <value>]参数说明
参数 | 说明 |
|---|---|
file_url | 本地文件或目录路径。 |
cloud_url | KS3文件路径，格式为ks3://bucketname/objectname。 |
--object-file | 需上传的文件列表，内容为本地文件的绝对路径，不同文件路径之间以换行分隔。 |
-r, --recursive | 递归进行操作。当指定该选项时，会对目录下所有符合条件的文件进行操作，否则只对路径指定的单个文件进行操作。 |
-f, --force | 强制操作，不进行询问提示。当目标文件已存在，且没有使用-u选项时，会覆盖目标文件（即所有文件重传）。 |
-u, --update | 更新操作，只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，KS3Util才会执行上传操作，否则会跳过该文件。 |
--update-rule | 使用 可选值： 1：目标文件不存在则更新。 2：目标文件不存在或大小不相等则更新。 3：目标文件不存在或时间戳更旧则更新。 4：目标文件不存在或时间戳更旧或大小不相等则更新。 5：目标文件不存在或CRC64不一致则更新。 |
--bigfile-threshold | 开启大文件分块操作的阈值，大于等于该值的文件会进行分块，并且支持断点续传。格式为：值+单位。单位可选，支持的单位：B、KB、MB、GB、TB，默认单位为B（Byte）。默认值：100MB（104857600）。 |
--part-size | 分块大小，默认情况下根据文件大小自行计算合适的值。格式为：值+单位。单位可选，支持的单位：B、KB、MB、GB、TB，默认单位为B（Byte）。取值范围：5MB-5GB（5242880-5368709120）。 如果有特殊需求或者需要性能调优，可以设置该值。 |
--only-current-dir | 表示仅操作当前目录下的文件，忽略子目录。 |
--storage-class | 设置对象的存储类型，可选值：STANDARD、STANDARD_IA、ARCHIVE。 |
--acl | 设置对象的访问权限，可选值：private、public-read。 |
--meta | 设置对象的元数据，格式为：header:value#header:value（多组值之间以#分隔），例如：Cache-Control:no-cache#Content-Encoding:gzip。 |
--tagging | 设置对象的标签，格式为："TagA=A&TagB=B"（多个标签以&分隔），例如："tag1=value1&tag2=value2"。 该选项的值需要使用双引号包含。 |
--sse-algorithm | 设置服务端加密算法，可选值：AES256、SM4。 |
--include | 包含对象匹配模式，满足匹配规则的文件将会被选中，如：*.jpg。 该选项可以出现多次，多个--include规则取并集。 |
--exclude | 不包含对象匹配模式，满足匹配规则的文件将会被排除，如：*.txt。 该选项可以出现多次，多个--exclude规则取并集。 |
--time-range | 时间段匹配模式，仅匹配最后修改时间在该时间段内的文件。时间段格式为：time1-time2，其中time1、time2需要填写UTC时间，格式为：yyyyMMddHHmmss。 详细请参考通用选项&过滤规则文档。 |
-j, --jobs | 多文件操作时的并发数，表示有多少个文件并行传输。默认值：5，取值范围：1-10000。 1. 批量上传小文件时可适当调大该值；批量上传大文件时，建议保持默认值。 2. 若带宽未跑满，可适当增大该值；若出现传输超时报错，则需适当减小。 3. 4. 总并发数 = jobs × parallel。 |
--parallel | 单文件内部操作的并发任务数，表示单个大文件有多少个块并行传输。取值范围：1-10000。 1. 默认根据文件大小自动调整，取值范围为1-12。 2. 单文件上传时，若带宽未跑满，可适当增大该值。 3. 批量上传时，建议保持默认或调小该值，避免与较大的 |
--checkpoint-dir | checkpoint目录的路径(默认值为:.ks3util_checkpoint)，断点续传时，操作失败KS3Util会自动创建该目录，并在该目录下记录checkpoint信息，操作成功会删除该目录。如果指定了该选项，请确保所指定的目录可以被删除。 |
--disable-crc64 | 关闭CRC64数据校验。默认情况下，KS3Util进行数据传输时都会打开CRC64校验。 |
--enable-symlink-dir | 表示允许上传软链接子目录指向的源文件。使用该参数请确保软链接无循环嵌套情况，否则可能存在数据循环上传风险。可通过 |
--cycle-symlink-check | 表示上传之前进行软链接循环检测。 |
--dry-run | 测试模式运行，不执行实际上传操作，用于验证流程的正确性。 |
--list-parallel | 扫描文件的并发数，默认值：1，取值范围：1-100。 该参数适合在以下场景使用：
仅当源目录下存在子目录层级时，可尝试适当调大后重启任务。 |
--list-type | 上传时指定列举文件使用的方法。默认值：1，可选值：1｜2。当指定为其他值时，等效于1。 |
--list-before-upload | 扫描完全部文件后再上传，只有上传目录时可以使用该选项。使用该选项时，KS3Util会先扫描全部文件并将路径保存在文本文件中，上传时会从该文件中读取待上传文件路径，不会再并行执行列举文件操作。 |
--output-dir | 输出文件的保存目录，包含批量操作时生成的清单文件，扫描生成的文件列表。默认值：ks3util_output（工具当前执行目录的ks3util_output目录下）。 |
除上述的功能参数，关于Util支持的通用选项参数，详情请参考通用选项&过滤规则文档。
使用示例
上传单文件。
如果目标路径以
/结尾，则表示将文件上传至该目录下，objectKey为目标路径 + 原文件名。./ks3util cp /home/sample.txt ks3://samplebucket/abc/
上传后的文件在ks3中的路径为：
ks3://samplebucket/abc/sample.txt。如果目标路径不以
/结尾，则表示将文件上传至该路径，objectKey为目标路径。./ks3util cp /home/sample.txt ks3://samplebucket/abc上传后的文件在ks3中的路径为：
ks3://samplebucket/abc。
上传文件夹，将文件夹（包括子文件夹）内的文件上传至KS3指定路径。批量操作需要使用
-r选项，如果指定路径不以/结尾，则会自动加上/。# 例1: 假设有以下文件 # /home/logs/a.log # /home/logs/bak/b.log # 上传后的文件为 # ks3://samplebucket/my-files/a.log # ks3://samplebucket/my-files/bak/b.log ./ks3util cp /home/logs/ ks3://samplebucket/my-files/ -r1. 如果需要保留文件夹名，则指定路径需以文件夹名结尾。
2. 默认情况下，KS3Util 会上传文件夹内的普通文件，但会跳过其中的软链接子目录。如需上传软链接所指向的源目录内容，可使用
--enable-symlink-dir参数开启此功能。上传文件夹，上传软链接子目录指向的源文件。
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --enable-symlink-dir上传文件夹，上传软链接子目录指向的源文件，且在上传之前进行软链接循环嵌套风险检测。
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --enable-symlink-dir --cycle-symlink-check仅上传当前目录下的文件，忽略子目录下的文件。
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --only-current-dir上传文件夹内的文件，并跳过已存在的文件。
当批量上传失败或需要增量上传时，可以使用-u选项跳过已存在且最后修改时间晚于源文件的文件。
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r -u上传文件夹内的文件，并设置更新规则为5（目标文件不存在或CRC64不一致则更新）。
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r -u --update-rule 5上传文件并指定读写权限ACL。
./ks3util cp sample.txt ks3://samplebucket/sample.txt --acl private上传文件并指定存储类型。
./ks3util cp sample.txt ks3://samplebucket/sample.txt --storage-class STANDARD上传文件并指定meta。
./ks3util cp sample.txt ks3://samplebucket/sample.txt --meta Content-Type:text/plain#Cache-Control:no-cache#X-Kss-Meta-A:a上传文件并指定标签。
./ks3util cp sample.txt ks3://samplebucket/sample.txt --tagging "a=1&b=2"上传文件并指定加密算法。
./ks3util cp sample.txt ks3://samplebucket/sample.txt --sse-algorithm AES256上传符合条件的文件。
上传文件夹中，文件后缀包含
.txt的文件。./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --include "*.txt"上传文件夹时，如果指定
--include和--exclude选项，KS3Util会上传符合指定条件的文件。上传文件夹中，文件后缀包含
.txt的文件，使用正则匹配模式。./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --enable-regex --include ".*\.txt"上传文件夹中，文件路径包含20240626的文件，使用正则匹配模式。
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --enable-regex --path-matching --include ".*20240626.*"上传文件夹中，文件后缀包含
.png，但排除文件名中有temp的文件，使用正则匹配模式。./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --enable-regex --include ".*\.png" --exclude ".*temp.*"上传文件夹中，文件路径包含20240626，但排除文件后缀为
.txt的文件，使用正则匹配模式。./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --enable-regex --path-matching --include ".*20240626.*" --exclude ".*\.txt"
上传指定列表中的文件。
使用准备：创建列表文件list.txt，假设为以下内容。
/root/abc/file1 /root/abc/test/file2上传/root/abc/目录下，且在列表list.txt中的文件到samplebucket的prefix/前缀下。
./ks3util cp /root/abc/ --object-file list.txt ks3://samplebucket/prefix/ -r上传后的文件在ks3中的路径为：
ks3://samplebucket/prefix/file1、ks3://samplebucket/prefix/test/file2。
上传指定列表中的目录。
使用准备：创建列表文件list.txt，假设为以下内容。
/root/abc/dir1/ /root/abc/test/dir2/目录路径需要以路径分隔符结尾。
上传/root/abc/目录下，且在列表list.txt中的目录到samplebucket的prefix/前缀下。
./ks3util cp /root/abc/ --object-file list.txt ks3://samplebucket/prefix/ -r上传后的目录在ks3中的路径为：
ks3://samplebucket/prefix/dir1/、ks3://samplebucket/prefix/test/dir2/。
上传文件夹，测试模式运行。
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --dry-run上传最后修改时间在指定范围的文件。
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --time-range "20241106120000-20241110120000"上传文件夹，设置扫描并发数为5。
./ks3util cp local_dir/ ks3://samplebucket/dest_prefix/ -r -f --list-parallel 5上传文件夹，更换扫描文件的方式。
./ks3util cp local_dir/ ks3://samplebucket/dest_prefix/ -r -f --list-type 2上传文件夹，使用扫描完全部文件后再上传的方式。
./ks3util cp local_dir/ ks3://samplebucket/dest_prefix/ -r -f --list-before-upload
点击打开新浏览器页面