rclone serve webdav 完全指南：把任意云端存储以 WebDAV 协议对外服务

rclone 内置的 serve webdav 子命令可以把任意 remote:path（本地目录、Google Drive、S3、Dropbox、Backblaze B2 等全部后端）通过 HTTP/HTTPS 以 WebDAV 协议暴露为一个标准的文件服务端点，供 Windows 资源管理器映射网络驱动器、Office 应用直接打开文件，或用 rclone 的 WebDAV 类型后端再次读写同一份数据。读完本文你将掌握如何启动/加固/调优该服务、处理 Windows 与 Office 的兼容性、启用 TLS 与认证、基于 VFS 层做缓存与并发调优，以及通过 Auth Proxy 动态生成后端。

该命令的完整实现位于 cmd/serve/webdav/webdav.go（此命令文档也由该目录源码自动生成，见 docs/content/commands/rclone_serve_webdav.md），属于 rclone serve 协议族的一员（协议列表见 rclone serve 文档）。

基本用法与能力边界

rclone serve webdav 会在本机启动一个 WebDAV 服务器，通过 HTTP 对外提供 remote 上的内容：

rclone serve webdav remote:path [flags]

文档 Synopsis（源码 cmd/serve/webdav/webdav.go 中的 Long 描述）明确列出三种典型消费方式：

1. 使用任意 WebDAV 客户端（如 Windows 资源管理器的"映射网络驱动器"、macOS 的"连接服务器"）；
2. 直接用浏览器访问（服务自带 HTML 目录列表页）；
3. 在 rclone 里再建一个 vendor 为 rclone 的 WebDAV 类型远程，去读/写它——这等于把任意后端"翻译"成 WebDAV 再供 rclone 复用。

从源码实现看，命令入口只接受一个 remote:path 参数（webdav.go 中 RunE 先执行 cmd.NewFsSrc(args) 解析远程），除非启用了 Auth Proxy（见后文，此时不需要任何位置参数）。命令名用 webdav 作为 cobra 子命令注册到 serve 之下（webdav.go），并同时注册了一个同名的 RC 接口用于通过 remote control 动态创建服务器实例。

ETag 控制：--etag-hash

--etag-hash 控制响应头里的 ETag 取值。不设置该 flag 时，ETag 基于对象的 ModTime（修改时间）与 Size（大小） 生成。

三种取值方式：

• 留空：关闭基于哈希的 ETag（默认）；
• auto：rclone 自动选取该后端支持的第一个哈希算法；
• 指定具名哈希，如 MD5、SHA-1（完整列表可用 rclone hashsum 命令 查看）。

在 webdav.go 中，auto 会调用 f.Hashes().GetOne() 取后端第一个支持哈希；否则按名解析哈希类型，解析失败直接报错。选定后，服务以该哈希计算 ETag：FileInfo.ETag 返回 "hash" 形式（webdav.go），而当使用哈希时还会通过 DeadProps 向 PROPFIND 响应输出 ownCloud 命名空间的 checksums 属性（格式如 MD5:<hash>，webdav.go），方便 ownCloud/Nextcloud 类客户端做完整性校验。若哈希不可得或出错则回退为 webdav.ErrNotImplemented。

该 flag 在 Options 注册表中对应的定义位于 webdav.go。

Gzip 压缩

当客户端通过请求头 Accept-Encoding: gzip 表明支持 gzip 时，服务器会对文本类与 XML 类响应体（包括 WebDAV PROPFIND 响应，及 HTML 目录页）进行 gzip 压缩以降低带宽占用。

实现细节见 webDAVCompressMiddleware：它使用 go-chi 的 middleware.Compress(5, "text/*", "application/xml") 压缩，压缩级别为 5，仅命中 text/* 与 application/xml 两种 MIME。特别地，当请求带 Range 头时直接跳过压缩（避免与范围请求语义冲突）。该中间件与 Accept-Ranges: bytes、Server: rclone/<版本> 响应头一起注册到路由（webdav.go）。

Windows 下访问与映射网络驱动器

Windows 可以把 WebDAV 共享文件夹映射成盘符（网络驱动器），但默认设置会阻止连接：Windows 出于安全策略不允许使用不安全的 Basic 认证，连登录对话框都不会弹出。通过"添加网络位置"向导连接时会得到报错：

The folder you entered does not appear to be valid. Please choose another.

解决办法是在客户端机器上修改注册表键：

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters\BasicAuthLevel

BasicAuthLevel 的取值含义：

0 - Basic authentication disabled
1 - Basic authentication enabled for SSL connections only
2 - Basic authentication enabled for SSL connections and for non-SSL connections

要允许明文 HTTP 下的 Basic 认证需设为 2。此外：

• 若涉及大文件，可将同键下的 FileSizeLimitInBytes 调大（WebClient 默认有 2GB 左右的单文件大小限制）；
• 修改后需进入服务管理界面，重启 WebClient 服务使配置生效。

让 Office 应用（Word/Excel/PowerPoint）走 WebDAV

Office 打开 WebDAV/SharePoint 地址时同样受 Basic 认证限制。按下面路径新建注册表项：

HKEY_CURRENT_USER\Software\Microsoft\Office\[14.0/15.0/16.0]\Common\Internet

在该键下新建 DWORD 值 BasicAuthLevel 并设为 2：

0 - Basic authentication disabled
1 - Basic authentication enabled for SSL connections only
2 - Basic authentication enabled for SSL and for non-SSL connections

Office 各主要版本对应注册表节：14.0（Office 2010）、15.0（Office 2013）、16.0（Office 2016/2019/365），按实际版本选择目录。

通过 Unix Socket 提供服务

服务器监听地址可指定为 Unix socket，适合本机进程间通信或配合反向代理：

rclone serve webdav --addr unix:///tmp/my.socket remote:path

然后用 rclone 自带的 WebDAV 后端连回去验证：

rclone --webdav-unix-socket /tmp/my.socket --webdav-url http://localhost lsf :webdav:

注意：socket 上跑的是无认证的 HTTP 协议，安全性由 socket 文件的权限（谁有权限 connect 该 socket）来保证。

符号链接 / 联接点（Symlinks / Junction points）处理

WebDAV 协议本身不支持符号链接与联接点，因此默认 rclone 会完全跳过它们。可选的处理方式：

• 加 -L：让 rclone 跟随符号链接指向的目标内容；
• 加 --local-links：让 rclone 以 .rclonelink 普通文件形式呈现符号链接（与本地后端的链接翻译方案兼容，见 local 后端 Symlinks/Junction points 章节）。

重要提醒：请勿使用 --links 来达到上述目的——自 v1.69 起 --links 会同时作用于 VFS 层，此处应使用只作用于 local 后端的 --local-links。

Server options：监听、超时与 URL 前缀

--addr：监听地址与端口

• 指定 IP 与端口：--addr 1.2.3.4:8000；
• 监听所有网卡：--addr :8080（默认仅监听 127.0.0.1:8080）；
• 让系统随机分配端口：:0（对外提供的 URL 会打印在启动日志中）；
• Unix socket：unix:///path/to/socket 或直接写绝对路径。

若把 --addr 设为公网或局域网可访问的地址，强烈建议开启认证（见下文 Authentication 章节）。

--addr 可以重复指定多次，从而同时在多个 IP/端口/socket 上监听；也可以改用下文介绍的 Socket activation 达到同样效果。

超时与请求头限制

• --server-read-timeout、--server-write-timeout：控制服务器读写超时。注意这是单次传输的总时长，默认均为 1h0m0s，大文件慢速传输时需留意；
• --max-header-bytes：服务器接受的 HTTP 请求头最大字节数，默认 4096，可按代理链路上游携带的大 Cookie/自定义头调大；
• --response-header：为所有响应追加（并覆盖同名已有值的）HTTP 头，格式 Header-Name: value，可重复使用该 flag 添加多个头。

--baseurl：URL 前缀（配合反向代理）

默认 rclone 从根路径 / 提供服务。传入 --baseurl "/rclone" 后内容挂到以 /rclone/ 开头的 URL 下，便于放在 Nginx/Caddy 等反向代理的子路径后面。rclone 会自动补齐首尾的 /，因此下列写法完全等价：

--baseurl "rclone"
--baseurl "/rclone"
--baseurl "/rclone/"

源码中前缀规范化的实现在 webdav.go："/" + strings.Trim(BaseURL, "/")，并以此前缀创建 webdav.Handler（webdav.go），保证 WebDAV 返回绝对引用时前缀正确。

--disable-zip：关闭目录打包下载

访问目录 HTML 页时，URL 带 ?download=zip 参数即可把整个目录实时打包为 zip 下载（实现在 serveDir，调用 vfs.CreateZip 流式输出，不占本地磁盘）。--disable-zip 可关闭该功能。

协议支持

服务端支持 HTTP/1.1 与 HTTP/2：

• TLS 连接自动协商 HTTP/2；
• 非 TLS 连接支持 h2c（HTTP/2 cleartext），即不加密也能跑 HTTP/2。

TLS（HTTPS）配置

默认走 HTTP；需要 HTTPS 时提供：

• --cert：PEM 编码的证书文件路径，可以是证书本身，也可以是证书与 CA 证书的拼接；
• --key：PEM 编码的私钥文件路径；
• --client-ca（可选）：若需做客户端证书校验，指向 PEM 编码的客户端 CA 证书文件路径。

关于监听粒度：配置 TLS 后，--addr 给出的每个监听器都默认提供 TLS；可以在单个地址前加 http:// 前缀强制该地址走明文 HTTP，或加 tls:// 前缀显式声明必须 TLS——若 tls:// 地址没有配套 --cert/--key 会直接报错。

--min-tls-version 设定可接受的最低 TLS 版本，合法值为 tls1.0、tls1.1、tls1.2、tls1.3，默认 tls1.0。

Socket activation（systemd 套接字激活）

如果服务管理器（systemd）通过 socket 向 rclone 传递了文件描述符（FD），rclone 会忽略 --addr 的所有参数，转而在这些 FD 上监听。这让 rclone 可以作为 systemd socket-activated 服务运行，配合 .socket 与 .service 单元文件使用。可先用 systemd-socket-activate 做临时验证：

systemd-socket-activate -l 8000 -- rclone serve

上述命令会在 TCP 8000 端口收到首个连接时按需拉起 rclone。

自定义页面模板：--template

--template 允许为 HTTP/WebDAV 服务的页面指定自定义模板（Go 模板语法）。服务器向模板暴露以下数据：

参数	子参数	说明
.Name		文件/目录的完整路径。
.Title		'.Name' 的目录列表标题。
.Sort		当前排序方式，通过 ?sort= 参数修改。可能值：namedirfirst、name、size、time（默认 namedirfirst）。
.Order		当前排序方向，通过 ?order= 参数修改。可能值：asc、desc（默认 asc）。
.Query		当前未使用。
.Breadcrumb		用于生成相对导航。
	.Link	相对根的链接地址。
	.Text	目录名。
.Entries		单个文件/目录的信息。
	.URL	条目的 URL。
	.Leaf	当前与 .URL 相同，设计意图为仅取名称。
	.IsDir	是否为目录的布尔值。
	.Size	条目字节大小。
	.ModTime	条目的 UTC 时间戳。

模板内还可调用以下函数，用于按条件动态渲染 HTML：

函数	说明
afterEpoch	返回给定时间距离 Unix epoch 的秒数。
contains	判断给定字符串中是否包含指定子串。
hasPrefix	判断给定字符串是否以指定前缀开头。
hasSuffix	判断给定字符串是否以指定后缀结尾。

目录列表与排序的处理逻辑见 serveDir，它读取 sort、order、download 查询参数并渲染 HTML 模板；测试用例（使用 golden 模板）见 webdav_test.go。

认证与用户管理

默认无需登录即可访问。可选三种认证方式：

1. htpasswd 文件（可容纳大量用户）；
2. 单用户：--user + --pass；
3. 反向代理透传用户：--user-from-header（如 --user-from-header=x-remote-user）——认证交给反代完成，rclone 直接信任指定请求头里的用户名。必须确保反代可信且头不可被伪造，否则错误配置可能导致未授权访问。

补充规则：若上述两种方法都未配置，但服务端通过 --client-ca 强制要求客户端证书，则客户端证书的 Common Name 会被视为用户名。

htpasswd 文件

--htpasswd /path/to/htpasswd

该文件为标准 Apache 格式，支持 MD5、SHA1 与 BCrypt（推荐 BCrypt）三种哈希。创建方式：

touch htpasswd
htpasswd -B htpasswd user
htpasswd -B htpasswd anotherUser

（-B 表示使用 bcrypt 算法。）rclone 运行期间可以随时更新该文件，无需重启服务。

其他相关 flag：--realm 设置认证域（realm）；--salt 可修改默认的密码哈希盐（默认 dlPL2MqE）。完整选项见 webdav.go 对应选项及命令文档 Options 一节。

Auth Proxy：动态生成后端

--auth-proxy /path/to/program 可以指定一个外部程序，在每次收到认证请求时即时生成后端，从而让单个 rclone serve webdav 充当任意后端的通用代理。其协议是简单的 JSON over STDIN/STDOUT。

约束：--auth-proxy 与 --authorized-keys 不能同时使用；设置了前者时，authorized keys 选项被忽略。

程序职责：从 STDIN 读取 user 与 pass（或 public_key），在 STDOUT 输出 JSON 格式的完整后端配置。rclone 会为输出补上该后端的默认参数，但不会使用环境变量或命令行配置——补齐完整配置是代理程序的责任。

配置中必须包含的额外字段：

• _root：该后端使用的根目录。

可选字段：

• _obscure：需要模糊化（obscure）的参数的逗号分隔字符串。

密码认证时，输入类似：

{
  "user": "me",
  "pass": "mypassword"
}

公钥认证时，输入类似：

{
  "user": "me",
  "public_key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDuwESFdAe14hVS6omeyX7edc...JQdf"
}

一个输出示例（创建 SFTP 后端）：

{
  "type": "sftp",
  "_root": "",
  "_obscure": "pass",
  "user": "me",
  "pass": "mypassword",
  "host": "sftp.example.com"
}

因为 _obscure 指定了 pass，rclone 在创建后端前会对该参数做模糊化（SFTP 后端要求密码以模糊化形式存储）。代理程序可以任意改写 user，例如把输入 [e-mail] 拆成输出里的 host=example.com、user=user，从而代理到多个 SFTP 后端（出于安全考虑通常应把 host 限制在白名单内）。

后端缓存以 user 与 pass/public_key 的哈希为键：一旦用户密码/公钥变化或代理返回的配置参数变化（如轮换的 api_key），下一次请求就会创建全新后端而非复用旧缓存。认证代理的相关入口与后端 Provider 实现在 cmd/serve/proxy 包内，serve webdav 侧通过 proxy.Provider 接入，代理激活时认证回调被替换为 auth。

底层架构：VFS 层与协议适配

serve webdav 依赖 rclone 的 VFS（Virtual File System）层把云端对象的语义"翻译"成接近本地磁盘文件系统的样子（webdav.go 包注释明确说明它是"backed by rclone VFS"）。每个 WebDAV 方法都映射为对 VFS 的调用：

• Mkdir → VFS.StatParent + dir.Mkdir；
• OpenFile → VFS.OpenFile；
• RemoveAll → VFS.Stat + node.RemoveAll；
• Rename → VFS.Rename；
• Stat → VFS.Stat。

对应实现见 webdav.go。服务通过 webdav.Handler（golang.org/x/net/webdav，内存锁系统 webdav.NewMemLS()）分发协议请求，并对仅 WebDAV 使用的扩展方法做显式注册：COPY、LOCK、MKCOL、MOVE、PROPFIND、PROPPATCH、UNLOCK（webdav.go）。

云存储对象与磁盘文件差异巨大（不能追加写、不能随机改写中间部分），VFS 层因此提供一组选项来调节兼容性与资源消耗；同时 VFS 实现了目录缓存（仅缓存目录/文件元信息，不缓存数据）。serve webdav 的这些参数通过 vfsflags 全部暴露为命令 flag（注册于 webdav.go）。集成测试见 webdav_test.go——它先启动服务器，再按 WebDAV 后端方式回连服务端跑 servetest 全量测试套件。

VFS Directory Cache 目录缓存

--dir-cache-time 控制目录条目被视作最新、不需要向后端刷新的时长。经 VFS 自己发起的修改会立即生效或主动使缓存失效：

    --dir-cache-time duration   Time to cache directory entries for (default 5m0s)
    --poll-interval duration    Time to wait between polling for changes. Must be smaller than dir-cache-time. Only on supported remotes. Set to 0 to disable (default 1m0s)

而绕过 rclone（如通过云厂商网页或另一份 rclone）直接改云端数据时：若后端不支持轮询，只能等目录缓存过期后才会被发现；若支持轮询，则会在一个 --poll-interval 内看到变化。

两种手动刷新缓存的手段：

1. 向 rclone 发送 SIGHUP 信号，无条件冲刷所有目录缓存（仅单实例场景）：

kill -SIGHUP $(pidof rclone)

2. 配置了 remote control 后，用 RC 接口冲刷整个目录缓存或指定文件/目录：

rclone rc vfs/forget
rclone rc vfs/forget file=path/to/file dir=path/to/dir

VFS File Buffering 读缓冲

--buffer-size 决定每个打开文件预读进内存的数据量上限。缓冲数据与单个打开文件绑定、不共享，并且只有"已下载但尚未被应用读走"的数据才会占用内存——缓冲区为空时内存占用很小。因此 rclone 用于缓冲的最大内存约为：

--buffer-size * open files（同时打开的文件数）

VFS File Caching 磁盘缓存

文件级磁盘缓存是让 VFS 表现得像普通文件系统所必需的（例如想"边读边写"同一文件就必须开启），可按需牺牲部分兼容性来关闭。注意该缓存独立于（已被取代的）cache 后端，两者可能都需要。

    --cache-dir string                     Directory rclone will use for caching.
    --vfs-cache-mode CacheMode             Cache mode off|minimal|writes|full (default off)
    --vfs-cache-max-age duration           Max time since last access of objects in the cache (default 1h0m0s)
    --vfs-cache-max-size SizeSuffix        Max total size of objects in the cache (default off)
    --vfs-cache-min-free-space SizeSuffix  Target minimum free space on the disk containing the cache (default off)
    --vfs-cache-poll-interval duration     Interval to poll the cache for stale objects (default 1m0s)
    --vfs-write-back duration              Time to writeback files after last use when using cache (default 5s)

以 -vv 运行会打印缓存目录位置。缓存文件默认放在系统用户缓存目录（随 OS 不同），可用 --cache-dir 或对应环境变量覆盖。

--vfs-cache-mode 共有 4 档，模式越高兼容性越好、代价是磁盘占用越多。写回规则：文件仅在关闭后且距最后访问超过 --vfs-write-back 秒时才上传远端；若 rclone 在文件上传前退出/崩溃，下次以相同参数运行时这些文件会被补传。

关于配额：--vfs-cache-max-size / --vfs-cache-min-free-space 可能被临时超额——因为配额每 --vfs-cache-poll-interval 才检查一次，且打开中的文件不能被逐出。超额时按"最久未被访问者优先"策略逐出，尽量保留热点文件。--vfs-cache-max-age 则按"距上次访问超过该时长即逐出"（默认 1 小时，被访问后计时清零），时间可用 s/m/h/d/w 单位表示。

并发安全警告：使用 --vfs-cache-mode 高于 off 时，绝不要运行两份共享同一/重叠 remote 的 rclone 并使用同一 VFS 缓存，否则可能数据损坏；可用 --cache-dir 为每份 rclone 分配独立缓存层级规避（remote 不重叠则无此顾虑）。

各缓存模式差异

--vfs-cache-mode off（默认）：读写直连后端，磁盘零缓存。代价是以下操作不可用：

• 文件不能同时以"读+写"打开；
• 以写打开的文件的不可 seek（随机定位写）；
• 以写方式打开已有文件必须带 O_TRUNC；
• 以读方式打开但带 O_TRUNC 的文件会被降级为只写；
• 只写打开的文件行为等同于带 O_TRUNC；
• O_APPEND、O_TRUNC 打开模式被忽略；
• 上传失败无法重试。

--vfs-cache-mode minimal：与 off 非常接近，唯一差别是"读+写"同时打开的文件会落到磁盘缓冲，写打开文件兼容性大幅提升、磁盘占用最小。仍受限的操作：

• 只写打开的文件不可 seek；
• 写打开已有文件必须带 O_TRUNC；
• 只写打开的文件忽略 O_APPEND、O_TRUNC；
• 上传失败无法重试。

--vfs-cache-mode writes：只读文件仍直连后端，而只写与读+写文件先缓冲到磁盘。此模式应支持所有常规文件系统操作。上传失败会以指数退避重试（最大间隔 1 分钟）。

--vfs-cache-mode full：所有读与写都经磁盘缓冲（从远端读的数据也落盘）。缓存中的文件是稀疏文件，rclone 会记录已下载的区间——若应用只读每个文件开头，缓存里就只有开头那部分数据（文件显示为完整大小，实际是只含已下载数据块的稀疏文件）。其余语义与 writes 相同，支持所有常规操作。读取时 rclone 会超前读取 --buffer-size（内存）加 --vfs-read-ahead（磁盘）字节；此模式下建议 --buffer-size 不要设过大、需要时把 --vfs-read-ahead 设大。

重要：并非所有文件系统支持稀疏文件，尤其 FAT/exFAT 不支持。若缓存目录所在文件系统不支持稀疏文件，rclone 性能会极差，并会在检测到时打印 ERROR 日志。

Fingerprinting（文件指纹）

VFS 多处依赖指纹判断本地缓存副本相对远端是否变化，指纹由以下属性组合：

• 大小（size）
• 修改时间（modtime）
• 哈希（hash）

其中可用才取。部分后端上某些属性读取昂贵（每对象多一次 API 调用或多余工作量）：例如 hash 在 local、sftp 后端要整文件读取并计算；modtime 在 s3、swift、ftp、qingstor 后端要多一次 API 调用。若使用 --vfs-fast-fingerprint，rclone 会将这类慢操作排除在指纹之外——精度降低但大幅加快缓存文件打开速度。在 local、s3、swift 后端之上跑 VFS 缓存时推荐开启。注意切换该 flag 会导致缓存内文件指纹失效、需要重新下载。

VFS Chunked Reading 分块读取

从远端读文件按块进行：只请求真正被读到的区间，可降低部分远端（按请求计费）的下载配额消耗，代价是请求次数增加。

    --vfs-read-chunk-size SizeSuffix        Read the source objects in chunks (default 128M)
    --vfs-read-chunk-size-limit SizeSuffix  Max chunk doubling size (default off)
    --vfs-read-chunk-streams int            The number of parallel streams to read at once

分块行为随 --vfs-read-chunk-streams 取值而不同。

--vfs-read-chunk-streams == 0

从 --vfs-read-chunk-size 起步，每次读取后翻倍块大小。当 --vfs-read-chunk-size-limit 大于初始块时，每个打开文件的块大小只翻倍到该上限为止；设为 off（默认）则不设上限、无限增长。

示例：--vfs-read-chunk-size 100M 且 --vfs-read-chunk-size-limit 0 时，依次下载 0-100M、100M-200M、200M-300M、300M-400M……；若设 --vfs-read-chunk-size-limit 500M，则变为 0-100M、100M-300M、300M-700M、700M-1200M、1200M-1700M……。把 --vfs-read-chunk-size 设为 0 或 off 即关闭分块读取。此模式的分块不驻留内存。

--vfs-read-chunk-streams > 0

同时并发读取 --vfs-read-chunk-streams 个大小为 --vfs-read-chunk-size 的块，每块大小保持恒定。该模式对高延迟链路或高带宽链路 + 高性能对象存储的提升非常显著。

最佳参数与后端及延迟强相关、需要实测：对 AWS S3 这类高性能对象存储，可从 --vfs-read-chunk-streams 16、--vfs-read-chunk-size 4M 起步（文档描述 S3 实测中吞吐大致随 streams 数线性增长）；高延迟链路也可套用类似设置，只是可能需要更多并发流才能吃满带宽。

VFS 性能调优 flag

    --no-checksum     Don't compare checksums on up/download.
    --no-modtime      Don't read/write the modification time (can speed things up).
    --no-seek         Don't allow seeking in files.
    --read-only       Only allow read-only access.

S3 与 Swift 后端尤其受益于 --no-modtime（或效果略异的 --use-server-modtime）——因为它们每次读取修改时间都要消耗一次事务。

乱序读写的处理：当应用乱序读写到达时，rclone 不立刻 seek，而是短等顺序读写到来（仅在不使用磁盘缓存文件时生效）：

    --vfs-read-wait duration   Time to wait for in-sequence read before seeking (default 20ms)
    --vfs-write-wait duration  Time to wait for in-sequence write before giving error (default 1s)

上传并发：当使用 writes/full 写缓存时，修改文件从缓存并行上传的数量由全局 flag --transfers 控制（默认 4；相关全局 flag --checkers 对 VFS 无影响）：

    --transfers int  Number of file transfers to run in parallel (default 4)

VFS 层符号链接支持

默认 VFS 不支持符号链接，可用下述 flag 开启：

    --links      Translate symlinks to/from regular files with a '.rclonelink' extension.
    --vfs-links  Translate symlinks to/from regular files with a '.rclonelink' extension for the VFS

多数云存储不直接支持符号链接，因此 rclone 把链接存成带特殊扩展名的普通文件：显示为符号链接的 link-to-file.txt 在云端实为 link-to-file.txt.rclonelink，文件内容是链接目标路径。差异在于作用范围：--links 全局开启（含 local 等支持符号链接的后端），--vfs-links 只作用于 VFS 层。此方案与 local 后端的 --local-links 兼容。--vfs-links 专为 rclone mount、rclone nfsmount、rclone serve nfs 设计，尚未在其他 serve 命令上充分测试。

当前实现限制：期望调用方自行解析子符号链接。例如如下目录树：

.
├── dir
│   └── file.txt
└── linked-dir -> dir

VFS 能正确解析 linked-dir，但不能解析 linked-dir/file.txt——对已测试的命令无碍，其它命令则可能受影响。另注：符号链接被移动进存在同名文件（或反之）的目录时可能产生重复文件，该已知问题见 rclone 仓库 issue #8245。

VFS 大小写与 Unicode 归一化

各平台文件系统大小写语义不同：Linux 区分大小写；现代 Windows 文件系统不区分但保留大小写（同目录不允许两个仅大小写不同的文件）；macOS 默认不区分大小写。

--vfs-case-insensitive 决定如何处理差异：

• false：文件名原样传给远端；
• true（或命令行只出现 flag 不写值）：执行"fixup"——当请求的文件名精确匹配不到、但存在仅大小写不同的同名文件时，rclone 透明地改用磁盘上实际存在的大小写版本。fixup 只在请求已存在文件时发生；新建文件的大小写语义由底层远端决定。

该 flag 缺省时的默认值取决于运行 rclone 的操作系统：Windows 与 macOS 为 true，其它平台为 false（flag 给出但不带值视为 true）。

--no-unicode-normalization 控制对"仅 Unicode 归一化不同（canonically equivalent）"文件名的同类 fixup。macOS 偏好 NFD、而多数平台用 NFC，因此强烈建议 macOS 用户保持默认 false 以免编码不兼容。

--vfs-block-norm-dupes：当目录在大小写+Unicode 归一化后仍存在多个重复文件名时，此 flag 可隐藏这些重复（有性能代价——列目录需整目录扫描找重复，建议非必需不开）。macOS 用户值得考虑开启：否则若远端目录同时存在某文件名的 NFC 与 NFD 版本，挂载点里会看到两个"看似都能编辑"的文件，实际编辑只会落到 NFD 那份上（类似 rclone sync 的处理，隐藏重复并记录错误日志）。

VFS 磁盘统计与 Used 空间

--vfs-disk-space-total-size 允许手动设定文件系统总空间统计（示例：256G，默认 -1），用于文件系统统计无法被自动正确读取的场景。

部分后端（最典型的是 S3）不报告已用字节数。如需在 df 中看到真实用量，加 --vfs-used-is-size：此时 rclone 不再依赖后端汇报，而是像 rclone size 一样全量扫描远端自行计算。

警告：与 rclone size 不同，该模式忽略过滤器以保证结果准确，因此非常低效且可能产生大量 API 调用、带来额外费用。请作为最后手段使用并务必配合缓存。

VFS Metadata 扩展文件

--vfs-metadata-extension 可让 VFS 以 JSON blob 文件的形式暴露对象的 metadata（元数据）。这些文件初始不出现在目录列表中，但可以被 stat、被打开，一旦打开过它们就会出现在目录列表里，直到目录缓存过期。注意部分后端只有传入 --metadata 才会产出元数据。

示例：rclone mount 配合 --metadata --vfs-metadata-extension .metadata 时——

$ ls -l /mnt/
total 1048577
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G

$ cat /mnt/1G.metadata
{
        "atime": "2025-03-04T17:34:22.317069787Z",
        "btime": "2025-03-03T16:03:37.708253808Z",
        "gid": "1000",
        "mode": "100664",
        "mtime": "2025-03-03T16:03:39.640238323Z",
        "uid": "1000"
}

$ ls -l /mnt/
total 1048578
-rw-rw-r-- 1 user user 1073741824 Mar  3 16:03 1G
-rw-rw-r-- 1 user user        185 Mar  3 16:03 1G.metadata

文件无元数据时返回 {}；读取元数据出错时以 {"error":"error string"} 形式返回。

命令完整 Options

      --addr stringArray                       IPaddress:Port or :Port to bind server to (default 127.0.0.1:8080)
      --allow-origin string                    Origin which cross-domain request (CORS) can be executed from
      --auth-proxy string                      A program to use to create the backend from the auth
      --baseurl string                         Prefix for URLs - leave blank for root
      --cert string                            TLS PEM key (concatenation of certificate and CA certificate)
      --client-ca string                       Client certificate authority to verify clients with
      --dir-cache-time Duration                Time to cache directory entries for (default 5m0s)
      --dir-perms FileMode                     Directory permissions (default 777)
      --disable-dir-list                       Disable HTML directory list on GET request for a directory
      --disable-zip                            Disable zip download of directories
      --etag-hash string                       Which hash to use for the ETag, or auto or blank for off
      --file-perms FileMode                    File permissions (default 666)
      --gid uint32                             Override the gid field set by the filesystem (not supported on Windows) (default 1000)
  -h, --help                                   help for webdav
      --htpasswd string                        A htpasswd file - if not provided no authentication is done
      --key string                             TLS PEM Private key
      --link-perms FileMode                    Link permissions (default 666)
      --max-header-bytes int                   Maximum size of request header (default 4096)
      --min-tls-version string                 Minimum TLS version that is acceptable (default "tls1.0")
      --no-checksum                            Don't compare checksums on up/download
      --no-modtime                             Don't read/write the modification time (can speed things up)
      --no-seek                                Don't allow seeking in files
      --pass string                            Password for authentication
      --poll-interval Duration                 Time to wait between polling for changes, must be smaller than dir-cache-time and only on supported remotes (set 0 to disable) (default 1m0s)
      --read-only                              Only allow read-only access
      --realm string                           Realm for authentication
      --response-header stringArray            Set HTTP header for all responses, overriding existing values
      --salt string                            Password hashing salt (default "dlPL2MqE")
      --server-read-timeout Duration           Timeout for server reading data (default 1h0m0s)
      --server-write-timeout Duration          Timeout for server writing data (default 1h0m0s)
      --template string                        User-specified template
      --uid uint32                             Override the uid field set by the filesystem (not supported on Windows) (default 1000)
      --umask FileMode                         Override the permission bits set by the filesystem (not supported on Windows) (default 002)
      --user string                            User name for authentication
      --user-from-header string                User name from a defined HTTP header
      --vfs-block-norm-dupes                   If duplicate filenames exist in the same directory (after normalization), log an error and hide the duplicates (may have a performance cost)
      --vfs-cache-max-age Duration             Max time since last access of objects in the cache (default 1h0m0s)
      --vfs-cache-max-size SizeSuffix          Max total size of objects in the cache (default off)
      --vfs-cache-min-free-space SizeSuffix    Target minimum free space on the disk containing the cache (default off)
      --vfs-cache-mode CacheMode               Cache mode off|minimal|writes|full (default off)
      --vfs-cache-poll-interval Duration       Interval to poll the cache for stale objects (default 1m0s)
      --vfs-case-insensitive                   If a file name not found, find a case insensitive match
      --vfs-disk-space-total-size SizeSuffix   Specify the total space of disk (default off)
      --vfs-fast-fingerprint                   Use fast (less accurate) fingerprints for change detection
      --vfs-handle-caching Duration            Time to keep file handle and downloaders alive after last close (default 5s)
      --vfs-links                              Translate symlinks to/from regular files with a '.rclonelink' extension for the VFS
      --vfs-metadata-extension string          Set the extension to read metadata from
      --vfs-read-ahead SizeSuffix              Extra read ahead over --buffer-size when using cache-mode full
      --vfs-read-chunk-size SizeSuffix         Read the source objects in chunks (default 128Mi)
      --vfs-read-chunk-size-limit SizeSuffix   If greater than --vfs-read-chunk-size, double the chunk size after each chunk read, until the limit is reached ('off' is unlimited) (default off)
      --vfs-read-chunk-streams int             The number of parallel streams to read at once
      --vfs-read-wait duration                 Time to wait for in-sequence read before seeking (default 20ms)
      --vfs-refresh                            Refreshes the directory cache recursively in the background on start
      --vfs-used-is-size rclone size           Use the rclone size algorithm for Used size
      --vfs-write-back duration                Time to writeback files after last use when using cache (default 5s)

以上 flag 的权威定义来自源码选项注册表 OptionsInfo（协议相关项）+ vfsflags 注册的 VFS 项；--dir-perms/--file-perms/--link-perms/--uid/--gid/--umask 等权限类选项在 Windows 上不生效。未被此处列出的全局选项见 global flags 页面。

Filter Options（目录过滤）

适用于目录列表的过滤 flag：

      --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 filter 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)

完整过滤语法可参考 filtering 文档。该命令在命令分组上标注为 "Filter" 组（webdav.go）。

端到端验证：一条龙自测

webdav_test.go 展示了最贴近实战的自测闭环：以 localhost:0（随机端口）启动服务器，配置 BaseURL=/prefix、Basic 用户 user/pass、模板与 --etag-hash MD5，然后构造一个 type=webdav、vendor=rclone 的配置（URL 取服务器实际地址、密码用 obscure.MustObscure 加密），再交给 servetest.Run 跑 WebDAV 后端的全套一致性测试。日常可用更轻量的方式验证：rclone lsf/rclone mount 之外的 rclone ls、rclone copy 均可直接以 :webdav: 为远端配合 --webdav-url 指向本服务做冒烟测试。

See Also

• rclone serve —— serve 协议族父命令（含 dlna/ftp/http/nfs/restic/s3/sftp/webdav 等全部子命令入口）。
• 如需让 rclone 作为 WebDAV 协议客户端访问本服务或第三方 WebDAV 服务，参见 WebDAV 后端文档。