简介基于 Go 语言开发的 Cloudreve 个人网盘系统完整源码定位明确帮助个人或小型团队摆脱商业网盘限速、涨价与隐私顾虑快速搭建自主可控的文件管理分享平台。源码采用后端 GoGin、前端 ReactReduxMaterial-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.Buildgit 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 18yarn build报内存溢出就用NODE_OPTIONS--max-old-space-size4096 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 后台新建策略关键字段这样填存储类型阿里云 OSSBucket你的 Bucket 名称不带地域后缀Endpointoss-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 / SecretKeyEndpoint 形如cos.ap-guangzhou.myqcloud.com。七牛则完全两套体系——它没有 Bucket 概念用「空间Bucket」但把上传凭证和下载域名分开。七牛的配置里AccessKey / SecretKey是 AK/SKBucket填空间名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 反向代理后上传大文件 502nginx 缓冲区与超时都是玄学现象内网直连 IP 上传 500MB 文件没事套了 Nginx 反代后超过 100MB 就 502。看 Nginx 错误日志全是upstream prematurely closed connection。原因两层——Nginx 默认client_max_body_size 1m这是硬限制超过直接 413就算你改了 body sizeNginx 往上游转发时默认不缓冲大文件而 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 前面还有一层 CDNCDN 的上传大小限制是另一道关卡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 的本质是调度器不是存储容器——别把所有文件堆在系统盘上配好外置策略比升级机器实在。希望帮到你也欢迎回来交流你自己的部署经验。本文还有配套的精品资源点击获取