Docker搭建Cloudreve私人网盘教程

经常需要把图片、文档和项目文件发给客户，可以考虑搭建一个自己的文件分享平台。

本篇教程使用 Docker Compose 部署 Cloudreve 私人网盘，搭配 Caddy 自动配置 HTTPS，实现文件上传、图片预览和链接分享。文件保存在自己的服务器上，日常使用通过浏览器完成。

教程从安装 Docker 开始，依次完成域名配置、创建管理员、本地存储设置、分享下载和数据备份。

1. 项目介绍

Cloudreve 是一个开源网盘程序，可以将服务器本地磁盘及其他存储服务接入统一的文件管理界面。

本次教程主要使用以下功能：

文件管理： 在浏览器中创建文件夹、上传和整理文件。
在线预览： 直接查看常见图片等受支持的文件。
链接分享： 将文件分享给客户或其他人下载。
本地存储： 将上传内容保存在自己的服务器磁盘中。
用户管理： 通过管理面板设置用户组及存储策略。

本次采用 Cloudreve、PostgreSQL、Redis 和 Caddy 组成的部署方案。其中，Caddy 负责 HTTPS 访问，Cloudreve 负责网盘功能，数据库和缓存通过 Docker 内部网络连接。部署方式参考 Cloudreve 官方 Docker 文档。

2. 相关地址

项目地址： Cloudreve GitHub
官方文档： Cloudreve 使用文档
Docker 部署说明： Cloudreve Docker 部署
本站 Docker 教程： Docker 安装教程

本文已包含本次部署需要的 Docker 安装步骤，可以直接往下操作。

3. 搭建环境

本次建议准备一台独立的 Linux 云服务器，使用以下配置进行个人或小团队演示：

CPU：建议 2 核及以上
内存：建议 4GB 及以上
磁盘：系统及应用建议预留至少 20GB，上传文件所需空间另外计算
系统：Debian 12 或 Ubuntu 24.04
Docker：使用 Docker Engine
Compose：使用 docker compose 插件
域名：准备一个可以修改 DNS 解析的域名或子域名
公网端口：TCP 80 和 443
Cloudreve：本教程固定使用 4.19.1

以上是本教程的建议配置。实际需求取决于文件数量、访问人数和使用方式。

本次使用服务器本地磁盘保存文件。计划长期存放照片、视频或客户资料时，应提前规划磁盘容量，并准备异机备份空间。

本次教程推荐使用莱卡云 Linux 云服务器进行搭建。

查看官网购买链接： https://www.lcayun.com

9折优惠码：bloglcayun

4. 搭建视频

本期视频演示以下操作：

安装并验证 Docker 和 Compose。
配置网盘域名和部署文件。
启动 Cloudreve，通过 HTTPS 访问。
创建管理员并设置本地存储。
上传文件、预览图片并创建分享。
模拟客户下载文件。
备份数据库、文件和配置。

建议对照下方文字教程操作，终端命令可直接复制使用。

5. 正式搭建

以下命令在服务器的 Bash 终端中执行，使用 root 用户。

如果当前使用的是具有 sudo 权限的普通用户，先执行：

sudo -i

本教程按全新部署编写。如果服务器已经运行 Cloudreve，请保留原有配置、数据库密码和数据目录。

5.1 安装 Docker 和 Compose

已经安装 Docker 的，可以先执行本节后面的验证命令；验证通过后跳过安装。

在 Debian 12 或 Ubuntu 24.04 上，执行：

(
  set -e
  . /etc/os-release
  case "$ID" in
    debian) cloudreve_dist=debian; cloudreve_suite="$VERSION_CODENAME" ;;
    ubuntu) cloudreve_dist=ubuntu; cloudreve_suite="${UBUNTU_CODENAME:-$VERSION_CODENAME}" ;;
    *) echo "本教程仅适用于 Debian 或 Ubuntu"; exit 1 ;;
  esac
  apt-get update
  apt-get install -y ca-certificates curl openssl
  install -m 0755 -d /etc/apt/keyrings
  curl -fsSL "https://download.docker.com/linux/$cloudreve_dist/gpg" \
    -o /etc/apt/keyrings/docker.asc
  chmod a+r /etc/apt/keyrings/docker.asc
  cat > /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/$cloudreve_dist
Suites: $cloudreve_suite
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
  apt-get update
  apt-get install -y docker-ce docker-ce-cli containerd.io \
    docker-buildx-plugin docker-compose-plugin
  systemctl enable --now docker
)

上述安装方式使用 Docker 官方软件源，并安装 Compose 插件。

安装完成后，依次执行：

docker --version
docker compose version
systemctl is-active docker
docker run --rm hello-world

正常情况下：

前两条命令显示版本信息。
Docker 服务状态显示 active。
测试容器输出包含 Hello from Docker!。

如果镜像下载失败，先检查服务器到镜像仓库的网络连接，确认测试容器可以运行后再继续。

若跳过了 Docker 安装，请另外确认已安装密码生成所需的工具：

apt-get update
apt-get install -y openssl

关于 Docker 的基础操作，也可以阅读本站的 Docker 安装教程。本次项目统一使用带空格的 docker compose 命令。

5.2 配置域名与端口

假设准备使用以下子域名：

pan.example.com

进入域名的 DNS 管理页面，添加一条 A 记录：

项目	填写内容
记录类型	A
主机记录	pan
记录值	服务器公网 IPv4 地址
TTL	使用默认值

其中，example.com 必须替换为自己的域名。

本次先使用直接 DNS 解析。没有配置 IPv6 时，不要为该子域名添加 AAAA 记录。

在云服务器安全组及系统防火墙中放行：

TCP 80
TCP 443

保留当前使用的 SSH 端口，方便继续管理服务器。

同时确认服务器的 80 和 443 端口没有被其他网站程序占用。如果已有宝塔、Nginx 或其他业务占用这些端口，建议使用独立服务器完成本教程。

5.3 创建目录和基础配置

先把下面命令中的 pan.example.com 替换为自己的网盘域名。

这里只填写域名，不要加 https://，也不要加路径或端口。

然后执行：

mkdir -p /opt/cloudreve/{data,postgres-data,redis-data,caddy,caddy-data,caddy-config}
cd /opt/cloudreve
(
  set -e
  if [ -e .env ]; then
    echo "已有 .env，请保留原配置，不要重复生成数据库密码。"
    exit 1
  fi
  umask 077
  cat > .env <<EOF
CLOUDREVE_DOMAIN=pan.example.com
POSTGRES_PASSWORD=$(openssl rand -hex 24)
EOF
)

这一步会创建项目目录，并自动生成数据库密码。

如果提示已经存在 .env，说明目录中有旧配置，请保留原文件。已经初始化的数据库，不能通过重新生成 .env 来更改密码。

接着，在当前 /opt/cloudreve 目录中创建 Caddy 配置：

cat > caddy/Caddyfile <<'CADDY'
{$CLOUDREVE_DOMAIN} {
    reverse_proxy cloudreve:5212
}
CADDY

Caddy 会使用 .env 中填写的域名，为网站申请和续期 HTTPS 证书，并将访问请求转发给 Cloudreve。域名解析及公网端口需要正常。

这份配置在创建管理员后继续使用。

5.4 创建 Compose 配置

继续在 /opt/cloudreve 目录执行以下完整命令：

cat > compose.yaml <<'YAML'
name: cloudreve
services:
  cloudreve:
    image: cloudreve/cloudreve:4.19.1
    restart: unless-stopped
    environment:
      TZ: Asia/Shanghai
      CR_CONF_Database.Type: postgres
      CR_CONF_Database.Host: postgres
      CR_CONF_Database.Port: "5432"
      CR_CONF_Database.User: cloudreve
      CR_CONF_Database.Name: cloudreve
      CR_CONF_Database.Password: ${POSTGRES_PASSWORD:?请先生成.env}
      CR_CONF_Redis.Server: redis:6379
    volumes:
      - ./data:/cloudreve/data
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
  postgres:
    image: postgres:17
    restart: unless-stopped
    environment:
      POSTGRES_USER: cloudreve
      POSTGRES_DB: cloudreve
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?请先生成.env}
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U cloudreve -d cloudreve"]
      interval: 10s
      timeout: 5s
      retries: 10
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - ./redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 10
  caddy:
    image: caddy:2-alpine
    restart: unless-stopped
    environment:
      CLOUDREVE_DOMAIN: ${CLOUDREVE_DOMAIN:?请填写域名}
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./caddy:/etc/caddy:ro
      - ./caddy-data:/data
      - ./caddy-config:/config
    depends_on:
      - cloudreve
YAML

本次对外提供访问的是 Caddy 的 80 和 443 端口。Cloudreve、PostgreSQL 和 Redis 通过 Docker 内部网络通信。

数据分别保存在项目目录下，容器重建后可以继续使用这些持久化数据。

5.5 启动 Cloudreve

依次执行以下命令，每条成功后再继续下一条：

docker compose config -q
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=50 caddy cloudreve

说明：

config -q 用于检查配置，成功时通常没有输出。
pull 用于下载镜像。
up -d 用于在后台启动服务。
ps 用于查看容器状态。
logs 用于查看启动日志。

正常情况下，PostgreSQL 和 Redis 会显示健康状态，Cloudreve 和 Caddy 持续运行。

首次启动时，需要等待数据库初始化和 HTTPS 证书签发。服务正常后，在浏览器打开：

https://pan.example.com

将示例域名替换为自己的实际域名，然后及时完成下一节的管理员创建。

6. 创建管理员并完成基础设置

6.1 创建管理员账户

打开自己的 HTTPS 网盘地址，进入注册页面。

按照页面提示填写：

自己控制的邮箱地址
独立的高强度密码
页面要求的其他信息

Cloudreve 的首个注册用户会成为管理员，因此服务启动后应及时创建自己的账户。 如果已经创建过账户，直接登录即可。

注册并登录后，打开：

https://pan.example.com/admin

将域名替换为实际域名，即可进入管理面板。

本次基础演示不需要自建邮局。邮件通知、邮箱验证和邮件找回密码等功能，可以在后续按实际需求配置 SMTP。

6.2 设置站点 URL

在管理面板的参数设置中，找到站点 URL，将其设置为自己的完整 HTTPS 地址，例如：

https://pan.example.com

保存设置。

站点 URL 应与日常访问网盘使用的地址保持一致，避免生成的文件地址指向旧域名或错误地址。

6.3 检查本地存储策略

在管理面板中找到存储策略，检查本机存储策略。

本次将本地文件的 Blob 目录设置为：

/cloudreve/data/uploads

这是容器内的路径，对应服务器上的：

/opt/cloudreve/data/uploads

然后检查当前账户所属用户组，确认已经分配该存储策略，并具有足够的存储配额。

如果默认策略已经满足以上条件，核对后即可继续使用。Cloudreve 的存储策略需要与用户组对应，才能按预期处理文件上传。

日常文件管理通过网盘界面进行，避免直接在服务器上传目录中手动添加或删除文件，造成文件记录与实际内容不一致。

7. 上传文件与在线预览

7.1 上传演示文件

返回网盘首页，新建一个文件夹：

演示交付

准备两个普通文件：

一张 JPG 图片
一个 TXT 说明文件

建议先使用较小的文件完成测试，再尝试上传大文件。

将文件拖入页面，或使用上传按钮选择文件。

等待上传完成后：

确认列表中出现两个文件。
检查文件名称和大小。
刷新页面，确认文件仍然存在。

完成这些检查后，再进行预览与分享。

7.2 预览图片

点击刚刚上传的 JPG 图片，检查是否能够正常打开预览。

本次先用常见图片格式验证预览功能。其他格式是否支持在线查看，取决于 Cloudreve 的功能、相关配置和浏览器支持情况。

文件保存在服务器本地磁盘中。后续使用时，需要关注服务器剩余空间和用户存储配额。

8. 创建分享链接并验证客户下载

选择刚刚上传的演示文件，创建分享。

根据实际需要设置分享选项，然后复制系统生成的完整分享链接。

为了模拟客户使用，打开浏览器无痕窗口，粘贴分享链接进行测试：

确认分享页面可以打开。
确认页面展示的是准备交付的文件。
点击下载，等待下载完成。
打开下载文件，检查内容是否正常。

无痕窗口可以避免当前管理员登录状态影响测试结果。也可以用手机移动网络访问一次，确认其他网络能够正常打开分享页面。

如果需要进一步确认下载内容与原文件一致，可以在 Windows PowerShell 中分别计算两个文件的 SHA256：

Get-FileHash -Algorithm SHA256 "原文件的完整路径"
Get-FileHash -Algorithm SHA256 "下载文件的完整路径"

将路径替换为真实文件路径。两次输出的哈希值应一致。

演示结束后，返回网盘取消这条分享，再使用无痕窗口重新打开原链接，确认分享已经失效。

取消分享会停止原链接继续提供访问，但不会删除对方已经下载到本地的文件副本。

9. 数据备份与版本更新

9.1 备份数据库、文件和配置

Cloudreve 的完整备份需要同时保存数据库、上传文件和相关配置。

以下命令会短暂停止 Cloudreve、Redis 和 Caddy，保留 PostgreSQL 运行以导出数据库。执行前请等待上传任务完成，并确认服务器有足够的备份空间。

(
  set -e
  cd /opt/cloudreve
  umask 077
  cloudreve_backup="/opt/cloudreve-backups/$(date +%Y%m%d-%H%M%S)"
  mkdir -p "$cloudreve_backup"
  trap 'docker compose up -d' EXIT
  docker compose stop cloudreve redis caddy
  docker compose exec -T postgres pg_dump -U cloudreve -d cloudreve \
    -Fc > "$cloudreve_backup/database.dump"
  tar -czf "$cloudreve_backup/files.tar.gz" \
    .env compose.yaml caddy data redis-data caddy-data caddy-config
  test -s "$cloudreve_backup/database.dump"
  tar -tzf "$cloudreve_backup/files.tar.gz" >/dev/null
  echo "备份目录：$cloudreve_backup"
)
cd /opt/cloudreve
docker compose ps

正常完成后，会输出本次备份目录，目录内包含：

文件	内容
`database.dump`	PostgreSQL 数据库导出文件
`files.tar.gz`	上传文件、应用配置、Redis 数据及 Caddy 数据

脚本退出时会尝试恢复服务。执行结束后，检查容器状态，并再次确认网盘可以登录和下载文件。

两个备份文件需要一起保存，并复制到其他设备。 只保存在同一台服务器上，无法应对整机或磁盘故障。

备份中包含账户数据、数据库密码和证书私钥，应妥善保管。正式依赖备份前，还应在独立环境进行恢复演练。

9.2 更新 Cloudreve

本教程固定使用 cloudreve/cloudreve:4.19.1，便于文章和录屏保持一致。

后续更新时：

先完成数据备份。
阅读目标版本的更新说明。
将 compose.yaml 中的 Cloudreve 镜像标签修改为确认存在的目标版本。
再执行更新命令。

cd /opt/cloudreve
docker compose config -q
docker compose pull cloudreve
docker compose up -d --no-deps cloudreve
docker compose ps
docker compose logs --tail=50 cloudreve

更新完成后，重新验证登录、上传、预览和分享下载。

如果镜像标签没有修改，执行 pull 不会自动选择其他版本。PostgreSQL 的主版本升级涉及数据迁移，应单独规划。

10. 常见问题

10.1 HTTPS 打不开，或者证书申请失败

优先检查以下项目：

域名 A 记录是否指向当前服务器公网 IP。
是否存在指向错误地址的 AAAA 记录。
云安全组和系统防火墙是否放行 TCP 80、443。
服务器上的 80、443 是否被其他程序占用。
.env 中的域名是否拼写正确。

查看 Caddy 日志：

cd /opt/cloudreve
docker compose logs --tail=100 caddy

根据日志处理解析、端口或证书签发问题，确认 HTTPS 正常后再登录。

10.2 页面显示 502，或者容器反复重启

先查看服务状态和日志：

cd /opt/cloudreve
docker compose ps
docker compose logs --tail=100 cloudreve postgres redis

重点检查：

PostgreSQL 和 Redis 是否正常运行。
.env 中的数据库密码是否被重新生成或修改。
磁盘是否还有可用空间。
日志是否存在数据库连接或目录权限错误。

已有数据的部署需要保留原数据库密码，排错时不要删除数据库目录重新开始。

10.3 上传失败，或者图片无法预览

检查：

当前用户组是否分配了正确的存储策略。
用户剩余配额是否足够。
服务器磁盘空间是否足够。
本地存储路径和目录权限是否正确。
管理面板中的站点 URL 是否为当前 HTTPS 域名。

如果曾经修改域名，生成的文件地址仍然使用旧地址，可核对站点 URL，并按官方说明清理 Blob URL 缓存后重新获取链接。

10.4 自己能打开，客户却打不开分享链接

先使用无痕窗口，并换到手机移动网络测试。

随后检查：

是否复制了系统生成的完整分享链接。
分享是否已经过期或被取消。
分享设置是否允许目标访客访问。
网盘域名是否能够从其他网络正常访问。
HTTPS 证书是否有效。

不要只凭管理员登录后的页面判断客户也能正常下载，应实际完成一次访客下载。

11. 写在最后

完成以上步骤后，就可以通过自己的 HTTPS 域名使用 Cloudreve，上传文件、预览图片，并通过分享链接向客户交付资料。

本次采用服务器本地存储，适合先从个人文件管理和小规模交付开始。长期使用时，应关注磁盘空间、分享记录和备份情况，升级前先做好数据备份。

如果还想监控网盘是否可以正常访问，可以继续参考本站的 Uptime Kuma 搭建教程，为 Cloudreve 的 HTTPS 地址添加监控。