【实用的开源工具】Cloudreve：自己的网盘，带 WebDAV 和离线下载

「实用的开源工具」系列：我只收集值得用的开源项目，写清楚它能做什么、怎么部署、有哪些坑，并在文末标明出处。内容整理自官方文档，核对日期 2026-10-31，具体版本以官方为准。文中的命令都是照官方文档整理的，上线前请先在一台测试机上走一遍。

项目信息卡

它能做什么

按官方 README 的功能列表整理：

• 多种存储后端：本地、从属节点（Remote node）、OneDrive、S3 兼容接口、七牛 Kodo、阿里云 OSS、腾讯云 COS、华为云 OBS、金山云 KS3、又拍云。
• 直传存储：上传下载由客户端直接和存储服务商传输。
• 离线下载：与 Aria2 / qBittorrent 联动，在服务器后台下载，完成后放进用户的文件里；可以用多个下载节点分担。
• WebDAV：README 写的是“WebDAV 支持覆盖所有存储提供商”。
• 多用户多用户组、分享链接（可设过期时间）、在线预览视频/图片/音频/ePub，在线编辑文本、Markdown、图片和 Office 文档。
• 压缩/解压/预览压缩包、批量下载、断点续传和并行上传、按元数据或标签搜索。

不适合的场景：官方文档开头写了，下面这些不适合用 Cloudreve：想用它统一管理多个网盘里的文件；想同时用别的文件管理器去管 Cloudreve 里存的文件；想把别家网盘“转售”给用户。官方的意思是，Cloudreve 本身是一个“网盘”，不是“管理其他网盘的工具”。

版本和授权要先搞清楚

• 社区版：开源，GPL-3.0，可以从 GitHub Release 下载二进制，或用镜像 cloudreve/cloudreve。
• Pro 版：官方文档里有单独的 Pro 页签。启动时需要授权密钥，通过命令行参数 --license-key 或环境变量 CR_LICENSE_KEY 传入，密钥从官方的 Pro 授权管理面板获取。Pro 版有自己的镜像仓库，需要先登录。
• 官方文档里能看到的 Pro 相关差异有：Pro 版里一个用户组可以绑定多个存储策略（社区版是一个用户组一个策略）；桌面同步客户端（目前文档写的是 Windows）需要连接 Pro 服务端。Pro 的授权主体是根域名，离线许可证过期后站点会变成只读。
• 从社区版升级到 Pro 版可以保留数据，官方提供了 ./cloudreve proupgrade 命令；文档特别提醒，如果用 SQLite，用户组的存储策略设置会丢失，需要重新配置。
• 我这里只写开源的社区版。Pro 版的具体功能清单和价格，请直接看官方网站，我没有逐项核对。

部署（Docker Compose，v4）

官方推荐 Docker Compose：它默认包含 Cloudreve、PostgreSQL、Redis，并带有 Aria2 离线下载器和缩略图组件（VIPS、FFMpeg、LibreOffice）以及 FFProbe。

官方的做法是克隆它的 compose 仓库：

git clone https://github.com/cloudreve/docker-compose.git ~/cloudreve
cd ~/cloudreve
cp .env.example .env

仓库里有 docker-compose.yml（基础栈：Cloudreve + PostgreSQL + Redis）、docker-compose.pro.yml（Pro 版覆盖文件）和 docker-compose.fts.yml（全文搜索附加组件）。社区版只需要第一个。官方当前的 docker-compose.yml 内容如下，我只把 5212 端口改成了只绑定本机（给反向代理用）：

services:
  cloudreve:
    image: cloudreve/cloudreve:v4
    container_name: cloudreve
    depends_on:
      postgresql:
        condition: service_started
      redis:
        condition: service_started
    restart: unless-stopped
    ports:
      - 127.0.0.1:5212:5212
      - 6888:6888
      - 6888:6888/udp
    environment:
      - CR_CONF_Database.Type=postgres
      - CR_CONF_Database.Host=postgresql
      - CR_CONF_Database.User=cloudreve
      - CR_CONF_Database.Name=cloudreve
      - CR_CONF_Database.Port=5432
      - CR_CONF_Redis.Server=redis:6379
    volumes:
      - backend_data:/cloudreve/data

  postgresql:
    image: postgres:17
    container_name: postgresql
    restart: unless-stopped
    environment:
      - POSTGRES_USER=cloudreve
      - POSTGRES_DB=cloudreve
      - POSTGRES_HOST_AUTH_METHOD=trust
    volumes:
      - database_postgres:/var/lib/postgresql/data

  redis:
    image: redis:latest
    container_name: redis
    restart: unless-stopped
    volumes:
      - redis_data:/data

volumes:
  backend_data:
  database_postgres:
  redis_data:

几点说明：

• 镜像标签 v4 是官方 compose 里的写法；Docker Hub 上同时有 latest 和具体版本标签（如 4.19.1）。想固定版本就改成具体版本号，改之前到 Docker Hub 确认这个标签存在。
• 6888 端口（TCP 和 UDP）是官方说明的“用于 Aria2 远程下载（BT）”的端口，所以我没有把它绑定到本机；如果你不用 BT 下载，可以删掉这两行。
• 这个官方 compose 里的 PostgreSQL 没有发布端口，并且设置了 POSTGRES_HOST_AUTH_METHOD=trust（同一个 Docker 网络里的容器连接数据库不需要密码）。这是官方示例的现状；怎么加固属于我的建议，见踩坑清单。

启动：

docker compose up -d

启动失败或容器不断重启时，官方的排查方法是先找到重启的容器，再看日志：docker logs -f 容器ID。

其他部署方式

• 单个 Docker 容器（官方的写法，默认用 SQLite，适合试用）：

docker run -d --name cloudreve \
    -p 5212:5212 \
    -p 6888:6888 \
    -p 6888:6888/udp \
    -v ~/cloudreve/data:/cloudreve/data \
    cloudreve/cloudreve:latest

官方提醒这种方式没配置数据库，所以用的是 SQLite；要接别的数据库，用 CR_CONF_Database.Type、CR_CONF_Database.Host、CR_CONF_Database.Port、CR_CONF_Database.User、CR_CONF_Database.Password、CR_CONF_Database.Name 这些环境变量。Redis 对应 CR_CONF_Redis.Server 等。

• 直接运行二进制（官方快速开始）：从 GitHub Release 下载对应系统的 cloudreve_版本_系统_架构.tar.gz，解压后 chmod +x ./cloudreve 再运行 ./cloudreve。官方的快速开始页面把它定位为试用；文档里另有 Supervisor 方式，用进程守护工具来跑主程序，数据库和 Redis 要自己配置。

第一次使用

官方文档在 Compose、Docker 和二进制三种方式下的说法一致：

1. 访问 http://localhost:5212（远程服务器可以先做 SSH 端口转发，或者先配好反向代理）。
2. 注册一个账号，第一个注册的账号会被设为管理员。 文档里没有提到默认的管理员账号或默认密码。
3. 登录后访问 你的域名/admin 进入管理后台。官方推荐至少做三件事：修改或添加站点 URL（Site URL）；在“存储策略（Storage Policies）”里添加或修改策略；在“用户组（User Groups）”里添加或修改用户组，并给用户组分配存储策略。

存储策略（Storage Policy）

存储策略决定文件存在哪里、怎么上传下载。官方的概念文档里有几点值得知道：

• 在后台的 Dashboard -> Storage Policies -> New storage policy 里创建。
• 社区版里，每个用户组分配一个存储策略，用户只能用自己所在用户组被分配的策略。
• 本地存储策略默认把文件放在 Cloudreve 可执行文件同目录下的 data/uploads（Blob Storage Directory 可改）。在容器里，官方说 Cloudreve 生成的所有额外文件（头像、配置文件、临时目录等）默认都在 /cloudreve/data 里，所以要把这个目录持久化。
• 一个文件或目录的“首选存储策略”，只决定以后新写入的数据存哪里，不代表已有文件的实际位置。
• 第三方对象存储（OSS、COS、OneDrive、S3 兼容等）的支持程度并不一样，官方有一张对比表（分片上传、缩略图、限速、是否需要回调、是否需要配置 CORS 等）。选之前请看官方的 存储策略对比。
• 需要“回调”的存储策略（对比表里标为 Required 的：从属节点、阿里云 OSS、七牛、又拍云、华为云 OBS），官方说明要求你的站点 URL 设置有效，并且能被存储服务访问到。

WebDAV

这一节要说明白信息来源：

• 官方 README 的功能列表里写了 “WebDAV support covering all storage providers”。
• 但是 V4 文档站（docs.cloudreve.org）目前没有单独的 WebDAV 页面（我查了中英文的 usage/webdav，都是 404），只有在反向代理的配置说明里提到了 WebDAV 的最大上传大小也受 client_max_body_size 影响。
• 完整的 WebDAV 使用说明目前只在 V3 文档（docsv3.cloudreve.org）里：需要先在后台为对应用户组开启 WebDAV 权限；WebDAV 账号和 Cloudreve 账号不互通，要在前台“WebDAV”页面单独创建账号，使用注册邮箱作为用户名、系统生成的密码；连接地址一般是 https://你的域名/dav；V3 文档还警告不要用 Windows 资源管理器自带的 WebDAV 客户端。
• 因为这是 V3 的描述，V4 的界面和路径可能有变化。我没有在 V4 文档里找到对应说明，所以请到你自己部署的站点里实际确认后再用，不要照搬 V3 文档里的路径。

离线下载

官方文档（Remote Download）的流程：

1. 官方 Docker 镜像里 已经带了 Aria2，和 Cloudreve 在同一个容器里运行，监听本机回环地址的 6800 端口，没有设置 RPC token。不需要另外装。
2. 如果要做 BT 下载，需要把 6888 端口（TCP 和 UDP）映射出来；官方还说，如果可以，建议让 Cloudreve 容器使用主机网络（--network host）以获得更好的传输性能。
3. 在 Cloudreve 后台打开节点设置，在“启用的功能”里勾选 Remote Download，填 Aria2 的 RPC 地址和 token（官方镜像里的 Aria2 没设 token），也可以填临时下载目录。临时下载目录留空时用默认的 data/temp，Cloudreve 需要对它有读、写、执行权限。
4. 在对应用户组的编辑页面里，开启远程下载权限。
5. 官方要求：下载器和 Cloudreve 必须能访问同一个目录（绝对路径要一致）。官方镜像内置的 Aria2 不用担心这一点；如果下载器放在别的容器里，要把同一个目录挂载给两边。
6. 如果想用 qBittorrent：官方要求版本高于 4.4，开启 Web UI；注意它只支持磁力链接和种子文件，不支持 HTTP 下载。想下载 HTTP 链接要用 Aria2。

反向代理

官方文档的 Nginx 配置（放在 server 块里）：

location / {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $http_host; # 官方强调：Host 头必须带，否则部分功能不能正常工作
    proxy_redirect off;
    proxy_pass http://127.0.0.1:5212;

    # 如果需要设置最大上传大小，取消注释
    # 官方说理论上本地存储策略的分片大小、WebDAV 最大上传大小、中转上传的最大大小，不应超过这里的设置
    # client_max_body_size 20000m;
}

官方文档里的其他要点：

• 先给域名配好虚拟主机和 HTTPS，再加上面的反向代理规则。官方也说明可以不用反向代理，直接在 data/conf.ini 里加 [SSL] 段，配置 Listen = :443、CertPath、KeyPath 来用内置服务器的 HTTPS。
• 让 Cloudreve 记录真实 IP： 用了反向代理后，真实 IP 会被覆盖，官方的办法是在 data/conf.ini 里设置 ProxyHeader = X-Forwarded-For（在 [System] 段）。配置文件说明里还警告：由于可能存在 XFF 注入问题，只有确认这个头可信时才这么设。
• 缓存： Cloudreve 用 Service Worker 缓存静态资源，官方要求你的 Web 服务器不要缓存 /sw.js、/index.html、/manifest.json。一些服务器管理面板会悄悄加上类似 location ~* \.(js|css|png|...)$ { expires 30d; } 的配置，要去掉，否则版本更新后页面缓存不会更新。
• 通过 Compose 部署时，配置项主要用 CR_CONF_ 开头的环境变量（格式 CR_CONF_<段>.<键>，例如 CR_CONF_System.Listen=:8080）覆盖 conf.ini 里的值。

更新与卸载

更新（官方文档，仅限 V4.x.x 内的升级）：

1. 先备份数据库。官方说：MySQL 可以用 mysqldump，SQLite 直接备份 cloudreve.db 文件。官方也承认理论上升级不会修改当前数据库，但仍建议备份。
2. Docker Compose 部署的升级命令：

docker compose down
docker compose pull
docker compose up -d

1. 如果是单个容器：停止并删除旧容器，用新镜像创建新容器，挂载同一个 /cloudreve/data 目录，并保持与之前相同的其他启动参数。
2. 之后还要去看官方的 Upgrade Cloudreve 页面完成后续步骤。如果你用了从属节点（slave node），它们也要升级到同一个版本。
3. 官方把“从 V3 升级到 V4”单独写成了一页，并明确列出了会丢失的数据（远程下载等后台任务记录、订单记录、举报记录、用户自定义侧边栏、硬件验证器、主题色配置等），分享链接和直链仍然有效。V3 的用户请先读完那一页再动手。

卸载（以下为通用做法，不是官方文档的说法）：docker compose down 只会停掉并删除容器，命名卷里的数据还在；确认不再需要数据后，才用 docker compose down -v 连卷一起删除。直接用本地目录挂载的话，要手动删目录。删之前请先备份。

踩坑清单

1. 第一个注册的账号就是管理员。 官方文档只写了这一条规则，没有默认账号。所以刚部署好就尽快自己注册，别在没注册管理员之前把站点暴露到公网（这是我的判断，原因是谁先注册谁就是管理员）。
2. 不配数据库时用的是 SQLite，不适合高并发。 官方明确说生产环境强烈建议用其他数据库；用官方 Compose 已经默认配好了 PostgreSQL。
3. Redis 可选，但没有 Redis 时缓存是内存缓存。 官方说明没配置 Redis 时，Cloudreve 用内存缓存，并在正常退出前把缓存持久化到 cache_persist.bin。
4. 用环境变量配了数据库或 Redis 的容器，后面改 conf.ini 不生效。 官方的做法是新建一个容器、带上新的配置，并且挂载同一个 /cloudreve/data 目录。
5. 反向代理必须正确传递 Host。 官方在配置里专门注释了这一点；文件下载链接的域名不对、下载不了、缩略图看不到，官方的第一步排查就是检查“站点 URL”列表，并在后台“文件系统”里点“清除 Blob URL 缓存”。
6. 上传失败提示 “Cannot parse response”，里面有 413 Request Entity Too Large。 说明 Nginx 的 client_max_body_size 太小：开分片上传时要比分片大，没开分片上传时要比文件大。
7. Cloudflare 免费版单次上传最大 100MB。 官方建议给存储策略开分片上传，并且分片小于 100MB。
8. 别让 Web 服务器缓存 /sw.js。 否则 Cloudreve 升级后用户的页面缓存不更新。
9. 离线下载的临时目录要两边共享。 Cloudreve 和下载器必须看到同一个目录；下载完成后转存失败并提示 no such file or directory，就是这个问题。
10. BT 下载慢或没速度，Cloudreve 优化不了。 官方说下载任务由下载器处理，可以尝试给 Aria2 手动添加 Tracker 服务器。
11. 官方 Compose 里的 PostgreSQL 用的是 trust 认证、Redis 用 latest 标签。 这是官方示例本身的写法。我的建议是：不要给 PostgreSQL 和 Redis 发布端口，不要把整个 Docker 网络开放给不信任的容器；想固定版本的话，把 redis:latest 也改成具体版本。
12. Pro 版和社区版不是同一个镜像。 社区版用 cloudreve/cloudreve，Pro 版是 release.cloudreve.org/cloudreve/pro:v4，且需要先登录该仓库并提供 CR_LICENSE_KEY。启动时报 “Please specify license key by ...”，说明你用了 Pro 镜像但没传授权密钥。
13. Docker 发布的端口会绕过 ufw 之类的防火墙。 这是通用经验，不是 Cloudreve 文档的说法。所以示例里把 5212 绑定在 127.0.0.1；6888 要对外开放才能 BT 下载，用不到就删掉。

出处

• Cloudreve 官方仓库 README（功能、许可证 GPL V3）
• 官方文档：Quick Start
• 官方文档：部署规划（Plan Deployment）
• 官方文档：Docker Compose 部署
• 官方文档：Docker 部署
• 官方文档：部署后的下一步（反向代理、站点 URL）
• 官方文档：配置文件说明
• 官方文档：概念（存储策略）
• 官方文档：存储策略对比
• 官方文档：本地存储
• 官方文档：远程下载
• 官方文档：升级 Cloudreve
• 官方文档：从 V3 升级
• 官方文档：升级到 Pro 版
• 官方文档：Pro 授权管理（中文）
• 官方 Docker Compose 仓库
• V3 文档：WebDAV（仅 V3，V4 文档站暂无对应页面）