rclone Local Filesystem 本地存储后端全解析：路径、编码、符号链接、高级选项与元数据

本地文件系统（Local Filesystem）是 rclone 中唯一一个不通过网络访问远程存储、而是直接读写本机磁盘目录的“后端”。它既承载着“把云盘同步到本地做备份”这一最常用场景，也是其他所有远端后端工作模型的参照系。本文以 docs/content/local.md 为核心主线，逐层讲解本地路径的使用方法、Windows 特有路径语义、文件名编码与受限字符替换规则、符号链接的三种处理策略、跨文件系统边界控制，以及 20 余项高级选项与系统元数据的源码级实现细节，帮助你精确、安全地驾驭基于本地磁盘的 rclone 传输。

一、最朴素的用法：直接用本地路径

在 rclone 的命令中，本地路径可以像普通文件系统路径一样直接书写（例如 /path/to/wherever），不需要事先进行任何 remote 配置。也就是说，本地盘就是 rclone 的“零配置后端”。

例如，把 /home/source 同步到 /tmp/destination：

rclone 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-L90），NewFs 是构造文件系统实例的入口函数（backend/local/local.go#L444）。

三、时间戳精度：依赖操作系统

rclone 对本地文件读写修改时间（modification time，即 mtime），精度由操作系统决定，文档给出的典型数值为：

操作系统	时间精度
Linux	1 ns
Windows	10 ns
macOS	1 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 平台上，处理文件名时替换以下字符：

字符	值	替换为
NUL	0x00	␀
/	0x2F	／

Windows 平台上替换以下字符（该列表基于 Windows 文件命名约定）：

字符	值	替换为	字符	值	替换为	字符	值	替换为
NUL	0x00	␀	FF	0x0C	␌	US	0x1F	␟
SOH	0x01	␁	CR	0x0D	␍	/	0x2F	／
STX	0x02	␂	SO	0x0E	␎	"	0x22	＂
ETX	0x03	␃	SI	0x0F	␏	*	0x2A	＊
EOT	0x04	␄	DLE	0x10	␐	:	0x3A	：
ENQ	0x05	␅	DC1	0x11	␑	<	0x3C	＜
ACK	0x06	␆	DC2	0x12	␒	>	0x3E	＞
BEL	0x07	␇	DC3	0x13	␓	?	0x3F	？
BS	0x08	␈	DC4	0x14	␔	\	0x5C	＼
HT	0x09	␉	NAK	0x15	␕	|	0x7C	｜
LF	0x0A	␊	SYN	0x16	␖
VT	0x0B	␋	ETB	0x17	␗
CAN	0x18	␘
EM	0x19	␙
SUB	0x1A	␚
ESC	0x1B	␛
FS	0x1C	␜
GS	0x1D	␝
RS	0x1E	␞

此外，Windows 文件名不能以以下字符结尾（仅在作为名字最后一个字符时替换）：

字符	值	替换为
SP	0x20	␠
.	0x2E	．

这些替换规则由 --local-encoding 选项统一控制（默认值为 Slash,Dot，详见下文高级选项），底层基于 lib/encoder 的编码器机制实现——rclone 对所有后端都采用“先把非法字符映射为安全形式、传输完成后再在目标端还原”的编码策略，从而保证跨平台文件名往返一致。

五、Windows 路径语义：UNC、GUID 卷与长路径

5.1 多样化的路径书写方式

在 Windows 上，本地路径的书写形式非常多样：

• 绝对路径：C:\path\to\wherever
• 相对路径：..\wherever
• UNC 网络路径：\\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\path

5.2 长路径的自动转换与 nounc

rclone 会自动把所有路径转换为加长路径格式（允许最长 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/one

6.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#L21（LinkSuffix = ".rclonelink"）；backend/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.txt，rclone 在写入 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 在初始化时记录根路径的设备号），目录遍历层会依据设备号决定是否继续深入。

八、高级选项逐项详解

以下为 local（Local Disk）后端专属的高级选项。它们均可用 rclone config 中的对应 Config 键配置，也都能通过环境变量 RCLONE_LOCAL_* 覆盖，或直接在命令行以 --local-xxx 形式传入。源码定义位于 backend/local/local.go 的 Options 与 fs.RegInfo.Options 中。

命令行标志	Config 键	环境变量	类型	默认值
--local-nounc	nounc	RCLONE_LOCAL_NOUNC	bool	false
--copy-links / -L	copy_links	RCLONE_LOCAL_COPY_LINKS	bool	false
--local-links	links	RCLONE_LOCAL_LINKS	bool	false
--skip-links	skip_links	RCLONE_LOCAL_SKIP_LINKS	bool	false
--skip-specials	skip_specials	RCLONE_LOCAL_SKIP_SPECIALS	bool	false
--local-zero-size-links	zero_size_links	RCLONE_LOCAL_ZERO_SIZE_LINKS	bool	false（已废弃）
--local-unicode-normalization	unicode_normalization	RCLONE_LOCAL_UNICODE_NORMALIZATION	bool	false
--local-no-check-updated	no_check_updated	RCLONE_LOCAL_NO_CHECK_UPDATED	bool	false
--one-file-system / -x	one_file_system	RCLONE_LOCAL_ONE_FILE_SYSTEM	bool	false
--local-case-sensitive	case_sensitive	RCLONE_LOCAL_CASE_SENSITIVE	bool	false
--local-case-insensitive	case_insensitive	RCLONE_LOCAL_CASE_INSENSITIVE	bool	false
--local-no-clone	no_clone	RCLONE_LOCAL_NO_CLONE	bool	false
--local-no-preallocate	no_preallocate	RCLONE_LOCAL_NO_PREALLOCATE	bool	false
--local-no-sparse	no_sparse	RCLONE_LOCAL_NO_SPARSE	bool	false
--local-no-set-modtime	no_set_modtime	RCLONE_LOCAL_NO_SET_MODTIME	bool	false
--local-metadata-restore-special-bits	metadata_restore_special_bits	RCLONE_LOCAL_METADATA_RESTORE_SPECIAL_BITS	bool	false
--local-fatal-if-no-space	fatal_if_no_space	RCLONE_LOCAL_FATAL_IF_NO_SPACE	bool	false
--local-time-type	time_type	RCLONE_LOCAL_TIME_TYPE	mtime|atime|btime|ctime	mtime
--local-hashes	hashes	RCLONE_LOCAL_HASHES	CommaSepList	空
--local-encoding	encoding	RCLONE_LOCAL_ENCODING	Encoding	Slash,Dot
--local-description	description	RCLONE_LOCAL_DESCRIPTION	string	空

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；
• 某些虚拟文件系统（如 LucidLink）；
• Android。

因此如今 rclone 总是实际读取链接内容，本标志已被废弃，仅保留以兼容旧配置。

8.7 --local-unicode-normalization

对路径与文件名应用 Unicode NFC 归一化。rclone 默认不触碰从文件系统读到的文件名编码；该选项把读到的名字统一转换为 NFC 形式。典型场景是 macOS：其文件系统通常提供分解形式（NFD）的 Unicode，某些语言的文字（如韩文）在部分操作系统上显示异常。不过 rclone 在 sync 逻辑内部本来就按 Unicode 归一化比较文件名，因此文档建议通常不要使用此标志（用了反而可能与预期行为重叠或产生额外开销）。

8.8 --local-no-check-updated

关闭“上传过程中检查文件是否发生变化”。默认情况下 rclone 在上传的同时核对文件大小与修改时间，若发现文件在上传期间被改动，会中止并以 “can't 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.CaseInsensitive（backend/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、netbsd；
• ctime：除 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-description

remote 的描述字符串（纯信息用途，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 时才宣称可读写用户元数据。

恢复元数据时（--metadata），rclone 会应用源端的 “mode”、“uid” 与 “gid”。它们来自可能不受信任的源端，因此以 root 身份从不信任源恢复元数据可能改变文件属主，不建议这样做；setuid/setgid/sticky 位默认也不恢复（见 --local-metadata-restore-special-bits）。

本地后端可返回的系统元数据项如下：

名称	说明	类型	示例	只读
atime	最后访问时间	RFC 3339	2006-01-02T15:04:05.999999999Z07:00	N
btime	文件诞生（创建）时间	RFC 3339	2006-01-02T15:04:05.999999999Z07:00	N
gid	属主组 ID	十进制数	500	N
mode	文件类型与权限	八进制，unix 风格	0100664	N
mtime	最后修改时间	RFC 3339	2006-01-02T15:04:05.999999999Z07:00	N
rdev	设备 ID（若为特殊文件）	十六进制	1abc	N
uid	属主用户 ID	十进制数	500	N

按平台拆分的元数据读写实现位于 backend/local/metadata_linux.go、metadata_unix.go、metadata_windows.go 等文件中。关于 --metadata 的全局使用说明可参见 docs.md 的 metadata 小节。

十、后端专用命令：backend noop

local 后端提供了 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-L1198：commandHelp 中声明命令名 noop 及其两个选项，Command 方法中的分支逻辑会处理 error 选项（为空时返回 unspecified error）与 echo 选项，从而验证命令行到后端、再到 rc 通道的整条调用链是否可用。

十一、总结：本地后端的设计要点

综合文档与源码，可以把 rclone local 后端的设计归纳为几个关键结论，便于在实际项目中做正确取舍：

1. 零配置优先：本地路径直接可用（rclone sync /a /b），注册 type = local 的 remote 仅服务于统一 remote 语法或为目录定制默认选项；
2. 一切为了跨平台一致性：文件名统一要求 UTF-8、非法字节与受限字符（Windows 的 "*:<>?\| 与不可打印控制符、盘符分隔等）由 lib/encoder 编码机制在传输层透明替换还原；Windows 路径统一转换为 \\?\ 加长格式；
3. 符号链接三种态度：默认忽略、-L 跟随复制内容、-l 以 .rclonelink 文本文件往返还原，且对“链接写穿到目标目录之外”有明确的安全防护；
4. 高级选项覆盖了真实生产环境的痛点：上传中被更新的文件、无属主权限的 CIFS、虚拟文件系统误报大小（预分配/稀疏文件）、GlusterFS 类 mtime 抖动、macOS APFS 的 reflink 克隆、磁盘写满时的静默重试等，均有对应的开关可以关闭默认行为；
5. 元数据体系以 mode/uid/gid/atime/btime/mtime/rdev 为骨架，恢复时默认剥离 setuid 等特殊位以规避不可信源投毒风险。

需要进一步深入时，可优先阅读 backend/local/local.go（注册与全部选项）、fs/fs.go（.rclonelink 与全局标志定义）、lib/encoder（文件名编码机制），并通过 backend/local 下的 *_test.go 文件观察各类行为的具体测试预期。