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

对象存储(KS3)

查看更多结果

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

页面目录

全部展开全部收起

产品更新动态

未找到含该关键词的产品

文档中心

对象存储(KS3)

常用工具

工具汇总

KS3Util命令行工具

对象操作

上传文件（cp）

最近更新时间：2025-11-07 15:16:09



cp命令可以用于将本地文件上传至KS3。

以下示例均以Linux为例。

命令格式

./ks3util cp file_url cloud_url 
[--object-file <value>]
[-r, --recursive] 
[-f, --force] 
[-u, --update]
[--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才会执行上传操作，否则会跳过该文件。
--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。
--include	包含对象匹配模式，满足匹配规则的文件将会被选中，如：*.jpg。该选项可以出现多次，多个--include规则取并集。
--exclude	不包含对象匹配模式，满足匹配规则的文件将会被排除，如：*.txt。该选项可以出现多次，多个--exclude规则取并集。
--time-range	时间段匹配模式，仅匹配最后修改时间在该时间段内的文件。时间段格式为：time1-time2，其中time1、time2需要填写UTC时间，格式为：yyyyMMddHHmmss。详细请参考通用选项&过滤规则文档。
-j, --jobs	多文件操作时的并发数，默认值：5，取值范围：1-10000。 1. 该参数决定有多少个文件并行上传。 2. 批量操作文件时适合调整该参数。 3. Util2.9.0版本默认值由3改为5。
--parallel	单文件内部操作的并发任务数，取值范围：1-10000。 1. 默认KS3 Util会根据操作类型和文件大小自动决定，自动取值范围是1-12。 2. 该参数决定单个文件有多少个块并行上传。 3. 操作单个大文件时适合调整该参数。 4. 总并发数= jobs * parallel。
--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
```
示例六：上传文件夹内的文件，并跳过已存在的文件。
批量上传失败重传时，可以指定--update（可缩写为-u）选项跳过已经上传成功的文件，实现增量上传。
```
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r -u
```

示例七：上传文件并指定读写权限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中的文件。
```
./ks3util cp / --object-file list.txt ks3://samplebucket/prefix/ -r
```
  上传后的文件在ks3中的路径为：ks3://samplebucket/prefix/root/abc/file1、ks3://samplebucket/prefix/root/abc/file2。
- Case2：上传list.txt中的文件，去掉/root/abc/前缀。
```
./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）

纯净模式常规模式

纯净模式

点击可全屏预览文档内容