如何5分钟跑通OmniCloud:面向新手的本地部署完整指南

原创2026-11-04 10:38:301,835 阅读

如何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 云盘聚合平台架构示意图:Google Drive、OneDrive、MEGA、Dropbox 多个账号聚合到统一云盘入口

部署前准备: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 页面,你就能在统一界面中浏览所有已连接网盘的文件:

OmniCloud 本地部署完成后的 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 页面,即可看到所有已连接账号的容量总览:

OmniCloud 网盘聚合存储总览界面:查看 Google Drive、OneDrive、MEGA、Dropbox 各账号的容量与状态

点击 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 存储分配策略配置界面:设置上传文件在各网盘账号间的分配方式

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,即可启用注册/登录流程

项目结构速览

熟悉部署后,可以按目录深入了解项目源码:

5 分钟,你已经拥有了一个聚合所有网盘的私人云盘工作台。接下来可以按需申请 OAuth 凭证接入更多网盘,把散落在各处的文件真正收拢到一个入口。

登录后查看全文
OmniCloud