简介vDrive是基于PHP的网络文件管理器专为媒体浏览与触摸屏操作优化。用户部署到PHP服务器后即可将个人网站变为自有云驱动器适合站长、开发者及需要自建轻量云盘的管理者。下载包仅1.03MB共148个文件61个js负责核心交互21个png和24个gif提供图标与动效9个html搭建页面结构8个css完成界面样式另附字体及离线缓存清单结构精简便于按需裁剪。目前已有2068人学习使用社区关注度不错。通过阅读源码可学习响应式文件管理器的前端逻辑、触摸事件适配以及PHP服务端集成方法部署过程不复杂适合有一定PHP基础的开发者快速上手为构建私有云盘或定制化文件系统提供一条可直接落地的参考路径。1. 自己把云驱动器装回家里vDrive 到底能替你解决哪件事本地磁盘被设计稿和录像素材塞满的那天我开始认真找能自己装的云盘。vDrive 的名字直译就是云驱动器本质是一个开源的、数据归属完全在自己手里的存储服务服务端跑在你自己的机器上浏览器、桌面同步端和手机 App 走同一套协议连回来文件落点始终在自己磁盘里。和公有云网盘比它解决两个很实际的痛点——容量可以由磁盘池随便扩隐私不用交给别人保管和传统 NAS 比它又省掉了配置 SMB、NFS、文件系统权限这一大堆杂活。这个方案适合一个人或三五人小团队做私有网盘、归档日志和素材库如果你要的其实是多人实时协作文档vDrive 大概率不是正确答案。2. vDrive 架构与选型元数据与内容分离一台旧电脑够不够2.1 为什么要在自己机器上搭网盘vDrive 的两个定位优势公有云网盘的问题不在功能在归属感。账号是服务商的目录结构是服务商的下载速度上限也是服务商的哪天服务调整规则你积累几年的分享链接说失效就失效。数据库和素材这类东西放在一个你能直接摸到磁盘的地方焦虑会小很多。vDrive 这类开源云驱动器把同步协议、分享链接、权限管理打包成一个服务你要做的只是准备一台常开的机器装好服务端剩下的逻辑和公有云网盘几乎一样学习成本很低。我在 GitHub 上翻过一批同类项目vDrive 给我的直接印象是它把公有云网盘的操作习惯完整搬进了自托管环境有网页控制台有桌面同步端有文件分享链接也有按设备区分的同步目录。对从网盘迁移过来的用户几乎不用改使用习惯。和 NAS 自带网盘相比它不需要你先搞明白用户组、共享文件夹、ACL 权限这些底层概念安装完初始化一个管理员账号就能用这对小团队非常友好。2.2 核心架构元数据与内容为什么要分开存放自托管云盘和普通文件服务器的本质差别在于它把文件的“描述信息”和“文件本体”分开了。元数据包括目录树、文件名、大小、版本号、哈希值、创建人和分享权限这部分一般存在数据库里文件内容则以原始文件或分片的形式存在磁盘目录可以直接被你用 rsync、find 这些传统工具访问。这种分离带来的好处是增量同步不用全量扫描文件服务端只需要对比数据库里的版本号和哈希就能知道哪些分片需要上传或下载。一个可落地的组件划分大概是这样的组件职责常见位置Web 控制台与 API 网关登录、建目录、分享、上传下载入口服务端进程监听 8080 等端口同步引擎客户端轮询版本、分片上传、冲突检测桌面端/手机端进程元数据库目录树、版本号、哈希、权限、分享记录服务端数据目录或独立数据库容器内容存储文件分片或原始文件服务端数据目录或对象存储桶后台任务缩略图生成、完整性校验、垃圾清理服务端进程或独立 worker这个结构决定了你备份时不能只拷文件目录否则恢复出来就是一堆没有名字编号的文件。很多第一次搭的人在这里翻车以为把 files 文件夹拷贝走就万事大吉结果元数据库和文件对不上整个目录树全乱。后面第 5 章会专门讲备份恢复顺序。2.3 vDrive、Nextcloud、Seafile 怎么选一张对比表找到边界自托管网盘选型是绕不开的话题。常见的三类选择Nextcloud 功能最全、插件生态最大但资源占用和响应延迟都比较明显Seafile 用块级同步协议海量小文件场景性能很强但二次开发和自定义界面麻烦vDrive 这类轻量方案介于两者之间胜在干净和低占用。维度NextcloudSeafilevDrive 这类轻量方案资源占用较高PHP 全家桶中等依赖数据库索引低单二进制或双容器可跑海量小文件同步一般慢在扫描强块级去重中等分片粒度可调多端体验全平台功能多全平台同步强主要覆盖 Web/桌面/移动核心场景插件与协作极丰富一般少而精适合场景想要在线 Office 生态代码库、大目录同步干净的私有云盘和素材库我的选择逻辑是这样需要在线编辑 Office 文档、要接一堆外部应用选 Nextcloud手上是几十万个代码文件和历史资料追求极致同步性能选 Seafile如果是给自己或小团队搭一个“像网盘但不是网盘”的东西界面轻、分享顺手、资源占用低vDrive 这类项目更省心。顺带提醒一句这类开源项目多为 AGPL 或 MIT 协议自己用不受限但改了代码再分发就要留意许可证传染问题。很多人在 Gitee 上发二开镜像时第一脚就踩在“开源许可证选什么”上后面被原作者投诉才来补救属于非常被动的局面。2.4 动手前先自检宿主机五条命令排除环境坑部署前我习惯先确认宿主机状态避免装到一半发现磁盘格式不支持或内存不够。下面这组命令值得先跑一遍# 确认系统架构32 位系统基本告别大部分现代镜像 uname -m # 确认数据盘挂载和剩余空间云盘数据比想象中涨得快 df -h /srv/vdrive # 确认内存小内存机器要调低同步并发数 free -h # 确认 Docker 版本太老的版本不支持 compose v2 docker version --format {{.Server.Version}} # 确认当前用户对数据目录可写权限问题最容易排查 id test -w /srv/vdrive echo writable这几条命令分别对应不同坑uname -m如果输出不是 x86_64 或 aarch64镜像选择面会小很多df看的是数据盘而不是系统盘很多人把数据写在 / 下面结果系统盘被塞满free结果如果低于 2GB建议把同步并发数从默认 8 降到 4否则服务端在校验哈希时内存会吃紧。3. 落地 vDrive 服务端compose 一把拉起再把存储指到对象存储3.1 最小可用部署docker compose 把服务端和元数据库一起拉起来假设你已经准备好一台 Linux 服务器或一台常开的旧电脑Docker 和 Compose 插件已装好。vDrive 常见部署形态是双容器一个服务端进程一个 PostgreSQL 元数据库。内容存储通过数据卷直接穿透到宿主机目录这样文件更容易被传统工具管理和备份。先创建一个项目目录写入下面的 compose 文件services: vdrive-server: # 版本号别死抄去你使用的 registry 看 release 标签 image: vdrive/server:latest container_name: vdrive-web restart: unless-stopped ports: - 8080:8080 volumes: - ./vdrive/data:/var/lib/vdrive/data - ./vdrive/files:/var/lib/vdrive/files environment: - TZAsia/Shanghai # 数据库连接串密码务必换成强密码 - VDRIVE_DB_DSNpostgres://vdrive:change_mevdrive-db:5432/vdrive depends_on: - vdrive-db vdrive-db: image: postgres:16-alpine container_name: vdrive-db restart: unless-stopped environment: - POSTGRES_USERvdrive - POSTGRES_PASSWORDchange_me # 显式指定 PGDATA避免嵌套卷初始化失败 - PGDATA/var/lib/postgresql/data/pgdata volumes: - ./vdrive/db:/var/lib/postgresql/data代码里的TZAsia/Shanghai不只是显示时区文件时间戳和版本号比较都依赖它不设会导致多设备之间判断文件新旧出现偏差是我最常看到的环境变量遗漏。PGDATA这个参数也有讲究Postgres 官方镜像预设了数据卷如果你挂载它的父目录而不指定 PGDATA容器初始化时可能因为目录非空而失败。depends_on只保证启动顺序不保证数据库已就绪所以服务端首次启动如果报数据库连接失败等几秒再 restart 即可。启动命令很简单cd /srv/vdrive docker compose up -d docker compose ps如果镜像拉取速度很慢常见做法是在 Docker 配置里加上国内镜像源加速。清华大学开源镜像站和阿里巴巴开源镜像站都提供了 docker registry mirror 的配置方法改完/etc/docker/daemon.json重启 docker 即可这能省掉大量等待时间。服务端启动后先做一次最小健康检查curl -s http://127.0.0.1:8080/api/v1/ping这一步必须用 127.0.0.1 而不是域名。如果本机回环地址都不通说明容器没起来或端口映射写错如果本机通但外网访问不了问题出在系统防火墙或云安全组放行规则而不是应用本身。3.2 首次初始化创建管理员账号、确认存储目录归属容器起来后浏览器打开http://服务器IP:8080第一次访问会引导创建管理员账号。这一步建议直接设置强密码并开启两步验证因为云盘一旦暴露在公网就会被扫描器盯上弱口令账号被爆破只是时间问题。服务端的数据目录建议放在独立数据盘并建立清晰的结构mkdir -p /srv/vdrive/{data,files} chown -R 1000:1000 /srv/vdrivechown这一步容易被忽略。容器内部进程通常以非 root 用户运行UID 可能是 1000 或 1001宿主机目录权限不对就会出现“能启动但写不进去文件”的奇怪现象——日志里报权限拒绝服务端却显示正常。如果确认 UID 不匹配可以在 compose 里给服务端加user: 1000:1000把宿主机用户直接映射进容器。初始化完成后建议先创建一个普通测试账号用测试账号上传一个文件再下载回来走通一遍完整链路。这个流程看起来多余但它能在你配置对象存储之前先排除服务端本身的问题后面出问题排查范围会小很多。3.3 把文件存储指到对象存储容量不再受本机磁盘限制本机磁盘总有满的一天。vDrive 这类开源云盘通常支持把内容存储切换到 S3 兼容接口常见搭配是单机部署 MinIO 或者直接用云对象存储。这样做的好处是文件的容量上限由存储桶决定服务端数据目录只放元数据备份和迁移也会更灵活。在数据目录下建立一个config.yaml写入对象存储接入信息storage: driver: s3 bucket: vdrive-data endpoint: https://minio.example.com region: us-east-1 access_key: YOUR_ACCESS_KEY secret_key: YOUR_SECRET_KEY # 分片大小大文件场景调大减少请求次数 chunk_size: 64MB # 开启服务端校验对象存储偶尔会静默损坏文件 checksum_verify: trueendpoint填 MinIO 地址时要注意它默认是http://而不是https://很多人在本地测试时填了 https 导致 TLS 握手失败。chunk_size默认值通常比较保守如果是千兆内网调大到 64MB 能明显减少请求次数。checksum_verify建议保持开启对象存储偶尔会发生底层数据静默损坏这个参数会在下载时重新计算哈希花少量 CPU 换数据完整性是值得的。改完配置重启服务端docker compose restart vdrive-server docker compose logs -f vdrive-server启动日志里看到 storage driver 初始化成功再去上传一个超过分片大小的文件验证。如果上传失败优先检查存储桶是否存在、访问密钥是否有读写权限。3.4 客户端同步必须设的三个参数忽略清单、并发数、冲突策略服务端配好只是开始同步体验好不好全在客户端参数。桌面客户端连接远端地址后有三个地方我每次都会调忽略清单、同步并发数、冲突策略。忽略清单是很多人当成“高级功能”跳过的东西实际上它在第一天就该配。客户端在同步目录下放一个.vdriveignore文件不需要重新连接同步引擎会动态读取.DS_Store Thumbs.db node_modules/ dist/ *.part ~$*.docx这些文件要么是系统临时文件要么是构建产物不同步到服务器能省下大量存储空间和同步流量。尤其是node_modules一个项目动辄几百 MB 的小文件同步起来会让服务端哈希校验 CPU 飙到顶。另一个容易漏的是~$*.docxOffice 打开文档时生成的临时锁文件不忽略的话服务器上会积累一堆垃圾文件。命令行同步时我一般这样指定参数vdrive sync ~/work \ --remote vdrive://userhost:8080/files \ --concurrency 4 \ --conflict keep-both \ --ignore .vdriveignore--concurrency控制分片上传的并行度小内存机器建议调到 2 或 4并发过高会把服务端打满反而比串行更慢。--conflict是冲突文件的处理策略keep-both会在服务端保留两个版本并生成.conflict-时间戳的副本适合不能丢失任何改动的场景keep-newest则保留修改时间最新的版本。我建议日常同步用keep-both它会多占一点存储但能避免数据被静默覆盖。怎样确认同步真的生效上传完成后到服务端看一眼find /srv/vdrive/files -type f | wc -l数量和你本地上传的文件数对得上说明内容存储写入成功。如果数量偏少多半是忽略清单把文件过滤掉了去客户端日志里查忽略记录即可。4. vDrive 部署与同步避坑五条踩出来的血泪经验4.1 容器重建后文件全部消失吓得差点重装现象执行docker compose down docker compose up -d后打开网盘发现目录是空的所有文件都不见了。原因compose 文件里的 volumes 写的是相对路径但第一次启动时如果目录还没创建Docker 可能创建了匿名卷绑定到容器路径。匿名卷在容器重建后会残留但不再挂载看起来就是“数据全没了”。其实数据还在旧的匿名卷里。解决先去确认挂载情况docker inspect -f {{json .Mounts}} vdrive-web重点看Source字段是/srv/vdrive/files还是乱码的卷名。如果是匿名卷先docker volume ls找到旧卷把文件拷回宿主机目录再在 compose 里显式写成绝对路径重新拉起容器。这个操作要多做一步shell 通配符会优先匹配空目录不要在没确认数据恢复前就清理旧卷。4.2 千兆内网同步只有 20MB/s跑不满是哪里卡住现象内网两台机器之间同步网卡和交换机都是千兆传输速度却稳定在 20MB/s 左右。原因服务端默认对每个分片做哈希校验小分片会让校验次数暴增磁盘随机读成为瓶颈同时客户端如果开了限速或分片大小太小瓶颈会叠加。解决先关掉客户端限速再调大服务端分片大小vdrive sync ~/work --remote vdrive://userhost:8080/files --rate-limit 0然后到config.yaml里把chunk_size从默认值调到 64MB重启服务端再试。这一步之后如果速度上到 80MB/s 以上说明瓶颈确实是校验频率而不是磁盘本身。如果调完还是 20MB/s就要检查两端是否走的是无线网络或者交换机端口有没有被协商成千兆以下。4.3 同一份文档反复出现 .conflict 副本越同步越乱现象办公电脑和笔记本同时在编辑同一个 docx 文件每次同步完服务器上就多出一个.conflict-时间戳的副本文件。原因冲突本身不可怕可怕的是两台设备系统时间不一致。vDrive 判断文件新旧依据的是修改时间戳A 设备时间慢了 5 分钟B 设备 10:00 保存的版本到了 A 那边可能被认为是旧版本于是服务端判定为冲突保留两个版本。解决先校准所有设备的系统时钟timedatectl set-ntp true timedatectl status手机端同样要打开自动确定日期时间。然后到服务端管理界面把冲突策略设置成keep-newest。如果某个项目不允许丢任何改动就保持keep-both但要在团队约定里写明同一时间只允许一个人编辑同一份文件。这条约定听着像废话但大部分 conflict 副本就是这么产生的。4.4 Web 管理页打不开容器却明明白白在运行现象docker ps显示 vdrive-web 状态是 Up但浏览器访问 8080 端口一直转圈连接超时。原因常见有两种。一是容器内进程只监听了 IPv6 地址compose 端口映射没生效二是系统防火墙或云安全组没放行 8080 端口。解决先判断问题是出在本机还是网络链路# 查看端口实际监听地址 ss -tlnp | grep 8080 # 本机回环测试 curl -s http://127.0.0.1:8080/api/v1/ping如果curl本机成功但外网不通去云控制台安全组和系统防火墙检查 8080 放行规则。如果ss输出显示监听在[::]:8080而不是0.0.0.0:8080说明服务端进程绑定地址有问题。更隐蔽的情况是浏览器本地开了系统的网络代理访问内网 IP 走了代理链路导致超时这时候换手机流量访问如果是通的基本就是本机网络出口的问题。4.5 备份脚本提示权限错误文件明明都在现象cron 里的备份任务执行到一半报rsync: failed to set permissions on ... Operation not permitted退避重试失败。原因容器内进程以 UID 1001 写入的文件备份脚本以宿主机 UID 1000 的账户运行rsync 尝试改权限时没权限。文件存在但备份链路不可用。解决要么把容器进程映射成宿主机用户要么备份脚本加参数跳过权限同步rsync -a --no-perms --no-owner --no-group /srv/vdrive/files/ /backups/vdrive-files/更推荐前面 3.2 提到的做法在 compose 的 service 定义里加user: 1000:1000配合宿主机chown -R 1000:1000 /srv/vdrive让容器内文件和备份账户归属同一个 UID以后不会再出这类权限错位。5. 把 vDrive 备份成一套后悔药恢复演练我每个季度做一次5.1 备份必须分两层元数据库和文件目录顺序反了会恢复出一堆乱码备份 vDrive 不是拷贝一个文件夹就完事。正确的顺序是先备份元数据库再备份文件目录最后把备份推到另一块磁盘或对象存储。下面的脚本是我日常在用的#!/usr/bin/env bash set -euo pipefail # 1. 导出元数据库Custom 格式便于恢复时筛选 export PGPASSWORDchange_me pg_dump -h 127.0.0.1 -U vdrive vdrive \ -Fc -f /backups/vdrive-meta-$(date %F).dump # 2. 文件目录快照--delete 保证服务端删除操作同步到备份 rsync -a --delete /srv/vdrive/files/ /backups/vdrive-files/ # 3. 推到异地对象存储--checksum 避免增量误判 rclone copy /backups remote:vdrive-backup/$HOSTNAME/ \ --transfers4 --checksum顺序的讲究在恢复时体现得最明显先恢复数据库 dump再挂回文件目录服务端启动后元数据里的哈希值和文件目录里的内容逐一比对正常才算恢复成功。如果先恢复文件目录再恢复数据库数据库导入期间服务端可能已经开始扫描不完整的文件目录产生大量误报的缺失记录。恢复演练我建议每个季度做一次不光备份还要实际恢复到另一台空机器上用vdrive fsck --repo /srv/vdrive/files校验一遍完整性。我吃过一次亏当年图省事只备份了文件目录没有备份元数据库机器宕机后恢复出来的是一堆无后缀名的乱码文件目录树、分享链接和版本记录全部丢失。从那以后我的备份脚本里第一行永远是pg_dump恢复顺序也固定为先库后文件。希望这个习惯也能帮到你至少别在某个周一的早上发现自己半年的素材只剩一坨二进制碎片。本文还有配套的精品资源点击获取