如何5分钟跑通OmniCloud:面向新手的本地部署完整指南
如何5分钟跑通OmniCloud:面向新手的本地部署完整指南
OmniCloud 是一个全栈的云盘聚合平台,能把 Google Drive、OneDrive、Dropbox、MEGA、pCloud、Yandex Disk 和任意 S3 兼容存储,通过统一的工作区聚合管理。本文带你完成 OmniCloud 本地部署:只需 Node.js 或 Docker,几行命令即可在自己的电脑上跑起来,无需任何编程基础。
OmniCloud 是什么?一个入口管理所有网盘
传统网盘各有独立客户端,文件分散在各处。OmniCloud 的思路是"聚合":所有网盘账号接入同一个界面后,你可以:
- 🗂️ 在 Home / My Drive / Recent / Starred / Shared / Quota 视图间统一浏览文件
- ⬆️ 通过拖拽上传文件,自动按策略分配到指定网盘账号
- 🔄 后台定时同步各网盘元数据到本地 SQLite,浏览速度更快
- ⚙️ 支持
local(单用户自用)与hosted(多用户注册登录)两种运行模式
下图直观展示了多个网盘账号如何汇入 OmniCloud 统一入口:
部署前准备:OmniCloud 环境要求清单
开始前请确认本机已安装以下环境(二选一即可):
| 方式 | 要求 | 适合人群 |
|---|---|---|
| 方式一:npm 启动 | Node.js 20+(推荐 LTS 版本)、npm | 想快速体验、便于调试的新手 |
| 方式二:Docker | Docker + Docker Compose | 想零配置、环境隔离的用户 |
💡 无需提前创建任何网盘开发者账号。MEGA、pCloud、S3 都在网页界面里直接填账号连接,零配置门槛。
方式一:npm 一键启动 OmniCloud(推荐新手)
第一步:获取项目代码
打开终端,执行以下命令克隆仓库并进入目录:
git clone https://gitcode.com/gh_mirrors/om/OmniCloud
cd OmniCloud
第二步:安装依赖
npm install
项目使用 npm workspaces 同时管理 backend/(Express API)和 frontend/(Vue 3 + Vite),一条命令装好前后端全部依赖。
第三步:创建后端环境变量文件
从模板复制一份后端配置文件(模板见 backend/.env.example):
# Linux / macOS
cp backend/.env.example backend/.env
# Windows (PowerShell)
copy backend\.env.example backend\.env
对于新手,模板默认值基本可以直接运行,建议重点检查以下两项:
| 变量 | 默认值 | 说明 |
|---|---|---|
PORT |
8787 |
后端 API 端口 |
APP_MODE |
local |
单用户模式,免登录直接使用 |
CORS_ORIGIN |
http://localhost:5173 |
前端地址,与 Vite 默认端口一致 |
OMNICLOUD_SECRET_HALF |
开发占位值 | 用于加密网盘凭证,自用场景建议换成随机字符串 |
配置逻辑可以在 backend/src/config/env.js 中查看,所有变量都有默认值兜底,这也是"开箱即用"的原因。
📌 只有当你想接入 Google Drive、OneDrive、Dropbox、Yandex Disk 这类 OAuth 网盘时,才需要在
.env里填写对应的CLIENT_ID/CLIENT_SECRET,详细步骤见 docs/provider-setup.md。
第四步:启动 OmniCloud
在项目根目录执行:
npm run dev
该命令会同时启动前后端(见 package.json 中 dev:api 与 dev:web 并行脚本),等待几秒后访问:
- 前端界面:
http://localhost:5173 - 后端 API:
http://localhost:8787
验证部署是否成功
打开浏览器访问 http://localhost:5173,看到首页即部署成功;也可以在 API 健康检查端点确认后端状态:
curl http://localhost:8787/api/health
进入 My Drive 页面,你就能在统一界面中浏览所有已连接网盘的文件:
方式二:Docker 一键部署 OmniCloud
如果你不想安装 Node 环境,Docker 方式更省事。项目内置了 Compose 编排文件 docker-compose.yml,包含 API 容器(Express)与 Nginx 前端容器。
1. 创建环境变量文件
cp backend/.env.example backend/.env
注意:Docker 模式下应用暴露在主机的 8080 端口,OAuth 回调地址应使用代理后的地址(Compose 文件已自动覆盖这些值):
GOOGLE_REDIRECT_URI=http://localhost:8080/api/accounts/google/callback
ONEDRIVE_REDIRECT_URI=http://localhost:8080/api/accounts/onedrive/callback
DROPBOX_REDIRECT_URI=http://localhost:8080/api/accounts/dropbox/callback
YANDEX_REDIRECT_URI=http://localhost:8080/api/accounts/yandex/callback
2. 构建并启动容器
docker compose up --build
启动后统一访问入口:
- 应用首页:
http://localhost:8080 - API(经 Nginx 代理):
http://localhost:8080/api
SQLite 数据库持久化在 Docker 卷 omnicloud_api_data 中,重启不丢数据。停止时执行:
docker compose down # 停止容器
docker compose down -v # 停止并删除数据库卷
连接你的第一个网盘账号
部署完成后,左侧导航进入 Storage 页面,即可看到所有已连接账号的容量总览:
点击 Connect 按钮连接新账号。各网盘的连接方式分为两类(详见 docs/provider-setup.md):
| 网盘 | 连接方式 | 是否需要改 .env |
|---|---|---|
| MEGA、pCloud | 界面内直接填邮箱/密码 | ❌ 不需要,最快上手 |
| S3 兼容存储(R2、B2、Storj、MinIO 等) | 界面内填 Access Key / Bucket / Endpoint | ❌ 不需要 |
| Google Drive、OneDrive、Dropbox、Yandex Disk | 先在官方控制台创建 OAuth 应用,把凭证填入 .env,再在界面点击连接 |
✅ 需要 |
🚀 新手建议从 MEGA 或 pCloud 开始:不用注册任何开发者应用,填好账号密码即可跑通完整流程。
连接多个账号后,还可以在 Storage 的 Allocation 标签页设置上传分配策略——轮询(Round Robin)、加权轮询、最空闲优先(Most Free Space)或手动排序(Custom Order),让上传的文件按你的规则自动分散到不同网盘:
OmniCloud 部署常见问题排查
| 问题 | 原因与解决办法 |
|---|---|
| 浏览器报 OAuth 回调无效 | 网盘控制台里注册的 Redirect URI 与 .env 中不一致,两处必须逐字符完全相同 |
| Google 应用显示不可用 | OAuth 同意界面处于测试模式时,需把自己的账号加为测试用户 |
| OneDrive 连接失败 | 确认填入的是 client secret 的 Value 而非 Secret ID |
MEGA 连接提示 EAGAIN |
MEGA 服务临时繁忙,稍等片刻重试即可 |
修改 .env 后不生效 |
环境变量只在启动时读取,重启 npm run dev 或容器即可 |
| 多用户部署 | 将 APP_MODE 改为 hosted 并设置强随机的 AUTH_SECRET,即可启用注册/登录流程 |
项目结构速览
熟悉部署后,可以按目录深入了解项目源码:
- frontend/src/:Vue 3 前端(Pinia 状态管理、i18n 多语言、文件浏览器组件)
- backend/src/adapters/:各网盘适配器(Google、OneDrive、Dropbox、MEGA、pCloud、S3、Yandex)
- backend/src/services/:同步、上传、分配、认证等核心服务
- backend/src/config/:环境变量与数据库配置
- docs/provider-setup.md:各网盘凭证申请完整教程
5 分钟,你已经拥有了一个聚合所有网盘的私人云盘工作台。接下来可以按需申请 OAuth 凭证接入更多网盘,把散落在各处的文件真正收拢到一个入口。



