Dufs 保姆级部署教程：一条命令起文件服务器的轻量级自托管工具

Dufs（仓库 sigoden/dufs，Rust 编写，Star 数约 1.1 万）是一个"与众不同"的实用型文件服务器：支持静态文件服务、上传下载、搜索、访问控制、WebDAV、HTTPS，整个服务只有一个二进制文件，docker run 一行命令就能起一个可以浏览、上传、删除、在线编辑文件的 Web 界面。它和本站写过的 Alist（多存储聚合网盘）定位不同——Dufs 不做聚合，专注把服务器上的一个目录干净利落地变成可用的文件站，适合个人网盘、内网文件共享、开发环境静态资源托管等场景。

一、项目介绍与适用场景

Dufs 官方定位："a distinctive utility file server"。它把"文件服务器"这件事做到极简：默认服务当前目录，-A 放开全部操作，-a 做精细的账号权限控制，--render-spa 直接托管前端单页应用。因为核心是单文件 Rust 程序，内存占用极小，部署形态灵活——Docker、cargo、Homebrew、官方预编译二进制（Linux/macOS/Windows）全都支持。

适用场景：个人/家庭文件共享、团队内网临时传文件、服务器静态资源目录、给 SPA 前端做文件托管、用 WebDAV 挂载远程目录、给自动化脚本提供一个简单的上传/下载端点等。

二、核心功能逐条拆解

1. 静态文件服务：默认只读模式直接浏览目录，支持 ?simple（仅文件名输出，类似 ls -1）与 ?json（JSON 路径列表）两种视图，方便脚本消费。
2. 上传/下载：浏览器拖拽上传文件与文件夹；curl -T 命令行上传；支持断点续传（curl -C-）与分段续传（X-Update-Range: append）。
3. 文件夹打包下载：请求 ?zip 即可把整个目录打包成 zip 下载，压缩级别可用 --compress 调（none/low/medium/high）。
4. 访问控制：--auth 支持 用户名:密码@路径:rw/ro 的细粒度权限，支持 sha-512 哈希密码，公开/只读/读写多账号并存。
5. WebDAV 支持：内置 WebDAV 协议，可被本机文件管理器或 davfs 直接挂载成磁盘。
6. HTTPS 直启：--tls-cert/--tls-key 原生支持 TLS，公网部署可以不经反代直接加密。
7. 搜索：?q=Dockerfile 类似 find -name 的目录内容搜索，配合 --allow-search 开关。
8. SPA/静态站托管：--render-spa 服务单页应用、--render-index 优先返回 index.html。
9. 自定义 UI：--assets 指定资源目录可整体换皮肤（官方提供三个占位变量），社区有多套第三方 UI。

三、全套官方链接

四、硬件与环境前置要求

Dufs 官方未声明特殊硬件要求，作为单二进制文件服务器，普通 VPS（1 核 512MB 内存）即可流畅运行；官方支持 Linux / macOS / Windows 与 Docker（镜像 sigoden/dufs）。安装方式三种任选：

• Docker：docker run -v 目录:/data -p 5000:5000 sigoden/dufs /data -A（官方 Quick Start）。
• cargo：cargo install dufs（需要 Rust 工具链，适合已有 Rust 环境的开发机）。
• Homebrew：brew install dufs（macOS 一条命令）。

没有特殊运行时依赖，也不依赖数据库——所有配置都是启动参数/环境变量/一个可选 YAML，停止即干净。

五、多平台部署步骤

5.1 Docker 部署（推荐）

第 1 步：拉取并运行官方镜像，把本地目录挂载进容器：

docker run -v `pwd`:/data -p 5000:5000 --rm sigoden/dufs /data -A

-v \pwd`:/data把当前目录挂到容器/data；-A表示允许所有操作（上传/删除/搜索/打包等）。--rm表示退出即删容器，正式常驻时去掉--rm并加--restart=unless-stopped`（见第七节）。

第 2 步：浏览器访问 http://服务器IP:5000，能看到目录列表即部署成功。

第 3 步：生产建议加权限与绑定地址：

docker run -d --name dufs --restart=unless-stopped \
  -v /srv/files:/data -p 127.0.0.1:5000:5000 \
  sigoden/dufs /data -a admin:你的密码@/:rw

5.2 预编译二进制部署（Linux/macOS/Windows）

第 1 步：到 GitHub Releases 下载对应平台的压缩包，解压后把 dufs 放进 $PATH。

第 2 步：Linux 下赋予执行权限并验证版本：

chmod +x dufs
./dufs --version

第 3 步：默认服务当前目录：

dufs

5.3 cargo 安装

有 Rust 工具链时 cargo install dufs 即可，安装完成后同样直接执行 dufs；升级用 cargo install dufs --force。

六、配置文件全部参数解释

Dufs 全部选项既可以用 CLI 参数，也可以用 DUFS_ 前缀环境变量，还可以写进 YAML 配置文件（--config）。常用项：

权限规则速记（官方 Advanced Topics 原文要点）：@ 分隔账号与路径、: 分隔用户名密码、, 分隔路径、路径后缀 :rw/:ro 设读写/只读。例如 -a admin:admin@/:rw 表示 admin 对全部路径读写；-a user:pass@/:rw,/dir1 表示 user 对根目录读写、对 /dir1 只读；-a @/ 表示所有人可公开访问。注意：--auth 权限受全局权限限制——未开 --allow-upload 时，即使账号配了 :rw 也不能上传（官方原文："If dufs does not enable upload permissions via --allow-upload, then the account will not have upload permissions even if it is granted read-write(:rw) permissions"）。

哈希密码：官方支持 sha-512 哈希密码，用 openssl passwd -6 123456 生成（以 $6$ 开头），启动时必须用单引号包裹避免 shell 把 $6 当变量展开；官方同时注明 digest 认证与哈希密码不兼容。

YAML 配置文件：dufs --config config.yaml，文件里把上面所有选项写成键值即可（serve-path: '.'、port: 5000、auth: [admin:admin@/:rw] 等，官方 README 有完整示例），适合系统化托管多实例。

七、启动、后台常驻与开机自启

7.1 前台启动

dufs -b 127.0.0.1 -p 80

7.2 Docker 常驻

docker run -d --name dufs --restart=unless-stopped \
  -v /srv/files:/data -p 5000:5000 sigoden/dufs /data -a admin:密码@/:rw

7.3 systemd 常驻（官方无现成 unit，按标准模板配置）

[Unit]
Description=Dufs file server
After=network.target

[Service]
ExecStart=/usr/local/bin/dufs /srv/files -a admin:密码@/:rw
Restart=always
User=www-data

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload && sudo systemctl enable --now dufs

7.4 HTTPS 直启

dufs --tls-cert my.crt --tls-key my.key

八、功能实操教程

第 1 步：只读模式起服务。进入要分享的目录执行 dufs，浏览器打开 http://服务器IP:5000 即可浏览下载，默认只读、不写任何文件，安全兜底。

第 2 步：放开上传与删除。dufs -A 允许所有操作，适合信任的内网环境；更稳妥的是按需放开：dufs --allow-upload 只允许上传。

第 3 步：加账号权限。dufs -a admin:123@/:rw 后，访问时要求输入 admin/123，该账号可读可写；再配 -a guest:guest@/ 让访客只读。

第 4 步：用 curl 走 API 上传下载（官方 Examples/API 原文）：

# 上传
curl -T 本地文件 http://127.0.0.1:5000/new-path/本地文件
# 下载
curl http://127.0.0.1:5000/path-to-file
# 目录打包下载
curl -o folder.zip http://127.0.0.1:5000/path-to-folder?zip
# 搜索
curl http://127.0.0.1:5000?q=Dockerfile
# 健康检查
curl http://127.0.0.1:5000/__dufs__/health

第 5 步：断点续传。下载用 curl -C- -o file http://127.0.0.1:5000/file；上传可用 X-Update-Range: append 分段续传（官方 Advanced Topics 有完整 shell 命令，先 curl -I 取已上传长度再 dd | curl -X PATCH 续传）。

第 6 步：托管 SPA / 静态站。dufs --render-spa 直接服务 react/vue 单页应用；dufs --render-index 目录请求时优先返回 index.html，适合把一个 build 产物目录直接变成线上站点。

第 7 步：隐藏敏感路径。dufs --hidden .git,.DS_Store,tmp，用 glob 匹配（--hidden '*.log'、--hidden '.*' 均支持；官方注明 glob 只匹配文件名/目录名，不匹配完整路径）。

第 8 步：WebDAV 挂载。以 WebDAV 客户端访问 http://服务器IP:5000（带账号则配认证），macOS 访达、Windows 资源管理器、Linux davfs2 均可直接挂载成网络磁盘，配合 --allow-upload 就是私人云盘。

第 9 步：自定义 UI。git clone 社区皮肤（如 dufs-material-assets）后用 dufs --assets 皮肤目录 生效；自建 UI 需包含 index.html，可使用 __INDEX_DATA__、__ASSETS_PREFIX__、__PATH_PREFIX__ 三个占位变量取内部数据。

第 10 步：日志落盘。dufs --log-file ./dufs.log --log-format '$remote_addr "$request" $status $http_user_agent' 记录访问日志，--log-format='' 可关闭日志。

九、全套报错故障排查

1. Address already in use / 端口被占用 原因：5000 端口已被占用，或 -p 80 需要 root 权限。 解决：换端口 -p 8080；低端口用 root 或加 sudo。

2. 访问返回 403 / 无法上传 原因：--auth 账号权限受限，或全局未开 --allow-upload。 解决：检查权限规则；按官方原文"auth 权限受 dufs 全局权限限制"，需同时开 --allow-upload。

3. 哈希密码启动报错 / 权限异常 原因：sha-512 哈希以 $6$ 开头，在 shell 中可能被当作变量展开。 解决：按官方提示用单引号包裹 dufs -a 'admin:$6$.../@/:rw'；注意 digest 认证与哈希密码不兼容（官方原文）。

4. 隐藏目录不生效 原因：--hidden 的 glob 只匹配文件名/目录名，不支持 dir1/file 路径写法（官方原文）。 解决：改成 --hidden dir1 或按扩展名 --hidden '*.log'。

5. Docker 容器内看不到文件 原因：挂载路径没对齐。 解决：镜像内以 /data 为服务路径，确保 -v 本地目录:/data 且命令末尾是 /data。

6. 移动/删除目录返回 403（X-Dufs-Error-Code: readonly-descendant） 原因：目录子树里存在更严格权限的路径，递归操作被拒（官方原文）。 解决：属正常保护行为，把目标子目录权限放开后再操作。

十、升级、回滚与卸载

• 升级：Docker 直接拉新镜像重建 docker pull sigoden/dufs && docker rm -f dufs && docker run ...；二进制/cargo 用户替换新版本文件或 cargo install dufs --force。
• 回滚：GitHub Releases 页面有历史版本，替换回旧二进制即可；Docker 可固定镜像 tag 防止意外升级。
• 卸载：删除容器与镜像（docker rm dufs && docker rmi sigoden/dufs），删除二进制与 systemd unit 文件即可；服务目录里的业务文件不会被删除，无残留数据（配置是启动参数而非安装产物）。

十一、商用许可与合规风险提示

• License：MIT 或 Apache-2.0 二选一（官方原文 "either the MIT License or the Apache License 2.0, at your option"），商用无忧。
• 提供文件共享服务时注意：被分享的内容版权与合规由你负责；开公网前务必配 --auth 权限或放在反代后面（官方文档也建议生产环境用反代做 TLS 与认证）。
• WebDAV/上传开放时，建议 --hidden 隐藏敏感目录，限制账号权限并定期轮换密码，避免被滥用作存储。

参考链接

• 官方 README：sigoden/dufs
• GitHub Releases：github.com/sigoden/dufs/releases
• Docker Hub：hub.docker.com/r/sigoden/dufs
• crates.io：crates.io/crates/dufs