Olares 云存储挂载实战:把 Google Drive、Dropbox、AWS S3 接入文件管理器的完整流程
Olares 云存储挂载实战:把 Google Drive、Dropbox、AWS S3 接入文件管理器的完整流程
本篇基于 Olares 的官方文档与仓库源码,完整讲解如何把 Google Drive、Dropbox、AWS S3、腾讯云 COS 等云存储挂载到 Olares,并在文件管理器中像本地存储一样访问和管理云端文件。读完后你不仅掌握 OAuth 授权与 API 密钥两条连接路径、卸载清理的完整操作,还能看懂后端集成账号(Integration Account)的存储结构与 REST 接口,甚至学会用 olares-cli 在命令行下完成同样的挂载与卸载。
云存储挂载的底层机制:集成账号
在 Olares 中,"挂载云存储"并不是在本地文件系统里挂一个卷,而是通过集成(Integration)机制完成的:系统在 user-service 中为每种第三方存储服务登记一个"集成账号",文件管理器在侧边栏的云存储目录下列出这些账号,所有文件操作经 Olares 后端代理转发到对应的云服务商。
从前端源码看,系统共登记了 5 类集成(见 集成服务定义):
| 账号类型(type) | 展示名称 | 认证方式 |
|---|---|---|
google |
Google Drive | OAuth 浏览器授权 |
dropbox |
Dropbox | OAuth 浏览器授权 |
awss3 |
AWS S3 | Access Key / Secret Key |
tencent |
Tencent COS | Access Key / Secret Key |
space |
Olares Space | OAuth(钱包/浏览器绑定) |
每类集成都对应一个独立的认证实现文件(awss3.ts、dropbox.ts、googleDrive.ts、tencent.ts 等),由 integrationService 统一按类型实例化。认证方式决定了连接入口:OAuth 类集成必须在 LarePass 手机端完成(授权流程依赖浏览器重定向),而 API 密钥类集成可在 Olares 桌面设置的"集成"页面直接录入。
所有集成账号的增删查都落在 user-service 的同一组 REST 接口上,这一点可以从前端 store integration.ts 中确认:
- 添加:
createAccount()→POST /api/account/create - 删除:
deleteAccount()→DELETE /api/account/<storeKey> - 查询完整记录(含 token):
getAccountFullData()→POST /api/account/retrieve
其中 storeKey 的拼装规则是 integration-account:<type>:<name>(有账号名时)或 integration-account:<type>(旧版单账号),见该文件中的 getStoreKey() 方法。同一类型可以登记多个账号(例如两个不同的 Google Drive),靠 name 字段区分。
连接云存储服务
通过 OAuth 连接(Google Drive、Dropbox)
基于 OAuth 登录的服务需在 LarePass 手机端完成授权:
- 在手机上打开 LarePass。
- 进入设置 > LarePass 设置 > 集成,点击右上角的添加按钮。
- 选择 Google Drive 或 Dropbox。
- 按提示登录并授权。
OAuth 流程产生的 access token 与浏览器会话绑定,因此 CLI 没有为这两类集成提供"一键添加"能力。CLI 集成命令的说明中明确写道:"OAuth flows (Google Drive, Dropbox) ... stay in the SPA — they are browser- and wallet-bound by design",即这类集成只能走 Web/移动端界面完成。
通过 API 密钥连接(AWS S3、腾讯云 COS)
AWS S3、腾讯云 COS 等服务需在 Olares 设置中使用 Access Key & Secret Key 手动配置:
- 从 Dock 或启动台打开设置,进入集成 > 关联您的账户与数据。
- 点击右上角添加账户。
- 选择 AWS S3 或 Tencent COS,点击确认。
- 在弹出的对话框中输入 Access Key、Secret Key、Region 和 Bucket name。
- 点击下一步。凭证验证通过后将显示成功提示。
前端录入表单的实际字段定义在 IntegrationAddInputs.vue:收集 access_key_id、access_key_secret、endpoint(S3 兼容端点 URL,地域信息由端点承载)四个必填项与一个可选的 bucket。提交时前端会把 Secret Key 同时填入 access_token 与 refresh_token 两个字段——因为对象存储这类"直连"流程中二者就是同一个值。
最终发往后端的请求体结构(由 CLI add 命令完整镜像,其注释与 SPA 的 IntegrationAddInputs.vue / AddAccountDialog.vue 逐字段对齐)如下:
{
"name": "<accessKeyID>",
"type": "awss3 | tencent",
"raw_data": {
"access_token": "<accessKeySecret>",
"refresh_token": "<accessKeySecret>",
"endpoint": "https://s3.us-east-1.amazonaws.com",
"bucket": "olares-backup",
"expires_in": 0,
"expires_at": 0
}
}
name 字段直接取 Access Key ID,这也是后续删除、查询该账号时定位它的依据。
同样的服务也可以在 LarePass 中添加:进入设置 > LarePass 设置 > 集成,点击右上角的添加按钮,选择服务并输入凭证。
提示:OAuth 类型的集成以及 Olares Space 需在 LarePass 应用中完成连接。
连接成功后,云存储将出现在文件管理器的云存储目录下。
命令行方式:用 olares-cli 添加与卸载
如果习惯脚本化操作,Olares 自带 CLI 提供了与 GUI 完全等价的对象存储集成管理子树 settings integration accounts(实现位于 cli/cmd/ctl/settings/integration/):
# 列出所有集成账号
olares-cli settings integration accounts list
# 按类型列出(如已挂多个 S3 账号时确认 name)
olares-cli settings integration accounts list-by-type awss3
# 添加 AWS S3(--bucket 可选,对应 SPA 中标注 "optional" 的字段)
olares-cli settings integration accounts add awss3 \
--access-key-id AKIA... \
--access-key-secret XYZ... \
--endpoint https://s3.us-east-1.amazonaws.com \
--bucket olares-backup
# 查看单个账号完整记录(含 raw_data)
olares-cli settings integration accounts get awss3 AKIA...
# 删除集成账号(先 list 确认 type/name 二元组)
olares-cli settings integration accounts delete awss3 AKIA...
accounts get 走的是 POST /api/account/retrieve,请求体为 {"name": "integration-account:<type>:<name>"}——这是唯一能取回完整 raw_data(含 token)的端点,list 系列只返回省略 token 的 mini 记录。delete 命令则在本地按 SPA 相同规则拼出 storeKey 再请求 DELETE /api/account/<storeKey>,保证 CLI 删掉的正是 GUI"删除"按钮指向的那一条记录(见 delete.go 中的注释)。
访问云存储
挂载后,你可以像使用本地存储一样访问和管理云端文件:
- 上传 / 下载文件
- 预览支持的文件类型
- 重命名、移动或删除文件和文件夹
你在文件管理器中的操作将自动同步至对应的云存储服务。
云存储路径的寻址规则
从 files 命令的路径 schema 看,文件后端把所有资源统一建模为三段式"前端路径":
<fileType>/<extend>[/<subPath>]
云存储的四个类型值 awss3、dropbox、google、tencent 都在合法类型表中,其中 extend 段填的是集成账号的 key(即添加时的 Access Key ID / 账号标识),subPath 是账号内部路径。CLI 示例(见 files 根命令 与 ls.go):
olares-cli files ls awss3/<account>/<bucket>
olares-cli files ls dropbox/<account>/
olares-cli files ls google/<account>/
olares-cli files ls tencent/<account>/
云存储响应的信封差异
ls.go 的注释披露了一个实操中容易踩坑的细节:本地卷(drive/、sync/ 等)与云盘返回的列表信封不同——
- 本地卷:子项在
.items[],顶层附带目录自身摘要(numDirs/numFiles/modified); - 云盘(awss3 / google / dropbox / tencent):子项在
.data[],没有父目录摘要,字节数用fileSize而非size字段,modified与mode直接返回空字符串。
CLI 的解码逻辑对两种形状做了兼容(size 缺省时回退 fileSize,空 modified 视为"未知"而非时间戳 0),如果你用 -o json 直接消费后端响应,需要自行注意这个差异。
云存储上的操作限制
并非所有本地卷能力在云盘上都可用,源码中的校验规则给出了明确边界:
- 分享不支持:
internal、public、smb三种 share 创建方式对 cloud 命名空间一律拒绝,测试 share_test.go 以 "TestValidateShareNamespace_RejectsCloudForAllFlavors" 固定了这一规则——云对象存储没有本地文件系统的路径语义可供跨账户分享。 - 压缩 / 解压不支持:
files compress/files extract/files archive对awss3、dropbox、google、tencent命名空间会在执行前直接拒绝(见 archive.go 与 compress.go 中的注释),错误提示会引导你改用 LarePass 应用在浏览器内完成云盘上的压缩/解压。
除上述限制外,上传、下载、预览、重命名、移动、删除均正常可用。
卸载云存储
卸载云存储即移除对应的集成服务,有三个等价入口:
- 在 LarePass 中:进入设置 > LarePass 设置 > 集成,点击要移除的集成,点击右上角更多按钮,选择删除。
- 在 Olares 设置中:进入集成 > 关联您的账户与数据,点击集成卡片,在账户设置页面点击删除。
- 在命令行中:
# 先列出账号确认 type 与 name
olares-cli settings integration accounts list
# 删除(对象存储的 name 即添加时的 Access Key ID;
# OAuth 类账号的 name 是服务商返回的用户标识,如 Dropbox uid、Google 邮箱)
olares-cli settings integration accounts delete awss3 AKIAIOSFODNN7EXAMPLE
olares-cli settings integration accounts delete dropbox 123456789
olares-cli settings integration accounts delete google alice@example.com
删除后,文件管理器的云存储目录下对应条目随之消失。注意删除操作移除的只是 Olares 侧的账号绑定,不会删除云端 Bucket 或云盘里的任何数据。
小结
Olares 的云存储挂载以"集成账号"为核心抽象:OAuth 类服务(Google Drive、Dropbox)在 LarePass 手机端授权,API 密钥类服务(AWS S3、腾讯云 COS)可在 Olares 设置或 olares-cli settings integration accounts add 中录入 Access Key / Secret Key / endpoint / bucket;连接成功后云存储统一出现在文件管理器的云存储目录,支持上传、下载、预览、重命名、移动与删除,分享与压缩/解压缩则被明确限制在本地卷使用。整个机制的接口面(/api/account/*、三段式前端路径、integration-account:<type>:<name> 存储键)在 CLI 源码中有完整镜像,便于脚本化运维与自动化验证。
