尧图网页设计 
rclone Local Filesystem 本地存储后端全解析路径、编码、符号链接、高级选项与元数据【免费下载链接】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本地文件系统Local Filesystem是 rclone 中唯一一个不通过网络访问远程存储、而是直接读写本机磁盘目录的“后端”。它既承载着“把云盘同步到本地做备份”这一最常用场景也是其他所有远端后端工作模型的参照系。本文以 docs/content/local.md 为核心主线逐层讲解本地路径的使用方法、Windows 特有路径语义、文件名编码与受限字符替换规则、符号链接的三种处理策略、跨文件系统边界控制以及 20 余项高级选项与系统元数据的源码级实现细节帮助你精确、安全地驾驭基于本地磁盘的 rclone 传输。一、最朴素的用法直接用本地路径在 rclone 的命令中本地路径可以像普通文件系统路径一样直接书写例如/path/to/wherever不需要事先进行任何 remote 配置。也就是说本地盘就是 rclone 的“零配置后端”。例如把/home/source同步到/tmp/destinationrclone sync --interactive /home/source /tmp/destination这条命令等价于rsync的本地用法--interactive或-i会先输出将要执行的操作供你确认。由于本地路径天然可以被 rclone 识别常见的“本地 ↔ 云盘”备份只需在命令一侧写路径、另一侧写已配置的 remote 即可例如rclone sync /data/photos gdrive:photos-backup二、把本地目录注册为 remote配置文件方式出于统一习惯也可以在配置文件中注册一个type local的 remote之后用 rclone 的 remote 路径语法remote:path/to/wherever访问本地文件系统。例如[localdisk] type local之后即可使用rclone lsd localdisk:/home/user/...。不过正如文档所指出的这“probably easier not to”——因为本地路径本身已经可以直接使用单独建一个 remote 通常没有必要。它真正的价值场景有两个想在.rclone.conf中为本地后端固定若干默认高级选项如nounc true见下文 Windows 长路径部分需要把某条本地目录作为只读/独立入口暴露给其他工具统一走 remote 语法。在源码层面这个 remote 由 backend/local/local.go 中的注册逻辑定义fs.RegInfo{Name: local, Description: Local Disk, NewFs: NewFs, ...}见 backend/local/local.go#L62-L90NewFs是构造文件系统实例的入口函数backend/local/local.go#L444。三、时间戳精度依赖操作系统rclone 对本地文件读写修改时间modification time即 mtime精度由操作系统决定文档给出的典型数值为操作系统时间精度Linux1 nsWindows10 nsmacOS1 s本地后端的 mtime 读写逻辑分布在 backend/local 的lchtimes*.go与setbtime.go等文件中按平台以构建标签区分实现。跨平台同步时这一精度差异会体现在“哪些文件被视为已变更”的判断上——例如源在 Linux 上精确到纳秒的 mtime若被写入一个仅支持 1 秒精度的目标盘反复比对时可能触发“看似变化实则未变”的重复传输规划任务时值得留意。四、文件名的 UTF-8 编码与非法字节处理4.1 盘面编码要求磁盘上的文件名应编码为 UTF-8。Windows 与 macOS 默认即是如此在 Linux 世界中较新的发行版同样使用 UTF-8。如果仍在使用采用非 UTF-8 命名例如 latin1的旧式 Linux 文件系统文档推荐使用convmv工具批量转换为 UTF-8——该工具可通过大多数发行版的软件包管理器安装rclone 仓库内也维护有对应的convmv命令实现见 cmd/convmv/convmv.go专门用于把目录中的文件名在编码之间转换。4.2 非法 UTF-8 字节的替换当 rclone 读到包含非法非 UTF-8字节的文件名时会将非法字符替换为对应字节的带引号表示形式。例如名字gro\xdf会作为gro‛DF被传输并输出一条 debug 消息需用-v查看Local file system at .: Replacing invalid UTF-8 characters in gro\xdf在 Windows 上由于 Windows API 使用 UTF-16这些无法转换的非法 UTF-8 字节也会被替换。关于替换策略的全局说明可参见仓库内的 overview 文档的 invalid-utf8 小节。4.3 受限字符的替换规则本地后端下文件名中哪些字符“不可用”取决于操作系统。要查看当前系统上 rclone 默认会替换哪些字符直接运行rclone help flags local-encoding非 Windows 平台上处理文件名时替换以下字符字符值替换为NUL0x00␀/0x2FWindows 平台上替换以下字符该列表基于 Windows 文件命名约定字符值替换为字符值替换为字符值替换为NUL0x00␀FF0x0C␌US0x1F␟SOH0x01␁CR0x0D␍/0x2FSTX0x02␂SO0x0E␎0x22ETX0x03␃SI0x0F␏*0x2AEOT0x04␄DLE0x10␐:0x3AENQ0x05␅DC10x11␑0x3CACK0x06␆DC20x12␒0x3EBEL0x07␇DC30x13␓?0x3FBS0x08␈DC40x14␔\0x5CHT0x09␉NAK0x15␕|0x7CLF0x0A␊SYN0x16␖VT0x0B␋ETB0x17␗CAN0x18␘EM0x19␙SUB0x1A␚ESC0x1B␛FS0x1C␜GS0x1D␝RS0x1E␞此外Windows 文件名不能以以下字符结尾仅在作为名字最后一个字符时替换字符值替换为SP0x20␠.0x2E这些替换规则由--local-encoding选项统一控制默认值为Slash,Dot详见下文高级选项底层基于 lib/encoder 的编码器机制实现——rclone 对所有后端都采用“先把非法字符映射为安全形式、传输完成后再在目标端还原”的编码策略从而保证跨平台文件名往返一致。五、Windows 路径语义UNC、GUID 卷与长路径5.1 多样化的路径书写方式在 Windows 上本地路径的书写形式非常多样绝对路径C:\path\to\wherever相对路径..\whereverUNC 网络路径\\server\share路径分隔符既可用\如C:\path\to\wherever也可用/如C:/path/to/wherever普通路径的长度限制为文件 259 字符、目录 247 字符。超过限制时可以使用加长路径extended-length path格式把上限提升到约 32,767 字符。该格式要求绝对路径并使用\\?\前缀例如\\?\D:\some\very\long\path。借助同一个\\?\前缀还可以直接按GUID 标识的卷访问路径例如\\?\Volume{b75e2c83-0000-0000-0000-602f00000000}\some\path5.2 长路径的自动转换与 nouncrclone 会自动把所有路径转换为加长路径格式允许最长 32,767 字符因此大多数情况下你无需关心该限制。转换会确保路径为绝对路径并加上\\?\前缀——这就是为什么在输出中你会看到相对路径.\files被显示成\\?\C:\files、\\server\share被显示成\\?\UNC\server\share。极少数情况下这种自动转换会与有缺陷的文件系统驱动冲突如 EncFS。若需全局关闭UNC 转换在.rclone.conf中加入[local] nounc true如果只想对特定目标选择性关闭可以单独注册一个带nounc的 local remote[nounc] type local nounc true然后这样使用——c:\src仍然走 UNC 转换而z:\dst不走rclone copy c:\src nounc:z:\dst注意若 z 盘上某个文件的绝对路径长度超过 259 字符这样的用法会出问题因此只有在确实必要时才应关闭转换。该选项在源码中对应Options.NoUNC配置键nounc相关实现见 backend/local/local.go 中的cleanRootPath调用与noUNC选项定义。六、符号链接与目录联接点的处理符号链接Windows 上行为类似的 junction point 目录联接点的默认行为是被 rclone 忽略。但 rclone 提供了两套方向相反的策略以及若干配套开关6.1 跟随链接--copy-links / -L加上--copy-links或短选项-L后rclone 会跟随符号链接复制其所指向的文件或目录。该标志适用于所有命令且与--links/-l互斥。例如目录结构为$ tree /tmp/a /tmp/a ├── b - ../b ├── expected - ../expected ├── one └── two └── three不使用标志时符号链接b、expected都被忽略$ rclone ls /tmp/a 6 one 6 two/three使用-L后链接指向的内容被复制进来$ rclone -L ls /tmp/a 4174 expected 6 one 6 two/three 6 b/two 6 b/one6.2 把链接翻译成普通文件--local-links / --links / -l这是与-L相反的策略加上该标志后rclone 会把本地存储上的符号链接复制为普通文本文件并以.rclonelink后缀存放到远端文本内容即符号链接的目标路径。这一标志同样适用于所有命令--local-links只对 local 后端生效而--links/-l对所有支持的远端后端与 VFS 生效。例如目录结构$ tree /tmp/a /tmp/a ├── file1 - ./file4 └── file2 - /home/user/file3用-l复制整个目录rclone copy -l /tmp/a/ remote:/tmp/a/远端产生带.rclonelink后缀的文件$ rclone ls remote:/tmp/a 5 file1.rclonelink 14 file2.rclonelink文件内容是符号链接的目标$ rclone cat remote:/tmp/a/file1.rclonelink ./file4 $ rclone cat remote:/tmp/a/file2.rclonelink /home/user/file3再以-l复制回来时链接会被还原$ rclone copy -l remote:/tmp/a/ /tmp/b/ $ tree /tmp/b /tmp/b ├── file1 - ./file4 └── file2 - /home/user/file3而如果不带-l复制回来.rclonelink会作为普通文件保留$ rclone copyto remote:/tmp/a/ /tmp/b/ $ tree /tmp/b /tmp/b ├── file1.rclonelink └── file2.rclonelink用-l复制单个文件时路径必须带上.rclonelink后缀$ rclone copy -l remote:/tmp/a/file1.rclonelink /tmp/c $ tree /tmp/c /tmp/c └── file1 - ./file4源码层面可以验证这一整套约定.rclonelink后缀定义于 fs/fs.go#L21LinkSuffix .rclonelinkbackend/local/local.go 的NewFs中会检查根路径是否以该后缀结尾并在TranslateSymlinks生效时去掉后缀解析backend/local/local.go#L500-L514若在启用-l时用不带后缀的名字直接引用一个符号链接会返回错误errLinksNeedsSuffix提示“需使用 .rclonelink 后缀”。同时-l/--links与-L/--copy-links同时开启会直接报错errLinksAndCopyLinks见 backend/local/local.go#L438-L457。相关的单元测试覆盖可在 backend/local/local_internal_test.go如其中构造symlink.txt.rclonelink测试项的用例中找到。6.3 链接目标与目标目录的安全边界当 rclone 把.rclonelink文件还原为本地符号链接时链接可以指向任何位置——包括用绝对路径或../指向你所复制目录之外。这是刻意为之的正常行为rclone 忠实还原链接原本的目标使备份能够完整往返。但 rclone绝不会通过这样的链接“写穿”write through到链接之外。具体而言如果源端同时存在一个链接例如指向目标目录之外的dir.rclonelink以及一个本应落在该链接内部的dir/file.txtrclone 在写入dir/file.txt时会拒绝跟随该符号链接——这个违规文件会被跳过并报错其余传输照常继续被跳过的文件会计入运行结束时打印的错误汇总中。这一保护机制可以防止恶意或失陷的远端在-l/--links模式下布下符号链接、再借机写到目标目录之外。普通的链接往返、以及目标完全落在目标目录内部的链接都不受影响。如果你的目标是有意预先在目标目录里创建了一个符号链接目录、并希望 rclone 写入其指向的真实目录那么对该次复制请不要使用-l/--links或者先把该符号链接移除。七、用 --one-file-system / -x 限制跨文件系统递归默认情况下 rclone 会沿着挂载点递归进入不同的文件系统。而设置--one-file-system或短选项-x后rclone 只停留在根路径所属的文件系统内不进入挂载在其下的其他文件系统。例如如下目录层级——disk1、disk2各自是挂在 root 下的独立磁盘root ├── disk1 - disk1 mounted on the root │ └── file3 - stored on disk1 ├── disk2 - disk2 mounted on the root │ └── file4 - stored on disk2 ├── file1 - stored on the root disk └── file2 - stored on the root disk执行rclone --one-file-system copy root remote:只会复制file1与file2$ rclone -q --one-file-system ls root 0 file1 0 file2对比不加该标志的情况$ rclone -q ls root 0 disk1/file3 0 disk2/file4 0 file1 0 file2两条重要提醒与du、rsync、tar等多数 Unix 工具一致rclone 把指向同一设备的 bind mount 视为同一文件系统不会拦截。该标志仅适用于 Unix 系系统在不支持它的系统如 Windows上会被忽略。从源码看该功能在 backend/local 中与设备号读取逻辑配套readDevice在初始化时记录根路径的设备号目录遍历层会依据设备号决定是否继续深入。八、高级选项逐项详解以下为 localLocal Disk后端专属的高级选项。它们均可用rclone config中的对应 Config 键配置也都能通过环境变量RCLONE_LOCAL_*覆盖或直接在命令行以--local-xxx形式传入。源码定义位于 backend/local/local.go 的Options与fs.RegInfo.Options中。命令行标志Config 键环境变量类型默认值--local-nouncnouncRCLONE_LOCAL_NOUNCboolfalse--copy-links/-Lcopy_linksRCLONE_LOCAL_COPY_LINKSboolfalse--local-linkslinksRCLONE_LOCAL_LINKSboolfalse--skip-linksskip_linksRCLONE_LOCAL_SKIP_LINKSboolfalse--skip-specialsskip_specialsRCLONE_LOCAL_SKIP_SPECIALSboolfalse--local-zero-size-linkszero_size_linksRCLONE_LOCAL_ZERO_SIZE_LINKSboolfalse已废弃--local-unicode-normalizationunicode_normalizationRCLONE_LOCAL_UNICODE_NORMALIZATIONboolfalse--local-no-check-updatedno_check_updatedRCLONE_LOCAL_NO_CHECK_UPDATEDboolfalse--one-file-system/-xone_file_systemRCLONE_LOCAL_ONE_FILE_SYSTEMboolfalse--local-case-sensitivecase_sensitiveRCLONE_LOCAL_CASE_SENSITIVEboolfalse--local-case-insensitivecase_insensitiveRCLONE_LOCAL_CASE_INSENSITIVEboolfalse--local-no-cloneno_cloneRCLONE_LOCAL_NO_CLONEboolfalse--local-no-preallocateno_preallocateRCLONE_LOCAL_NO_PREALLOCATEboolfalse--local-no-sparseno_sparseRCLONE_LOCAL_NO_SPARSEboolfalse--local-no-set-modtimeno_set_modtimeRCLONE_LOCAL_NO_SET_MODTIMEboolfalse--local-metadata-restore-special-bitsmetadata_restore_special_bitsRCLONE_LOCAL_METADATA_RESTORE_SPECIAL_BITSboolfalse--local-fatal-if-no-spacefatal_if_no_spaceRCLONE_LOCAL_FATAL_IF_NO_SPACEboolfalse--local-time-typetime_typeRCLONE_LOCAL_TIME_TYPEmtime|atime|btime|ctimemtime--local-hasheshashesRCLONE_LOCAL_HASHESCommaSepList空--local-encodingencodingRCLONE_LOCAL_ENCODINGEncodingSlash,Dot--local-descriptiondescriptionRCLONE_LOCAL_DESCRIPTIONstring空8.1 --local-nounc禁用 Windows 上的 UNC长路径名转换。配置示例仅提供true“Disables long file names”即关闭长文件名支持。注意该选项在非 Windows 平台运行时甚至不会作为高级选项出现源码中Advanced: runtime.GOOS ! windows因为它在其他平台上没有意义。8.2 --copy-links / -L跟随符号链接并复制其指向的内容。默认false与前文 6.1 节的语义一致。8.3 --local-links对本地后端启用“把符号链接翻译为带.rclonelink后缀的普通文件”的往返转换。当全局的--links/-l打开时local 后端也会被一并启用——源码中NewFs会执行if ci.Links { opt.TranslateSymlinks true }的覆盖逻辑backend/local/local.go#L452-L455。8.4 --skip-links不警告被跳过的符号链接。默认情况下 rclone 遇到因未加-l/-L而被忽略的符号链接或 junction point 会输出警告显式设置本标志等于声明“我已知晓它们应被跳过”从而静默处理。8.5 --skip-specials不警告被跳过的管道pipe、套接字socket与设备对象device。含义与--skip-links类似只是作用对象从符号链接换成特殊文件。8.6 --local-zero-size-links已废弃假设符号链接的Stat大小为 0并转而实际读取链接内容。该选项对应一段历史rclone 曾把Stat报告的大小当作链接大小但这一做法在多个环境会失效Windows某些虚拟文件系统如 LucidLinkAndroid。因此如今 rclone总是实际读取链接内容本标志已被废弃仅保留以兼容旧配置。8.7 --local-unicode-normalization对路径与文件名应用 Unicode NFC 归一化。rclone 默认不触碰从文件系统读到的文件名编码该选项把读到的名字统一转换为 NFC 形式。典型场景是 macOS其文件系统通常提供分解形式NFD的 Unicode某些语言的文字如韩文在部分操作系统上显示异常。不过 rclone 在 sync 逻辑内部本来就按 Unicode 归一化比较文件名因此文档建议通常不要使用此标志用了反而可能与预期行为重叠或产生额外开销。8.8 --local-no-check-updated关闭“上传过程中检查文件是否发生变化”。默认情况下 rclone 在上传的同时核对文件大小与修改时间若发现文件在上传期间被改动会中止并以 “cant copy - source file is being updated” 开头报错。但在某些文件系统上该 mtime 校验会误报例如 GlusterFS此时可用此标志关闭。关闭后 rclone 会尽力传输正在被更新的文件若文件只是被追加内容如日志文件rclone 会按第一次 stat 到的大小把文件传完若文件在传输全程都被改写不只是追加传输可能以哈希校验失败告终。具体而言一旦文件被第一次 stat()rclone 将只传输 stat 给出的大小只对 stat 给出的大小做校验和不再更新该文件的 stat 信息。注意不要在 Windows 卷影副本Volume Shadow Copy, VSS上使用该标志。VSS 中的文件在目录列表Windows 上初始 stat 值的来源与直接 stat 时偶尔会显示不同大小关闭此检查会引入不一致风险其他复制工具始终使用直接 stat 的值而设置本标志会禁用这一行为。8.9 --one-file-system / -x不跨越文件系统边界仅 Unix/macOS详见本文第七节。8.10 --local-case-sensitive / --local-case-insensitive强制文件系统报告自身为大小写敏感 / 不敏感。默认情况下本地后端在 Windows/macOS 上自报为大小写不敏感其余平台自报为大小写敏感。源码中的判定函数caseInsensitive()逻辑为显式设置了case_sensitive则返回不敏感false显式设置了case_insensitive则返回 true否则按runtime.GOOS windows || runtime.GOOS darwin推断backend/local/local.go#L552-L566。该特性值随后写入fs.Features.CaseInsensitivebackend/local/local.go#L472影响 rclone 对重名文件的去重判断。8.11 --local-no-clone禁用本地到本地服务端复制时的 reflink 克隆。默认情况下对 local→local 传输rclone 会尽可能“克隆”clone文件仅在克隆不受支持时才退化为“复制”copy。克隆产生一种浅拷贝shallow copy即 reflink初始与原文件共享数据块与“硬链接”不同克隆出的两个文件相互独立任何一方后续被修改都不影响另一方克隆通常优于复制更快且天然去重两份相同文件并不会比一份占用更多存储。但对于追求数据冗余的场景可以用--local-no-clone关闭克隆、强制做“深拷贝”。当前克隆仅在 macOS 的APFS上受支持其他平台的支持可能在将来加入。相关实现见 backend/local/clone_darwin.go源码中当NoClone被设置时会将f.features.Copy置空以禁用服务端复制backend/local/local.go#L490-L493。8.12 --local-no-preallocate禁用为目标文件预分配磁盘空间。预分配有助于防止文件系统碎片化但某些虚拟文件系统层如 Google Drive File Stream可能错误地把文件实际大小当作预分配的空间大小导致校验和与大小检查失败。遇到此类环境时用本标志关闭预分配即可。8.13 --local-no-sparse禁用多线程下载时的稀疏文件sparse file支持。Windows 上做多线程下载时 rclone 默认创建稀疏文件避免操作系统对大片区域补零造成的长时间停顿但稀疏文件会引起磁盘碎片、且操作可能变慢因此可用本标志关闭。源码在创建下载文件时会打印提示“Writing sparse files: use --local-no-sparse or --multi-thread-streams 0 to disable”见 backend/local/local.go#L1752-L1758即也可以把多线程流数设为 0 达到同样效果。8.14 --local-no-set-modtime禁用上传完成后设置修改时间。默认 rclone 会在文件上传完毕后回写 mtime当运行 rclone 的用户并不拥有所写文件时例如复制到归其他用户所有的 CIFS 挂载上回写 mtime 可能触发权限错误。开启此选项后复制完成后不再回写 modtime。8.15 --local-metadata-restore-special-bits允许从元数据中恢复 setuid、setgid 与 sticky 位。用--metadata恢复元数据时rclone 会应用源端的 “mode”但默认只应用权限位、剥离 setuid/setgid/sticky。原因很直接mode 来自可能不受信任的源端把 setuid/setgid 位恢复到新写入的、由源控制的内容上可能制造出 setuid 二进制——尤其在以 root 身份从不受信来源恢复时很危险。若你信任源端、并希望恢复这些特殊位例如恢复由 rclone 制作的系统备份再打开此开关。8.16 --local-fatal-if-no-space把磁盘空间不足错误升级为致命错误。开启后写入期间的ENOSPC错误会作为致命错误直接返回rclone 中止而非重试。对备份脚本尤其有用磁盘写满时应该响亮地停下halt loudly而不是反复重试空转。相关测试覆盖可见 backend/local/local_internal_diskfull_test.go。8.17 --local-time-type设置本地后端返回何种时间。默认 rclone 全部基于 mtime设置该标志后列表输出中返回的时间将变成指定类型——例如rclone lsl --local-time-type ctime会显示 ctime。若操作系统不支持指定类型rclone 会静默回退为所有系统都支持的 mtime。各平台支持情况mtime所有系统都支持atime除 plan9、js 外的所有系统btime仅 Windows、macOS、freebsd、netbsdctime除 Windows、plan9、js 外的所有系统。可取值示例值含义mtime最后修改时间atime最后访问时间btime创建时间ctime最后状态变更时间注意设置时间时仍只会设置修改时间因此该选项仅对读取场景有意义。8.18 --local-hashes以逗号分隔指定受支持的校验和类型列表。默认值为空使用 rclone 的默认行为。8.19 --local-encoding指定本地后端的文件名编码掩码默认值为Slash,Dot对应第四节替换表中非 Windows 平台的/与文件名结尾点号规则等基础处理。总体编码规则说明见仓库的 overview 文档的 encoding 小节。在 Windows 上默认行为会在内部追加对应的受限字符集合这就是第四节表格差异的来源。8.20 --local-descriptionremote 的描述字符串纯信息用途Required: false。九、系统与用户元数据本地后端会按操作系统返回相应的系统元数据设置系统元数据在所有系统上受支持而用户元数据user metadata仅在 linux、freebsd、netbsd、macOS 与 Solaris 上受支持——Windows 上暂不支持底层 xattr 库的已知限制。用户元数据以扩展属性extended attributes存储前缀为user.*且要求底层文件系统本身支持扩展属性。元数据对文件与目录均适用。在源码注册信息中local 后端的特性表backend/local/local.go#L471-L486声明了ReadMetadata、WriteMetadata、ReadDirMetadata、WriteDirMetadata等并将UserMetadata/UserDirMetadata绑定到xattrSupported——即仅当平台支持 xattr 时才宣称可读写用户元数据。恢复元数据时--metadatarclone 会应用源端的 “mode”、“uid” 与 “gid”。它们来自可能不受信任的源端因此以 root 身份从不信任源恢复元数据可能改变文件属主不建议这样做setuid/setgid/sticky 位默认也不恢复见--local-metadata-restore-special-bits。本地后端可返回的系统元数据项如下名称说明类型示例只读atime最后访问时间RFC 33392006-01-02T15:04:05.999999999Z07:00Nbtime文件诞生创建时间RFC 33392006-01-02T15:04:05.999999999Z07:00Ngid属主组 ID十进制数500Nmode文件类型与权限八进制unix 风格0100664Nmtime最后修改时间RFC 33392006-01-02T15:04:05.999999999Z07:00Nrdev设备 ID若为特殊文件十六进制1abcNuid属主用户 ID十进制数500N按平台拆分的元数据读写实现位于 backend/local/metadata_linux.go、metadata_unix.go、metadata_windows.go 等文件中。关于--metadata的全局使用说明可参见 docs.md 的 metadata 小节。十、后端专用命令backend nooplocal 后端提供了 backend 命令机制用于在单个 remote 上执行与后端相关的操作。统一调用形式为rclone backend COMMAND remote:命令的帮助会说明各参数含义如何传递选项与参数可参考 backend 命令文档。也可以对正在运行的后端通过 rc 接口的backend/command远程触发。local 后端当前唯一的 backend 命令是noop——一个用于测试 backend 命令机制的“空操作”rclone backend noop remote: [options] [arguments]它主要用于测试 backend 命令通道附带了两个可改变输出的选项echo把传入的参数原样回显error根据选项值返回一个错误。源码定义见 backend/local/local.go#L1168-L1198commandHelp中声明命令名noop及其两个选项Command方法中的分支逻辑会处理error选项为空时返回unspecified error与echo选项从而验证命令行到后端、再到 rc 通道的整条调用链是否可用。十一、总结本地后端的设计要点综合文档与源码可以把 rclone local 后端的设计归纳为几个关键结论便于在实际项目中做正确取舍零配置优先本地路径直接可用rclone sync /a /b注册type local的 remote 仅服务于统一 remote 语法或为目录定制默认选项一切为了跨平台一致性文件名统一要求 UTF-8、非法字节与受限字符Windows 的*:?\|与不可打印控制符、盘符分隔等由 lib/encoder 编码机制在传输层透明替换还原Windows 路径统一转换为\\?\加长格式符号链接三种态度默认忽略、-L跟随复制内容、-l以.rclonelink文本文件往返还原且对“链接写穿到目标目录之外”有明确的安全防护高级选项覆盖了真实生产环境的痛点上传中被更新的文件、无属主权限的 CIFS、虚拟文件系统误报大小预分配/稀疏文件、GlusterFS 类 mtime 抖动、macOS APFS 的 reflink 克隆、磁盘写满时的静默重试等均有对应的开关可以关闭默认行为元数据体系以 mode/uid/gid/atime/btime/mtime/rdev 为骨架恢复时默认剥离 setuid 等特殊位以规避不可信源投毒风险。需要进一步深入时可优先阅读 backend/local/local.go注册与全部选项、fs/fs.go.rclonelink与全局标志定义、lib/encoder文件名编码机制并通过 backend/local 下的*_test.go文件观察各类行为的具体测试预期。【免费下载链接】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），仅供参考 rclone Local Filesystem 本地存储后端全解析：路径、编码、符号链接、高级选项与元数据
rclone Local Filesystem 本地存储后端全解析路径、编码、符号链接、高级选项与元数据【免费下载链接】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本地文件系统Local Filesystem是 rclone 中唯一一个不通过网络访问远程存储、而是直接读写本机磁盘目录的“后端”。它既承载着“把云盘同步到本地做备份”这一最常用场景也是其他所有远端后端工作模型的参照系。本文以 docs/content/local.md 为核心主线逐层讲解本地路径的使用方法、Windows 特有路径语义、文件名编码与受限字符替换规则、符号链接的三种处理策略、跨文件系统边界控制以及 20 余项高级选项与系统元数据的源码级实现细节帮助你精确、安全地驾驭基于本地磁盘的 rclone 传输。一、最朴素的用法直接用本地路径在 rclone 的命令中本地路径可以像普通文件系统路径一样直接书写例如/path/to/wherever不需要事先进行任何 remote 配置。也就是说本地盘就是 rclone 的“零配置后端”。例如把/home/source同步到/tmp/destinationrclone sync --interactive /home/source /tmp/destination这条命令等价于rsync的本地用法--interactive或-i会先输出将要执行的操作供你确认。由于本地路径天然可以被 rclone 识别常见的“本地 ↔ 云盘”备份只需在命令一侧写路径、另一侧写已配置的 remote 即可例如rclone sync /data/photos gdrive:photos-backup二、把本地目录注册为 remote配置文件方式出于统一习惯也可以在配置文件中注册一个type local的 remote之后用 rclone 的 remote 路径语法remote:path/to/wherever访问本地文件系统。例如[localdisk] type local之后即可使用rclone lsd localdisk:/home/user/...。不过正如文档所指出的这“probably easier not to”——因为本地路径本身已经可以直接使用单独建一个 remote 通常没有必要。它真正的价值场景有两个想在.rclone.conf中为本地后端固定若干默认高级选项如nounc true见下文 Windows 长路径部分需要把某条本地目录作为只读/独立入口暴露给其他工具统一走 remote 语法。在源码层面这个 remote 由 backend/local/local.go 中的注册逻辑定义fs.RegInfo{Name: local, Description: Local Disk, NewFs: NewFs, ...}见 backend/local/local.go#L62-L90NewFs是构造文件系统实例的入口函数backend/local/local.go#L444。三、时间戳精度依赖操作系统rclone 对本地文件读写修改时间modification time即 mtime精度由操作系统决定文档给出的典型数值为操作系统时间精度Linux1 nsWindows10 nsmacOS1 s本地后端的 mtime 读写逻辑分布在 backend/local 的lchtimes*.go与setbtime.go等文件中按平台以构建标签区分实现。跨平台同步时这一精度差异会体现在“哪些文件被视为已变更”的判断上——例如源在 Linux 上精确到纳秒的 mtime若被写入一个仅支持 1 秒精度的目标盘反复比对时可能触发“看似变化实则未变”的重复传输规划任务时值得留意。四、文件名的 UTF-8 编码与非法字节处理4.1 盘面编码要求磁盘上的文件名应编码为 UTF-8。Windows 与 macOS 默认即是如此在 Linux 世界中较新的发行版同样使用 UTF-8。如果仍在使用采用非 UTF-8 命名例如 latin1的旧式 Linux 文件系统文档推荐使用convmv工具批量转换为 UTF-8——该工具可通过大多数发行版的软件包管理器安装rclone 仓库内也维护有对应的convmv命令实现见 cmd/convmv/convmv.go专门用于把目录中的文件名在编码之间转换。4.2 非法 UTF-8 字节的替换当 rclone 读到包含非法非 UTF-8字节的文件名时会将非法字符替换为对应字节的带引号表示形式。例如名字gro\xdf会作为gro‛DF被传输并输出一条 debug 消息需用-v查看Local file system at .: Replacing invalid UTF-8 characters in gro\xdf在 Windows 上由于 Windows API 使用 UTF-16这些无法转换的非法 UTF-8 字节也会被替换。关于替换策略的全局说明可参见仓库内的 overview 文档的 invalid-utf8 小节。4.3 受限字符的替换规则本地后端下文件名中哪些字符“不可用”取决于操作系统。要查看当前系统上 rclone 默认会替换哪些字符直接运行rclone help flags local-encoding非 Windows 平台上处理文件名时替换以下字符字符值替换为NUL0x00␀/0x2FWindows 平台上替换以下字符该列表基于 Windows 文件命名约定字符值替换为字符值替换为字符值替换为NUL0x00␀FF0x0C␌US0x1F␟SOH0x01␁CR0x0D␍/0x2FSTX0x02␂SO0x0E␎0x22ETX0x03␃SI0x0F␏*0x2AEOT0x04␄DLE0x10␐:0x3AENQ0x05␅DC10x11␑0x3CACK0x06␆DC20x12␒0x3EBEL0x07␇DC30x13␓?0x3FBS0x08␈DC40x14␔\0x5CHT0x09␉NAK0x15␕|0x7CLF0x0A␊SYN0x16␖VT0x0B␋ETB0x17␗CAN0x18␘EM0x19␙SUB0x1A␚ESC0x1B␛FS0x1C␜GS0x1D␝RS0x1E␞此外Windows 文件名不能以以下字符结尾仅在作为名字最后一个字符时替换字符值替换为SP0x20␠.0x2E这些替换规则由--local-encoding选项统一控制默认值为Slash,Dot详见下文高级选项底层基于 lib/encoder 的编码器机制实现——rclone 对所有后端都采用“先把非法字符映射为安全形式、传输完成后再在目标端还原”的编码策略从而保证跨平台文件名往返一致。五、Windows 路径语义UNC、GUID 卷与长路径5.1 多样化的路径书写方式在 Windows 上本地路径的书写形式非常多样绝对路径C:\path\to\wherever相对路径..\whereverUNC 网络路径\\server\share路径分隔符既可用\如C:\path\to\wherever也可用/如C:/path/to/wherever普通路径的长度限制为文件 259 字符、目录 247 字符。超过限制时可以使用加长路径extended-length path格式把上限提升到约 32,767 字符。该格式要求绝对路径并使用\\?\前缀例如\\?\D:\some\very\long\path。借助同一个\\?\前缀还可以直接按GUID 标识的卷访问路径例如\\?\Volume{b75e2c83-0000-0000-0000-602f00000000}\some\path5.2 长路径的自动转换与 nouncrclone 会自动把所有路径转换为加长路径格式允许最长 32,767 字符因此大多数情况下你无需关心该限制。转换会确保路径为绝对路径并加上\\?\前缀——这就是为什么在输出中你会看到相对路径.\files被显示成\\?\C:\files、\\server\share被显示成\\?\UNC\server\share。极少数情况下这种自动转换会与有缺陷的文件系统驱动冲突如 EncFS。若需全局关闭UNC 转换在.rclone.conf中加入[local] nounc true如果只想对特定目标选择性关闭可以单独注册一个带nounc的 local remote[nounc] type local nounc true然后这样使用——c:\src仍然走 UNC 转换而z:\dst不走rclone copy c:\src nounc:z:\dst注意若 z 盘上某个文件的绝对路径长度超过 259 字符这样的用法会出问题因此只有在确实必要时才应关闭转换。该选项在源码中对应Options.NoUNC配置键nounc相关实现见 backend/local/local.go 中的cleanRootPath调用与noUNC选项定义。六、符号链接与目录联接点的处理符号链接Windows 上行为类似的 junction point 目录联接点的默认行为是被 rclone 忽略。但 rclone 提供了两套方向相反的策略以及若干配套开关6.1 跟随链接--copy-links / -L加上--copy-links或短选项-L后rclone 会跟随符号链接复制其所指向的文件或目录。该标志适用于所有命令且与--links/-l互斥。例如目录结构为$ tree /tmp/a /tmp/a ├── b - ../b ├── expected - ../expected ├── one └── two └── three不使用标志时符号链接b、expected都被忽略$ rclone ls /tmp/a 6 one 6 two/three使用-L后链接指向的内容被复制进来$ rclone -L ls /tmp/a 4174 expected 6 one 6 two/three 6 b/two 6 b/one6.2 把链接翻译成普通文件--local-links / --links / -l这是与-L相反的策略加上该标志后rclone 会把本地存储上的符号链接复制为普通文本文件并以.rclonelink后缀存放到远端文本内容即符号链接的目标路径。这一标志同样适用于所有命令--local-links只对 local 后端生效而--links/-l对所有支持的远端后端与 VFS 生效。例如目录结构$ tree /tmp/a /tmp/a ├── file1 - ./file4 └── file2 - /home/user/file3用-l复制整个目录rclone copy -l /tmp/a/ remote:/tmp/a/远端产生带.rclonelink后缀的文件$ rclone ls remote:/tmp/a 5 file1.rclonelink 14 file2.rclonelink文件内容是符号链接的目标$ rclone cat remote:/tmp/a/file1.rclonelink ./file4 $ rclone cat remote:/tmp/a/file2.rclonelink /home/user/file3再以-l复制回来时链接会被还原$ rclone copy -l remote:/tmp/a/ /tmp/b/ $ tree /tmp/b /tmp/b ├── file1 - ./file4 └── file2 - /home/user/file3而如果不带-l复制回来.rclonelink会作为普通文件保留$ rclone copyto remote:/tmp/a/ /tmp/b/ $ tree /tmp/b /tmp/b ├── file1.rclonelink └── file2.rclonelink用-l复制单个文件时路径必须带上.rclonelink后缀$ rclone copy -l remote:/tmp/a/file1.rclonelink /tmp/c $ tree /tmp/c /tmp/c └── file1 - ./file4源码层面可以验证这一整套约定.rclonelink后缀定义于 fs/fs.go#L21LinkSuffix .rclonelinkbackend/local/local.go 的NewFs中会检查根路径是否以该后缀结尾并在TranslateSymlinks生效时去掉后缀解析backend/local/local.go#L500-L514若在启用-l时用不带后缀的名字直接引用一个符号链接会返回错误errLinksNeedsSuffix提示“需使用 .rclonelink 后缀”。同时-l/--links与-L/--copy-links同时开启会直接报错errLinksAndCopyLinks见 backend/local/local.go#L438-L457。相关的单元测试覆盖可在 backend/local/local_internal_test.go如其中构造symlink.txt.rclonelink测试项的用例中找到。6.3 链接目标与目标目录的安全边界当 rclone 把.rclonelink文件还原为本地符号链接时链接可以指向任何位置——包括用绝对路径或../指向你所复制目录之外。这是刻意为之的正常行为rclone 忠实还原链接原本的目标使备份能够完整往返。但 rclone绝不会通过这样的链接“写穿”write through到链接之外。具体而言如果源端同时存在一个链接例如指向目标目录之外的dir.rclonelink以及一个本应落在该链接内部的dir/file.txtrclone 在写入dir/file.txt时会拒绝跟随该符号链接——这个违规文件会被跳过并报错其余传输照常继续被跳过的文件会计入运行结束时打印的错误汇总中。这一保护机制可以防止恶意或失陷的远端在-l/--links模式下布下符号链接、再借机写到目标目录之外。普通的链接往返、以及目标完全落在目标目录内部的链接都不受影响。如果你的目标是有意预先在目标目录里创建了一个符号链接目录、并希望 rclone 写入其指向的真实目录那么对该次复制请不要使用-l/--links或者先把该符号链接移除。七、用 --one-file-system / -x 限制跨文件系统递归默认情况下 rclone 会沿着挂载点递归进入不同的文件系统。而设置--one-file-system或短选项-x后rclone 只停留在根路径所属的文件系统内不进入挂载在其下的其他文件系统。例如如下目录层级——disk1、disk2各自是挂在 root 下的独立磁盘root ├── disk1 - disk1 mounted on the root │ └── file3 - stored on disk1 ├── disk2 - disk2 mounted on the root │ └── file4 - stored on disk2 ├── file1 - stored on the root disk └── file2 - stored on the root disk执行rclone --one-file-system copy root remote:只会复制file1与file2$ rclone -q --one-file-system ls root 0 file1 0 file2对比不加该标志的情况$ rclone -q ls root 0 disk1/file3 0 disk2/file4 0 file1 0 file2两条重要提醒与du、rsync、tar等多数 Unix 工具一致rclone 把指向同一设备的 bind mount 视为同一文件系统不会拦截。该标志仅适用于 Unix 系系统在不支持它的系统如 Windows上会被忽略。从源码看该功能在 backend/local 中与设备号读取逻辑配套readDevice在初始化时记录根路径的设备号目录遍历层会依据设备号决定是否继续深入。八、高级选项逐项详解以下为 localLocal Disk后端专属的高级选项。它们均可用rclone config中的对应 Config 键配置也都能通过环境变量RCLONE_LOCAL_*覆盖或直接在命令行以--local-xxx形式传入。源码定义位于 backend/local/local.go 的Options与fs.RegInfo.Options中。命令行标志Config 键环境变量类型默认值--local-nouncnouncRCLONE_LOCAL_NOUNCboolfalse--copy-links/-Lcopy_linksRCLONE_LOCAL_COPY_LINKSboolfalse--local-linkslinksRCLONE_LOCAL_LINKSboolfalse--skip-linksskip_linksRCLONE_LOCAL_SKIP_LINKSboolfalse--skip-specialsskip_specialsRCLONE_LOCAL_SKIP_SPECIALSboolfalse--local-zero-size-linkszero_size_linksRCLONE_LOCAL_ZERO_SIZE_LINKSboolfalse已废弃--local-unicode-normalizationunicode_normalizationRCLONE_LOCAL_UNICODE_NORMALIZATIONboolfalse--local-no-check-updatedno_check_updatedRCLONE_LOCAL_NO_CHECK_UPDATEDboolfalse--one-file-system/-xone_file_systemRCLONE_LOCAL_ONE_FILE_SYSTEMboolfalse--local-case-sensitivecase_sensitiveRCLONE_LOCAL_CASE_SENSITIVEboolfalse--local-case-insensitivecase_insensitiveRCLONE_LOCAL_CASE_INSENSITIVEboolfalse--local-no-cloneno_cloneRCLONE_LOCAL_NO_CLONEboolfalse--local-no-preallocateno_preallocateRCLONE_LOCAL_NO_PREALLOCATEboolfalse--local-no-sparseno_sparseRCLONE_LOCAL_NO_SPARSEboolfalse--local-no-set-modtimeno_set_modtimeRCLONE_LOCAL_NO_SET_MODTIMEboolfalse--local-metadata-restore-special-bitsmetadata_restore_special_bitsRCLONE_LOCAL_METADATA_RESTORE_SPECIAL_BITSboolfalse--local-fatal-if-no-spacefatal_if_no_spaceRCLONE_LOCAL_FATAL_IF_NO_SPACEboolfalse--local-time-typetime_typeRCLONE_LOCAL_TIME_TYPEmtime|atime|btime|ctimemtime--local-hasheshashesRCLONE_LOCAL_HASHESCommaSepList空--local-encodingencodingRCLONE_LOCAL_ENCODINGEncodingSlash,Dot--local-descriptiondescriptionRCLONE_LOCAL_DESCRIPTIONstring空8.1 --local-nounc禁用 Windows 上的 UNC长路径名转换。配置示例仅提供true“Disables long file names”即关闭长文件名支持。注意该选项在非 Windows 平台运行时甚至不会作为高级选项出现源码中Advanced: runtime.GOOS ! windows因为它在其他平台上没有意义。8.2 --copy-links / -L跟随符号链接并复制其指向的内容。默认false与前文 6.1 节的语义一致。8.3 --local-links对本地后端启用“把符号链接翻译为带.rclonelink后缀的普通文件”的往返转换。当全局的--links/-l打开时local 后端也会被一并启用——源码中NewFs会执行if ci.Links { opt.TranslateSymlinks true }的覆盖逻辑backend/local/local.go#L452-L455。8.4 --skip-links不警告被跳过的符号链接。默认情况下 rclone 遇到因未加-l/-L而被忽略的符号链接或 junction point 会输出警告显式设置本标志等于声明“我已知晓它们应被跳过”从而静默处理。8.5 --skip-specials不警告被跳过的管道pipe、套接字socket与设备对象device。含义与--skip-links类似只是作用对象从符号链接换成特殊文件。8.6 --local-zero-size-links已废弃假设符号链接的Stat大小为 0并转而实际读取链接内容。该选项对应一段历史rclone 曾把Stat报告的大小当作链接大小但这一做法在多个环境会失效Windows某些虚拟文件系统如 LucidLinkAndroid。因此如今 rclone总是实际读取链接内容本标志已被废弃仅保留以兼容旧配置。8.7 --local-unicode-normalization对路径与文件名应用 Unicode NFC 归一化。rclone 默认不触碰从文件系统读到的文件名编码该选项把读到的名字统一转换为 NFC 形式。典型场景是 macOS其文件系统通常提供分解形式NFD的 Unicode某些语言的文字如韩文在部分操作系统上显示异常。不过 rclone 在 sync 逻辑内部本来就按 Unicode 归一化比较文件名因此文档建议通常不要使用此标志用了反而可能与预期行为重叠或产生额外开销。8.8 --local-no-check-updated关闭“上传过程中检查文件是否发生变化”。默认情况下 rclone 在上传的同时核对文件大小与修改时间若发现文件在上传期间被改动会中止并以 “cant copy - source file is being updated” 开头报错。但在某些文件系统上该 mtime 校验会误报例如 GlusterFS此时可用此标志关闭。关闭后 rclone 会尽力传输正在被更新的文件若文件只是被追加内容如日志文件rclone 会按第一次 stat 到的大小把文件传完若文件在传输全程都被改写不只是追加传输可能以哈希校验失败告终。具体而言一旦文件被第一次 stat()rclone 将只传输 stat 给出的大小只对 stat 给出的大小做校验和不再更新该文件的 stat 信息。注意不要在 Windows 卷影副本Volume Shadow Copy, VSS上使用该标志。VSS 中的文件在目录列表Windows 上初始 stat 值的来源与直接 stat 时偶尔会显示不同大小关闭此检查会引入不一致风险其他复制工具始终使用直接 stat 的值而设置本标志会禁用这一行为。8.9 --one-file-system / -x不跨越文件系统边界仅 Unix/macOS详见本文第七节。8.10 --local-case-sensitive / --local-case-insensitive强制文件系统报告自身为大小写敏感 / 不敏感。默认情况下本地后端在 Windows/macOS 上自报为大小写不敏感其余平台自报为大小写敏感。源码中的判定函数caseInsensitive()逻辑为显式设置了case_sensitive则返回不敏感false显式设置了case_insensitive则返回 true否则按runtime.GOOS windows || runtime.GOOS darwin推断backend/local/local.go#L552-L566。该特性值随后写入fs.Features.CaseInsensitivebackend/local/local.go#L472影响 rclone 对重名文件的去重判断。8.11 --local-no-clone禁用本地到本地服务端复制时的 reflink 克隆。默认情况下对 local→local 传输rclone 会尽可能“克隆”clone文件仅在克隆不受支持时才退化为“复制”copy。克隆产生一种浅拷贝shallow copy即 reflink初始与原文件共享数据块与“硬链接”不同克隆出的两个文件相互独立任何一方后续被修改都不影响另一方克隆通常优于复制更快且天然去重两份相同文件并不会比一份占用更多存储。但对于追求数据冗余的场景可以用--local-no-clone关闭克隆、强制做“深拷贝”。当前克隆仅在 macOS 的APFS上受支持其他平台的支持可能在将来加入。相关实现见 backend/local/clone_darwin.go源码中当NoClone被设置时会将f.features.Copy置空以禁用服务端复制backend/local/local.go#L490-L493。8.12 --local-no-preallocate禁用为目标文件预分配磁盘空间。预分配有助于防止文件系统碎片化但某些虚拟文件系统层如 Google Drive File Stream可能错误地把文件实际大小当作预分配的空间大小导致校验和与大小检查失败。遇到此类环境时用本标志关闭预分配即可。8.13 --local-no-sparse禁用多线程下载时的稀疏文件sparse file支持。Windows 上做多线程下载时 rclone 默认创建稀疏文件避免操作系统对大片区域补零造成的长时间停顿但稀疏文件会引起磁盘碎片、且操作可能变慢因此可用本标志关闭。源码在创建下载文件时会打印提示“Writing sparse files: use --local-no-sparse or --multi-thread-streams 0 to disable”见 backend/local/local.go#L1752-L1758即也可以把多线程流数设为 0 达到同样效果。8.14 --local-no-set-modtime禁用上传完成后设置修改时间。默认 rclone 会在文件上传完毕后回写 mtime当运行 rclone 的用户并不拥有所写文件时例如复制到归其他用户所有的 CIFS 挂载上回写 mtime 可能触发权限错误。开启此选项后复制完成后不再回写 modtime。8.15 --local-metadata-restore-special-bits允许从元数据中恢复 setuid、setgid 与 sticky 位。用--metadata恢复元数据时rclone 会应用源端的 “mode”但默认只应用权限位、剥离 setuid/setgid/sticky。原因很直接mode 来自可能不受信任的源端把 setuid/setgid 位恢复到新写入的、由源控制的内容上可能制造出 setuid 二进制——尤其在以 root 身份从不受信来源恢复时很危险。若你信任源端、并希望恢复这些特殊位例如恢复由 rclone 制作的系统备份再打开此开关。8.16 --local-fatal-if-no-space把磁盘空间不足错误升级为致命错误。开启后写入期间的ENOSPC错误会作为致命错误直接返回rclone 中止而非重试。对备份脚本尤其有用磁盘写满时应该响亮地停下halt loudly而不是反复重试空转。相关测试覆盖可见 backend/local/local_internal_diskfull_test.go。8.17 --local-time-type设置本地后端返回何种时间。默认 rclone 全部基于 mtime设置该标志后列表输出中返回的时间将变成指定类型——例如rclone lsl --local-time-type ctime会显示 ctime。若操作系统不支持指定类型rclone 会静默回退为所有系统都支持的 mtime。各平台支持情况mtime所有系统都支持atime除 plan9、js 外的所有系统btime仅 Windows、macOS、freebsd、netbsdctime除 Windows、plan9、js 外的所有系统。可取值示例值含义mtime最后修改时间atime最后访问时间btime创建时间ctime最后状态变更时间注意设置时间时仍只会设置修改时间因此该选项仅对读取场景有意义。8.18 --local-hashes以逗号分隔指定受支持的校验和类型列表。默认值为空使用 rclone 的默认行为。8.19 --local-encoding指定本地后端的文件名编码掩码默认值为Slash,Dot对应第四节替换表中非 Windows 平台的/与文件名结尾点号规则等基础处理。总体编码规则说明见仓库的 overview 文档的 encoding 小节。在 Windows 上默认行为会在内部追加对应的受限字符集合这就是第四节表格差异的来源。8.20 --local-descriptionremote 的描述字符串纯信息用途Required: false。九、系统与用户元数据本地后端会按操作系统返回相应的系统元数据设置系统元数据在所有系统上受支持而用户元数据user metadata仅在 linux、freebsd、netbsd、macOS 与 Solaris 上受支持——Windows 上暂不支持底层 xattr 库的已知限制。用户元数据以扩展属性extended attributes存储前缀为user.*且要求底层文件系统本身支持扩展属性。元数据对文件与目录均适用。在源码注册信息中local 后端的特性表backend/local/local.go#L471-L486声明了ReadMetadata、WriteMetadata、ReadDirMetadata、WriteDirMetadata等并将UserMetadata/UserDirMetadata绑定到xattrSupported——即仅当平台支持 xattr 时才宣称可读写用户元数据。恢复元数据时--metadatarclone 会应用源端的 “mode”、“uid” 与 “gid”。它们来自可能不受信任的源端因此以 root 身份从不信任源恢复元数据可能改变文件属主不建议这样做setuid/setgid/sticky 位默认也不恢复见--local-metadata-restore-special-bits。本地后端可返回的系统元数据项如下名称说明类型示例只读atime最后访问时间RFC 33392006-01-02T15:04:05.999999999Z07:00Nbtime文件诞生创建时间RFC 33392006-01-02T15:04:05.999999999Z07:00Ngid属主组 ID十进制数500Nmode文件类型与权限八进制unix 风格0100664Nmtime最后修改时间RFC 33392006-01-02T15:04:05.999999999Z07:00Nrdev设备 ID若为特殊文件十六进制1abcNuid属主用户 ID十进制数500N按平台拆分的元数据读写实现位于 backend/local/metadata_linux.go、metadata_unix.go、metadata_windows.go 等文件中。关于--metadata的全局使用说明可参见 docs.md 的 metadata 小节。十、后端专用命令backend nooplocal 后端提供了 backend 命令机制用于在单个 remote 上执行与后端相关的操作。统一调用形式为rclone backend COMMAND remote:命令的帮助会说明各参数含义如何传递选项与参数可参考 backend 命令文档。也可以对正在运行的后端通过 rc 接口的backend/command远程触发。local 后端当前唯一的 backend 命令是noop——一个用于测试 backend 命令机制的“空操作”rclone backend noop remote: [options] [arguments]它主要用于测试 backend 命令通道附带了两个可改变输出的选项echo把传入的参数原样回显error根据选项值返回一个错误。源码定义见 backend/local/local.go#L1168-L1198commandHelp中声明命令名noop及其两个选项Command方法中的分支逻辑会处理error选项为空时返回unspecified error与echo选项从而验证命令行到后端、再到 rc 通道的整条调用链是否可用。十一、总结本地后端的设计要点综合文档与源码可以把 rclone local 后端的设计归纳为几个关键结论便于在实际项目中做正确取舍零配置优先本地路径直接可用rclone sync /a /b注册type local的 remote 仅服务于统一 remote 语法或为目录定制默认选项一切为了跨平台一致性文件名统一要求 UTF-8、非法字节与受限字符Windows 的*:?\|与不可打印控制符、盘符分隔等由 lib/encoder 编码机制在传输层透明替换还原Windows 路径统一转换为\\?\加长格式符号链接三种态度默认忽略、-L跟随复制内容、-l以.rclonelink文本文件往返还原且对“链接写穿到目标目录之外”有明确的安全防护高级选项覆盖了真实生产环境的痛点上传中被更新的文件、无属主权限的 CIFS、虚拟文件系统误报大小预分配/稀疏文件、GlusterFS 类 mtime 抖动、macOS APFS 的 reflink 克隆、磁盘写满时的静默重试等均有对应的开关可以关闭默认行为元数据体系以 mode/uid/gid/atime/btime/mtime/rdev 为骨架恢复时默认剥离 setuid 等特殊位以规避不可信源投毒风险。需要进一步深入时可优先阅读 backend/local/local.go注册与全部选项、fs/fs.go.rclonelink与全局标志定义、lib/encoder文件名编码机制并通过 backend/local 下的*_test.go文件观察各类行为的具体测试预期。【免费下载链接】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），仅供参考