全部文档
当前文档
最近更新时间：2026-10-08 14:10:48
check 命令用于在数据迁移完成后校验源端与目标端文件的一致性，默认仅比对对象元数据与文件大小，不下载数据，仅显式开启严格校验模式时才会读取数据流计算校验值。
本文所述功能需 2.18.0 及以上版本支持，如您的版本较低，请升级后使用。
check 命令支持以下五种校验类型：
校验类型 | 命令形态 | 适用场景 |
|---|---|---|
本地上传到 KS3 |
| 本地上传至 KS3 后校验 |
KS3 下载到本地 |
| 从 KS3 下载至本地后校验 |
KS3 迁移到 KS3 |
| KS3 桶间复制后校验，支持跨区域、跨账号 |
其他云存储迁移到 KS3 |
| 从 OSS、COS、TOS、OBS 等 S3 兼容源站迁移后校验 |
指定 URL 列表迁移到 KS3 |
| 通过 URL 清单逐条校验迁移结果 |
check 命令按以下顺序逐级校验：
存在性校验：校验源端与目标端文件是否都存在，任一端不存在则记为失败。
大小校验：校验两端文件大小是否一致，不一致则记为失败。
CRC64 校验：若两端都携带 CRC64 校验值则直接对比，一致则记为成功；缺值时进入下一级。
MD5 校验：若两端都携带 MD5 校验值则直接对比，一致则记为成功；缺值时进入下一级。
默认模式：大小一致但缺少可对比的 CRC64/MD5 时，记为成功，不下载任何数据。
严格校验模式（--enable-strict-check）：当缺少校验值时，读取数据流计算校验值后完成对比。
校验完成后，控制台输出汇总统计：
成功数：校验通过的文件数（含成功字节数）。
失败数：拆分为"不存在""校验值不一致""其他错误"三类。
跳过数：源端为目录的条目计为跳过，不影响普通文件的校验。
如需导出完整明细，使用 --output-check-result 选项生成 CSV 文件，各字段含义：
字段 | 说明 |
|---|---|
| 源端路径 / 目标端路径 |
| 源端大小 / 目标端大小 |
| 源端校验值 / 目标端校验值 |
| 校验值来源， |
| 校验状态： |
| 校验方法： |
| 结果描述或失败原因 |
./ks3util check src_url dst_url
[-r, --recursive]
[-j, --jobs <value>]
[--output-check-result]
[--output-dir <value>]
[--enable-strict-check]
[--sample-rate <value>]
[-f, --force]
[--bandwidth-limit <value>]
[--profile <value>]
[--url-file <value>]
[--only-current-dir]
[--enable-symlink-dir]参数 | 说明 |
|---|---|
-r, --recursive | 递归进行操作。当指定该选项时，会对目录下所有符合条件的文件进行操作，否则只对路径指定的单个文件进行操作。 |
-j, --jobs | 文件校验并发数，默认值：5，取值范围：1-10000。 |
--output-check-result | 输出校验结果明细。默认仅输出成功与失败的文件数量；启用后会将每个文件的校验结果逐条写入 CSV 文件。 |
--output-dir | 输出文件的保存目录，默认为工具当前执行目录下的 |
--enable-strict-check | 使用严格校验模式。默认情况下，若文件缺少 crc64 或 md5 校验值，则会比较文件大小；启用该参数后，会下载文件数据流，计算校验值来完成校验。 |
--sample-rate | 抽样校验比例，取值 1–100 的整数，按该百分比随机抽取文件进行校验，未设置时默认对所有文件校验。 |
-f, --force | 强制执行，跳过严格校验模式的确认提示。 |
--bandwidth-limit | 客户端带宽限速，用于限制严格校验模式下载文件的速度。格式为：值+单位，默认单位为 B（Byte），可选单位 B、KB、MB、GB。例如 100MB 表示限速 100MB/s。 |
--profile | 指定使用的配置 profile，跨账号、跨云两端凭证不同时可用 |
--url-file | 待校验的 HTTP URL 列表文件，每行一个 URL。仅用于 URL 列表迁移到 KS3 的校验。 |
--only-current-dir | 仅操作当前目录下的文件，忽略子目录。 |
--enable-symlink-dir | 校验软链接子目录指向的源文件。 |
将本地文件或目录上传至 KS3 后，校验本地源文件与 KS3 目标对象的一致性。源端为本地文件系统，目标端为 KS3 对象。
准备：配置目标端 KS3 的访问凭证（用 config 命令配置默认 profile 即可）。
./ks3util config递归校验本地 local_dir/ 目录与 KS3 桶 samplebucket 的 data/ 前缀下对象的一致性。
./ks3util check local_dir/ ks3://samplebucket/data/ -r递归校验并输出校验报告。
./ks3util check local_dir/ ks3://samplebucket/data/ -r --output-check-result从 KS3 下载文件或目录到本地后，校验 KS3 源对象与本地目标文件的一致性。源端为 KS3 对象，目标端为本地文件系统。
准备：配置源端 KS3 的访问凭证（用 config 命令配置默认 profile 即可）。
./ks3util config递归校验 KS3 桶 samplebucket 的 data/ 前缀下对象与本地 local_dir/ 目录的一致性。
./ks3util check ks3://samplebucket/data/ local_dir/ -r递归校验并输出校验报告。
./ks3util check ks3://samplebucket/data/ local_dir/ -r --output-check-result在 KS3 桶间复制对象后，校验源桶与目标桶对象的一致性。源端与目标端均为 KS3 对象，支持跨区域、跨账号复制后的校验。
准备：同账号同区域配置默认 profile 即可；跨账号需分别为源端、目标端配置访问凭证。建立源端配置 src。
./ks3util config profile src输出示例：
配置文件不存在，初始化配置：
文件路径：/home/user/.ks3utilconfig
对于以下配置，回车将跳过该配置项的设置：
请输入accessKeyID：srcAK
请输入accessKeySecret：srcSK
请输入endpoint [ks3-cn-beijing.ksyuncs.com]：ks3-cn-beijing.ksyuncs.com
配置文件初始化成功。再建立目标端配置 dst（流程同上，配置名输入 dst，填入目标端凭证）。
./ks3util config profile dst同账号同区域，递归校验源桶 src-bucket 与目标桶 dst-bucket 的 data/ 前缀下对象的一致性。
./ks3util check ks3://src-bucket/data/ ks3://dst-bucket/data/ -r跨账号，递归校验并输出校验报告，用 --profile src,dst 指定两端凭证。
./ks3util check ks3://src-bucket/data/ ks3://dst-bucket/data/ -r --profile src,dst --output-check-result将其他云存储（如 OSS、COS、TOS、OBS 等 S3 兼容源站）的对象迁移到 KS3 后，校验源站对象与 KS3 目标对象的一致性。源端以 s3:// 为前缀，目标端以 ks3:// 为前缀。
准备：S3 兼容源站与 KS3 目标分属不同凭证，需分别为两端配置访问凭证。建立源端配置 src（endpoint 填 S3 源站域名）。
./ks3util config profile src输出示例：
配置文件不存在，初始化配置：
文件路径：/home/user/.ks3utilconfig
对于以下配置，回车将跳过该配置项的设置：
请输入accessKeyID：srcAK
请输入accessKeySecret：srcSK
请输入endpoint [ks3-cn-beijing.ksyuncs.com]：s3.example.com
配置文件初始化成功。再建立目标端配置 dst（流程同上，配置名输入 dst，endpoint 填 KS3 域名）。
./ks3util config profile dst递归校验 S3 兼容源站 src-bucket 与 KS3 桶 dst-bucket 的 data/ 前缀下对象的一致性，用 --profile src,dst 指定两端凭证。
./ks3util check s3://src-bucket/data/ ks3://dst-bucket/data/ -r --profile src,dst递归校验并输出校验报告。
./ks3util check s3://src-bucket/data/ ks3://dst-bucket/data/ -r --profile src,dst --output-check-result通过 URL 清单（每行一个 HTTP/HTTPS URL）将文件迁移到 KS3 后，按清单逐条校验迁移结果。源端为 URL 列表，目标端以 ks3:// 为前缀。
准备：配置目标端 KS3 的访问凭证（用 config 命令配置默认 profile 即可）。
./ks3util config按 URL 清单 url_list.txt 校验迁移到 KS3 桶 samplebucket 的对象的一致性。
./ks3util check --url-file url_list.txt ks3://samplebucket/校验并输出校验报告。
./ks3util check --url-file url_list.txt ks3://samplebucket/ --output-check-result纯净模式