wehub-resource-sync
449 lines
13 KiB
Markdown
449 lines
13 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/sigoden/dufs) · [上游 README](https://github.com/sigoden/dufs/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
# Dufs
|
||
|
||
[](https://github.com/sigoden/dufs/actions/workflows/ci.yaml)
|
||
[](https://crates.io/crates/dufs)
|
||
[](https://hub.docker.com/r/sigoden/dufs)
|
||
|
||
Dufs 是一款独具特色的实用文件服务器，支持静态文件服务、上传、搜索、访问控制、WebDAV……
|
||
|
||
|
||
|
||
## 功能
|
||
|
||
- 提供静态文件服务
|
||
- 将文件夹下载为 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 <file> Specify configuration file
|
||
-b, --bind <addrs> Specify bind address or unix socket
|
||
-p, --port <port> Specify port to listen on [default: 5000]
|
||
--path-prefix <path> Specify a path prefix
|
||
--hidden <value> Hide paths from directory listings, e.g. tmp,*.log,*.lock
|
||
-a, --auth <rules> 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 <path> Set the path to the assets directory for overriding the built-in assets
|
||
--log-format <format> Customize http log format
|
||
--log-file <file> Specify the file to save logs to, other than stdout/stderr
|
||
--compress <level> Set zip compress level [default: low] [possible values: none, low, medium, high]
|
||
--completions <shell> Print shell completion script for <shell> [possible values: bash, elvish, fish, powershell, zsh]
|
||
--tls-cert <path> Path to an SSL/TLS certificate to serve with HTTPS
|
||
--tls-key <path> 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
|
||
```
|
||
|
||
<details>
|
||
<summary><h2>高级主题</h2></summary>
|
||
|
||
### 访问控制
|
||
|
||
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 <glob>,...` 在目录列表中隐藏路径。
|
||
|
||
```
|
||
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'
|
||
```
|
||
</details>
|
||
|
||
### 日志格式
|
||
|
||
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 <file> DUFS_CONFIG=config.yaml
|
||
-b, --bind <addrs> DUFS_BIND=0.0.0.0
|
||
-p, --port <port> DUFS_PORT=5000
|
||
--path-prefix <path> DUFS_PATH_PREFIX=/dufs
|
||
--hidden <value> DUFS_HIDDEN=tmp,*.log,*.lock
|
||
-a, --auth <rules> 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 <path> DUFS_ASSETS=./assets
|
||
--log-format <format> DUFS_LOG_FORMAT=""
|
||
--log-file <file> DUFS_LOG_FILE=./dufs.log
|
||
--compress <compress> DUFS_COMPRESS=low
|
||
--tls-cert <path> DUFS_TLS_CERT=cert.pem
|
||
--tls-key <path> DUFS_TLS_KEY=key.pem
|
||
```
|
||
|
||
## 配置文件
|
||
|
||
可通过选择选项 `--config <path-to-config.yaml>` 来指定并使用配置文件。
|
||
|
||
以下为配置项：
|
||
|
||
```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
|
||
|
||
</details>
|
||
|
||
## 许可证
|
||
|
||
Copyright (c) 2022-2024 dufs-developers.
|
||
|
||
dufs 可在 MIT License 或 Apache License 2.0 条款下使用，由你选择其一。
|
||
|
||
许可详情请参阅 LICENSE-APACHE 与 LICENSE-MIT 文件。
|