金山云-文档中心-上传文件（cp）

对象存储(KS3)

查看更多结果

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

页面目录

全部展开全部收起

产品更新动态

未找到含该关键词的产品

文档中心

对象存储(KS3)

常用工具

工具汇总

KS3Util命令行工具

对象操作

上传文件（cp）

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



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	使用`-u`选项进行增量操作时的更新规则，只有当目标文件满足指定规则时才会更新，否则文件会被跳过。默认值：3。可选值： 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. 若该值设置的较大，建议同时将--parallel设置为较小的值（比如设置--parallel 1），以防止总并发过大。 4. 总并发计算公式= jobs * parallel。
--parallel	单文件内部操作的并发任务数，表示单个大文件有多少个块并行传输。取值范围：1-10000。 1. 默认根据文件大小取不同的值，自动取值范围为1-12。 2. 上传单个大文件时，若传输速度未跑满预期带宽，可适当上调该值。
--checkpoint-dir	checkpoint目录的路径(默认值为:.ks3util_checkpoint)，断点续传时，操作失败KS3Utill会自动创建该目录，并在该目录下记录checkpoint信息，操作成功会删除该目录。如果指定了该选项，请确保所指定的目录可以被删除。
--disable-crc64	关闭CRC64数据校验。默认情况下，KS3Util进行数据传输时都会打开CRC64校验。
--enable-symlink-dir	表示允许上传软链接子目录指向的源文件。使用该参数请确保软链接无循环嵌套情况，否则可能存在数据循环上传风险。可通过`--cycle-symlink-check`参数进行上传前的软链接循环嵌套检测。
--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支持的通用选项参数，详情请参考通用选项&过滤规则文档。

使用示例

示例一：上传单文件，上传文件时，如果dest_prefix以/结尾，则objectKey为dest_prefix + 原文件名，否则objectKey为dest_prefix。

# 例1: 上传后的对象为ks3://samplebucket/abc/sample.txt
./ks3util cp /home/sample.txt ks3://samplebucket/abc/

# 例2: 上传后的对象为ks3://samplebucket/abc
./ks3util cp /home/sample.txt 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/ -r
```
1. 如果需要保留文件夹名，则指定路径需以文件夹名结尾。
2. 当文件夹内存在软链接子目录时，默认会把软链接子目录当成一个空文件上传，不会上传软链接子目录对应的源文件。KS3Util提供了--enable-symlink-dir参数支持上传软链接子目录指向的源文件。

示例三：上传文件夹，上传软链接子目录指向的源文件。

./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --enable-symlink-dir

示例四：上传文件夹，上传软链接子目录指向的源文件，且在上传之前进行软链接循环嵌套风险检测。
```
./ks3util cp local_dir ks3://samplebcket/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://samplebcket/dest_prefix/ -r -u
```
示例七：上传文件夹内的文件，并设置更新规则为5（目标文件不存在或CRC64不一致则更新）。
```
./ks3util cp local_dir ks3://samplebcket/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

示例十一：上传文件并指定标签tagging。

./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/file2
```
- Case1：上传根目录下，文件列表list.txt中的文件到samplebucket的prefix/前缀下。
```
./ks3util cp / --object-file list.txt ks3://samplebucket/prefix/ -r
```
  上传后的文件在ks3中的路径为：ks3://samplebucket/prefix/root/abc/file1、ks3://samplebucket/prefix/root/abc/file2。
- Case2：上传/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/file2。

示例十五：上传文件夹，测试模式运行。

./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --dry-run

示例十六：上传最后修改时间在指定范围的文件。

./ks3util cp local_dir ks3://samplebcket/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

示例十九：上传文件夹，使用扫描完全部文件后再上传的方式。
```
./ks3util cp local_dir/ ks3://samplebucket/dest_prefix/ -r -f --list-before-upload
```

文档导读

上一篇：对象操作概述

下一篇：下载文件（cp）

纯净模式常规模式

纯净模式

点击可全屏预览文档内容