以下是基于 dufs 搭建 WebDAV 服务的详细教程，涵盖安装、配置、权限设置及客户端连接等关键步骤：

* * *

### 一、安装 dufs

#### 1\. **Docker 部署（推荐）**

```bash
docker run -d \
  --name dufs-webdav \
  -p 5000:5000 \
  -v /本地目录路径:/data \
  sigoden/dufs:latest \
  /data --allow-all --auth "user:password@/:rw"
```

- **参数说明**：
    - `-p 5000:5000`：映射容器端口到宿主机。
    - `-v /本地目录路径:/data`：将本地目录挂载到容器内 `/data`，作为文件存储路径。
    - `--allow-all`：允许所有操作（上传、删除、搜索等）。
    - `--auth "user:password@/:rw"`：设置用户名/密码，`rw` 表示读写权限，`ro` 为只读[1](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")[11](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")[34](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")。

#### 2\. **二进制安装**

- 从 [GitHub Releases](https://github.com/sigoden/dufs/releases) 下载对应系统的可执行文件。
- 启动命令示例：
    
    ```bash
    ./dufs /data -p 5000 --allow-all --auth "user:password@/:rw"
    ```
    
- 支持参数：`-p`（端口）、`--allow-upload`（仅允许上传）、`--auth`（认证）等[11](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")[16](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")[79](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")。

* * *

### 二、WebDAV 服务配置

#### 1\. **基础配置**

- **启用 WebDAV**：dufs 默认支持 WebDAV，无需额外配置，直接通过端口访问。
- **HTTPS 支持**（可选）：
    
    ```bash
    --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem
    ```
    
    需提供 SSL 证书和密钥路径[79](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")[34](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")。

#### 2\. **权限控制**

- **路径级权限**：通过 `--auth` 参数指定不同路径的权限，例如：
    
    ```bash
    --auth "user1:pass1@/public:ro, /private:rw"
    ```
    
    表示 `/public` 目录只读，`/private` 目录可读写[79](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")[22](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")。

#### 3\. **隐藏文件/目录**

- 使用 `--hidden` 参数隐藏特定文件（如临时文件）：
    
    ```bash
    --hidden "*.tmp,logs/"
    ```[79](@ref)
    
    ```
    

* * *

### 三、客户端连接 WebDAV

#### 1\. **Windows 客户端**

1.  打开“此电脑” → 右键选择“添加一个网络位置”。
2.  输入地址：`http://服务器IP:5000`。
3.  输入用户名和密码（与 `--auth` 参数一致）。

#### 2\. **Mac/Linux**

- 使用命令行工具 `curl` 或 `davfs2` 挂载：
    
    ```bash
    sudo mount -t davfs http://服务器IP:5000 /mnt/dufs
    ```
    

#### 3\. **第三方工具（如 RaiDrive、Cyberduck）**

- 选择 WebDAV 协议，填写服务器地址、端口、账号密码即可[34](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")[42](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")。

* * *

### 四、常见问题排查

1.  **端口冲突**：若默认端口 5000 被占用，使用 `-p 新端口:5000` 修改。
2.  **权限不足**：确保挂载的本地目录有读写权限（Linux/Mac 使用 `chmod` 调整）。
3.  **认证失败**：检查 `--auth` 参数格式是否正确，避免特殊字符（如 `@` 需转义）。
4.  **HTTPS 证书错误**：自签证书需在客户端导入信任[34](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")[79](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")。

* * *

### 五、高级功能扩展

- **静态网站托管**：添加 `--render-index` 参数，目录中放置 `index.html` 文件即可[11](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")[16](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")。
- **API 调用**：通过 `curl` 上传/下载文件：
    
    ```bash
    # 上传文件
    curl -T 本地文件路径 http://服务器IP:5000/目标路径 -u user:password
    # 下载文件
    curl -O http://服务器IP:5000/文件路径 -u user:password
    ```[11](@ref)[79](@ref)
    
    ```
    

* * *

通过上述步骤，可快速搭建一个支持 WebDAV 的 dufs 文件服务器。如需更复杂的配置（如多用户分级权限），可参考 [官方文档](https://github.com/sigoden/dufs) 或结合 Nginx 反向代理实现负载均衡[34](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")[79](/C:/Program%20Files/Joplin/resources/app.asar/@ref "@ref")。

以下是一个详细的 `dufs` 配置文件示例（YAML/TOML 格式），结合注释解释每个配置项的作用，帮助您快速搭建 WebDAV 服务：

* * *

### 六、配置文件示例（`dufs-config.yml`）

```yaml
# dufs 配置文件示例（YAML 格式）

# 监听地址与端口
port: 5000
host: 0.0.0.0  # 允许所有IP访问（默认localhost）

# WebDAV 基础设置
webdav: true    # 启用WebDAV支持（默认true）

# 认证与权限
auth:
  - path: /              # 控制根目录权限
    user: admin          # 用户名
    password: "123456"   # 密码（建议使用环境变量替代明文）
    permissions: rw      # 读写权限（ro=只读）
  - path: /public        # 子目录权限
    user: guest
    password: "guest123"
    permissions: ro

# 访问控制
access_control:
  allow_upload: true     # 允许上传
  allow_delete: true     # 允许删除
  allow_search: true     # 允许搜索文件
  hidden: ["*.tmp", ".DS_Store"]  # 隐藏指定文件/目录

# TLS/HTTPS 加密（可选）
tls:
  cert: /path/to/cert.pem  # SSL证书路径
  key: /path/to/key.pem    # SSL私钥路径

# 静态文件托管（可选）
render_index: true       # 启用目录索引（显示index.html）
```

* * *

### 配置文件解析

#### 1\. **监听设置**

- `port`: WebDAV 服务监听的端口（默认 `5000`）。
- `host`: 绑定 IP 地址，`0.0.0.0` 允许外部访问，`127.0.0.1` 仅限本机。

#### 2\. **WebDAV 支持**

- `webdav: true`: 必须启用 WebDAV 才能通过客户端连接。

#### 3\. **认证与权限**

- `auth`: 定义不同路径的访问权限：
    - `path`: 受控目录路径（如 `/` 表示根目录）。
    - `user`/`password`: 认证信息（密码建议通过环境变量注入）。
    - `permissions`: `rw`（读写）或 `ro`（只读）。

#### 4\. **访问控制**

- `allow_upload`/`allow_delete`: 控制文件操作权限。
- `hidden`: 隐藏特定文件（支持通配符 `*`）。

#### 5\. **HTTPS 加密**

- `tls`: 配置 SSL 证书和私钥路径，启用 HTTPS（需有效证书）。

#### 6\. **静态网站**

- `render_index: true`: 自动渲染目录中的 `index.html`。

* * *

### 使用配置文件启动服务

#### 方式 1：直接运行二进制

```bash
dufs --config dufs-config.yml
```

#### 方式 2：Docker 部署

```bash
docker run -d \
  -p 5000:5000 \
  -v /本地目录:/data \
  -v $(pwd)/dufs-config.yml:/app/config.yml \  # 挂载配置文件
  sigoden/dufs \
  --config /app/config.yml
```

* * *

### 进阶配置示例

#### 多用户权限分层

```yaml
auth:
  - path: /
    user: admin
    password: "admin@2023"
    permissions: rw
  - path: /projects
    user: dev
    password: "dev-secret"
    permissions: rw
  - path: /public
    user: anonymous
    password: ""
    permissions: ro
```

#### 环境变量注入密码（更安全）

```bash
# 通过环境变量传递敏感信息
export DUF_ADMIN_PASS="secure-password"

# 启动命令中引用环境变量
dufs --auth "admin:${DUF_ADMIN_PASS}@/:rw"
```

* * *

### 客户端连接验证

使用 **RaiDrive** 或 **Cyberduck** 测试：

- 协议: `WebDAV` 或 `WebDAV HTTPS`
- 地址: `http://your-ip:5000` 或 `https://your-domain:5000`
- 账号/密码: 与配置文件中的 `auth` 部分一致。

* * *

### 常见问题

#### 1\. 配置文件路径错误

- 确保 Docker 容器内路径与挂载路径一致（使用 `-v` 正确映射）。

#### 2\. 权限冲突

- 本地目录权限需与容器用户匹配（Linux 建议 `chmod 755 /本地目录`）。

#### 3\. HTTPS 证书无效

- 自签证书需在客户端手动信任，或使用 Let's Encrypt 免费证书。

* * *

通过配置文件，您可以灵活管理复杂的权限规则和功能组合。如需更多高级选项（如日志级别、CORS 等），可参考 [官方文档](https://github.com/sigoden/dufs)。