rclone bisync 双向同步命令完全指南选项详解、执行原理与数据安全防护【免费下载链接】rclonersync for cloud storage - Google Drive, S3, Dropbox, Backblaze B2, One Drive, Swift, Hubic, Wasabi, Google Cloud Storage, Azure Blob, Azure Files, Yandex Files项目地址: https://gitcode.com/GitHub_Trending/rc/rclonerclone bisync是 rclone 提供的一个高级双向同步命令它通过维护上一次运行生成的 Path1 与 Path2 文件系统清单listing来感知两侧各自发生的New / Newer / Older / Deleted变化并将变化双向传播实现“云盘界的 rsync”。本指南以命令参考文档 rclone_bisync.md 为主体结合主手册 bisync.md 与 cmd/bisync 下的实现源码完整梳理该命令的每一次同步选项、冲突处理机制、安全阀与源码级设计原理。读完本文你将能安全地完成第一次--resync初始化、正确地规划后续例行同步的参数组合并在出问题时准确判断该使用--resync、--recover还是--resilient。一、命令定位与工作原理rclone bisync 的官方定位是 “Perform bidirectional synchronization between two paths”在两个路径之间执行双向同步自v1.58引入见命令文档头部元数据与 cmd/bisync/cmd.go 中commandDefinition的versionIntroduced: v1.58注解。与rclone sync单向镜像不同bisync 的核心思路是比较“上次同步的状态”而非两个实时文件系统它保留 Path1、Path2 各自上一次的完整文件清单每次运行重新列出两侧文件与上次清单比对找出变化。变化分为New新增、Newer更新、Older更旧与Deleted已删除把 Path1 上的变化传播到 Path2同时把 Path2 上的变化传播回 Path1。命令文档对此有一句明确的警告Bisync 属于高级命令使用需谨慎——使用前必须完整阅读 bisync 主手册尤其是其Limitations限制小节否则可能导致数据丢失。在代码层面一次运行由 cmd/bisync/operations.go 中的Bisync()入口承载其大致编排为应用比较compare默认值与各选项setCompareDefaults初始化工作目录并计算本次同步的basePath据此派生.path1.lst、.path2.lst清单文件以及-new临时清单通过setLockFile获取锁文件避免多个实例并发运行注册 SIGINT 优雅停机处理然后执行runLocked完成清单对比、差异排队与复制/删除。从 v1.66 起bisync 重新设计为“快照”模型主手册Concurrent modifications一节说明极大地降低了同步过程中文件被并发修改所带来的风险本次未检测到的变化会在下一次运行时被捕获而不再直接让整次运行抛出 critical 错误。二、命令语法与首次使用流程命令基本语法与命令文档 Synopsis 完全一致rclone bisync remote1:path1 remote2:path2 [flags]两个位置参数均为“本地路径或带:及可选子路径的远程存储”可用rclone listremotes查看已配置的 remote。cmd/bisync/cmd.go 还做了参数校验若两个路径解析出的是文件而非目录将报错paths must be existing directories。主手册Getting started小节给出了标准的上手流程安装 rclone 并配置好两个 remote确认工作目录可写。bisync 会把清单等运行文件放在缓存目录下的bisync子目录即代码 cmd/bisync/cmd.go 中filepath.Join(config.GetCacheDir(), bisync)Linux 为~/.cache/rclone/bisyncmacOS 为~/Library/Caches/rclone/bisyncWindows 为C:\Users\用户名\AppData\Local\rclone\bisync用--resync标志执行首次运行之后的例行同步一律去掉--resync重要建议用 filters 文件排除无关内容并开启--check-access做安全检查。主手册给出的“第一次命令”示范几乎涵盖了推荐的稳妥参数组合rclone bisync remote1:path1 remote2:path2 --create-empty-src-dirs --compare size,modtime,checksum --slow-hash-sync-only --resilient -MvP --drive-skip-gdocs --fix-case --resync --dry-run先加--dry-run演练一遍确认无误后去掉--dry-run再跑一次最后连--resync一并移除进入例行同步。一次典型运行的日志语义主手册给出了一份典型运行日志可以直观看到各阶段rclone bisync /testdir/path1/ /testdir/path2/ --verbose INFO : Synching Path1 /testdir/path1/ with Path2 /testdir/path2/ INFO : Path1 checking for diffs INFO : - Path1 File is new - file11.txt INFO : - Path1 File is newer - file2.txt INFO : - Path1 File was deleted - file4.txt INFO : Path1: 7 changes: 1 new, 3 newer, 0 older, 3 deleted INFO : Path2 checking for diffs INFO : Path2: 7 changes: 1 new, 3 newer, 0 older, 3 deleted INFO : Applying changes INFO : - Path1 Queue copy to Path2 - /testdir/path2/file11.txt INFO : - Path2 Queue delete - /testdir/path2/file4.txt NOTICE: - WARNING New or changed in both paths - file5.txt NOTICE: - Path1 Renaming Path1 copy - /testdir/path1/file5.txt..path1 INFO : - Do queued deletes on - Path1 INFO : Updating listings INFO : Validating listings for Path1 /testdir/path1/ vs Path2 /testdir/path2/ INFO : Bisync successful它揭示的运行阶段依次是分别对两侧“检查差异checking for diffs→ 汇总统计 → 应用变更先排队 copy/delete/rename→ 执行已排队的复制与删除 → 更新清单Updating listings→ 校验最终清单Validating listings→ 成功结束”。这与代码中deltas.go负责差异推导、queue.go负责变更排队、march.go负责遍历合并march的结构相互印证。三、bisync 专属选项全解这一节是命令文档的核心内容下述约 30 个 flag 由 cmd/bisync/cmd.go 的init()逐一注册到Options结构体可作为双向同步选项的权威清单。3.1 初始化与恢复类选项默认值说明-1, --resyncfalse执行 resync 初始化运行等价于--resync-mode path1。建议先配合--verbose或--dry-run观察--resync-modenone不 resync 时字符串取值path1, path2, newer, older, larger, smaller。resync 时优先保留哪一侧版本若使用--resync则默认path1--recoverfalse自动从被打断的运行中恢复无需重新--resync--resilientfalse允许后续运行对某些“较轻”的错误自动重试而不再强制要求--resync主手册明确说明bisync 依赖“上次清单”因此第一次运行必须--resync中断后未完成同步时命令会进入安全状态以阻止后续运行造成破坏详见主手册Error Handling与 operations.go 中 SIGINT 处理逻辑。--resilient与--recover是 v1.6x 之后引入的“降级”恢复手段前者针对可重试的非致命错误后者针对中断恢复二者都可避免每次都退回到代价高昂的全量--resync。从源码看operations.go当发生 critical 错误且retryable为真时若设置了--resilient且当前不是--resync运行才会允许下次重试而非直接标记失败。3.2 安全防护类选项默认值说明--check-accessfalse确保在 Path1、Path2 两侧文件系统都找到预期的RCLONE_TEST文件否则中止--check-filenameRCLONE_TEST--check-access检查使用的文件名--check-synctrue控制是否对最终两侧清单做一致性比对true默认同步后比对并校验、false跳过、only只比对上一次清单不做同步--forcefalse绕过--max-delete安全阀强制执行同步建议配合--verbose--max-lock0s永不过期锁文件超过该时长视为过期可强制接管最小2m--check-access的设计意图是探测文件系统健康状态如果某次远端挂载失效、权限错乱导致 listing 异常为空安全机制会在造成大规模误删前中止见主手册Safety measures。代码中默认文件名常量定义在 cmd/bisync/cmd.goDefaultCheckFilename RCLONE_TEST。若--check-filename为空则自动填入该默认值见 operations.go。--check-sync的三态在 cmd/bisync/cmd.go 中有精确定义CheckSyncTrue同步后校验最终清单默认、CheckSyncFalse关闭最终比对节省一次校验、CheckSyncOnly只基于上一次清单做差异诊断、不执行任何同步。only模式非常适合排查“如果此刻同步会发生什么”而绝不改动数据。3.3 目录同步策略类选项默认值说明--create-empty-src-dirsfalse同步空目录的创建与删除与--remove-empty-dirs不兼容--remove-empty-dirsfalse在最后清理阶段移除所有空目录主手册Empty directories一节解释了原因bisync以及 rclone 整体天然面向“文件”工作而非目录因此默认情况下一侧新建/删除的空目录不会传播到另一侧。需要空目录结构保持严格一致时再显式开启上述两个开关二者互斥。3.4 差异比较与校验类compare 家族选项默认值说明--comparesize,modtimebisync 专属的比较维度列表如size,modtime,checksum--ignore-listing-checksumfalse清单比较不用校验和若还要跳过拷贝后的校验和复核需追加--ignore-checksum--no-slow-hashfalse仅在“hash 计算较慢”的后端上忽略清单校验和--slow-hash-sync-onlyfalse对清单与差异推导忽略慢速校验和但同步调用内部仍考虑它--download-hashfalse后端无法直接提供 hash 时通过下载内容计算 hash可能很慢且消耗大量流量--checksum-c见 Copy Optionsfalse用“大小校验和”判断变化在 compare.go 中会联动把比较维度切换为 checksum这套维度体系值得展开结合 cmd/bisync/compare.go 的实现默认取size modtime若设置了全局--checksum且未开--ignore-listing-checksum则自动切换为size checksum若设置了--size-only则只比较大小setCompareDefaults第 39-47 行。三个维度被全部关闭是非法状态代码会直接报错must set a Compare method. (size, modtime, and checksum cant all be false.)compare.go。若选择 modtime 比较但某一侧后端不支持 modtimefs.ModTimeNotSupported会给出黄色 WARNING建议改用--checksum或--size-onlycompare.go。hash 类型选择采用“公共优先”策略先取 Path1、Path2 都支持的共同 hashHashes().Overlap()如果两侧没有共同 hash 则回退到modtime,size比较compare.go。--download-hash是极端兜底仅当一侧支持 MD5、另一侧不支持任何 hash 时才通过真实下载计算 MD5 参与比较compare.go、operations.go 的tryDownloadHash其中对“未知长度文件”会安全地跳过。慢 hash 后端如部分对象存储的 CRC/大文件 hash对应Features().SlowHash--no-slow-hash直接忽略--slow-hash-sync-only则只在“推导差异”时忽略、真正 copy 时仍校验见SlowHashDetected相关分支compare.go。--compare指定三个维度时是“并集”语义还是精确指定代码setFromCompareFlagcompare.go实现的是精确指定解析逗号列表后未列出的维度一律被显式关闭exclusions (override defaults)并联动改写下层 sync 的 config如开启 checksum 比较则ci.CheckSumtrue关闭 modtime 则ci.UseServerModTimetrue等。这意味着--compare size,modtime等价于默认与仅--compare checksum的语义并不相同前者精确等价默认组合后者会禁用 modtime。3.5 冲突处理类conflict 家族选项默认值说明--conflict-resolvenone自动解决冲突优先保留的版本none, path1, path2, newer, older, larger, smaller--conflict-losernum对“失败方”存在赢家时或“双方”无赢家时采取的动作空、num、pathname、delete--conflict-suffixconflict重命名冲突失败方时使用的后缀可传单个字符串或用两个逗号分隔字符串分别为 Path1/Path2 指定不同后缀当同一个文件在 Path1 和 Path2 上都发生了新增/修改且两侧内容不一致就构成一次真正的冲突。主手册的Unusual sync checks表格给出了精确判定矩阵例如类型结果默认行为Path1 新 AND Path2 新内容不同按--conflict-resolve与--conflict-loser处理默认保留双方副本Path2 更新 AND Path1 也修改且两侧不一致同上按冲突策略处理Path2 更新 AND Path1 删除Path2 版本胜出copy 回 Path1Path2 删除 AND Path1 修改Path1 版本胜出copy 到 Path2冲突的“失败方”会被以冲突后缀重命名归档--conflict-suffix指定两侧可不同从而非破坏性地保留两个版本绝不静默丢弃数据。这与主手册Safety measures中“通过创建冲突副本非破坏性地处理冲突”的描述一致。值得说明的是从 v1.64 起 bisync 对“虚假冲突”的识别大幅改进当它准备为“两侧都变化”的文件做冲突重命名前会先用与rclone check相同的函数比较两侧当前内容若两侧实际相同则直接跳过、不再制造冗余冲突副本bisync.mdOperation一节。这同时也让“两侧做相同目录改名”无需再--resync。3.6 备份类选项默认值说明--backup-dir1空Path1 侧的--backup-dir。必须是同一 remote 上不与同步路径重叠的路径--backup-dir2空Path2 侧的--backup-dir。必须是同一 remote 上不与同步路径重叠的路径主手册同样强调被覆盖/删除的文件若要进备份目录则该目录必须位于同一 remote 且与两侧同步根互不重叠否则会产生“删除被同步回去”的环路风险。--backup-dir的原始值会在Bisync()开始时被暂存到opt.OrigBackupDiroperations.go随后按方向分派到 dir1/dir2。3.7 过滤与运行环境类选项默认值说明--filters-file空从一个文件读取过滤规则--workdir$HOME/.cache/rclone/bisync自定义工作目录便于测试--no-cleanupfalse保留工作文件清单、队列等便于排障与测试--filters-file有一处值得注意的源码级行为applyFilterscmd/bisync/cmd.go会计算该过滤器文件的 MD5并把它写到旁边同名.md5文件中此后若过滤器文件内容发生变化或.md5不存在且本次不是--resync运行命令会直接中止并要求先跑--resync。原因很直观过滤器影响“哪些文件被纳入清单”中途变更过滤器会污染清单一致性因此必须以 resync 重建基线。这是在命令文档之外、由源码可以确认的隐含约束。--max-lock与锁机制bisync 在运行时创建锁文件防止并发实例主手册指出这正是它能安全放进 cron 并发的关键。--max-lock让超过指定时长最小 2m的陈旧锁被视为过期锁的实现位于 cmd/bisync/lockfile.go。若保留工作文件可配合--no-cleanup排查问题。四、与其他命令共享的选项组命令文档同时列出了四个共享选项组这些选项同样适用于 copy/sync 类命令仅在此处针对 bisync 场景起作用。4.1 Copy Options拷贝相关--check-first Do all the checks before starting transfers -c, --checksum Check for changes with size checksum (if available, or fallback to size only) --compare-dest stringArray Include additional server-side paths during comparison --copy-dest stringArray Implies --compare-dest but also copies files from paths into destination --cutoff-mode HARD|SOFT|CAUTIOUS Mode to stop transfers when reaching the max transfer limit (default HARD) --ignore-case-sync Ignore case when synchronizing --ignore-checksum Skip post copy check of checksums --ignore-existing Skip all files that exist on destination --ignore-size Ignore size when skipping use modtime or checksum -I, --ignore-times Dont skip items that match size and time - transfer all unconditionally --immutable Do not modify files, fail if existing files have been modified --inplace Download directly to destination file instead of atomic download to temp/rename -l, --links Translate symlinks to/from regular files with a .rclonelink extension --max-backlog int Maximum number of objects in sync or check backlog (default 10000) --max-duration Duration Maximum duration rclone will transfer data for (default 0s) --max-transfer SizeSuffix Maximum size of data to transfer (default off) -M, --metadata If set, preserve metadata when copying objects --modify-window Duration Max time diff to be considered the same (default 1ns) --multi-thread-chunk-size SizeSuffix Chunk size for multi-thread downloads / uploads (default 64Mi) --multi-thread-cutoff SizeSuffix Use multi-thread downloads for files above this size (default 256Mi) --multi-thread-streams int Number of streams to use for multi-thread downloads (default 4) --multi-thread-write-buffer-size SizeSuffix In memory buffer size for writing when in multi-thread mode (default 128Ki) --name-transform stringArray Transform paths during the copy process --no-check-dest Dont check the destination, copy regardless --no-traverse Dont traverse destination file system on copy --no-update-dir-modtime Dont update directory modification times --no-update-modtime Dont update destination modtime if files identical --order-by string Instructions on how to order the transfers, e.g. size,descending --partial-suffix string Add partial-suffix to temporary file name when --inplace is not used (default .partial) --refresh-times Refresh the modtime of remote files --server-side-across-configs Allow server-side operations (e.g. copy) to work across different configs --size-only Skip based on size only, not modtime or checksum --streaming-upload-cutoff SizeSuffix Cutoff for switching to chunked upload if file size is unknown (default 100Ki) -u, --update Skip files that are newer on the destination需要注意一个实现细节--update、--no-check-dest、--no-traverse等方向性语义与 bisync 的“双向”模型冲突setCompareDefaults在检测到它们被设置时会打 WARNING 并忽略compare.gonotSupported辅助函数。此外主手册Concurrent modifications一节特别提示对 Local/FTP/SFTP 使用--inplace时不会创建临时文件再原子改名一旦连接中断可能留下损坏文件并在下次同步反向传播因此双向场景建议省略--inplace。4.2 Sync Options同步相关--backup-dir string Make backups into hierarchy based in DIR --delete-after When synchronizing, delete files on destination after transferring (default) --delete-before When synchronizing, delete files on destination before transferring --delete-during When synchronizing, delete files during transfer --fix-case Force rename of case insensitive dest to match source --ignore-errors Delete even if there are I/O errors --list-cutoff int To save memory, sort directory listings on disk above this threshold (default 1000000) --max-delete int When synchronizing, limit the number of deletes (default -1) --max-delete-size SizeSuffix When synchronizing, limit the total size of deletes (default off) --suffix string Suffix to add to changed files --suffix-keep-extension Preserve the extension when using --suffix --track-renames When synchronizing, track file renames and do a server-side move if possible --track-renames-strategy string Strategies to use when synchronizing using track-renames hash|modtime|leaf (default hash)其中--max-delete在 bisync 语境下有一套专属的百分比语义applyContextcmd/bisync/cmd.go把它的取值解释为“0–100 的百分比”默认值是常量DefaultMaxDelete 50cmd.go并限制在 0–100 区间内随后把下层fs/operations的ci.MaxDelete重置为-1bisync handles this parameter specially避免与通用 delete 限流逻辑叠加。这就是命令文档中--force所谓“绕过--max-delete安全检查”的含义当检测到单侧删除数量超过 50%默认阈值时bisync 会怀疑“清单失效被误读成全部删除”从而中止保护数据详见主手册Safety measures的“Abort on excessive deletes”。4.3 Important Options常用重要选项-n, --dry-run Do a trial run with no permanent changes -i, --interactive Enable interactive mode -v, --verbose count Print lots more stuff (repeat for more)--dry-run在 bisync 中尤其关键——首次--resync与任何--force决策前都建议先 dry-run 演练--verbose/-vv配合命令文档建议的--debugname 文件隐藏测试用 flag还能追踪单个文件在整个流程各阶段的走向。4.4 Filter Options过滤相关--delete-excluded Delete files on dest excluded from sync --exclude stringArray Exclude files matching pattern --exclude-from stringArray Read file exclude patterns from file (use - to read from stdin) --exclude-if-present stringArray Exclude directories if filename is present --files-from stringArray Read list of source-file names from file (use - to read from stdin) --files-from-raw stringArray Read list of source-file names from file without any processing of lines (use - to read from stdin) --files-from0 stringArray Read list of source-file names from file using NUL as separator (use - to read from stdin) -f, --filter stringArray Add a file filtering rule --filter-from stringArray Read file filtering patterns from a file (use - to read from stdin) --hash-filter string Partition filenames by hash k/n or randomly /n --ignore-case Ignore case in filters (case insensitive) --include stringArray Include files matching pattern --include-from stringArray Read file include patterns from file (use - to read from stdin) --max-age Duration Only transfer files younger than this in s or suffix ms|s|m|h|d|w|M|y (default off) --max-depth int If set limits the recursion depth to this (default -1) --max-size SizeSuffix Only transfer files smaller than this in KiB or suffix B|K|M|G|T|P (default off) --metadata-exclude stringArray Exclude metadatas matching pattern --metadata-exclude-from stringArray Read metadata exclude patterns from file (use - to read from stdin) --metadata-filter stringArray Add a metadata filtering rule --metadata-filter-from stringArray Read metadata filtering patterns from a file (use - to read from stdin) --metadata-include stringArray Include metadatas matching pattern --metadata-include-from stringArray Read metadata include patterns from file (use - to read from stdin) --min-age Duration Only transfer files older than this in s or suffix ms|s|m|h|d|w|M|y (default off) --min-size SizeSuffix Only transfer files bigger than this in KiB or suffix B|K|M|G|T|P (default off)需要提醒的是过滤规则会影响清单基线。因此文档与实践都推荐尽早用过滤文件并保持稳定若确实要改过滤规则建议按前述--filters-file的 MD5 约束处理——即在--resync时变更过滤文件让工具记录新哈希。在命令行直接加--exclude等过滤选项同样改变清单内容重大调整后跑一次--resync重建基线是稳妥做法主手册Filtering一节提供了更详细的过滤器策略与 Dropbox 风格示例过滤文件可参考 docs/content/bisync.md。五、底层安全措施与异常流结合命令文档Safety measures小节与源码可以总结出 bisync 赖以“安全”的四道防线锁文件防并发--max-lock决定陈旧锁何时过期默认永不过期0。这使得 bisync 可以放心交给 cron 周期性调度。RCLONE_TEST健康检查--check-access--check-filename两侧缺失标记文件即中止防止挂载失效时“空目录全删”的误判。删除量安全阀--max-delete默认 50%保护 --force显式放行。附带还有“全部既有文件都变化”的检查若一侧既有文件的时间戳集体漂移如系统时区变更bisync 会不修改任何数据直接中止需要你结合--dry-run审慎决策后再用--force或--resync处理主手册All files changed check。非破坏性冲突 失败标记冲突文件被重命名归档保留而不是覆盖一旦发生 critical 错误markFailed会给两侧清单打上失败标记使下一次运行必须--resync才能重建可信基线operations.go 的信号处理与失败路径除非设置--recover/--resilient。另外中断恢复有一条清晰的分工普通中断且无失败标记时可直接重跑有失败标记或需要重建基线时必须--resync而 v1.6x 后的--recover会尝试基于未损坏的中间状态自动续跑。六、测试与进一步研读bisync 是集成测试覆盖最重的命令之一单元/集成测试主文件 cmd/bisync/bisync_test.go约 2000 行覆盖 local↔remote、remote↔remote 以及--check-sync only、--check-access、空目录、过滤等典型矩阵锁机制测试见 cmd/bisync/lockfile_test.go调试/故障注入测试见 cmd/bisync/bisync_debug_test.gobisync 还暴露了 rc 接口core/bisync通过 cmd/bisync/rc.go 注册参数path1、path2、dryRun以及自动生成的全部选项参数便于在 GUI / rcd 服务中调用主手册提供了大量实战示例与排障Troubleshooting、Usage examples、Testing、Benchmarks小节详见 docs/content/bisync.md命令文档的“See Also”亦指向 rclone 命令总览 与全局参数文档 docs/content/flags.md。七、使用要点速查第一次rclone bisync A:path1 B:path2 --resync --dry-run -v→ 确认后去掉--dry-run。例行同步去掉--resync可直接交给 cron并发安全由锁文件保证。推荐组合--compare size,modtime,checksum --slow-hash-sync-only --resilient--check-access--create-empty-src-dirs按需可作为大多数双向云盘同步的起点参考主手册 Getting started 示例。千万不要在两个生产路径都频繁原地改写同一批文件的情况下不做冲突预案直接同步也不要在无--resync时中途更换过滤规则会触发 filters-file MD5 中止保护。出问题先看日志New / Newer / Older / Deleted与WARNING New or changed in both paths是判断是否需要--resync、--recover还是走冲突归档流程的第一手线索。说明本文选项表与默认值以当前仓库的自动生成命令文档 docs/content/commands/rclone_bisync.md 为准该文件头部注明由cmd/bisync/源码经make commanddocs自动生成请勿手工编辑实现细节以 cmd/bisync 源码与 docs/content/bisync.md 主手册为准。【免费下载链接】rclonersync for cloud storage - Google Drive, S3, Dropbox, Backblaze B2, One Drive, Swift, Hubic, Wasabi, Google Cloud Storage, Azure Blob, Azure Files, Yandex Files项目地址: https://gitcode.com/GitHub_Trending/rc/rclone创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考