webdav 轻量级 WebDAV 服务器：从安装到生产部署的完整路径-开发者社区

webdav 轻量级 WebDAV 服务器：从安装到生产部署的完整路径

【免费下载链接】webdavA simple and standalone WebDAV server.项目地址: https://gitcode.com/gh_mirrors/we/webdav

webdav 是一个用 Go 编写的轻量级 WebDAV 服务器，编译后就是一个独立二进制文件，没有依赖数据库，也无需其他运行时。它解决的问题很直接：把一个目录通过 WebDAV 协议暴露出去，配合 Basic 认证和 CRUD 权限规则，让 Windows、macOS、Linux 甚至手机上的文件管理器都能直接挂载使用。适合个人同步、小团队共享、Android 备份这类不需要重型文件系统的场景。

适用场景：什么时候该用 webdav

先判断它是否匹配你的需求，再动手部署：

私有文件同步：在多台机器之间映射网络驱动器，不依赖云盘服务；
Android 设备备份：搭配 SeedVault 这类应用，用 WebDAV 作为备份目标，仓库 README 中专门给出了对应的用户配置示例；
办公文档共享：给不同成员分配不同目录与权限，最小配置就能落地；
轻量自动化：webdav 还支持兼容 SabreDAV 的PATCH局部更新扩展，请求使用application/x-sabredav-partialupdate内容类型并携带X-Update-Range（支持bytes=start-end、bytes=start-、bytes=-N、append等取值），适合大文件断点式写入的客户端约定。

它不适合需要复杂审计、版本管理或高并发公网服务的场景，这类需求应选专业文件服务器。

快速开始：三种安装方式与最小配置

装好二进制后，一条命令加一个配置文件即可启动。默认监听0.0.0.0:6065，默认只读权限（R）。

方式一：Go 工具链

go install github.com/hacdias/webdav/v5@latest

方式二：Homebrew（macOS/Linux）

brew install webdav

方式三：Docker 镜像

docker pull ghcr.io/hacdias/webdav:latest # 或 docker pull hacdias/webdav:latest

Docker 的最小运行命令如下，配置文件以只读方式挂入：

docker run \ -p 6065:6065 \ -v ./config.yml:/config.yml:ro \ -v ./data:/data \ ghcr.io/hacdias/webdav -c /config.yml

最小可用配置config.yml：

address: 0.0.0.0 port: 6065 directory: /data permissions: R users: - username: admin password: admin

注意一个容易踩坑的行为：配置中只要定义了users，Basic 认证就会自动启用；不定义任何用户，服务器是完全匿名的。内网试用可以接受，公网部署务必加上用户。

命令行还常用这些参数：-c指定配置文件，-a监听地址，-p端口，-t开启 TLS，--cert/--key指定证书，-P设置 URL 前缀。所有参数也可以用WD_前缀的环境变量覆盖，例如WD_CERT。不带-c时，程序会在当前目录和/etc/webdav/下查找config.yml（也支持 JSON、TOML）。

关键配置：目录、认证与最小权限规则

这一节解决"谁能读写哪些文件"。权限由四个字母组成：C（创建）、R（读）、U（更新）、D（删除），可自由组合，如RC、CRUD。

给不同角色划目录：每个用户可以用directory指定自己的根目录，超出范围不可见。团队文档共享可以这样分层：

users: - username: manager password: "{env}MANAGER_PASSWORD" permissions: CRUD directory: /data/team - username: developer password: "{env}DEV_PASSWORD" permissions: RU directory: /data/dev

密码支持三种写法：明文、{bcrypt}$2y$...哈希（用内置命令webdav bcrypt生成），以及{env}变量名从环境变量读取。生产环境建议后两者，避免密码进配置文件版本库。

用 rules 做路径级控制：全局权限之外的精细控制靠规则，每条规则二选一——按path前缀匹配或按regex正则匹配，相对路径以用户目录为起点：

permissions: R rules: - path: /confidential permissions: none - path: /public/access/ permissions: CRUD - regex: "^.+.pdf$" permissions: RU

两个必须知道的行为细节：

规则从最后一条往前匹配，命中的第一条规则即生效，所以把更具体的规则写在后面；
permissions: none表示显式拒绝，比"不给权限"更可靠，适合封禁敏感目录。

用户自己定义了 rules 时，行为由rulesBehavior决定：overwrite（默认，全局规则对该用户不生效）或append（用户规则优先检查，再回落到全局规则）。

多目录挂载：把单个directory换成directories，可以把多个不相干的目录虚拟挂载为一个根下的多个入口（directory与directories不可同时使用）：

directories: - media: /data/media - /data/archive - name: backups path: /data/backups

生产部署：TLS、反向代理与防暴力破解

TLS 直接终结在 webdav 上：配置tls: true并指定cert/key文件路径即可，也可以交给前置代理做 HTTPS。

Nginx 反向代理的两个关键点：一是必须转发X-Real-IP、X-Forwarded-For、Host等头，否则容易出现 502；二是COPY/MOVE操作依赖Destination头，而客户端通常会带上完整 URL（含域名），需要在代理层剥掉域名只留路径，否则搬运会失败：

location / { proxy_pass http://127.0.0.1:6065; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; set $dest $http_destination; if ($http_destination ~ "^https://example.com(?<path>(.+))") { set $dest /$path; } proxy_set_header Destination $dest; }

Caddy 则可用header_regexp匹配dest头并重写Destination，思路相同。如果代理在中间，记得把behindProxy设为true，让日志按X-Forwarded-For记录真实客户端地址。

systemd 服务化，实现开机自启与崩溃重启：

[Unit] Description=WebDAV After=network.target [Service] Type=simple User=root ExecStart=/usr/bin/webdav --config /opt/webdav.yml Restart=on-failure [Install] WantedBy=multi-user.target

Fail2Ban 防暴力破解：webdav 的日志中会输出invalid password/invalid username记录（JSON 格式含remote_address字段），可据此写过滤器。在filter.d/webdav.conf中匹配这两类记录并提取<HOST>，再在jail.d/webdav.conf里配置对应端口与日志路径；Docker 部署时建议加--log-driver journald --name webdav，jail 中用journalmatch = CONTAINER_NAME=webdav代替文件路径。

另外，log.format可切到json便于机器采集，log.outputs支持多个输出目标。

常见问题与排查思路

按出现频率排序：

现象	原因	处理
连接后全部 405/403	默认权限是`R`，只读	配置`permissions: CRUD`或按目录放宽 rules
反向代理后 COPY/MOVE 报错	`Destination`头带域名未处理	参照上文 Nginx 重写逻辑
公网出现 502	代理层请求头不完整	补全`X-Real-IP`、`Host`等转发头
没有认证、目录裸奔	配置里没写`users`	至少定义一个用户启用 Basic 认证
规则"不生效"	规则从后往前匹配	检查书写顺序，具体规则放后面
大文件写入失败	客户端未走局部更新	确认使用`X-Update-Range`协商，见仓库 README 的 Partial updates 一节