简介：基于 Go 语言开发的 Cloudreve 个人网盘系统完整源码，定位明确：帮助个人或小型团队摆脱商业网盘限速、涨价与隐私顾虑，快速搭建自主可控的文件管理分享平台。源码采用后端 Go+Gin、前端 React+Redux+Material-UI 的架构，内置多用户管理、文件分享链接、有效期/访问密码/下载次数限制等权限控制机制，并抽象存储驱动，支持本地、七牛、阿里云 OSS、腾讯云 COS、又拍云、OneDrive 等主流后端，具备较强的扩展性。zip 压缩包共 341 个文件，以 Go 源码为主（314 个），另有 YAML、Dockerfile、Markdown 与依赖管理文件，覆盖容器化部署、服务配置与项目说明，整体约 594KB，轻量易读。已有 656 人学习下载。对想研究云存储多后端接入、熟悉 Gin 项目结构或搭建私有网盘的开发者而言，源码提供了清晰的驱动抽象和完整的文件管理、用户权限实现；既可部署使用，也可作为二次开发的基础模板。
1. Cloudreve 是个什么项目：Go 写的个人网盘，为什么不用 Nextcloud
如果你在群里问「个人网盘用什么开源方案」，十有八九有人甩给你 Nextcloud 的 Docker 一行命令。但真把 Nextcloud 跑起来你会发现：PHP 环境、插件市场、更新习惯、资源占用，每一样都在消耗你有限的耐心。Cloudreve 是另一个路线——它用 Go 语言写核心、前端用 Vue，整个项目编译完就是一个二进制文件加一个静态目录，部署成本低到离谱。它主打的是「存储后端解耦」：本地磁盘、七牛、阿里云 OSS、腾讯云 COS、又拍云、OneDrive 都能接，而且策略是运行时切换，不锁死。这个源码包适合两类人：一是想搭一个干净、快、不用天天折腾的私人网盘；二是想在 Go 项目里抄作业，学单二进制分发、存储抽象层怎么设计的。先说明白一件事：Cloudreve 本质是「壳 + 调度器」，文件本体存在你配的存储后端里，搞清楚这个关系，后面所有配置都不会懵。
2. 先跑起来再谈别的：本地环境、源码编译与数据库初始化
2.1 建议先用 Release 二进制跑一遍，再碰源码
我见过太多人一上来就go build，结果卡在依赖下载、CGO 开关、前端静态资源缺失上，连界面都看不到就放弃了。Cloudreve 仓库里每次发版都会带编译好的二进制和cloudreve.db初始化逻辑，我的建议是：先下载对应平台的 Release 包，把它跑起来、登录后台、创建一个存储策略，确认流程走通之后，再去动源码。这样才能区分「项目本身的坑」和「你编译环境的坑」。
跑起来只需要三步。先把二进制放到一个干净目录，给它执行权限：
mkdir -p /opt/cloudreve && cd /opt/cloudreve wget https://github.com/cloudreve/Cloudreve/releases/download/3.8.3/cloudreve_3.8.3_linux_amd64.tar.gz tar -zxvf cloudreve_3.8.3_linux_amd64.tar.gz chmod +x cloudreve这里 3.8.3 是举例，实际以你拿到的源码包内附版本或官方 Release 页为准。解压后目录里应该只有一个二进制文件，没有配置文件。首次运行会做两件事：生成conf.ini，打印一个随机管理员账号密码，注意看启动日志：
./cloudreve看到类似Admin credentials: admin / xxxxxx的输出，立刻复制保存。它只在首次启动输出，之后想要找回只能重置数据库。日志里还会给出监听地址，默认是0.0.0.0:5212。浏览器访问该端口，用输出里的账号密码登录，进后台第一件事是改密码，然后去「存储策略」里建一个本地磁盘策略，上传一个文件测试。这个流程跑通，说明二进制、数据库、权限三件事都是好的。
为什么必须建存储策略才能上传？因为 Cloudreve 的设计里，默认策略是「本机」没错，但它要求你在后台显式确认路径。很多人卡在「上传一直转圈」，其实就是没建策略或策略路径不可写。这个设计后面讲存储章节会细说。
2.2 从源码编译：Go 环境、构建参数与前端资源
二进制跑通之后你再碰源码，心态完全不一样。Cloudreve 的源码包结构大致是：backend/是 Go 服务端，frontend/是 Vue 3 前端，根目录的build.sh负责把两者合并。服务端编译本身不难，卡点几乎都在前端构建上。
先确认 Go 版本。Cloudreve 3.x 的主线要求 Go 1.18 以上，建议直接装 1.20 或更高：
go version # 如果没装或者版本太低，先装一个，比如 Ubuntu 下： sudo apt install golang-go # 或者去 go.dev/dl 下载 tar 包手动解压到 /usr/local/go export PATH=$PATH:/usr/local/go/binGo 语言近两年的版本节奏很快，如果你之前没用过，记住一个原则：不要用发行版仓库里那个老版本，去官方下载。Go 不像是 Python 那样「差点版本问题不大」，泛型和标准库行为差异会直接影响编译结果。
进入backend/目录编译服务端：
cd backend go build -tags "sqlite" -ldflags "-X github.com/HFO4/cloudreve/pkg/conf.Build=`git rev-parse --short HEAD`" -o ../release/cloudreve这段命令里，-tags sqlite是启用内嵌 SQLite 支持，官方 Release 默认就是 SQLite + MySQL 双支持，但自己编译时只带 SQLite 能少装一堆依赖，适合先跑通。-ldflags里注入的是 commit hash，这个只是让后台版本页好看一点，不影响功能。编译成功后release/cloudreve就是你自己的二进制。
然后编前端。Cloudreve 的前端构建是最容易翻车的环节，因为yarn build需要完整 Node 环境，而且 Vue 3 + Vite 的依赖树很敏感：
cd frontend yarn install --frozen-lockfile yarn build构建产物会输出到frontend/dist。标准的发布流程是把dist里的所有文件拷贝到服务端可执行文件同级的statics/目录，Cloudreve 启动时会自动服务这些静态文件。build.sh干的就是这件事：
# 在项目根目录执行 ./build.sh它会依次做：编译前端、拷贝静态资源、编译后端、产出最终 release 压缩包。我一般不用一键脚本，而是手动分三步，因为哪一步失败了你能立刻定位。yarn install报错先看 Node 版本，Vite 5 要求 Node 18+；yarn build报内存溢出就用NODE_OPTIONS=--max-old-space-size=4096 yarn build，这个参数在小内存 VPS 上是救命稻草。
编译源码的价值不只是「拿到一个二进制」，而是你能改默认端口、改前端标题、删掉用不到的存储驱动，做一个真正属于自己的分发版。后面进阶章节会讲自定义标题和隐藏存储策略这类小改造。
3. 存储策略才是重头戏：对接 OSS、COS、七牛、OneDrive 的最小配置
3.1 存储策略的核心概念：网盘只是个调度层
Cloudreve 把「文件存哪」抽象成一张表，后台叫「存储策略」。每一条策略包含：驱动类型、Bucket 信息、API 密钥、URL 前缀、是否允许直链等字段。任何一个用户上传文件时，都能在后台指定走哪条策略——这就是它和 Nextcloud 最大的区别：Nextcloud 是文件系统挂在本地，外部存储是插件；Cloudreve 是默认就按「外部对象存储优先」设计的。
理解这个抽象关系后，你就明白三个常见困惑：
- 文件管理界面里删除文件，为什么存储桶里还有残留？因为 Cloudreve 默认「软删除」，文件标记删除但对象存储里的实体可能还在，需要定时清理任务。
- 为什么换绑存储策略后历史文件还能访问？因为数据库里保存了每一条文件的存储策略 ID，换绑定只影响新上传文件。
- 离线下载的文件去哪了？取决于你在后台给「离线下载」任务指定的默认策略，如果一个策略都没建，离线下载会直接失败。
文件分块上传也是存储策略层面的逻辑。Cloudreve 会按分片大小配置（默认 4 MB）把文件切成块，逐块上传到存储后端，上传完成后在数据库里记录文件完整信息。这个设计对 OSS 这类支持分片的对象存储很友好，对 WebDAV 这类接口就慢一些。所以策略类型选错最直接的表现就是上传速度异常。
建策略之前，先去后台「存储策略 → 新建」看一眼驱动列表。Cloudreve 3.x 支持：本机存储、阿里云 OSS、腾讯云 COS、七牛、又拍云、OneDrive（含世纪互联）、S3 通用协议。S3 通用协议我多说一句：Cloudflare R2、MinIO、华为云 OBS 都在这一项里，不要到处找「R2 专属策略」。
3.2 阿里云 OSS 配置：字段对应关系与权限最小化
以阿里云 OSS 为例，这是国内用户用得最多的。建策略前先去阿里云控制台做两件事：创建 Bucket 并设置为私有读写；创建一个 RAM 子账号，只授予这个 Bucket 的读写权限。把 AccessKey ID 和 Secret 留好。
然后回到 Cloudreve 后台新建策略，关键字段这样填：
- 存储类型：阿里云 OSS
- Bucket：你的 Bucket 名称，不带地域后缀
- Endpoint：
oss-cn-hangzhou.aliyuncs.com，按你的 Region 填 - AccessKey ID / AccessKey Secret：上面建的 RAM 凭证
- 回调地址 / 上传凭证有效期：默认即可，内网环境不需要改
填完保存，回到策略列表点「测试」。Cloudreve 会尝试往 Bucket 写入一个测试对象并读回，全通才给过。我见过有人在这步反复失败，报错都是AccessDenied，原因是 RAM 策略写得太宽或太窄。最小权限策略这样写：
{ "Version": "1", "Statement": [ { "Effect": "Allow", "Action": [ "oss:PutObject", "oss:GetObject", "oss:DeleteObject" ], "Resource": [ "acs:oss:*:*:your-bucket-name", "acs:oss:*:*:your-bucket-name/*" ] } ] }your-bucket-name替换成你的 Bucket。这段 JSON 只允许三大基础操作，没有列桶权限、没有生命周期管理权限。够用且安全，将来真出问题也容易排查。
3.3 腾讯云 COS 与七牛：字段几乎一致，但要注意域名绑定
腾讯云 COS 和阿里云 OSS 基本同构，区别在字段名：COS 管 API 密钥叫SecretId / SecretKey，Endpoint 形如cos.ap-guangzhou.myqcloud.com。七牛则完全两套体系——它没有 Bucket 概念，用「空间（Bucket）」但把上传凭证和下载域名分开。七牛的配置里，AccessKey / SecretKey是 AK/SK，Bucket填空间名，Domain必须填你已经绑定的 CDN 加速域名或默认测试域名，不能填qiniu.com结尾的内网地址，否则上传成功但预览直接裂。
OneDrive 是另一个极端：它不需要 AK/SK，走 OAuth 授权。Cloudreve 后台点「新建 OneDrive 策略」后会给你一个授权链接，你用微软账号登录授权，回调地址要填 Cloudreve 的域名，默认是http://你的域名/api/v3/onedrive/callback。如果你没配域名而是用 IP 访问，OneDrive 授权大概率失败，因为微软不允许 IP 回调。解决方法是先在本地 hosts 里把某个域名指向服务器，或者用内网穿透工具把 5212 端口临时暴露出来。
3.4 测试策略的完整步骤：从建策略到传到读回
建完任何一条策略，我都建议走一遍「创建目录 → 上传图片 → 复制直链 → 无痕模式打开」四步验证法。直链打开 403 说明 Bucket 权限没配对或者 URL 签名参数没生效；能打开但速度慢，先检查你是不是选了「默认 CDN 域名」而不是自定义加速域名；能打开但浏览器直接下载而不是预览，检查 Bucket 的 Content-Type 是不是被 Cloudreve 正确写入。
这里有个常见误区：Cloudreve 的「直链」分为两种，一种是在文件列表里点开预览，走的是 Cloudreve 代理转发；另一种是「复制直链」功能，走的是对象存储的 CDN 地址。前者要求 Cloudreve 服务端能访问存储桶，后者要求你在 Bucket 绑定的域名里配置过 CORS。阿里云 OSS 的 CORS 规则不配好，前端上传会一直挂在初始化阶段，报错跨域请求被阻止。配置 CORS 时来源填*，方法选GET, PUT, POST, DELETE，暴露头填ETag, x-oss-request-id，保存后再试上传。
腾讯云 COS 有一个比阿里云「默认更强」的特性：同名覆盖默认关闭。如果你在 Cloudreve 里重传一个同名文件，COS 会报FileAlreadyExists。Cloudreve 侧的表现是上传进度条走完，然后报「上传失败」。解决路径：在 COS 控制台把该 Bucket 的「同名文件覆盖」打开，或者去 Cloudreve 的策略设置里开启「覆盖上传前删除旧文件」。用后者多一次请求，但符合安全习惯。
4. 避坑手册：部署和存储策略的高频翻车现场
4.1 后台秒开但上传 100% 失败：存储策略路径不可写
现象：Cloudreve 界面打开正常，登录正常，新建目录正常，一旦上传文件就卡在「正在上传」然后弹失败。后台日志只有一句put object failed，没有详细堆栈。
原因：你用的「本机存储」策略里填的路径，对运行 Cloudreve 的进程用户不可写。比如你用 root 启动，但策略里写了/home/cloudreve/uploads，这个目录属于另一个用户，权限是 755。Cloudreve 进程写不进去。
解决：chown -R或者直接在策略里把存储路径改到/opt/cloudreve/uploads这种你完全可控的目录，然后保存策略，再建一个新目录测试上传。经验是：第一次建策略的人，先把路径写成 Cloudreve 二进制所在目录的绝对路径，别写/home/或/var/www/这种系统老目录。
4.2 反向代理后上传大文件 502：nginx 缓冲区与超时都是玄学
现象：内网直连 IP 上传 500MB 文件没事，套了 Nginx 反代后超过 100MB 就 502。看 Nginx 错误日志，全是upstream prematurely closed connection。
原因：两层——Nginx 默认client_max_body_size 1m，这是硬限制，超过直接 413；就算你改了 body size，Nginx 往上游转发时默认不缓冲大文件，而 Go 服务端读取请求体需要时间，Nginx 的proxy_read_timeout 60s一到就断开连接，Go 那边刚收到一半请求体，连接就断了，报 502。
解决：在 server 块里加三行配置：
client_max_body_size 0; proxy_request_buffering off; proxy_read_timeout 300s;client_max_body_size 0表示不限制大小；proxy_request_buffering off让 Nginx 收到多少转多少，不攒到全部收完再转；proxy_read_timeout 300s给大文件上传留够时间。改完nginx -t然后 reload。这里要提醒一句：如果 Nginx 前面还有一层 CDN，CDN 的上传大小限制是另一道关卡，Cloudflare 免费套餐对单文件 100MB 有硬限制，所以大文件上传要绕开 CDN 或者走 WebDAV。
4.3 定时任务没有触发：后台“队列任务”按钮没点开
现象：设置了「每天凌晨 3 点清理回收站」，但三天后回收站文件还在。
原因：Cloudreve 后台的任务调度不是系统 cron 驱动的，它依赖一个内部的定时器，而这个定时器在后台「设置 → 系统 → 队列任务」里默认是关闭的。也就是说，只要这个开关没打开，所有定期任务全部静默失效。
解决：登录后台，进「设置 → 系统」，把「队列任务」开关打开，保存。顺带确认任务间隔单位是「分钟」，不是「秒」。然后手动建一个「立即执行」的测试任务——在「管理面板 → 文件 → 清理回收站」里点手动执行，确认任务真的跑得通。从那以后我每次部署完 Cloudreve，都把它列进部署检查清单，和改管理员密码并列。
4.4 离线下载已创建但不跑：下载节点连不上目标站
现象：创建离线下载任务后，任务列表里一直显示「等待中」或「处理中」，进度永远不动。
原因：Cloudreve 的离线下载需要在执行机上能访问目标 URL，而国内 VPS 访问 GitHub 等外网资源经常超时。如果策略配的是内网存储桶，下载节点把文件抓回来后写入存储桶的这一步，如果执行机到存储桶的内网链路不通，任务也一样挂住。
解决：先去后台把下载器的「并发数」从 4 改 1，降低资源竞争；再手动在服务器上curl -I 你的下载链接，看能不能在三秒内返回响应头。连不上就换下载源，或者在执行机上挂系统代理——注意，Cloudreve 的下载器读不读环境变量看你编译时的配置，Release 包默认不读，这个坑我在离线下载 GitHub Release 包时踩过两次。最终做法是在服务器上配好http_proxy后重新编译 Cloudreve，编译完在后台看系统信息 → 下载节点里显示的节点版本，确认是自定义编译的版本。
5. 进阶玩法：把 Cloudreve 变成真正属于你的存储网关
到这里，基础部署和存储策略你都已经跑通了。这一章讲讲我平时会用到的三个改造方向，每一个都直接影响日常体验。
自定义标题、Logo 和备案信息。Cloudreve 的前端构建产物里，statics/里的index.html可以直接改<title>标签，改完刷新页面就生效。但如果你想连登录页左侧的插图都换掉，需要重新构建前端。这里有个讨巧的办法：frontend/src/views/Login.vue里的背景图引用了一个静态资源路径，你直接把新图覆盖到statics/img/下同名文件，不用重新构建整个前端，浏览器强刷就出来了。后台的「站点名称」设置会影响页面标题后缀和邮件通知抬头，这个在「设置 → 基本设置 → 站点信息」里改，不用动代码。
WebDAV 挂载是 Cloudreve 被低估的能力。开启方式：后台「设置 → 偏好设置 → WebDAV 服务」，启用后你会得到一个 WebDAV 地址和一组专用账号密码。Mac 的访达和 Windows 的资源管理器都原生支持这个协议，挂载后你可以像操作本地文件夹一样操作网盘。这里一个细节：WebDAV 服务复用的上传链路是「代理上传」而不是「直传」，所以大文件通过 WebDAV 上传时走的是 Cloudreve 服务端中转，对服务器带宽有压力。如果你主要用 WebDAV 做备份，建议给 WebDAV 账号单独建一个存储策略，指向最便宜的对象存储，避免大流量打爆服务器带宽。
最后说一个大部分人不知道但非常实用的参数：conf.ini里[system]段的hash_file开关。默认开，每个文件上传时都会算一次 SHA-1，这能实现「秒传」——服务器上已经有相同内容文件时，直接引用旧物理文件。对小文件是福利，对大文件是灾难，5GB 以上文件算 SHA-1 的时间可能比上传还久。如果你明确不做去重，把hash_file = false关掉，上传大文件的速度会有肉眼可见的提升。这个参数改完重启 Cloudreve 才生效。
这三件事做完，基本就是「你自己的网盘了」。记住一句话：Cloudreve 的本质是调度器，不是存储容器——别把所有文件堆在系统盘上，配好外置策略比升级机器实在。希望帮到你，也欢迎回来交流你自己的部署经验。
本文还有配套的精品资源，点击获取
