Go 语言 WebDAV 服务器:hacdias/webdav 完整指南
一个用 Go 编写的轻量级、跨平台、单文件的 WebDAV 服务器
一、什么是 WebDAV?
WebDAV(Web Distributed Authoring and Versioning)是 HTTP 协议的扩展,允许客户端像操作本地文件系统一样对远程服务器上的文件进行增、删、改、查、移动、复制等操作。
它最大的价值在于跨平台文件共享:
- Windows 资源管理器可以直接”映射网络驱动器”
- macOS Finder 可以”连接到服务器”
- iOS/Android 各类 App(如 Documents、nPlayer、Fileball)都原生支持
- 各类同步工具(rclone、Cyberduck)也都能对接
而 hacdias/webdav 正是在这个场景下非常出色的一个开源实现。
二、项目简介
hacdias/webdav 是用 Go 语言编写的 WebDAV 服务器,作者是 Henrique Dias。它以一个单一可执行二进制文件的形式发布,零依赖、开箱即用,非常适合个人搭建私有文件服务。
核心特点
| 特性 | 说明 |
|---|---|
| 🚀 单文件部署 | 编译后只有一个二进制文件,无需任何运行时依赖 |
| 🗂️ 跨平台 | Linux / Windows / macOS / FreeBSD 全覆盖(含 ARM 架构) |
| 🔐 认证支持 | 内置 Basic Auth,支持多用户与密码哈希 |
| 🌐 TLS/HTTPS | 支持原生证书与 Let’s Encrypt 自动签发 |
| 👥 多用户与权限 | 可配置多个账户,独立目录、独立权限 |
| 📁 权限控制 | 支持读、写、目录列表、相对路径等细粒度开关 |
| 🧩 CORS 支持 | 方便前后端分离的 Web 应用对接 |
| ⚙️ YAML 配置 | 配置清晰、人类可读 |
| 📊 日志与代理 | 内置日志,支持反向代理头处理 |
它本质上是基于 golang.org/x/net/webdav 包的封装与管理层,把复杂的配置、权限、认证都做成了易用的方案。
三、快速上手
1. 安装方式
方式一:直接下载二进制
从 Releases 下载对应平台的二进制即可。
方式二:使用 Go 安装
go install github.com/hacdias/webdav/v5@latest
方式三:Docker
docker run -p 6065:6065 \ -v /path/to/data:/data \ -v /path/to/config.yml:/config.yml \ ghcr.io/hacdias/webdav -c /config.yml
方式四:包管理器
- macOS:
brew install webdav - Arch Linux:
yay -S webdav
2. 最小配置
创建 config.yaml:
address: 0.0.0.0
port: 6065
directory: /var/webdav
users:
- username: admin
password: admin123
启动:
webdav --config config.yaml
访问 http://localhost:6065 即可。
四、配置详解
hacdias/webdav 的配置文件采用 YAML 格式,功能项覆盖得相当全面。下面列几个常用的配置项。
全局配置
# 监听地址与端口
address: 0.0.0.0
port: 6065
# WebDAV 根目录(默认 ./data)
directory: /var/webdav
# 是否允许修改(全局开关)
modify: true
# 日志级别:error / info / debug
log:
format: console # console 或 json
level: info
# 是否信任反向代理的 X-Forwarded-* 头
# 部署在 Nginx/Caddy 后建议设为 true
behindProxy: false
# 是否启用 CORS
cors:
enabled: true
allowed_headers:
- Authorization
allowed_hosts:
- https://example.com
# TLS 支持
tls: false
cert: cert.pem
key: key.pem
# Let's Encrypt 自动证书
# tls: true
# cert: /path/to/cache
用户级配置
每个用户都可以拥有自己独立的目录与权限:
users:
- username: admin
password: admin # 明文密码
directory: /data/admin
scope: / # 限定访问子路径,如 /home
modify: true # 是否允许写
rules: "" # 规则文件(可选)
- username: reader
# 密码支持 bcrypt 哈希,避免明文
password: "$2y$10$..."
directory: /data/readonly
modify: false
permissions: R # R = 只读;CRUD 全部权限
- username: guest
directory: /data/public
permissions: R
权限说明
| 权限 | 含义 |
|---|---|
R |
Read(读取) |
C |
Create(新建) |
U |
Update(修改) |
D |
Delete(删除) |
组合写法如 RU、CRUD,若不指定则默认允许全部。
生成 bcrypt 密码
推荐使用哈希密码而非明文。可用 htpasswd 生成:
htpasswd -bnBC 10 "" yourpassword | tr -d ':\n'
或者在 Go 代码里:
import "golang.org/x/crypto/bcrypt"
hash, _ := bcrypt.GenerateFromPassword([]byte("yourpassword"), bcrypt.DefaultCost)
五、实践场景
场景一:家庭 NAS 共享
在家用树莓派或旧电脑上跑一个 Docker 容器即可:
version: '3'
services:
webdav:
image: ghcr.io/hacdias/webdav:latest
restart: always
ports:
- 6065:6065
volumes:
- ./data:/data
- ./config.yaml:/config.yaml
command: -c /config.yaml
Windows 资源管理器里”映射网络驱动器”,填 http://你的IP:6065 就能用,就像操作本地硬盘一样。
场景二:反向代理 + HTTPS
生产环境强烈建议放在 Caddy 或 Nginx 后面,自动获得 HTTPS:
Caddy 示例:
files.example.com {
reverse_proxy localhost:6065
}
同时要在配置里开启 behindProxy: true,否则 WebDAV 的 Location 重定向可能出错。
场景三:多用户隔离
一机多用户,各自目录独立、权限独立:
address: 0.0.0.0
port: 6065
directory: /data
users:
- username: alice
password: "xxx"
directory: /data/alice
permissions: CRUD
- username: bob
password: "yyy"
directory: /data/bob
permissions: CRUD
- username: guest
password: "guest"
directory: /data/public
permissions: R
场景四:与 rclone 结合
rclone 直接支持 WebDAV 协议,一条命令就能挂载:
rclone config # 选择 webdav,填入地址、用户名、密码后 # 挂载到本地目录 rclone mount mywebdav: /mnt/webdav --vfs-cache-mode writes
配合 rclone 你还可以轻松实现与 S3、Google Drive、OneDrive 之间的同步。
六、源码结构一览
对于想了解内部实现或做二次开发的开发者,可以快速浏览下源码结构。项目本身相当精简:
. ├── main.go # 入口,处理 flag 与配置加载 ├── cmd/ # 命令与配置解析 │ ├── config.go # 配置结构体定义 │ └── ... ├── lib/ # 核心逻辑 │ ├── handler.go # WebDAV handler 封装、认证拦截 │ ├── rule.go # 规则引擎 │ └── ... └── ...
核心思路:
main.go解析-c参数,读取 YAMLcmd.Config反序列化配置- 根据用户配置构造若干个
webdav.Handler(每个用户一份) - 通过自定义
http.Handler做认证拦截,按用户选择对应的Handler golang.org/x/net/webdav提供了底层 WebDAV 协议实现(FileSystem+LockSystem)
其中特别值得注意的是规则引擎:可以在配置里针对路径、方法、用户设定允许或拒绝的规则,实现比”全局读写开关”更细的控制。这在团队协作或半公开共享时会非常有用。
七、优点与局限
优点
- ✅ 极简:单个二进制文件,部署成本极低
- ✅ 安全渐进:支持 bcrypt 哈希密码、HTTPS、权限控制
- ✅ 协议标准:基于官方
x/net/webdav,兼容性可靠 - ✅ 活跃维护:作者持续更新,社区生态完善
- ✅ 容器友好:有官方 Docker 镜像
局限
- ⚠️ 无 Web 界面:纯 WebDAV 后端,不能直接在浏览器里浏览(需要搭配第三方 UI 或用系统客户端)
- ⚠️ 单机为主:没有分布式或多节点方案,文件存在本地
- ⚠️ 无版本控制:不具备快照、版本历史等高级功能
- ⚠️ 规则引擎相对复杂:进阶配置有一定学习曲线
八、一些实用建议
- 生产环境务必使用 HTTPS:WebDAV 传输密码和文件,明文 HTTP 风险极大
- 用 bcrypt 哈希密码,避免配置文件泄露导致密码裸奔
- 反向代理记得开
behindProxy,不然重定向 URL 会指向内网地址 - 限制
directory不要覆盖系统重要目录 - 给访客账户用
R权限,防止被意外写入或删除 - 搭配 rclone / Restic / Duplicati 等工具,可以做自动化备份、跨云同步
九、总结
hacdias/webdav 用极简的方式把”构建一个可靠 WebDAV 服务器”这件事做到了极致——一个二进制文件,一份 YAML 配置,就能在几分钟内搭建起一个功能完整、可控可管的私有文件服务。
对于想摆脱公共网盘、搭建私有云盘、做跨设备文件同步的开发者来说,它是一个非常值得考虑的选择。而对于 Go 开发者来说,它的源码也是学习”如何用 Go 写一个生产级的 HTTP 服务”的优秀范例——代码精简、职责清晰、封装得当。
参考链接:
- 项目主页:https://github.com/hacdias/webdav
- 官方文档:https://github.com/hacdias/webdav#readme
x/net/webdav:https://pkg.go.dev/golang.org/x/net/webdav- rclone WebDAV:https://rclone.org/webdav/



还没有评论,来说两句吧...