# Caddy WebDAV 配置：子路径挂载与权限控制


## WebDAV 是什么

WebDAV（Web Distributed Authoring and Versioning）是 HTTP 协议的扩展，允许客户端通过 HTTP 协议进行文件的上传、下载、删除、移动、复制等操作。简单理解：**通过 HTTP 挂载远程文件系统**。

在 KDE Dolphin、Windows 资源管理器、macOS Finder 中可以直接挂载 WebDAV 作为网络驱动器，不需要安装额外客户端。

## 插件安装

`caddy-webdav` 插件已在自定义构建中包含。WebDAV 需要和 `file_server` 共存，所以要调整路由优先级，在全局配置中添加：

```caddyfile
{
    order webdav before file_server
}
```

这告诉 Caddy：在处理请求时，优先让 `webdav` 指令处理，处理不了的再交给 `file_server`。如果不加这行，`file_server` 会优先拦截所有请求，WebDAV 的 PROPFIND、MKCOL 等方法永远不会被触发。

## 基础配置

```caddyfile
test.example.com {
    route {
        reverse_proxy 127.0.0.1:5002
    }

    route /dav/* {
        basic_auth {
            username xxx
        }
        webdav {
            root /path/to/webdav_dir
            prefix /dav
        }
    }
}
```

### 配置分析

**`route` 块**：使用 `route` 而不是直接在站点块中声明，是为了控制指令的执行顺序。站点主服务（`reverse_proxy`）和 WebDAV 使用不同的 `route` 块，互不干扰。

**`/dav/*` 路径匹配**：WebDAV 功能只在 `/dav/` 路径下生效，不影响主站点的漫画阅读功能。用户访问 `https://test.example.com/` 看到的是漫画阅读器，访问 `https://test.example.com/dav/` 则是文件管理界面。

**`basic_auth`**：WebDAV 暴露了文件系统的读写能力，必须加上认证。这里用 Caddy 内置的 `basic_auth` 配合 bcrypt 密码哈希。

**`webdav` 配置**：

- `root`：WebDAV 暴露的文件系统根目录，这里是 webdav 的数据目录
- `prefix`：告诉 WebDAV 处理器，URL 中的 `/dav` 前缀对应的实际路径是根目录。当客户端请求 `/dav/test.txt` 时，实际访问的是 `/path/to/webdav_dir/test.txt`

## 生成 bcrypt 密码

`basic_auth` 需要 bcrypt 格式的密码哈希。Caddy 自带 `caddy hash-password` 命令：

```bash
caddy hash-password --plaintext "你的密码"

# 输出类似：
# $2a$14$...（示例哈希，请用 caddy hash-password 生成）
```

Caddy 的 bcrypt 使用的是 cost 14（迭代 2^14 次），比默认的 10 更慢但更安全。生成的哈希可以直接复制到 Caddyfile 中。

## 注意事项

### 权限控制

`basic_auth` 在 Caddy 中是站点级别的——一个用户验证通过后可以访问所有受保护的路径。Caddy 本身不提供细粒度的文件权限控制。当然如果用户比较固定，可以通过如下配置按用户隔离 webdav 根目录：

```caddyfile
test.example.com {
    route {
        reverse_proxy 127.0.0.1:5002
    }

    route /dav/* {
        basic_auth {
            user1 pass1
            user2 pass2
        }
        webdav {
            root /path/to/webdav_dir/{http.auth.user.id}
            prefix /dav
        }
    }
}
```

### 上传大小限制

WebDAV 上传大文件时，确保 Caddy 的 `request_body` 限制足够大：

```caddyfile
webdav.example.com {
    request_body {
        max_size 10000MB
    }
    webdav {
        root /srv/data
    }
}
```

Caddy 默认的请求体限制是 10MB，上传大文件时会出现 413 Request Entity Too Large 错误。

### HTTPS 必须

WebDAV 传输文件包含认证信息，必须使用 HTTPS。如果你用的是 Caddy，HTTPS 是默认行为，不需要额外配置。

## 参考链接

- [mholt/caddy-webdav](https://github.com/mholt/caddy-webdav)
- [Caddy order 指令](https://caddyserver.com/docs/caddyfile/options#order)
- [Caddy basic_auth](https://caddyserver.com/docs/caddyfile/directives/basic_auth)
- [xcaddy 构建自定义 Caddy](/posts/custom-caddy-build/)


---

> 作者: Nite  
> URL: https://www.nite07.com/zh-cn/posts/caddy-webdav/