# 欢迎 {% hint style="info" %} 当前文档针对的是 V3.x 版本，V4 的文档请前往 [docs.cloudreve.org](https://docs.cloudreve.org/zh/)。 {% endhint %} ## Cloudreve 是什么？ Cloudreve 可以让您快速搭建起公私兼备的网盘系统。Cloudreve 在底层支持不同的云存储平台，用户在实际使用时无须关心物理存储方式。你可以使用 Cloudreve 搭建个人用网盘、文件分享系统，亦或是针对大小团体的公有云系统。 ## 问题反馈 如果在使用过程中发现了什么缺陷，或是有新的需求提议，请先检查一下以前的文档、[issue](https://github.com/cloudreve/Cloudreve/issues) 、[讨论社区](https://forum.cloudreve.org/)是否提过。 如果疑似 Bug 或是功能提议，请创建一个 [issue](https://github.com/cloudreve/Cloudreve/issues) 用于追踪问题； 如果是日常使用上的疑问，请到 [讨论社区](https://forum.cloudreve.org/) 创建新的话题，并详细描述你遇到的问题。 ## 联系 你可以加入以下群组与其他正在使用 Cloudreve 的用户交流： * [Telegram 群组](https://t.me/cloudreve_official) * [QQ 群组](https://qm.qq.com/cgi-bin/qm/qr?k=pjwJ2pi_V4LN_JdPZk_HMwJv_x8zuCPX\&jump_from=webapi) 或是与开发者联系： Email： # 快速开始 ## 获取 Cloudreve 你可以在 [GitHub Release](https://github.com/cloudreve/Cloudreve/releases) 页面获取已经构建打包完成的主程序。其中每个版本都提供了常见系统架构下可用的主程序，命名规则为`cloudreve_版本号_操作系统_CPU架构.tar.gz` 。比如，普通 64 位 Linux 系统上部署 3.0.0 版本，则应该下载`cloudreve_3.0.0_linux_amd64.tar.gz`。 如果你想体验最新的功能特性，可以在 [GitHub Actions](https://github.com/cloudreve/Cloudreve/actions) 中下载每次 commit 后构建的开发版。注意，开发版并不稳定，无法用于生产用途，且不保证完全可用。 如果想要自行从源代码构建，请参阅以下章节： {% content-ref url="/pages/-M2GxI0i-XWQfstBtnTW" %} [构建](/getting-started/build) {% endcontent-ref %} ## 启动 Cloudreve {% tabs %} {% tab title="Linux" %} Linux 下，直接解压并执行主程序即可： ```bash #解压获取到的主程序 tar -zxvf cloudreve_VERSION_OS_ARCH.tar.gz # 赋予执行权限 chmod +x ./cloudreve # 启动 Cloudreve ./cloudreve ``` {% endtab %} {% tab title="Windows" %} Windows 下，直接解压获取到的 zip 压缩包，启动 `cloudreve.exe` 即可。 {% endtab %} {% endtabs %} Cloudreve 在首次启动时，会创建初始管理员账号，请注意保管管理员密码，此密码只会在首次启动时出现。如果您忘记初始管理员密码，需要删除同级目录下的`cloudreve.db`，重新启动主程序以初始化新的管理员账户。 Cloudreve 默认会监听`5212`端口。你可以在浏览器中访问`http://服务器IP:5212`进入 Cloudreve。 以上步骤操作完后，最简单的部署就完成了。你可能需要一些更为具体的配置，才能让 Cloudreve 更好的工作，具体流程请参考下面的配置流程。 ## 可选部署流程 ### 反向代理 在自用或者小规模使用的场景下，你完全可以使用 Cloudreve 内置的 Web 服务器。但是如果你需要使用 HTTPS，亦或是需要与服务器上其他 Web 服务共存时，你可能需要使用主流 Web 服务器反向代理 Cloudreve ，以获得更丰富的扩展功能。 你需要在 Web 服务器中新建一个虚拟主机，完成所需的各项配置（如启用 HTTPS），然后在网站配置文件中加入反代规则： {% tabs %} {% tab title="NGINX" %} 在网站的`server`字段中加入： ``` location / { proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Host $http_host; proxy_redirect off; proxy_pass http://127.0.0.1:5212; # 如果您要使用本地存储策略，请将下一行注释符删除，并更改大小为理论最大文件尺寸 # client_max_body_size 20000m; } ``` {% endtab %} {% tab title="Apache" %} 在`VirtualHost`字段下加入反代配置项`ProxyPass`，比如： ```markup ServerName myapp.example.com ServerAdmin webmaster@example.com DocumentRoot /www/myapp/public # 以下为关键部分 AllowEncodedSlashes NoDecode ProxyPass "/" "http://127.0.0.1:5212/" nocanon ``` {% endtab %} {% tab title="IIS" %} **1. 安装 IIS URL Rewrite 和 ARR 模块** * URL Rewrite: [点击下载](https://www.iis.net/downloads/microsoft/url-rewrite#additionalDownloads) * ARR: [点击下载](https://www.iis.net/downloads/microsoft/application-request-routing#additionalDownloads) 如已安装，请跳过本步。 **2. 启用并配置 ARR** 打开 IIS，进入主页的 **Application Request Routing Cache**，再进入右边的 **Server Proxy Settings...**，勾选最上面的 **Enable proxy**，同时取消勾选下面的 **Reverse rewrite host in response headers**。点击右边的 应用 保存更改。 进入主页最下面的 **配置编辑器 (Configuration Editor)**，转到 `system.webServer/proxy` 节点，调整 **preserveHostHeader** 为 **True** 后点击右边的 应用 保存更改。 如果不取消勾选反向重写主机头，会导致 Cloudreve API 无法返回正确的地址，导致无法预览图片视频等。 **3. 配置反代规则** 这是 `web.config` 文件的内容，将它放在目标网站根目录即可。此样例包括两个规则与一个限制： * HTTP to HTTPS redirect (强制 HTTPS，需要自行配置 SSL 后才可使用，不使用请删除该 rule) * Rerwite (反代) * `requestLimits` 中的 `60000000` 为传输文件大小限制，单位 byte，如果您要使用本地存储策略请更改大小为理论最大文件尺寸 ```xml ``` {% endtab %} {% endtabs %} ### 进程守护 以下两种方式可任选其一。 #### Systemd ```bash # 编辑配置文件 vim /usr/lib/systemd/system/cloudreve.service ``` 将下文 `PATH_TO_CLOUDREVE` 更换为程序所在目录： ```bash [Unit] Description=Cloudreve Documentation=https://docs.cloudreve.org After=network.target After=mysqld.service Wants=network.target [Service] WorkingDirectory=/PATH_TO_CLOUDREVE ExecStart=/PATH_TO_CLOUDREVE/cloudreve Restart=on-abnormal RestartSec=5s KillMode=mixed StandardOutput=null StandardError=syslog [Install] WantedBy=multi-user.target ``` ```bash # 更新配置 systemctl daemon-reload # 启动服务 systemctl start cloudreve # 设置开机启动 systemctl enable cloudreve ``` 管理命令： ```bash # 启动服务 systemctl start cloudreve # 停止服务 systemctl stop cloudreve # 重启服务 systemctl restart cloudreve # 查看状态 systemctl status cloudreve ``` #### Supervisor 首先安装`supervisor`，已安装的可以跳过。 ```bash # 安装 supervisor sudo yum install python-setuptools sudo easy_install supervisor # 初始化全局配置文件 sudo touch /etc/supervisord.conf sudo echo_supervisord_conf > /etc/supervisord.conf ``` 编辑全局配置文件： ```bash sudo vim /etc/supervisord.conf ``` 将文件底部的`[include]` 分区注释符号`;`删除，加入新的配置文件包含路径： ```bash [include] files = /etc/supervisor/conf/*.conf ``` 创建 Cloudreve 应用配置所在文件目录，并创建打开配置文件： ```bash sudo mkdir -p /etc/supervisor/conf sudo vim /etc/supervisor/conf/cloudreve.conf ``` 根据实际情况填写以下内容并保存： ```bash [program:cloudreve] directory=/home/cloudreve command=/home/cloudreve/cloudreve autostart=true autorestart=true stderr_logfile=/var/log/cloudreve.err stdout_logfile=/var/log/cloudreve.log environment=CODENATION_ENV=prod ``` 其中以下配置项需要根据实际情况更改： * `directory`: Cloudreve 主程序所在目录 * `command`: Cloudreve 主程序绝对路径 * `stderr_logfile`: 错误日志路径 * `stdout_logfile`: 通常日志路径 通过全局配置文件启动 supervisor： ```bash supervisord -c /etc/supervisord.conf ``` 日后你可以通过以下指令管理 Cloudreve 进程： ```bash # 启动 sudo supervisorctl start cloudreve # 停止 sudo supervisorctl stop cloudreve # 查看状态 sudo supervisorctl status cloudreve ``` ## Docker > 使用之前，请确保您知道 docker 的工作机制，在一般情况下，上述部署流程已经能够覆盖绝大多数使用场景。 我们提供官方的 docker image，支持三种架构 `armv7`, `arm64` 以及 `amd64`, 你可以使用以下命令部署 ### 创建目录结构 请**确保**运行之前： > 1. 手动创建 `conf.ini` 空文件或者符合 Cloudreve 配置文件规范的 `conf.ini`, 并将 `` 替换为该路径 > 2. 手动创建 `cloudreve.db` 空文件, 并将 `` 替换为该路径 > 3. 手动创建 `uploads` 文件夹, 并将 `` 替换为该路径 > 4. 手动创建 `avatar` 文件夹，并将 `` 替换为该路径 或者，直接使用以下命令创建： ```bash mkdir -vp cloudreve/{uploads,avatar} \ && touch cloudreve/conf.ini \ && touch cloudreve/cloudreve.db ``` ### 运行 然后，运行 docker container： ```bash docker run -d \ -p 5212:5212 \ --mount type=bind,source=,target=/cloudreve/conf.ini \ --mount type=bind,source=,target=/cloudreve/cloudreve.db \ -v :/cloudreve/uploads \ -v :/cloudreve/avatar \ cloudreve/cloudreve:latest ``` ## Docker Compose 除此之外，我们还提供 `docker compose` 部署，并且整合了离线下载服务 在此之前，需要创建 `data` 目录作为离线下载临时中转目录 ### 创建目录结构 ```bash mkdir -vp cloudreve/{uploads,avatar} \ && touch cloudreve/conf.ini \ && touch cloudreve/cloudreve.db \ && mkdir -p aria2/config \ && mkdir -p data/aria2 \ && chmod -R 777 data/aria2 ``` ### 运行 然后将以下文件保存为 `docker-compose.yml`，放置于当前目录，与 cloudreve 同一层级，同时，修改文件中的 `RPC_SECRET` ```yml version: "3.8" services: cloudreve: container_name: cloudreve image: cloudreve/cloudreve:latest restart: unless-stopped ports: - "5212:5212" volumes: - temp_data:/data - ./cloudreve/uploads:/cloudreve/uploads - ./cloudreve/conf.ini:/cloudreve/conf.ini - ./cloudreve/cloudreve.db:/cloudreve/cloudreve.db - ./cloudreve/avatar:/cloudreve/avatar depends_on: - aria2 aria2: container_name: aria2 image: p3terx/aria2-pro restart: unless-stopped environment: - RPC_SECRET=your_aria_rpc_token - RPC_PORT=6800 volumes: - ./aria2/config:/config - temp_data:/data volumes: temp_data: driver: local driver_opts: type: none device: $PWD/data o: bind ``` 运行镜像 ```bash # 后台运行模式，可以从 docker/docker-compose 的日志中获取默认管理员账户用户名和密码 docker-compose up -d # 或者，直接运行，log 将会直接输出在当前控制台中，请注意退出之后保持当前容器运行 docker-compose up ``` 在之后的控制面板中，按照如下配置 1. **\[不可修改]** RPC 服务器地址 => `http://aria2:6800` 2. **\[可修改, 需保持和 docker-compose.yml 文件一致]** RPC 授权令牌 => `your_aria_rpc_token` 3. **\[不可修改]** Aria2 用作临时下载目录的 节点上的绝对路径 => `/data` ### 更新 关闭当前运行的容器，此步骤不会删除挂载的配置文件以及相关目录 ```bash docker-compose down ``` 如果此前已经拉取 docker 镜像，使用以下命令获取最新镜像 ```bash docker pull cloudreve/cloudreve ``` 重复运行步骤即可 # 配置文件 ## 配置文件 首次启动时，Cloudreve 会在同级目录下创建名为`conf.ini`的配置文件，你可以修改此文件进行一些参数的配置，保存后需要重新启动 Cloudreve 生效。 你也可以在启动时加入`-c`参数指定配置文件路径： ``` ./cloudreve -c /path/to/conf.ini ``` 一个完整的配置文件示例如下： {% code title="conf.ini" %} ```ini [System] ; 运行模式 Mode = master ; 监听端口 Listen = :5212 ; 是否开启 Debug Debug = false ; Session 密钥, 一般在首次启动时自动生成 SessionSecret = 23333 ; Hash 加盐, 一般在首次启动时自动生成 HashIDSalt = something really hard to guss ; 呈递客户端 IP 时使用的 Header ProxyHeader = X-Forwarded-For ; SSL 相关 [SSL] ; SSL 监听端口 Listen = :443 ; 证书路径 CertPath = C:\Users\i\Documents\fullchain.pem ; 私钥路径 KeyPath = C:\Users\i\Documents\privkey.pem ; 启用 Unix Socket 监听 [UnixSocket] Listen = /run/cloudreve/cloudreve.sock ; 设置产生的 socket 文件的权限 Perm = 0666 ; 数据库相关，如果你只想使用内置的 SQLite 数据库，这一部分直接删去即可 [Database] ; 数据库类型，目前支持 sqlite/mysql/mssql/postgres Type = mysql ; MySQL 端口 Port = 3306 ; 用户名 User = root ; 密码 Password = root ; 数据库地址 Host = 127.0.0.1 ; 数据库名称 Name = v3 ; 数据表前缀 TablePrefix = cd_ ; 字符集 Charset = utf8mb4 ; SQLite 数据库文件路径 DBFile = cloudreve.db ; 进程退出前安全关闭数据库连接的缓冲时间 GracePeriod = 30 ; 使用 Unix Socket 连接到数据库 UnixSocket = false ; 从机模式下的配置 [Slave] ; 通信密钥 Secret = 1234567891234567123456789123456712345678912345671234567891234567 ; 回调请求超时时间 (s) CallbackTimeout = 20 ; 签名有效期 SignatureTTL = 60 ; 跨域配置 [CORS] AllowOrigins = * AllowMethods = OPTIONS,GET,POST AllowHeaders = * AllowCredentials = false SameSite = Default Secure = lse ; Redis 相关 [Redis] Server = 127.0.0.1:6379 Password = DB = 0 ; 从机配置覆盖 [OptionOverwrite] ; 可直接使用 `设置名称 = 值` 的格式覆盖 max_worker_num = 50 ``` {% endcode %} ## 配置案例 ### 使用 MySQL 默认情况下，Cloudreve 会使用内置的 SQLite 数据库，并在同级目录创建数据库文件`cloudreve.db`，如果您想要使用 MySQL，请在配置文件中加入以下内容，并重启 Cloudreve。注意，Cloudreve 只支持大于或等于 5.7 版本的 MySQL 。 ```ini [Database] ; 数据库类型，目前支持 sqlite/mysql/mssql/postgres Type = mysql ; MySQL 端口 Port = 3306 ; 用户名 User = root ; 密码 Password = root ; 数据库地址 Host = 127.0.0.1 ; 数据库名称 Name = v3 ; 数据表前缀 TablePrefix = cd ; 字符集 Charset = utf8 ``` {% hint style="info" %} 更换数据库配置后，Cloudreve 会重新初始化数据库，原有的数据将会丢失。 {% endhint %} ### 使用 Redis 你可以在配置文件中加入 Redis 相关设置： ```ini [Redis] Server = 127.0.0.1:6379 Password = your password DB = 0 ``` {% hint style="info" %} 请为 Cloudreve 指定未被其他业务使用的 DB，以避免冲突。 {% endhint %} 重启 Cloudreve 后，可注意控制台输出，确定 Cloudreve 是否成功连接 Redis 服务器。使用 Redis 后，以下内容将被 Redis 接管： * 用户会话（重启 Cloudreve 后不会再丢失登录会话） * 数据表高频记录查询缓存（如存储策略、设置项） * 回调会话 * OneDrive 凭证 ### 启用 HTTPS {% hint style="info" %} 如果您正在使用 Web 服务器反向代理 Cloudreve，推荐您在 Web 服务器中配置 SSL，本小节所阐述的启用方式只针对使用 Cloudreve 内置 Web 服务器的情境下有效。 {% endhint %} 在配置文件中加入： ```ini [SSL] Listen = :443 CertPath = C:\Users\i\Documents\fullchain.pem KeyPath = C:\Users\i\Documents\privkey.pem ``` 其中 `CertPath` 和`KeyPath` 分别为 SSL 证书和私钥路径。保存后重启 Cloudreve 生效。 ### 覆盖从机节点的配置项 Cloudreve 的某些配置项是存储在数据库中的，但是从机节点并不会连接数据库，你可以在配置文件中覆盖相应的配置项。 比如，从机节点作为存储端运行时，你可以通过下面的配置设定从机生成的缩略图规格： ```ini [OptionOverwrite] thumb_width = 400 thumb_height = 300 thumb_file_suffix = ._thumb thumb_max_task_count = -1 thumb_encode_method = jpg thumb_gc_after_gen = 0 thumb_encode_quality = 85 ``` 如果从机节点作为离线下载节点使用，你可以通过下面的配置覆盖默认的重试、超时参数，以避免默认的数值过于保守导致文件转存失败： ```ini [OptionOverwrite] ; 任务队列最多并行执行的任务数 max_worker_num = 50 ; 任务队列中转任务传输时，最大并行协程数 max_parallel_transfer = 10 ; 中转分片上传失败后重试的最大次数 chunk_retries = 10 ``` # 构建 Cloudreve 项目主要由两部分组成：后端主仓库 [cloudreve/Cloudreve](https://github.com/cloudreve/Cloudreve)，以及前端仓库 [cloudreve/frontend](https://github.com/cloudreve/frontend)。编译 Cloudreve 后端前，需要先构建`assets` 目录下的前端子模块，并使用 [statik](https://github.com/rakyll/statik) 嵌入到后端仓库。 ## 环境准备 1. 参照 [Getting Started - The Go Programming Language](https://golang.org/doc/install) 安装并配置 Go 语言开发环境 (>=1.18)； 2. 参考 [下载 | Node.js](https://nodejs.org/zh-cn/download/) 安装 Node.js; 3. 参考 [安装 | Yarn](https://classic.yarnpkg.com/zh-Hans/docs/install#windows-stable) 安装 Yarn; ## 开始构建 ### 克隆代码 ```bash # 克隆仓库 git clone --recurse-submodules https://github.com/cloudreve/Cloudreve.git # 签出您要编译的版本 git checkout 3.x.x ``` ### 构建静态资源 ```bash # 进入前端子模块 cd assets # 安装依赖 yarn install # 开始构建 yarn run build # 构建完成后删除映射文件 cd build find . -name "*.map" -type f -delete # 返回项目主目录打包静态资源 cd ../../ zip -r - assets/build >assets.zip ``` 完成后，所构建的静态资源文件位于 `assets/build` 目录下。 你可以将此目录改名为`statics` 目录，放置在 Cloudreve 主程序同级目录下并重启 Cloudreve，Cloudreve 将会使用此目录下的静态资源文件，而非内置的。 ### 编译项目 ```bash # 回到项目主目录 cd ../ # 获得当前版本号、Commit export COMMIT_SHA=$(git rev-parse --short HEAD) export VERSION=$(git describe --tags) # 开始编译 go build -a -o cloudreve -ldflags " -X 'github.com/cloudreve/Cloudreve/v3/pkg/conf.BackendVersion=$VERSION' -X 'github.com/cloudreve/Cloudreve/v3/pkg/conf.LastCommit=$COMMIT_SHA'" ``` {% hint style="info" %} 首次编译时，Go 会下载相关依赖库，如果您的网络环境不佳，可能会导致这一步速度过慢或者失败。你可以使用 [GOPROXY.IO](https://goproxy.io/zh/) 加快模块下载速度。 {% endhint %} 编译完成后，会在项目根目录下生成最终的可执行文件`cloudreve` 。 ## 构建助手 你可以使用 [goreleaser](https://goreleaser.com/intro/) 快速完成构建、打包等操作，使用方法如下： ```bash # 安装 goreleaser go install github.com/goreleaser/goreleaser@latest # 构建项目 goreleaser build --clean --single-target --snapshot ``` 或者交叉编译出所有可用版本： ```sh goreleaser build --clean --snapshot ``` # 存储策略 存储策略定义了文件的存储平台、上传和功能限制。用户组与存储策略绑定，此用户组下的用户将共享同一个存储策略。在 Pro 版中，你可以为单个用户组指定多个存储策略，用户可以自由切换存储策略。 在 Cloudreve 的文件系统中，每个文件都记录了其对应的存储策略，用户可以同时拥并管理有多个存储策略的文件。切换用户组的存储策略后，已经上传的文件不会受到影响。 # 对比 中转Cloudreve 支持多种底层存储策略，但是由于 API 限制等各方面因素，Cloudreve 对每种策略的支持程度并不一致，本章节将会详细列出不同存储策略之间的具体支持性区别。 ## 基本对比
本机从机七牛OSSCOS又拍云OneDriveS3
上传✅✅✅✅✅✅✅✅
分片上传✅✅✅✅❌❌✅✅
下载✅✅✅✅✅✅✅✅
复制✅✅✅✅✅✅✅✅
移动✅✅✅✅✅✅✅✅
普通预览✅✅✅✅✅✅✅✅
Office 预览✅✅✅✅✅✅✅✅
删除✅✅✅✅✅✅✅✅
原生缩略图✅✅✅✅✅✅✅❌
代理缩略图N/A✅✅✅✅✅✅✅
打包下载✅✅✅✅✅✅✅✅
真实文件名下载✅✅✅✅✅✅❌✅
理论最大文件无限无限无限无限5 GB150 GB250 GB无限
公网接入要求无无需要需要需要需要需要需要
可用于对公使用✅✅✅✅✅✅以 ToS 为准❌
## 高级功能 | | 本机 | 从机 | 七牛 | OSS | COS | 又拍云 | OneDrive | S3 | | -------- | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | -------------------- | | 离线下载 | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | | 下载限速 | :white\_check\_mark: | :white\_check\_mark: | :x: | :white\_check\_mark: | :white\_check\_mark: | :x: | :x: | :x: | | 中转直链永久有效 | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | | 原始直链永久有效 | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :x: | :white\_check\_mark: | | 解压缩 | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | | 压缩 | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | | | | | | | | | | | ## 流量路径 | | 本机 | 从机 | 七牛 | OSS | COS | 又拍云 | OneDrive | S3 | | ----------- | -------------------- | -------------------- | -------------------- | -------------------- | -------------------- | -------------------- | -------------------- | -------------------- | | Web 上传客户端直传 | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | | 下载直传 | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | | 打包下载/压缩/解压缩 | 直传 | 中转 | 中转 | 中转 | 中转 | 中转 | 中转 | 中转 | | 离线下载 | 直传 | 中转 | 中转 | 中转 | 中转 | 中转 | 中转 | 中转 | | 文本编辑 | 直传 | 中转 | 中转 | 中转 | 中转 | 中转 | 中转 | 中转 | | WebDAV 上传直传 | :white\_check\_mark: | :x: | :x: | :x: | :x: | :x: | :x: | :x: | | WebDAV 下载直传 | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | # S3 兼容 通过 AWS S3 存储策略，你可以使用 Cloudreve 对接所有兼容 AWS S3 协议的存储平台。本文将介绍 [Cloudflare R2](https://www.cloudflare.com/products/r2/) 和 [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html) 两个平台的对接方法。 {% hint style="warning" %} S3 存储策略仅可用于自用或给受信任的群体使用。因为缺乏统一的回调机制，用户可以跳过 Cloudreve 的记录而上传文件到存储桶。 {% endhint %} ## S3 API 兼容要求 Cloudreve 利用了以下 S3 API，请确保你的存储平台兼容实现了下列 API。 ### Bucket Level * [PutBucketCors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketCors.html) 可选，用于辅助配置 CORS 策略，如果未实现此 API，您也可以手动配置。 ### Object Level * [ListObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html) 可选，用于后台导入外部文件。 * [CreateMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html) * [CompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) * [AbortMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html) * [UploadPart](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html) * [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) * [DeleteObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) * [HeadObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) ## Cloudflare R2 ### 选择1：Private Bucket 前往 [Cloudflare R2](https://www.cloudflare.com/products/r2/) 购买套餐开通 R2 服务。创建 Bucket 后，在 Cloudreve 管理面板添加 AWS S3 存储策略并填入创建的 Bucket 的名称，Bucket 类型选择为 “阻止全部公共访问”，填入 Cloudflare 提供的 Endpoint 地址（**需要将结尾除的 Bucket 名手动删去**），Endpoint 格式选择为“强制路径格式”：
在第五项 Bucket 区域代码中填入`auto`: ![](/files/PY7z8cKakCEURz1EXMRH) 进入到 R2 服务面板主页，进入“Manage R2 API Tokens”创建一组 API Token，权限选择为允许编辑，根据需求设定凭证有效期：
{% hint style="info" %} API Token 过期后请生成新的 Token 并填写到 Cloudreve 的对应存储策略中。 {% endhint %} 创建后将 AccessKey 和 SecretKey 填入 Cloudreve：
继续填写存储策略配置，进行到第5步时，点击让 Cloudreve 帮你创建 CORS 策略：
至此，你就可以绑定并使用新创建的 R2 存储策略了。 ### 选择2：Public Bucket 如果您需要使用公共 Bucket，配置流程大概与 [#xuan-ze-1private-bucket](#xuan-ze-1private-bucket "mention") 相同，其中额外的操作在于： 在 R2 Bucket 设置中开启 Public Access，然后在 Cloudreve 中填写存储策略信息。其中，Bucket 类型选择为“允许公共读取”；Endpoint 格式选择为“主机名优先”；选择“使用CDN”并填入刚刚得到的 Public Bucket URL（别忘了去掉开头的`https`）：
其他配置与 Public Bucket 的情况保持一致即可。 ## Backblaze B2 前往 [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html) 创建账号，点击“Create a Bucket”创建 Bucket 。可以根据自己需求选择 Public 或 Private Bucket，推荐使用 Private Bucket 以提高安全性。为存储桶取名后，其他参数保持默认，点击创建 Bucket 。 在 Cloudreve 管理面板添加 AWS S3 存储策略，填入你创建的 Bucket 名称。根据 Bucket 类型，如果是 Private 请选择“阻止全部公共访问”，Public 请选择“允许公共读取”。在 B2 管理面板找到 Bucket 的 Endpoint，在其头部追加 `https://` 填入 Cloudreve：
在 Cloudreve 填写 Bucket 所属的区域，可以通过 Endpoint 来判断。比如 Endpoint `s3.us-west-005.backblazeb2.com` 的区域代码就是 `us-west-005`。你无法在 Cloudreve 提供的下拉菜单中找到对应地区，直接填入区域代码即可。 在 B2 面板 Account -> App Keys 中点击“Add a New Application Key”，填入任意 Key 的名称，选择刚刚创建的 Bucket，其他参数保持默认即可： ![](/files/wtG5eAGFESFHIFRbekCw) 创建后，将`keyID` 填入`AccessKey`; `applicationKey`填入`SecretKey`：
继续填写存储策略配置，进行到第5步时，点击跳过：
由于 Backblaze B2 的 S3 API 兼容性欠佳，无法在 Cloudreve 中一键创建 CORS 策略 因此，接下来你需要通过 [B2 CLI](https://www.backblaze.com/docs/cloud-storage-command-line-tools) 进行操作 根据 [Backblaze 的官方文档](https://www.backblaze.com/docs/cloud-storage-command-line-tools) 下载 B2 CLI 工具 {% hint style="info" %} Linux 用户可以运行以下的命令来下载 B2 CLI 工具 ```bash wget https://github.com/Backblaze/B2_Command_Line_Tool/releases/latest/download/b2-linux chmod +x ./b2-linux ``` {% endhint %} 然后执行 `./b2-linux account authorize` 进行账号登录（可以使用上文中创建的 `keyID` 和 `applicationKey`） 根据提示，填入 `keyID` 与 `applicationKey` 后，会输出一段当前账号的 JSON 配置 {% hint style="warning" %} 此处以及后续所获得的 JSON 配置输出均包含账号敏感信息，如需分享请做好脱敏 {% endhint %} 执行以下命令修改存储桶 CORS 配置 ```bash ./b2-linux bucket update --cors-rules '[ { "allowedHeaders": [ "authorization", "range", "content-type" ], "allowedOperations": [ "s3_head", "s3_get", "s3_put", "s3_post", "s3_delete" ], "allowedOrigins": [ "*" ], "corsRuleName": "s3DownloadFromAnyOriginWithUpload", "exposeHeaders": ["ETag"], "maxAgeSeconds": 3600 } ]' ``` 如果你希望得到更好的安全性，可以将 `allowedOrigins` 中的星号换成你 Cloudreve 的域名 完成后会输出一次当前存储桶的完整配置，一般情况下它看起来会是这样 ```json { "accountId": "", "bucketId": "", "bucketInfo": {}, "bucketName": "", "bucketType": "allPrivate", "corsRules": [ { "allowedHeaders": [ "authorization", "range", "content-type" ], "allowedOperations": [ "s3_head", "s3_put", "s3_delete", "s3_post", "s3_get" ], "allowedOrigins": [ "*" ], "corsRuleName": "s3DownloadFromAnyOriginWithUpload", "exposeHeaders": [ "etag" ], "maxAgeSeconds": 3600 } ], "defaultRetention": { "mode": null }, "defaultServerSideEncryption": { "mode": "none" }, "isFileLockEnabled": false, "lifecycleRules": [], "options": [ "s3" ], "replication": { "asReplicationDestination": null, "asReplicationSource": null }, "revision": 9 } ``` 不出意外的话，到这里 CORS 已经配置成功，可以在 Cloudreve 正常进行文件操作了 # WebDAV WebDAV 是一种基于 HTTP 协议的文件传输协议，如今有许多第三方文件管理器、视频播放器等产品都支持通过 WebDAV 协议访问 Cloudreve 中的文件，你可以借此实现跨平台的文件共享与同步。 要使用 WebDAV，请先前往后台管理面板为对应用户组开启 WebDAV 使用权限。WebDAV 所使用的账号与 Cloudreve 账号**并不互通**，需要单独创建。前往前台 导航左侧 - WebDAV - 创建新账号 创建供 WebDAV 使用的账号信息。创建完成后系统会为此账号自动生成密码，使用 WebDAV 时请使用注册邮箱作为账号名，密码则为上述系统所生成的密码。 创建 WebDAV 账号时，你可以为此账号指定相对根目录，此账号只能通过 WebDAV 访问所指定相对根目录下的目录及文件。对于捐助版，用户还可以为不同目录挂载不同的存储策略，在 WebDAV 下上传新文件时会优先使用为目录挂载的存储策略。 ## 常见客户端使用说明 ### 使用 Windows 资源管理器(不推荐) {% hint style="warning" %} 不建议使用 Windows 默认的 WebDAV 客户端，该客户端实现有较大缺陷，在网络发生波动时，易导致整个操作系统卡顿甚至死机，一旦该客户端发生阻塞，您甚至无法通过紧急重启来恢复系统响应。此外，您无法获知传输进度，也无法中断正在进行的 WebDAV 传输（即使结束资源管理器的进程，传输也不会停止），出于这种原因，默认情况下，Windows 拒绝操作大于 50MB 的文件，即使[修改注册表](https://superuser.com/questions/1540281/windows-10-webdav-issue-freezes-crashes-stalls-with-files-over-50-mb)，也没有任何办法操作大于 4GB 的文件。 {% endhint %} {% hint style="info" %} 使用这种方式前，请确保你的 Cloudreve 站点已启用 HTTPS。如果需要在非 HTTPS 协议下添加，需要修改注册表`\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters` 将`BasicAuthLevel` 的值改为`2`。 {% endhint %} 在 “此电脑”空白处右键，选择“添加一个网络位置”： ![](/files/z8BM9Bat4JjHPwbVTGpG) 输入站点 WebDAV 连接地址，一般格式为`https://您的域名/dav`，填写完成后输入您的 Cloudreve 账号和系统生成的账号密码即可。 已知问题：重启后无法访问已添加的 WebDAV 挂载，需要重新输入账号密码。这是由于 Windows 不再支持 BasicAuth 下存储 WebDAV 账号及密码信息 ([相关说明](https://docs.microsoft.com/en-us/troubleshoot/windows-client/networking/cannot-automatically-reconnect-dav-share))。Cloudreve 会在后续版本中更换 WebDAV 验证方式以改善此问题。 # 离线下载 Cloudreve 的离线下载核心由 [Aria2](https://aria2.github.io) 驱动。正确配置并启用离线下载功能后，用户可以创建磁力链、HTTP、种子下载任务，由服务端下载完成后加入到用户文件中。 对于云存储策略，离线下载任务完成后，Cloudreve 会将所下载的文件转存到云存储端，在转存结束前，用户无法下载、管理已下载的文件。用户可以在前台任务队列中查看转存任务进度。 Cloudreve 支持“从机离线下载”，您可以将离线下载任务分流至多台服务器处理，避免这些任务过多占用主机的资源。每个负责处理离线下载任务的节点需要运行一组 Cloudreve 和 Aria2 实例。您可以按照管理面板中的节点添加向导指引配置并添加新节点。从机离线下载节点与用于从机存储策略的 节点本质上是一样的，您可以将从机 Cloudreve 实例同时用作存储节点和离线下载节点。如果您不需要从机节点处理离线下载任务，只想让当前主机 Cloudreve 处理离线下载，只需要编辑主机节点并配置 Aria2 相关信息即可。用户创建的离线下载任务会被轮流分配到所有可用的离线下载节点处理。 ## 启用离线下载 ### Aria2 RPC 配置 Aria2 的安装、启动过程不在本文讨论范围之内。您需要在 Cloudreve 相同的机器上启动 Aria2。 {% hint style="info" %} 推荐在日常启动流程中，先启动 Aria2，再启动 Cloudreve，这样 Cloudreve 可以向 Aria2 订阅事件通知，下载状态变更处理更及时。当然，如果没有这一流程，Cloudreve 也会通过轮询追踪任务状态。 {% endhint %} 在启动 Aria2 时，需要在其配置文件中启用 RPC 服务，并设定 RPC Secret，以便后续使用。 ```bash # 启用 RPC 服务 enable-rpc=true # RPC监听端口 rpc-listen-port=6800 # RPC 授权令牌，可自行设定 rpc-secret= ``` ### 接入 Cloudreve 前往 Cloudreve 的 管理面板-离线下载节点-添加/编辑 节点-离线下载，根据指引填写信息并测试是否可以与 Aria2 正常通信。 对于其中重要参数项的解释如下： **RPC 服务器地址** Aria2 RPC 服务器的地址，一般可填写为`http://127.0.0.1:6800/` 。其中`6800` 为上文 Aria2 配置文件中指定的监听端口。您可以使用 WebSocket 通信，此处填写为`ws://127.0.0.1:6800/` 。 **RPC Secret** 上文中您在 Aria2 配置文件中设定的 RPC 授权令牌。 **临时下载目录** Cloudreve 会指定 Aria2 将文件下载到此目录中，下载完成后 Cloudreve 会复制到指定的存储策略，并删除文件。此目录**必须为绝对路径**，否则 Cloudreve 在任务下载完成后会找不到文件。Windows 下指定的绝对路径应该携带盘符，比如`G:\www\downloads` 。 **状态刷新间隔（秒）** 指定针对每一个任务，Cloudreve 向 Aria2 轮询更新任务状态的间隔。用户再前台看到的任务进度不会实时更新，而是根据这里设定的间隔自动刷新。 **全局任务参数** 在此处指定 Cloudreve 创建 Aria2 下载任务时携带的额外参数，如果 Aria2 未与其他服务公共时，你也可以在 Aria2 的配置文件中指定这些参数。具体的可用参数可参考[官方文档](https://aria2.github.io/manual/en/html/aria2c.html#options)，以 JSON 的格式填写在这里。如果格式有误，可能会导致无法创建任务。以下为一个填写示例，指定了最大并行任务数和 Tracker 服务器列表： ```javascript { "max-concurrent-downloads": 10, "bt-tracker": [ "udp://tracker.coppersurfer.tk:6969/announce", "udp://tracker.opentrackr.org:1337/announce", "udp://tracker.leechers-paradise.org:6969/announce" ] } ``` 您也可在用户组配置中，为每个用户组指定其特有的参数，比如限制最大下载速度等。具体格式与上述一致，不再复述。 ### 用户组权限 对于您想要允许使用离线下载功能的用户组，请在用户组编辑页面开启离线下载使用权限。 ## 常见问题 #### 测试 Aria2 连接时提示`无法请求 RPC 服务, Post "XXX": dial tcp XXX connect: connection refused` 填写的 RPC 地址有误，无法连接，检查地址是否有误、Aria2 是否启动、端口是否与 Aria2 配置文件中指定的一致。 #### 测试 Aria2 连接时提示 `无法请求 RPC 服务, invalid character '<' looking for beginning of value` 填写的 RPC 地址有误，可以连接，但其并不是 Aria2 的 RPC服务，请检查地址是否有误、端口是否正确。这一错误的原因一般是将 RPC 地址 填写为了某项 Web 服务的地址。 #### Cloudreve 任务列表里任务状态不更新/更新不及时 Cloudreve 会定期轮询任务状态，任务创建后状态不会实时更新，请耐心等待。您也可以在 管理面板-参数设置-离线下载-状态刷新间隔（秒）中调整更新频率。 #### BT 下载太慢/无速度 下载任务是由 Aria2 进行处理，无法通过 Cloudreve 做出优化。一个可能的解决方案是，手动添加 Tracker 服务器。你可以在 Aria2 配置文件中指定 Tracker： ```bash bt-tracker=udp://tracker.coppersurfer.tk:6969/announce,http://tracker.internetwarriors.net:1337/announce,udp://tracker.opentrackr.org:1337/announce ``` 以上指定的 Tracker 列表只是示例，你需要根据实际自己填写。你可以使用 [trackerslist](https://github.com/ngosang/trackerslist) 项目中每日更新的最佳 Tracker 列表。 #### BT 任务进度100%后，任务仍长期处在”进行中“的列表中不被处理 默认情况下 Aria2 会对下载完成的 BT 任务进行做种，做种完成后才会被 Cloudreve 认定为已完成，并进行后续处理。您可以在 Aria2 配置文件中指定做种分享率或做种时间，当达到任一条件后，做种会停止： ```bash # 做种分享率, 0为一直做种, 默认:1.0 seed-ratio=1.0 # 作种时间大于30分钟，则停止作种 seed-time=30 ``` # 自定义前端 默认情况下，Cloudreve 会使用内置的静态资源文件，包括 HTML 文档、JS 脚本、CSS、图像资源等。如果您需要使用自己个性化修改后的静态资源，请将[前端仓库](https://github.com/cloudreve/frontend)编译编译得到的`build` 目录重命名为`statics` 并置于 Cloudreve 同级目录下，重启 Cloudreve 后生效。 有关前端仓库的构建流程，请参阅以下章节： {% content-ref url="/pages/-M2GxI0i-XWQfstBtnTW" %} [构建](/getting-started/build) {% endcontent-ref %} {% hint style="warning" %} 请使用与 Cloudreve 主程序版本一致的前端仓库构建，您可以在所使用的 Cloudreve 主仓库的`assets` 子模块找到对应的前端仓库版本。 Pro 版本的前端资源与社区版本不能互相通用。 {% endhint %} 您可以在启动 Cloudreve 时加上`eject` 命令行参数，将内置的静态资源提取到`statics` 目录下： ```bash ./cloudreve -eject ``` # 扩展文档预览/编辑 Cloudreve 会通过文件的扩展名自动选择预览器。Cloudreve 内置了多种文件格式的预览器，包括视频、音频、代码、文本、Office 文档等。其中 Office 文档预览器提供了较高的扩展性，你可以在 后台 - 参数设置 - 图像与预览 - 文件预览 中更换默认的文档预览服务地址。也可以通过开启 WOPI 集成，将 Office 文档预览器替换为更强大的预览/编辑器，并自主定义可被预览/编辑的文件扩展名。本文将介绍三种支持 WOPI 协议的服务的部署及对接方式。你也可以通过实现自己的 WOPI 客户端，扩展 Cloudreve 的预览编辑能力（不仅限于 Office 文档）。 ## Collabora Online (LibreOffice Online) 使用 Docker 部署 Collabora Online（[官方文档](https://sdk.collaboraonline.com/docs/installation/CODE_Docker_image.html#code-docker-image)）： ```sh docker pull collabora/code docker run -t -d -p 127.0.0.1:9980:9980 \ -e "aliasgroup1=<允许使用此服务的 Cloudreve 地址，包含明确端口>" \ -e "username=<面板管理员用户名>" \ -e "password=<面板管理员密码>" \ --name code --restart always collabora/code ``` 以官方演示站为例： ```sh docker run -t -d -p 127.0.0.1:9980:9980 \ -e "aliasgroup1=https://demo.cloudreve.org:443" \ -e "username=<面板管理员用户名>" \ -e "password=<面板管理员密码>" \ --name code --restart always collabora/code ``` Container 启动后，配置 Nginx 或其他 Web 服务器反向代理 `https://127.0.0.1:9980`, 可参考 [Proxy settings](https://sdk.collaboraonline.com/docs/installation/Proxy_settings.html)，确保反代后的服务能够被你的最终用户访问，你可以手动访问 `<你的服务主机>/hosting/discovery` 来确认是否返回了预期的 XML 响应。 在 后台 - 参数设置 - 图像与预览 - 文件预览 - WOPI 客户端 中开启 `使用 WOPI` 并在 `WOPI Discovery Endpoint` 中填入`<你的服务主机>/hosting/discovery`。保存后可在前台测试文档预览和编辑：
## OnlyOffice OnlyOffice 在 6.4 版本后支持了 WOPI 协议，请参考 官方文档 部署你的 [OnlyOffice](https://helpcenter.onlyoffice.com/) 实例。推荐使用 [Docker-DocumentServer](https://github.com/ONLYOFFICE/Docker-DocumentServer) 来快速部署。 参考 [官方文档](https://helpcenter.onlyoffice.com/installation/docs-developer-configuring.aspx#WOPI) 配置 OnlyOffice 开启 WOPI 功能。如果使用 Docker，可在创建 Contianer 时指定 `WOPI_ENABLED` 为 `true` 来开启： ```sh docker run -i -t -d -p 8080:80 -e WOPI_ENABLED=true onlyoffice/documentserver ``` 你可以手动访问 `<你的 OnlyOffice 主机>/hosting/discovery` 来确认是否返回了预期的 XML 响应。 在 后台 - 参数设置 - 图像与预览 - 文件预览 - WOPI 客户端 中开启 `使用 WOPI` 并在 `WOPI Discovery Endpoint` 中填入`<你的服务主机>/hosting/discovery`。保存后可在前台测试文档预览和编辑：
{% hint style="warning" %} OnlyOffice 不支持过滤 WOPI 请求来源，如果你有对公使用需求，请通过外部应用防火墙检查预览页面请求中 `wopisrc` 参数是否为预期的 Cloudreve 站点。 {% endhint %} ## Office Online Server (On-Prem) [Office Online Server](https://learn.microsoft.com/en-us/officeonlineserver/office-online-server) 是微软推出的可私有部署的 Office 在线文档服务。请参考 [官方文档](https://learn.microsoft.com/en-us/officeonlineserver/deploy-office-online-server) 在你的 Windows Server 上部署。 你可以手动访问 `<你的 OnlyOffice 主机>/hosting/discovery` 来确认是否返回了预期的 XML 响应。 在 后台 - 参数设置 - 图像与预览 - 文件预览 - WOPI 客户端 中开启 `使用 WOPI` 并在 `WOPI Discovery Endpoint` 中填入`<你的服务主机>/hosting/discovery`。保存后可在前台测试文档预览和编辑：
{% hint style="warning" %} Office Online Server 不支持过滤 WOPI 请求来源，如果你有对公使用需求，请通过外部应用防火墙检查预览页面请求中 `wopisrc` 参数是否为预期的 Cloudreve 站点。 {% endhint %} ## WOPI 协议 Web Application Open Platform Interface (WOPI) 协议是一种用于集成 Web 文档编辑器的协议，你可以在 [微软的文档](https://learn.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/online/) 中阅读详细的协议定义。Cloudreve 可以对接实现了 WOPI 协议的文档处理服务，用于扩展已有的文档预览和编辑能力。 ### 兼容性 Cloudreve 对 WOPI REST 方法的实现情况如下表所示：
Method支持情况
CheckFileInfo✅
GetFile✅
Lock⚠️（可调用但无效果）
RefreshLock⚠️（可调用但无效果）
Unlock⚠️（可调用但无效果）
PutFile✅
PutRelativeFile❌
RenameFile✅
# 缩略图 Cloudreve 支持使用多种缩略图生成器，为不同类型的文件生成缩略图，包括图像、视频、Office 文档。您也可以借助“缩略图代理”功能扩展原本不支持缩略图生成的存储策略。 ## 缩略图生成逻辑 ### 何时生成 自 3.8.0 开始，Cloudreve 不会在文件上传后立即尝试为其生成缩略图，而是在尝试加载缩略图时生成。这一小节描述了 Cloudreve 会在何时决定加载缩略图。对于每个文件，其缩略图的状态可分为以下三种： * **未知**：新文件上传后的默认状态。在文件列表查看此文件时，Cloudreve 会尝试生成并展示缩略图，如果失败，则将状态标记为`无缩略图`；如果成功，则将状态标记为`缩略图存在`。 * **缩略图存在：**在文件列表查看此文件时，Cloudreve 会尝试加载缩略图。 * **缩略图不存在：**在文件列表查看此文件时，Cloudreve 不会展示缩略图。 在下列情况下，文件的缩略图状态会被重设为`未知`： * 文件被转移到其他存储策略； * 文件被重命名时，处于`缩略图不存在`状态，且文件的扩展名发生变化； * 文件内容被更新。 ### 如何生成 这一小节描述了 Cloudreve 如何为文件生成缩略图。Cloudreve 支持多种缩略图生成器，在生成缩略图时会按照“流水线”模式依此尝试每个生成器，直到有生成器成功返回了缩略图。目前支持的生成器及其尝试顺序如下表所示：
生成器描述不支持的存储策略优先级（高到低）
存储策略原生使用第三方存储策略原生接口生成缩略图，不会产生缩略图文件，只会产生缩略图的 URL 以供重定向。本机、S31
LibreOffice使用 LibreOffice 生成 Office 文档的缩略图。这一生成器依赖于任一其他图像生成器（Cloudreve 内置 或 VIPS）。除了本机存储外，所有未开启“生成器代理”的其他类型存储策略。2
VIPS使用 libvips 处理缩略图图像，支持更多图像格式，资源消耗更低。除了本机存储外，所有未开启“生成器代理”的其他类型存储策略。3
FFmpeg使用 FFmpeg 生成视频缩略图。除了本机存储外，所有未开启“生成器代理”的其他类型存储策略。4
Cloudreve 内置无第三方依赖，使用 Cloudreve 内置的图像处理能力，仅支持 PNG、JPEG、GIF 格式的图片。除了本机存储外，所有未开启“生成器代理”的其他类型存储策略。5
有关各个生成器的详细介绍在后续章节中。 ### 生成器代理 默认情况下，所有非本机存储策略只支持使用存储策略原生生成器，这一生成器速度最快，但支持的文件格式有限，某些存储策略（如 S3）甚至根本不支持缩略图生成。你可以在参数设置 - 图像与预览 - 缩略图 - 生成器代理中为这些存储策略开启“生成器代理”。开启后，如果原生生成器无法产生缩略图，Cloudreve 会尝试将文件下载下来后用流水线生成，再将生成的缩略图回传到存储策略。这一过程速度较慢，更适合自用场景，或者是小规模站点。 ## 生成器 这一章节将详细介绍各个生成器及配置流程。 ### 存储策略原生 在调用此生成器时，Cloudreve 会根据文件扩展及文件大小进行预检查，如果校验失败，Cloudreve 会跳过此生成器。默认的扩展名检查规则是根据各个存储提供商的文档制定，你可以在 专家模式编辑存储策略 - 可生成缩略图的文件扩展名 中覆盖这一规则。这里列出的大小限制独立于 Cloudreve 的缩略图大小统一限制（参数设置 - 图像与预览 - 缩略图 - 基本设置 - 最大原始文件尺寸）。 所有存储策略的默认支持规则如下表： | 存储策略 | 扩展名 | 最大原始文件 | 来源 | | -------- | ----------------------------------- | ------ | ------------------------------------------------------------------------- | | COS | JPG、BMP、GIF、PNG、WebP | 32 MB | | | OneDrive | 不检查扩展名 （直接尝试生成） | 不检查大小 | - | | OSS | JPG、PNG、BMP、GIF、WebP、TIFF、HEIC、AVIF | 20 MB | | | Qiniu | PSD、JPG、PNG、GIF、WebP、TIFF、BMP、AVIF | 20 MB | | | 从机 | PNG、JPG、GIF （可扩展更多生成器，请参阅后续章节） | 不检查大小 | - | | Upyun | JPG、JPEG、PNG、WebP、GIF、BMP、SVG | 不检查 | | 要注意的是，上述检查规则只是 Cloudreve 用于判断是否需要跳转到下一生成器，具体能否生成缩略图取决于存储端。 {% hint style="info" %} #### 从机的原生生成器 从机的原生生成器本质上就是“Cloudreve 内置”生成器。你可以在从机端配置其他生成器，并在存储策略专家模式中覆盖支持的扩展名列表，达到扩展从机原生生成器的效果。 以 VIPS 为例，在从机的配置文件中通过[配置项覆盖](/getting-started/config#fu-gai-cong-ji-jie-dian-de-pei-zhi-xiang)开启 VIPS： ``` [OptionOverwrite] thumb_vips_enabled = 1 thumb_vips_path = vips thumb_vips_exts = csv,mat,img,hdr,pbm,pgm,ppm,pfm,pnm,svg,svgz,j2k,jp2,jpt,j2c,jpc,gif,png,jpg,jpeg,jpe,webp,tif,tiff,fits,fit,fts,exr,jxl,pdf,heic,heif,avif,svs,vms,vmu,ndpi,scn,mrxs,svslide,bif,raw ``` 同理，可以在从机上开启其他生成器： ``` [OptionOverwrite] thumb_builtin_enabled = 1 thumb_ffmpeg_enabled = 1 thumb_ffmpeg_path = ffmpeg thumb_ffmpeg_exts = mp4,avi thumb_ffmpeg_seek = 00:00:01.00 thumb_libreoffice_enabled = 1 thumb_libreoffice_path = soffice thumb_libreoffice_exts = pptx,docx ``` {% endhint %} ### LibreOffice 主页： 此生成器可以为 Office 文档生成缩略图，需要依赖于其他任一支持图片的生成器（VIPS 或者 Cloudreve 原生）。 以 Ubuntu 为例，安装 LibreOffice： ```sh sudo apt install libreoffice ``` ### VIPS 主页： 以 Ubuntu 为例： ```sh sudo apt install libvips-tools ``` Cloudreve 仅支持 8.5 或更新的 libvips，你可以通过如下命令确认安装的版本： ```sh vips -v ``` 某些较老发行版的包管理器中无最新版本的 libvips，推荐从源代码编译安装最新版： ### FFMpeg 主页：[https://ffmpeg.org](https://ffmpeg.org/) 以 Ubuntu 为例： ```shell sudo apt install ffmpeg ``` ### Cloudreve 内置 无需安装第三方库，可直接生成常见图像（PNG、JPEG、GIF）的缩略图。 # 捐助版相关 # 介绍 您可以选择赞助 Cloudreve 的开发，作为回报，您可以获得功能加强的 Cloudreve Pro 版本。 Pro 版本目前的独占特性如下，您可以在[官方演示站](https://demo.cloudreve.org)体验。 * 为同一用户组绑定多个存储策略，用户可自由切换 * 支持在存储策略之间转移文件 * 用户可为不同目录绑定不同存储策略，无缝切换存储策略 * 容量包购买 * 用户购买 * 积分充值 * 激活码（兑换用户组、容量包、积分） * 创建付积分下载的分享 * 第三方支付对接（PAYJS、支付宝当面付） * QQ互联登录 * 保存其他用户分享到自己网盘 * WebDAV 下为不同目录绑定不同存储策略 * 分享举报、处理 * 为新注册的用户指定初始文件 * 站点公告模块 * 注册邮箱后缀白名单/黑名单 * 可加购客户端批量授权 * 为不同用户组设定不同的可用离线下载节点 * (持续更新中...) [详细图文介绍及常见问题>>](https://forum.cloudreve.org/d/1587) 目前捐赠版的限时优惠售价为 ￥399，支持根域相同情况下授权多域名，如 [www.abc.com,pan.abc.com](http://www.abc.com,pan.abc.com). 赞助页面： # iOS 客户端批量授权 ### 关于站点批量授权（VOL） 默认情况下，[Cloudreve iOS 客户端](https://cloudreve.org/ios) 面向最终用户订阅制收费，订阅后用户可以连接绑定所有 Cloudreve 的站点。 站点批量授权允许 Cloudreve 网站管理员为最终用户解锁 iOS 客户端访问权限。为您的站点购买站点批量授权后，最终用户无需订阅也可使用 iOS 免费连接绑定您的 Cloudreve 站点。 ### 价格 每个根域名：￥398 / $63.9 （以购买时的最终价格为准），授权永久有效。 ### 授权条件 * 根域名已经购买 [Cloudreve Pro](https://cloudreve.org/pro) 授权； * Cloudreve Pro 版本 >= 3.6.0; * Cloudreve iOS 客户端版本 >= 1.3.0 ### 购买方法 1. 登录 [Cloudreve Pro 授权管理面板](https://cloudreve.org/login)，找到需要解锁 VOL 的根域名，点击购买授权：
2. 付款购买后，前往您的 Cloudreve 管理面板，在 参数设置 - 站点信息 - 移动客户端 中同步授权：
### 注意事项 * VOL 授权的根域名跟随 Pro 授权根域名，修改后需要重新在 Cloudreve 管理面板同步授权。 * VOL 为去中心化验证，购买后无法退款，请谅解！ * VOL 授权只能解锁您的 Cloudreve 站点，非订阅用户连接其他站点时能需要付费订阅 iOS 客户端。 # 自定义支付渠道 除了 Cloudreve 已经支持的支付平台以外，你也可以通过实现 Cloudreve 的付款接口来对接你自己的支付平台，或是桥接其他第三方平台。 自定义支付接口你实现需要一个独立的 HTTP 服务，并提供： * 暴露一个 API 端点，用于处理 Cloudreve 的创建订单请求，并返回支付页面 URL； * 客户完成支付后，发送 HTTP 请求到指定的 URL 以通知 Cloudreve 支付完成。 ## 支付接口定义 按照本章规范实现你的支付接口，部署接口并确保其能与 Cloudreve 相互进行网络通信。 ### 创建订单 ## 当有新订单创建时，Cloudreve 向支付你的接口发送的请求。 `POST` `<你的支付接口>` #### Headers | Name | Type | Description | | ---------------------- | ------ | -------------------------------------------------------------------- | | Authorization | String |

使用您在后台设定的

通信密钥

计算的签名，详情请参阅“验证请求签名”小节

| | X-Cr-Cloudreve-Version | String | Cloudreve 主程序的版本 | | X-Cr-Site-Id | String | Cloudreve 的站点 ID，可用于区分不同站点 | | X-Cr-Site-Url | String | Cloudreve 的站点 URL | #### Request Body | Name | Type | Description | | --------------------------------------------- | ------ | -------------------------------------------- | | name\* | String | 订单标题 | | order\_no\* | String | 订单编号 | | notify\_url\* | String | 支付成功的回调通知 URL，详情请参考后续“支付成功回调”章节。请存储此项以便后续使用。 | | amount\* | String | 订单总金额，单位：分 | {% tabs %} {% tab title="200: OK 订单创建成功时" %} ```javascript { // 成功的响应固定为 0 "code": 0, // 付款收银台页面的 URL，默认会被生成为二维码展示给用户，用户也可选择直接 // 打开此 URL "data": "https://examplepayment.com/checkout/26544743" } ``` {% endtab %} {% tab title="200: OK 订单创建失败时" %} ```javascript { // 任意非0代码表示订单创建失败 "code": 500, // 错误的详细描述 "error": "Failed to create a payment." } ``` {% endtab %} {% endtabs %} 请求实例： ```http POST /order/create Host: examplepayment.com Authorization: Bearer Vep6hl1x8fiQLasEauMEUqxFKyEqSXb9D_BBQpOiTd8=:1676027218 X-Cr-Site-Url: https://demo.cloudreve.org X-Cr-Site-Id: b7de8bba-8f86-40fe-8171-c2625b6c4a61 X-Cr-Cloudreve-Version: 3.6.2 { "name":"Cloudreve - 10 GB 容量包", "order_no":"20230209190648343421", "notify_url":"http://demo.cloudreve.org/api/v3/callback/custom/20230209190648343421/363f8866-6d0a-4dbf-a560-0c17de2eb7f9?sign=F-AdeTf7cR1uwmV1dqJ1kN_POGivKk_awMRPZUCZyhA%3D%3A1676027208", "amount":100 } ``` #### 验证请求签名 你可以在 Cloudreve 后台设定`通信密钥`，Cloudreve 创建订单的请求会使用此密钥进行加密并放在`Authorization` header 中，你可以通过以下算法验证这一签名： 1. 将 `Authorization` 值中 `Bearer` 之后的部分取出，使用`:`分割字符串，其第二部分是签名过期的时间戳，验证确保其大于当前时间戳。将`:`前一部分记为`SIGNATURE`； 2. 参考 [getSignContent](https://github.com/cloudreve/Cloudreve/blob/b441d884f61d59da86d861b14d1302ec25bbea40/pkg/auth/auth.go#L71) 对请求正文及 header进行编码，并使用 HMAC 算法对编码内容及过期时间戳计算签名：[Sign](https://github.com/cloudreve/Cloudreve/blob/b441d884f61d59da86d861b14d1302ec25bbea40/pkg/auth/hmac.go#L20)； 3. 对比签名后的内容和`SIGNATURE`是否一致。 ### 支付成功回调 当用户完成支付后，你需要向此订单被创建时制定的 `notify_url` 发送一个 GET 请求以通知 Cloudreve 用户完成支付。如果回调请求失败，请以指数后退间隔进行重试，除非响应中明确返回了错误信息及代码。 ## 用户完成支付后，向订单关联的 \`notify\_url\` 发送请求通知 Cloudreve 支付成功。 `GET` `` {% tabs %} {% tab title="200: OK 请求成功" %} ```javascript { "code": 0 } ``` {% endtab %} {% tab title="200: OK 订单处理失败" %} ```javascript { // 任意非0代码表示订单创建失败 "code": 500, // 错误的详细描述 "error": "Failed to fulfill a payment." } ``` {% endtab %} {% endtabs %} ## 添加支付接口 实现并部署支付接口后，请在 Cloudreve 后台 - 增值服务 - 自定义支付渠道 中开启并填写接口地址。 ## 第三方实现 | 支付平台 | 许可 | 文档 | | ---- | ----- | ------------------------------------------------- | | 易支付 | 开放源代码 | | | 爱发电 | MIT许可 | | # 数据库脚本 Cloudreve 内置了一些常用数据库脚本，可用于日常维护、版本升级等操作。您可以在启动时添加命令行参数 `--database-script