rclone checksum 详解：用 SUM 文件校验云端存储文件完整性的完整指南

导读

rclone checksum 是 rclone（"rsync for cloud storage"）中用于将远端存储上的文件哈希值逐一与本地/远端 SUM 清单文件（如 md5sum 生成的校验和文件）比对的命令。它只做只读校验、绝不改动文件系统，适用于数据完整性巡检、迁移后一致性验证、长期归档文件的防篡改审计等场景。读完本文，你将掌握 rclone checksum 的完整语法、全部报告类参数（--differ、--combined 等）的语义与组合用法，并理解其底层基于 march 遍历与并发哈希计算的实现机制。

命令定位：checksum 与 hashsum / check 的关系

在深入参数之前，先明确 rclone 命令族中的分工，这有助于判断何时该用 checksum：

命令	功能定位	典型场景
rclone hashsum [<hash> remote:path]	生成（而不是比对）远端所有对象的哈希清单，输出格式与标准 md5sum/sha1sum 工具一致	先为远端目录产出 SUM 文件
rclone check source:path dest:path	直接比较两个远端/本地文件系统中的文件是否匹配（自动挑选两端共同支持的哈希）	两个目录树之间的对拍
rclone checksum <hash> sumfile dst:path	用一份 SUM 文件作为"源"，去校验目标路径中的文件哈希是否与清单一致	用已有的 md5sum/sha1sum 清单核验远端数据

三者共享同一套底层校验报告机制（--one-way、--differ、--combined 等来自 cmd/check/check.go 的公共 flags，由 cmd/checksum/checksum.go 通过 check.AddFlags(cmdFlags) 复用）；而 hashsum 也能通过 --checkfile/-C 指定 SUM 文件后调用同一份校验核心。命令入口代码见 cmd/checksum/checksum.go：先解析哈希类型，再用 cmd.NewFsSrcFileDst 把「SUM 文件」与「目标路径」解析为文件系统，最终调用 operations.CheckSum。该命令自 v1.56 起提供（见源码 Annotations 中的 versionIntroduced）。

语法与基本用法

rclone checksum <hash> sumfile dst:path [flags]

三个位置参数的含义：

• <hash>：要使用的哈希算法名，大小写不敏感，如 MD5、SHA-1、SHA256、CRC-32、BLAKE3 等。rclone 内置的可用哈希类型在 fs/hash/hash.go 中注册：md5、sha1、whirlpool、crc32、sha256、sha512、blake3、xxh3、xxh128。哈希名解析逻辑见 Type.Set（fs/hash/hash.go），支持小写名称与大小写别名。
• sumfile：SUM 清单文件路径。文件可位于本地或任意已配置的远端，其格式兼容标准 md5sum/sha1sum 工具输出，即每行 哈希值 [空格][*|空格]文件名。SUM 文件中的哈希值大小写不敏感（解析时统一转为小写，见 fs/operations/check.go）。
• dst:path：待校验的目标目录路径，rclone 会递归列出其下所有文件并与清单逐项比对。

最小示例

# 1) 先用 hashsum 为本地/远端目录生成 MD5 SUM 清单
rclone hashsum MD5 remote:backup > backup.md5

# 2) 用该清单校验远端目录，SUM 文件同样可以放在远端
rclone checksum MD5 backup.md5 remote:backup

# 校验结果 OK 的日志形如：
# 2026/09/07 04:10:01 DEBUG : file1.txt: md5 = 5d41402abc4b2a76b9719d911017c592 OK
# 2026/09/07 04:10:01 : remote:backup: 123 matching files
# 2026/09/07 04:10:01 : remote:backup: 0 differences found

命令对目标文件只做哈希读取与比对，不写入、不删除、不移动任何数据，即文档所述 "It doesn't alter the file system"。这一点在实现层面有保证：CheckSum 全程只调用 obj.Hash 或下载流式哈希，从不调用任何写接口。

核心选项逐一解析

--download：远端不支持哈希时的兜底方案

默认情况下，checksum 直接向远端索取其已存储的哈希元数据（obj.Hash(ctx, hashType)），速度快、零流量。但当远端本身不支持该哈希算法时，校验无法进行。

加入 --download 后，命令会把文件内容下载到本地并在流式读取过程中计算哈希，从而做到"任何哈希可用于任何远端"，代价是消耗下载带宽。这一分支的实现见 fs/operations/check.go：download 为真时通过 Open 打开对象、用 hash.StreamTypes(in, hash.NewHashSet(hashType)) 单遍流式计算。--download 变量在 cmd/checksum/checksum.go 中注册。

此外，若未指定 --download 而所选哈希类型不被目标远端支持，CheckSum 会直接报错（fs/operations/check.go）：hash type is not supported by file system。

--one-way：单向校验，忽略目标端多余文件

默认双向模式下，目标端存在的、SUM 清单里没有的文件会被当作"源缺失"而报告为差异。指定 --one-way 后只要求源（清单）中的文件在目标中存在且匹配，目标端多出的文件不视为问题。在 fs/operations/check.go 中可以看到：对象在目标中找到但清单里没有条目时，若 OneWay 为真则直接跳过（return），不会计为差异。这一特性适合"只需确认已归档内容未被篡改/丢失"的审计场景，因为目标目录可能本来就持续新增了别的文件。

差异报告参数（均可写入文件或 stdout）

以下五个参数将"符合条件的文件路径"逐行写入指定的文件名；若传 - 则输出到标准输出（stdout）：

参数	写入内容
--match string	源与目标都存在且哈希一致的文件
--differ string	源与目标都存在但内容不一致的文件
--missing-on-src string	只存在于目标端（清单中缺失）的文件
--missing-on-dst string	只存在于源/清单中（目标端缺失）的文件
--error string	读取或哈希过程中出错（以及清单中重复条目）的文件

提醒：对 checksum 而言，SUM 文件被视作 source（源），dst:path 被视作 destination（目标），因此 --missing-on-src 实际报告的是"清单里没有、但目标端存在的文件"，--missing-on-dst 报告的是"清单里有、但目标端找不到的文件"。理解这一方向约定才不会读反结果。参数命名与选项列表可在 cmd/check/check.go 核对。

--combined：diff 风格的综合报告

--combined 把所有文件汇总到同一份报告里，每行格式为"一个符号 + 空格 + 路径"，酷似 diff 输出，便于一眼扫出全貌：

符号	含义
= path	源与目标都有，且完全一致
- path	目标端有、源（清单）缺失（仅存在于 destination）
+ path	源（清单）有、目标端缺失（仅存在于 source）
* path	两端都有但内容不同
! path	读取或哈希源/目标时出错

示例：--combined - 把带符号的综合结果直接打到终端。上述符号规则与源码中的 sigil 完全对应——reportFilename 以 sigil 前缀写入 combined 流，-/+/*/=/! 分别对应 DstOnly、SrcOnly、differ、match、error 五种结局（见 fs/operations/check.go 与各计数点的 c.report(...) 调用）。

-h, --help

查看该命令的完整帮助。

并发控制：--checkers

默认的并行校验数为 8（--checkers 的全局默认值）。校验过程通过 CheckFn 中的 token channel（容量为 ci.Checkers）限制并发哈希计算的 goroutine 数量（fs/operations/check.go）。大量小文件场景可调大 --checkers 提速；需小心别给 API 造成压力。

实操：综合使用范例

双向校验并输出多类报告

rclone checksum MD5 sums.md5 remote:backup \
  --combined report.txt \
  --differ differs.txt \
  --missing-on-dst missing-on-dst.txt \
  --missing-on-src missing-on-src.txt \
  --match matches.txt

生成的 report.txt 片段示例：

= docs/README.md
* photos/img001.jpg
+ data/archive.tar.gz
! logs/corrupt.log

一次性输出汇总报告到终端

rclone checksum SHA256 manifest.sha256 remote:data --combined -

单向审计模式（忽略远端新增文件）

rclone checksum SHA-1 archive.sha1 remote:archive --one-way --differ - --error -

对不提供哈希的远端做强校验

rclone checksum MD5 local.md5 remote:nohash-bucket --download --combined -

SUM 文件解析与容错规则

checksum 对 SUM 文件采用严格的正则解析：每行必须匹配 ^([^ ]+) *$，即"哈希 + 空格 + 可选的 *（二进制标记）+ 文件名"。完整解析逻辑见 ParseSumFile（fs/operations/check.go），值得注意的行为有：

• 空白行被跳过；格式非法的行会被忽略并打印警告，最多提示 3 处、后续警告静默（suppressed...）；
• 同一文件出现重复条目时，后者被视为非法并被跳过（避免哈希覆盖歧义）；运行时若遇到清单中文件名的重复消费，会按"duplicate file"错误处理并计入 --error；
• 所有哈希值按小写归一化存储，与文档中"SUM 文件哈希值大小写不敏感"一致；
• 若 SUM 文件无法打开或解析失败，命令直接报错（cannot open sum file / failed to parse sum file）。

底层实现原理：校验是如何完成的

理解 rclone checksum 的实现能帮你预判其行为边界。核心链路如下：

1. 入口：cmd/checksum 命令在 cmd/checksum/checksum.go 中注册 --download 并复用 cmd/check 的公共 flags；执行体把参数交给 operations.CheckSum（cmd/checksum/checksum.go）。
2. 选项组装：cmd/check 的 GetCheckOpt 根据各报告参数把 - 映射为 os.Stdout、其余按文件名创建输出文件，统一收集为待关闭的 io.Closer（cmd/check/check.go）。
3. 解析清单：CheckSum 打开 SUM 文件对象，调用 ParseSumFile 得到 map[文件名]哈希值 的内存字典（fs/operations/check.go）。
4. 遍历目标并并发比对：对 dst:path 用 ListFn 递归枚举对象；每个对象通过 token channel 限流后进入 goroutine，非 download 模式直接取远端哈希，download 模式则下载并流式计算（fs/operations/check.go、fs/operations/check.go）。单对象结果由 matchSum 归类：匹配/不匹配/无法校验/出错分别计数并决定写入哪个报告流（fs/operations/check.go）。
5. 清点未消费条目：遍历结束后，仍在字典中"未被消费"的条目说明目标端找不到对应文件，作为 MissingOnDst（+）补报；此外校验会尊重过滤规则，被 --include/--exclude/--files-from 等过滤掉的路径不会误报缺失（fs/operations/check.go）。
6. 结果统计与退出码：reportResults 汇总并打印 X files missing、X differences found、X matching files 等统计（fs/operations/check.go）。只要存在差异或错误，命令最终会返回错误并使 rclone 以非零退出码结束——这使 checksum 可以安全地嵌入 CI/巡检脚本作为断言。

与过滤/列表类全局选项的关系

checksum 还接受 rclone 的 Filter 选项与 Listing 选项（这部分由命令的 groups: Filter,Listing 注解声明，可作用于路径列举阶段）：

• Filter Options：--include、--exclude、--exclude-from、--filter、--files-from、--min-size、--max-size、--min-age、--max-age、--ignore-case、--max-depth 等，用于裁剪"实际参与比对的文件范围"。注意 SUM 文件中的哈希是按目标端实际列举结果消费的，被过滤掉的目标文件其对应清单条目最终会被忽略（见上一步骤 5 的 IncludeRemote 判断），因此当需要"只校验目录子集"时，可同时用过滤规则与完整清单精确配合。
• Listing Options：--fast-list（远程支持时用递归列表，更快但更耗内存）、--default-time（modtime 未知时展示用的时间）。--fast-list 在大目录 + 支持递归列举的远端（如 S3、Google Drive）上能显著减少 API 事务数。
• 更完整的全局选项请参考 rclone 的 flags 全局说明（如存在）与 rclone 命令文档。

结果解读与退出行为速查

命令结束时会在日志中打印几类汇总（对应 fs/operations/check.go）：

• N files missing（目标端缺文件数，来源统计 dstFilesMissing）；
• N hashes missing（清单中无法在目标找到的条目数）；
• N differences found（两端都存在但哈希不一致 + 单向缺失等所有差异总和）；
• N errors while checking（读取出错数）；
• N hashes could not be checked（远端未返回哈希，仅在非 download 且无共同哈希的个别情形）；
• N matching files（完全一致数）。

一旦 differences > 0 或发生错误，进程以非零退出码返回。因此：

• 本地无 */! 报告且 0 differences found → 退出码 0，可视为通过；
• 出现 */+/- → 数据不一致，建议进一步用 --download 复验后处理；
• 出现 ! → 需先排查读取/网络层面的错误再谈一致性。

小结：何时用 checksum、何时用 check

• 手头已有 md5sum/sha1sum 风格的清单文件（如发布包签名、第三方下发的校验文件）→ 用 rclone checksum <hash> sumfile dst:path 直接在远端核验；
• 需要在两端目录树之间直接互检 → 用 rclone check；
• 需要先为远端生成清单再分发 → 用 rclone hashsum ... --output-file（或专门的 md5sum/sha1sum 命令）；
• 需要校验加密远端内容时，可使用针对 crypt remote 的专用 cryptcheck。

checksum 是文档中标注为只读、基于哈希元数据的轻量级命令，通过 --download 可扩展为全量内容校验，配合 --combined 的报告能很好地作为数据完整性的可追溯审计手段。

关键源码索引

• 命令实现：cmd/checksum/checksum.go
• 共享 flags（--one-way、--combined、--differ、--missing-on-*、--match、--error）与选项组装：cmd/check/check.go
• 核心校验算法 CheckSum、SUM 解析 ParseSumFile、报告 sigil 规则与并发控制：fs/operations/check.go
• 校验核心测试 TestParseSumFile、TestCheckSum、TestCheckSumDownload、TestCheckSumConcurrency：fs/operations/check_test.go
• 哈希类型注册与解析：fs/hash/hash.go
• 命令文档索引：docs/content/commands/rclone.md