> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/sigoden/dufs) · [上游 README](https://github.com/sigoden/dufs/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 # Dufs [![CI](https://github.com/sigoden/dufs/actions/workflows/ci.yaml/badge.svg)](https://github.com/sigoden/dufs/actions/workflows/ci.yaml) [![Crates](https://img.shields.io/crates/v/dufs.svg)](https://crates.io/crates/dufs) [![Docker Pulls](https://img.shields.io/docker/pulls/sigoden/dufs)](https://hub.docker.com/r/sigoden/dufs) Dufs 是一款独具特色的实用文件服务器，支持静态文件服务、上传、搜索、访问控制、WebDAV…… ![demo](https://user-images.githubusercontent.com/4012553/220513063-ff0f186b-ac54-4682-9af4-47a9781dee0d.png) ## 功能 - 提供静态文件服务 - 将文件夹下载为 zip 文件 - 上传文件和文件夹（拖放） - 创建/编辑/搜索文件 - 可断点续传/部分上传与下载 - 访问控制 - 支持 HTTPS - 支持 WebDAV - 可方便地使用 curl ## 安装 ### 使用 cargo ``` cargo install dufs ``` ### 使用 docker ``` docker run -v `pwd`:/data -p 5000:5000 --rm sigoden/dufs /data -A ``` ### 使用 [Homebrew](https://brew.sh) ``` brew install dufs ``` ### macOS、Linux、Windows 二进制文件 从 [Github Releases](https://github.com/sigoden/dufs/releases), 下载，解压后将 dufs 添加到 $PATH。 ## CLI ``` Dufs is a distinctive utility file server - https://github.com/sigoden/dufs Usage: dufs [OPTIONS] [serve-path] Arguments: [serve-path] Specific path to serve [default: .] Options: -c, --config Specify configuration file -b, --bind Specify bind address or unix socket -p, --port Specify port to listen on [default: 5000] --path-prefix Specify a path prefix --hidden Hide paths from directory listings, e.g. tmp,*.log,*.lock -a, --auth Add auth roles, e.g. user:pass@/dir1:rw,/dir2 -A, --allow-all Allow all operations --allow-upload Allow upload files/folders --allow-delete Allow delete files/folders --allow-search Allow search files/folders --allow-symlink Allow symlink to files/folders outside root directory --allow-archive Allow download folders as archive file --allow-hash Allow ?hash query to get file sha256 hash --enable-cors Enable CORS, sets `Access-Control-Allow-Origin: *` --render-index Serve index.html when requesting a directory, returns 404 if not found index.html --render-try-index Serve index.html when requesting a directory, returns directory listing if not found index.html --render-spa Serve SPA(Single Page Application) --assets Set the path to the assets directory for overriding the built-in assets --log-format Customize http log format --log-file Specify the file to save logs to, other than stdout/stderr --compress Set zip compress level [default: low] [possible values: none, low, medium, high] --completions Print shell completion script for [possible values: bash, elvish, fish, powershell, zsh] --tls-cert Path to an SSL/TLS certificate to serve with HTTPS --tls-key Path to the SSL/TLS certificate's private key -h, --help Print help -V, --version Print version ``` ## 示例 以只读模式提供当前工作目录服务 ``` dufs ``` 允许所有操作，如上传/删除/搜索/创建/编辑…… ``` dufs -A ``` 仅允许上传操作 ``` dufs --allow-upload ``` 提供指定目录服务 ``` dufs Downloads ``` 提供单个文件服务 ``` dufs linux-distro.iso ``` 提供单页应用（如 react/vue）服务 ``` dufs --render-spa ``` 提供带 index.html 的静态网站服务 ``` dufs --render-index ``` 要求用户名/密码 ``` dufs -a admin:123@/:rw ``` 在指定的 host:ip 上监听 ``` dufs -b 127.0.0.1 -p 80 ``` 在 unix socket 上监听 ``` dufs -b /tmp/dufs.socket ``` 使用 HTTPS ``` dufs --tls-cert my.crt --tls-key my.key ``` ## API 上传文件 ```sh curl -T path-to-file http://127.0.0.1:5000/new-path/path-to-file ``` 下载文件 ```sh curl http://127.0.0.1:5000/path-to-file # download the file curl http://127.0.0.1:5000/path-to-file?hash # retrieve the sha256 hash of the file ``` 将文件夹下载为 zip 文件 ```sh curl -o path-to-folder.zip http://127.0.0.1:5000/path-to-folder?zip ``` 删除文件/文件夹 ```sh curl -X DELETE http://127.0.0.1:5000/path-to-file-or-folder ``` 创建目录 ```sh curl -X MKCOL http://127.0.0.1:5000/path-to-folder ``` 将文件/文件夹移动到新路径 ```sh curl -X MOVE http://127.0.0.1:5000/path -H "Destination: http://127.0.0.1:5000/new-path" ``` 列出/搜索目录内容 ```sh curl http://127.0.0.1:5000?q=Dockerfile # search for files, similar to `find -name Dockerfile` curl http://127.0.0.1:5000?simple # output names only, similar to `ls -1` curl http://127.0.0.1:5000?json # output paths in json format ``` 使用授权（基本认证或摘要认证均可） ```sh curl http://127.0.0.1:5000/file --user user:pass # basic auth curl http://127.0.0.1:5000/file --user user:pass --digest # digest auth ``` 可断点续传下载 ```sh curl -C- -o file http://127.0.0.1:5000/file ``` 可断点续传上传 ```sh upload_offset=$(curl -I -s http://127.0.0.1:5000/file | tr -d '\r' | sed -n 's/content-length: //p') dd skip=$upload_offset if=file status=none ibs=1 | \ curl -X PATCH -H "X-Update-Range: append" --data-binary @- http://127.0.0.1:5000/file ``` 健康检查 ```sh curl http://127.0.0.1:5000/__dufs__/health ```

高级主题

 ### 访问控制 Dufs 支持基于账户的访问控制。你可以通过 `--auth`/`-a` 控制谁可以在哪些路径上执行哪些操作。 ``` dufs -a admin:admin@/:rw -a guest:guest@/ dufs -a user:pass@/:rw,/dir1 -a @/ ``` 1. 使用 `@` 分隔账户与路径。无账户表示匿名用户。 2. 使用 `:` 分隔账户的用户名与密码。 3. 使用 `,` 分隔路径。 4. 使用路径后缀 `:rw`/`:ro` 设置权限：`read-write`/`read-only`。`:ro` 可省略。 - `-a admin:admin@/:rw`：`admin` 对所有路径拥有完整权限。 - `-a guest:guest@/`：`guest` 对所有路径拥有只读权限。 - `-a user:pass@/:rw,/dir1`：`user` 对 `/*` 拥有读写权限，对 `/dir1/*` 拥有只读权限。 - `-a @/`：所有路径公开可访问，任何人都可以查看/下载。 **认证权限受 dufs 全局权限限制。** 如果 dufs 未通过 `--allow-upload` 启用上传权限，则即使账户被授予 `read-write`(`:rw`) 权限，也无法拥有上传权限。 #### 哈希密码 DUFS 支持使用 sha-512 哈希密码。 创建哈希密码： ```sh $ openssl passwd -6 123456 # or `mkpasswd -m sha-512 123456` $6$tWMB51u6Kb2ui3wd$5gVHP92V9kZcMwQeKTjyTRgySsYJu471Jb1I6iHQ8iZ6s07GgCIO69KcPBRuwPE5tDq05xMAzye0NxVKuJdYs/ ``` 使用哈希密码： ```sh dufs -a 'admin:$6$tWMB51u6Kb2ui3wd$5gVHP92V9kZcMwQeKTjyTRgySsYJu471Jb1I6iHQ8iZ6s07GgCIO69KcPBRuwPE5tDq05xMAzye0NxVKuJdYs/@/:rw' ``` > 哈希密码包含 `$6`，在某些 shell 中可能被展开为变量，因此必须用**单引号**将其包裹。 关于哈希密码的两点重要说明： 1. Dufs 仅支持 sha-512 哈希密码，因此请确保密码字符串始终以 `$6$` 开头。 2. 摘要认证（Digest authentication）无法与哈希密码正常配合使用。 ### 隐藏路径 Dufs 支持通过选项 `--hidden ,...` 在目录列表中隐藏路径。 ``` dufs --hidden .git,.DS_Store,tmp ``` > --hidden 中使用的 glob 仅匹配文件和目录名称，不匹配路径。因此 `--hidden dir1/file` 无效。 ```sh dufs --hidden '.*' # hidden dotfiles dufs --hidden '*/' # hidden all folders dufs --hidden '*.log,*.lock' # hidden by exts dufs --hidden '*.log' --hidden '*.lock' ```
### 日志格式 Dufs 支持通过选项 `--log-format` 自定义 HTTP 日志格式。 日志格式可使用以下变量。 | variable | description | | ------------ | ------------------------------------------------------------------------- | | $remote_addr | 客户端地址 | | $remote_user | 通过认证提供的用户名 | | $request | 完整原始请求行 | | $status | 响应状态码 | | $http_ | 任意请求头字段。例如：$http_user_agent、$http_referer | 默认日志格式为 `'$time_iso8601 $log_level - $remote_addr "$request" $status`。 ``` 2022-08-06T06:59:31+08:00 INFO - 127.0.0.1 "GET /" 200 ``` 也支持 JSON 日志格式。 ``` dufs --log-format '{"time":"$time_local","addr":"$remote_addr","uri":"$request_uri", "method":"$request_method","status":$status}' {"time":"2022-08-06T06:59:31+08:00","addr":"127.0.0.1","uri":"/", "method":"GET","status":200} ``` 禁用 HTTP 日志 ``` dufs --log-format='' ``` 记录 user-agent ``` dufs --log-format '$remote_addr "$request" $status $http_user_agent' ``` ``` 2022-08-06T06:53:55+08:00 INFO - 127.0.0.1 "GET /" 200 Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36 ``` 记录 remote-user ``` dufs --log-format '$remote_addr $remote_user "$request" $status' -a /@admin:admin -a /folder1@user1:pass1 ``` ``` 2022-08-06T07:04:37+08:00 INFO - 127.0.0.1 admin "GET /" 200 ``` ## 环境变量 所有选项均可通过以 `DUFS_` 为前缀的环境变量进行设置。 ``` [serve-path] DUFS_SERVE_PATH="." --config DUFS_CONFIG=config.yaml -b, --bind DUFS_BIND=0.0.0.0 -p, --port DUFS_PORT=5000 --path-prefix DUFS_PATH_PREFIX=/dufs --hidden DUFS_HIDDEN=tmp,*.log,*.lock -a, --auth DUFS_AUTH="admin:admin@/:rw|@/" -A, --allow-all DUFS_ALLOW_ALL=true --allow-upload DUFS_ALLOW_UPLOAD=true --allow-delete DUFS_ALLOW_DELETE=true --allow-search DUFS_ALLOW_SEARCH=true --allow-symlink DUFS_ALLOW_SYMLINK=true --allow-archive DUFS_ALLOW_ARCHIVE=true --allow-hash DUFS_ALLOW_HASH=true --enable-cors DUFS_ENABLE_CORS=true --render-index DUFS_RENDER_INDEX=true --render-try-index DUFS_RENDER_TRY_INDEX=true --render-spa DUFS_RENDER_SPA=true --assets DUFS_ASSETS=./assets --log-format DUFS_LOG_FORMAT="" --log-file DUFS_LOG_FILE=./dufs.log --compress DUFS_COMPRESS=low --tls-cert DUFS_TLS_CERT=cert.pem --tls-key DUFS_TLS_KEY=key.pem ``` ## 配置文件 可通过选择选项 `--config ` 来指定并使用配置文件。 以下为配置项： ```yaml serve-path: '.' bind: 0.0.0.0 port: 5000 path-prefix: /dufs hidden: - tmp - '*.log' - '*.lock' auth: - admin:admin@/:rw - user:pass@/src:rw,/share - '@/' # According to the YAML spec, quoting is required. allow-all: false allow-upload: true allow-delete: true allow-search: true allow-symlink: true allow-archive: true allow-hash: true enable-cors: true render-index: true render-try-index: true render-spa: true assets: ./assets/ log-format: '$remote_addr "$request" $status $http_user_agent' log-file: ./dufs.log compress: low tls-cert: tests/data/cert.pem tls-key: tests/data/key_pkcs1.pem ``` ### 自定义 UI Dufs 允许用户使用自己的资源（assets）自定义 UI。 ``` dufs --assets my-assets-dir/ ``` > 如果只需对当前 UI 做少量调整，你可以复制 dufs 的 [assets](https://github.com/sigoden/dufs/tree/main/assets) 目录并据此修改。当前 UI 未使用任何框架，仅为纯 HTML/JS/CSS。只要你具备一些 Web 开发基础知识，修改起来应该不难。 你的资源文件夹必须包含 `index.html` 文件。 `index.html` 可使用以下占位变量来获取内部数据。 - `__INDEX_DATA__`：目录列表数据 - `__ASSETS_PREFIX__`：资源 URL 前缀 > 也支持自定义 404.html 页面。 以下是一些第三方自定义 UI 项目： - https://github.com/TransparentLC/dufs-material-assets - https://github.com/cercky/dufs_web - https://github.com/52funny/dufs-tabler-web ## 许可证 Copyright (c) 2022-2024 dufs-developers. dufs 可在 MIT License 或 Apache License 2.0 条款下使用，由你选择其一。 许可详情请参阅 LICENSE-APACHE 与 LICENSE-MIT 文件。