Cloudreve 私人云盘搭建教程：从部署到文件共享传输避坑指南

简介这是一套基于Cloudreve的私人云盘源码面向希望自建文件存储与共享服务的个人用户、小型团队及企业IT人员可用于搭建本地化网盘系统实现文件备份、共享与传输。压缩包共约2000个文件整体19.42MB以776个PHP核心程序、322个JavaScript脚本、148个HTML页面和71个CSS样式为主另含23个SQL数据库脚本、46个JSON配置及44个Markdown说明文档覆盖前端界面、后端逻辑与部署配置。资源附带以宝塔面板为例的安装视频教程涵盖PHP7.0以上环境、fileinfo扩展安装、数据库创建、源码上传及伪静态规则配置等关键环节并提示URL Rewrite常见问题。目前已有699人学习下载。读者可获得一套结构完整、界面简洁的云网盘系统源码支持多格式文件与视频共享适合用于单位内部数据备份或二次开发学习目录清晰便于按模块查阅。1. 从一套私人云盘源码说起Cloudreve 能解决哪些真实需求很多人第一次接触 Cloudreve是因为受够了公有网盘的限速、弹窗和会员墙想在自己的云主机上搭一套「私人云盘源码」。Cloudreve 就是这类需求里被反复提到的一个方案它是一套开源的云网盘系统用 Go 写后端、前端是 SPA支持本地存储、对象存储、WebDAV、离线下载、多用户和文件共享传输。标题里说的「简洁好看」不是虚的它的默认主题确实干净后台管理也做得比较完整装完之后给同事、家人或小团队用体验接近商业网盘。这套东西适合谁一类是有云主机、想给自己和几个朋友做文件共享传输的人一类是小团队想内部传素材、发大文件又不想把数据全交给第三方还有一类是拿它当练手项目顺便学一下反向代理、数据库、对象存储怎么串起来。它不适合的是完全不懂命令行、也不愿意碰服务器的人——虽然有一键脚本和安装视频教程但真出问题时还是得能看懂日志和配置。下面我按「先讲清楚它是什么、再动手搭、最后说坑」的顺序把一套能跑起来的 Cloudreve 云盘系统讲透。2. Cloudreve 云盘系统的架构与部署选型为什么这么搭2.1 后端、数据库、存储三层到底怎么分工Cloudreve 的运行可以拆成三层来看。第一层是 Cloudreve 主程序本身它是一个编译好的二进制文件负责处理 HTTP 请求、用户鉴权、文件元数据管理和分享逻辑。第二层是数据库默认用 SQLite生产环境一般换成 MySQL 或 PostgreSQL存的是用户表、文件记录、分享链接这些结构化数据。第三层是存储后端也就是文件实体真正放的地方可以是服务器本地磁盘也可以是对象存储比如 S3 兼容的 MinIO、阿里云 OSS、腾讯云 COS 等。理解这三层分工后面配置才不会乱。很多人翻车是因为把「数据库」和「文件存储」混为一谈以为换了数据库文件就搬家了其实文件实体在存储策略里数据库只记路径和元信息。选型上个人自用 SQLite 完全够省一个服务小团队并发上传下载多建议直接上 MySQL避免 SQLite 写锁在并发时拖后腿。存储这块如果云主机磁盘不大强烈建议一开始就接对象存储本地只留缓存和缩略图扩容时不用迁移数据。2.2 云主机系统与运行环境的选择云主机用什么系统直接决定后面命令怎么写。Cloudreve 官方发布的二进制对 Linux 支持最好常见做法是选 Debian 12 或 Ubuntu 22.04 这类长期支持版本包管理熟、社区资料多。如果你习惯 CentOS 系Rocky Linux 9 也能跑但要注意它默认的防火墙和 SELinux 策略容易在反向代理那一步卡住。Windows Server 也能运行但生产环境不推荐主要是权限和守护进程管理麻烦。运行环境上Cloudreve 本体不需要额外装 Go 或 Node下载对应架构的压缩包解压即可。真正需要额外准备的是反向代理一般用 Nginx 或 Caddy。Nginx 资料多、可控性强Caddy 配置简单、自动签证书。我的习惯是面向公网、要配 HTTPS 和自定义规则的用 Nginx只是内网或想省事的用 Caddy。下面这张表把两种常见组合列清楚方便你按自己情况选。组件轻量自用方案小团队方案操作系统Debian 12Ubuntu 22.04数据库SQLiteMySQL 8存储后端本地磁盘S3 兼容对象存储反向代理CaddyNginx进程守护systemdsystemd2.3 用 systemd 把 Cloudreve 跑成常驻服务下载解压之后直接./cloudreve能跑但一关终端就停这不是生产做法。正确姿势是交给 systemd 管理。先建一个专用用户避免用 root 跑# 创建专用系统用户不允许登录 sudo useradd -r -s /sbin/nologin cloudreve # 建目录并授权 sudo mkdir -p /opt/cloudreve sudo chown -R cloudreve:cloudreve /opt/cloudreve # 把解压后的程序放进去假设已解压到当前目录 sudo mv cloudreve /opt/cloudreve/ sudo chmod x /opt/cloudreve/cloudreve接着写 systemd 单元文件关键是WorkingDirectory要指向程序所在目录因为 Cloudreve 默认在当前目录生成conf.ini和数据库文件# /etc/systemd/system/cloudreve.service [Unit] DescriptionCloudreve Afternetwork.target [Service] Usercloudreve Groupcloudreve WorkingDirectory/opt/cloudreve ExecStart/opt/cloudreve/cloudreve Restarton-failure RestartSec5 [Install] WantedBymulti-user.target写完执行sudo systemctl daemon-reload再sudo systemctl enable --now cloudreve。这里有个参数要留意Restarton-failure保证程序崩溃后自动拉起RestartSec5是重试间隔别设太短否则端口没释放就重启会反复失败。启动后用systemctl status cloudreve看状态第一次运行会在/opt/cloudreve下生成初始管理员账号密码务必记下来这是登录后台的唯一入口。3. 从零跑通 Cloudreve反向代理、HTTPS 与文件共享传输配置3.1 Nginx 反向代理的最小可用配置Cloudreve 默认监听 5212 端口直接暴露这个端口既不安全也不方便配证书所以要用 Nginx 反代。核心是把域名请求转发到本地 5212同时把上传大文件需要的client_max_body_size调大否则超过默认 1M 的上传会直接 413。下面是一份能直接抄的配置server { listen 80; server_name pan.example.com; # 换成你自己的域名 # 上传大文件必须放开否则 413 client_max_body_size 2048m; location / { proxy_pass http://127.0.0.1:5212; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 长连接和超时传大文件时很关键 proxy_http_version 1.1; proxy_read_timeout 3600s; proxy_send_timeout 3600s; } }proxy_set_header这几行不是可选项Cloudreve 要靠X-Forwarded-Proto判断用户是不是走的 HTTPS缺了它后台生成的分享链接可能变成 http浏览器会拦。proxy_read_timeout和proxy_send_timeout设到 3600 秒是为了大文件传输时不被 Nginx 提前掐断。改完nginx -t测试语法再systemctl reload nginx生效。3.2 用 Certbot 给云盘加上 HTTPS没有 HTTPS 的网盘浏览器会标「不安全」分享出去的链接别人也不敢点。用 Certbot 签 Lets Encrypt 证书是最省事的做法# 安装 certbot 和 nginx 插件 sudo apt install certbot python3-certbot-nginx -y # 自动改写 nginx 配置并申请证书 sudo certbot --nginx -d pan.example.com执行过程中会问你是否强制跳转 HTTPS选 2Redirect即可。Certbot 会自动往你的 server 块里插入 443 监听和证书路径并加一条 80 跳 443 的规则。证书 90 天过期Certbot 装好后会自动加定时任务续期可以用sudo certbot renew --dry-run模拟一次确认续期流程没问题。这里要注意如果你的域名解析还没生效或者 80 端口被占用申请会失败先把这两件事确认好再跑。3.3 存储策略与文件共享传输的落地设置登录后台后第一件事是配存储策略。默认策略指向本地uploads目录个人用没问题。如果要接对象存储在「存储策略」里新建填 Endpoint、Bucket、AccessKey、SecretKey注意路径风格PathStyle这个开关MinIO 一般要打开云厂商的 OSS 通常关闭。配好后把默认策略切过去新上传的文件就走对象存储了。文件共享传输这块Cloudreve 支持生成分享链接、设置提取码和过期时间。分享外链的域名取决于你后台「站点 URL」的设置一定要填成https://pan.example.com否则生成的链接会带内网 IP 或错误端口。WebDAV 也是它的一大亮点在「WebDAV」里开启后可以用 RaiDrive、Windows 映射网络驱动器等方式挂载把云盘当本地盘用。开启 WebDAV 后记得在 Nginx 里也放行对应路径否则挂载会 404。4. 搭建 Cloudreve 最容易翻车的几个地方避坑与排查4.1 上传大文件报 413 或传到一半中断现象是上传几百兆的文件时浏览器提示 413 Request Entity Too Large或者进度条走到一半卡死。原因有两处一是 Nginx 的client_max_body_size没改默认 1M二是proxy_read_timeout太短大文件传输时间超过默认 60 秒被断开。解决办法是把这两个参数按 3.1 的配置调大client_max_body_size设成你允许的最大单文件大小超时设到 3600 秒。改完 reload Nginx再传一次验证。4.2 分享链接打开是 http 或指向内网 IP现象是后台生成的分享链接复制出来是http://开头或者域名变成了127.0.0.1。原因是 Nginx 没传X-Forwarded-Proto或者后台「站点 URL」没设对。先在 Nginx 配置里补上proxy_set_header X-Forwarded-Proto $scheme;再到后台把站点 URL 改成完整的https://域名。两处都改完重新生成分享链接就正常了。这个坑很隐蔽因为后台自己访问没问题只有分享出去才暴露。4.3 systemd 启动失败提示权限或目录错误现象是systemctl status cloudreve显示 failed日志里报 permission denied 或找不到 conf.ini。原因是程序运行用户对/opt/cloudreve没有写权限或者WorkingDirectory写错。解决方法是确认目录属主是 cloudreve 用户chown -R cloudreve:cloudreve /opt/cloudreve并检查单元文件里WorkingDirectory和ExecStart路径一致。改完daemon-reload再重启。用 root 跑虽然能绕过但不建议出了安全问题得不偿失。4.4 数据库换 MySQL 后连不上或表结构缺失现象是把 SQLite 换成 MySQL 后程序启动报连接错误或者能连上但登录后台提示表不存在。原因是conf.ini里的数据库配置格式写错或者没让 Cloudreve 自己初始化表结构。正确做法是先在 MySQL 里建好库和用户然后在conf.ini的[Database]段填对Type、Host、Port、User、Password、Name首次启动时 Cloudreve 会自动建表。注意Type要写mysql端口默认 3306字符集建议库级设成utf8mb4否则中文文件名可能乱码。4.5 WebDAV 挂载成功但无法写入现象是 WebDAV 能挂载、能看文件列表但上传或重命名时报错。原因通常是 Nginx 没有正确转发 WebDAV 需要的 HTTP 方法如 PROPFIND、PUT、MKCOL或者存储目录权限不足。解决方法是确认反代配置里没有限制请求方法并检查存储后端目录对 cloudreve 用户可写。如果是对象存储还要确认 AccessKey 有写权限。这个坑排查时先看 Nginx 的 access.log里面会记录具体是哪个方法被拒。5. 让 Cloudreve 更好用离线下载、多用户与备份的进阶技巧把基础跑通之后真正拉开体验差距的是几个进阶设置。第一个是离线下载Cloudreve 支持对接 Aria2 或 qBittorrent把磁力、种子任务丢给它们下载完成后自动入库。配置时在后台「离线下载」里填 RPC 地址和密钥Aria2 那边要开--rpc-secret两边密钥一致才能连上。这个功能对经常下素材的人很实用但要注意磁盘空间别让下载目录把系统盘撑爆。第二个是多用户和容量配额。Cloudreve 支持给每个用户设独立容量和上传策略小团队用的时候建议按角色分组管理员只留一两个普通用户默认走限速策略避免个别人占满带宽。配额在用户组里设改完对新上传立即生效但已用容量不会自动重算必要时手动刷新。第三个是备份这是我最想强调的。血泪经验是数据库和存储目录必须一起备份只备份其中一个恢复出来就是残缺的。SQLite 直接拷cloudreve.dbMySQL 用mysqldump存储目录如果是本地用rsync增量同步到另一块盘或另一台机器。我一般写个定时脚本每天凌晨跑一次保留最近 7 天。恢复时先停服务还原数据库和文件再启动顺序反了会出元数据和实体对不上的问题。最后一个技巧是验证。搭完之后别只看首页能打开要实际走一遍注册普通用户、上传一个大文件、生成分享链接用无痕窗口打开、用 WebDAV 挂载传一个文件、再删掉。这一圈走下来反向代理、权限、存储、分享四条链路才算真的通了。我自己每次重装都会走这套流程比看任何文档都靠谱。希望帮到你。本文还有配套的精品资源点击获取