Cloudreve 是什么？

Cloudreve 可以让您快速搭建起公私兼备的网盘系统。Cloudreve 在底层支持不同的云存储平台，用户在实际使用时无须关心物理存储方式。你可以使用 Cloudreve 搭建个人用网盘、文件分享系统，亦或是针对大小团体的公有云系统。

项目地址：https://github.com/cloudreve/Cloudreve

安装Docker🐳

利用Docker-compose搭建，易于更新

使用官方的 docker image，支持三种架构 armv7, arm64 以及 amd64, 你可以使用以下命令部署

需要创建 data 目录作为离线下载临时中转目录

先建立文件夹

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

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

运行镜像

# 后台运行模式，可以从 docker/docker-compose 的日志中获取默认管理员账户用户名和密码
docker-compose up -d

# 或者，直接运行，log 将会直接输出在当前控制台中，请注意退出之后保持当前容器运行
docker-compose up

我们现在可以输入 http://ip:5212/访问了。

在之后的控制面板中，按照如下配置

1. [不可修改] RPC 服务器地址 => http://aria2:6800
2. [可修改, 需保持和 docker-compose.yml 文件一致] RPC 授权令牌 => your_aria_rpc_token
3. [不可修改] Aria2 用作临时下载目录的 节点上的绝对路径 => /data

更新

关闭当前运行的容器，此步骤不会删除挂载的配置文件以及相关目录

docker-compose down

如果此前已经拉取 docker 镜像，使用以下命令获取最新镜像

docker pull cloudreve/cloudreve

配置文件

首次启动时，Cloudreve 会在同级目录下创建名为 conf.ini的配置文件，你可以修改此文件进行一些参数的配置，保存后需要重新启动 Cloudreve 生效。

你也可以在启动时加入 -c参数指定配置文件路径：

./cloudreve -c /path/to/conf.ini

一个完整的配置文件示例如下：

conf.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

配置案例

使用 MySQL

默认情况下，Cloudreve 会使用内置的 SQLite 数据库，并在同级目录创建数据库文件 cloudreve.db，如果您想要使用 MySQL，请在配置文件中加入以下内容，并重启 Cloudreve。注意，Cloudreve 只支持大于或等于 5.7 版本的 MySQL 。

[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

更换数据库配置后，Cloudreve 会重新初始化数据库，原有的数据将会丢失。

使用 Redis

你可以在配置文件中加入 Redis 相关设置：

[Redis]
Server = 127.0.0.1:6379
Password = your password
DB = 0

请为 Cloudreve 指定未被其他业务使用的 DB，以避免冲突。

重启 Cloudreve 后，可注意控制台输出，确定 Cloudreve 是否成功连接 Redis 服务器。使用 Redis 后，以下内容将被 Redis 接管：

• 用户会话（重启 Cloudreve 后不会再丢失登录会话）
• 数据表高频记录查询缓存（如存储策略、设置项）
• 回调会话
• OneDrive 凭证

启用 HTTPS

如果您正在使用 Web 服务器反向代理 Cloudreve，推荐您在 Web 服务器中配置 SSL，本小节所阐述的启用方式只针对使用 Cloudreve 内置 Web 服务器的情境下有效。

在配置文件中加入

[SSL]
Listen = :443
CertPath = C:\Users\i\Documents\fullchain.pem
KeyPath = C:\Users\i\Documents\privkey.pem

其中 CertPath 和 KeyPath 分别为 SSL 证书和私钥路径。保存后重启 Cloudreve 生效。

覆盖从机节点的配置项

Cloudreve 的某些配置项是存储在数据库中的，但是从机节点并不会连接数据库，你可以在配置文件中覆盖相应的配置项。

比如，从机节点作为存储端运行时，你可以通过下面的配置设定从机生成的缩略图规格：

[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

如果从机节点作为离线下载节点使用，你可以通过下面的配置覆盖默认的重试、超时参数，以避免默认的数值过于保守导致文件转存失败：

[OptionOverwrite]
; 任务队列最多并行执行的任务数
max_worker_num = 50
; 任务队列中转任务传输时，最大并行协程数
max_parallel_transfer = 10
; 中转分片上传失败后重试的最大次数
chunk_retries = 10

存储策略对比

中转Cloudreve 支持多种底层存储策略，但是由于 API 限制等各方面因素，Cloudreve 对每种策略的支持程度并不一致，本章节将会详细列出不同存储策略之间的具体支持性区别。

基本对比

高级功能

流量路径

S3 兼容

Cloudreve 利用了以下 S3 API，兼容Backblaze B2 和 Cloudflare R2平台的存储桶对接。

扩展文档预览/编辑

Cloudreve 会通过文件的扩展名自动选择预览器。Cloudreve 内置了多种文件格式的预览器，包括视频、音频、代码、文本、Office 文档等。其中 Office 文档预览器提供了较高的扩展性，你可以在 后台 - 参数设置 - 图像与预览 - 文件预览 中更换默认的文档预览服务地址。也可以通过开启 WOPI 集成，将 Office 文档预览器替换为更强大的预览/编辑器，并自主定义可被预览/编辑的文件扩展名。本文将介绍三种支持 WOPI 协议的服务的部署及对接方式。你也可以通过实现自己的 WOPI 客户端，扩展 Cloudreve 的预览编辑能力（不仅限于 Office 文档）。

Collabora Online (LibreOffice Online)

使用 Docker 部署 Collabora Online（官方文档）：

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

以官方演示站为例：

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，确保反代后的服务能够被你的最终用户访问，你可以手动访问 <你的服务主机>/hosting/discovery 来确认是否返回了预期的 XML 响应。

在 后台 - 参数设置 - 图像与预览 - 文件预览 - WOPI 客户端 中开启 使用 WOPI 并在 WOPI Discovery Endpoint 中填入 <你的服务主机>/hosting/discovery。保存后可在前台测试文档预览和编辑：

OnlyOffice

OnlyOffice 在 6.4 版本后支持了 WOPI 协议，请参考 官方文档 部署你的 OnlyOffice 实例。推荐使用 Docker-DocumentServer 来快速部署。

参考 官方文档 配置 OnlyOffice 开启 WOPI 功能。如果使用 Docker，可在创建 Contianer 时指定 WOPI_ENABLED 为 true 来开启：

复制

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。保存后可在前台测试文档预览和编辑：

OnlyOffice 不支持过滤 WOPI 请求来源，如果你有对公使用需求，请通过外部应用防火墙检查预览页面请求中 wopisrc 参数是否为预期的 Cloudreve 站点。

Office Online Server (On-Prem)

Office Online Server 是微软推出的可私有部署的 Office 在线文档服务。请参考 官方文档 在你的 Windows Server 上部署。

你可以手动访问 <你的 OnlyOffice 主机>/hosting/discovery 来确认是否返回了预期的 XML 响应。

在 后台 - 参数设置 - 图像与预览 - 文件预览 - WOPI 客户端 中开启 使用 WOPI 并在 WOPI Discovery Endpoint 中填入 <你的服务主机>/hosting/discovery。保存后可在前台测试文档预览和编辑：

缩略图

Cloudreve 支持使用多种缩略图生成器，为不同类型的文件生成缩略图，包括图像、视频、Office 文档。您也可以借助“缩略图代理”功能扩展原本不支持缩略图生成的存储策略。

缩略图生成逻辑

何时生成

自 3.8.0 开始，Cloudreve 不会在文件上传后立即尝试为其生成缩略图，而是在尝试加载缩略图时生成。这一小节描述了 Cloudreve 会在何时决定加载缩略图。对于每个文件，其缩略图的状态可分为以下三种：

• 未知：新文件上传后的默认状态。在文件列表查看此文件时，Cloudreve 会尝试生成并展示缩略图，如果失败，则将状态标记为 无缩略图；如果成功，则将状态标记为 缩略图存在。
• **缩略图存在：**在文件列表查看此文件时，Cloudreve 会尝试加载缩略图。
• **缩略图不存在：**在文件列表查看此文件时，Cloudreve 不会展示缩略图。

在下列情况下，文件的缩略图状态会被重设为 未知：

• 文件被转移到其他存储策略；
• 文件被重命名时，处于 缩略图不存在状态，且文件的扩展名发生变化；
• 文件内容被更新。

如何生成

这一小节描述了 Cloudreve 如何为文件生成缩略图。Cloudreve 支持多种缩略图生成器，在生成缩略图时会按照“流水线”模式依此尝试每个生成器，直到有生成器成功返回了缩略图。目前支持的生成器及其尝试顺序如下表所示：

有关各个生成器的详细介绍在后续章节中。

生成器代理

默认情况下，所有非本机存储策略只支持使用存储策略原生生成器，这一生成器速度最快，但支持的文件格式有限，某些存储策略（如 S3）甚至根本不支持缩略图生成。你可以在参数设置 - 图像与预览 - 缩略图 - 生成器代理中为这些存储策略开启“生成器代理”。开启后，如果原生生成器无法产生缩略图，Cloudreve 会尝试将文件下载下来后用流水线生成，再将生成的缩略图回传到存储策略。这一过程速度较慢，更适合自用场景，或者是小规模站点。

生成器

这一章节将详细介绍各个生成器及配置流程。

存储策略原生

在调用此生成器时，Cloudreve 会根据文件扩展及文件大小进行预检查，如果校验失败，Cloudreve 会跳过此生成器。默认的扩展名检查规则是根据各个存储提供商的文档制定，你可以在 专家模式编辑存储策略 - 可生成缩略图的文件扩展名 中覆盖这一规则。这里列出的大小限制独立于 Cloudreve 的缩略图大小统一限制（参数设置 - 图像与预览 - 缩略图 - 基本设置 - 最大原始文件尺寸）。

所有存储策略的默认支持规则如下表：

要注意的是，上述检查规则只是 Cloudreve 用于判断是否需要跳转到下一生成器，具体能否生成缩略图取决于存储端。

从机的原生生成器

从机的原生生成器本质上就是“Cloudreve 内置”生成器。你可以在从机端配置其他生成器，并在存储策略专家模式中覆盖支持的扩展名列表，达到扩展从机原生生成器的效果。

以 VIPS 为例，在从机的配置文件中通过配置项覆盖开启 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

LibreOffice

主页：https://www.libreoffice.org/discover/libreoffice/

此生成器可以为 Office 文档生成缩略图，需要依赖于其他任一支持图片的生成器（VIPS 或者 Cloudreve 原生）。

以 Ubuntu 为例，安装 LibreOffice：

sudo apt install libreoffice

VIPS

主页：https://www.libvips.org/

以 Ubuntu 为例：

sudo apt install libvips-tools

Cloudreve 仅支持 8.5 或更新的 libvips，你可以通过如下命令确认安装的版本：

vips -v

某些较老发行版的包管理器中无最新版本的 libvips，推荐从源代码编译安装最新版：https://www.libvips.org/install.html

FFMpeg

主页：https://ffmpeg.org

以 Ubuntu 为例：

sudo apt install ffmpeg

Cloudreve 内置

无需安装第三方库，可直接生成常见图像（PNG、JPEG、GIF）的缩略图。

数据库脚本

Cloudreve 内置了一些常用数据库脚本，可用于日常维护、版本升级等操作。您可以在启动时添加命令行参数 --database-script <script name> 执行各个脚本。

校准用户容量

如果因为系统故障、手动操作数据库记录导致用户已用空间与实际不符时，你可以运行以下数据库脚本，Cloudreve 会重新校准所有已注册用户的容量使用。

./cloudreve --database-script CalibrateUserStorage

重置管理员密码

以下数据库脚本可以重设初始管理员（即 UID 为 1 的用户）的密码，新密码会在命令行日志中输出，请注意保存。

./cloudreve --database-script ResetAdminPassword

反向代理

参考教程：安装及使用

⚠️Nginx Proxy Manager（以下简称NPM）会用到80、443端口，所以本机不能占用（比如原来就有Nginx）

互联网使用请确保完成了域名解析