Olares 云存储挂载实战:把 Google Drive、Dropbox、AWS S3 接入文件管理器的完整流程

原创2026-10-15 14:28:561,419 阅读
文章标签:云原生后端运维

Olares 云存储挂载实战:把 Google Drive、Dropbox、AWS S3 接入文件管理器的完整流程

本篇基于 Olares 的官方文档与仓库源码,完整讲解如何把 Google Drive、Dropbox、AWS S3、腾讯云 COS 等云存储挂载到 Olares,并在文件管理器中像本地存储一样访问和管理云端文件。读完后你不仅掌握 OAuth 授权与 API 密钥两条连接路径、卸载清理的完整操作,还能看懂后端集成账号(Integration Account)的存储结构与 REST 接口,甚至学会用 olares-cli 在命令行下完成同样的挂载与卸载。

Olares 文件管理器中的云存储目录

云存储挂载的底层机制:集成账号

在 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 手机端完成授权:

  1. 在手机上打开 LarePass。
  2. 进入设置 > LarePass 设置 > 集成,点击右上角的添加按钮。
  3. 选择 Google Drive 或 Dropbox。
  4. 按提示登录并授权。

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 手动配置:

  1. 从 Dock 或启动台打开设置,进入集成 > 关联您的账户与数据。
  2. 点击右上角添加账户。
  3. 选择 AWS S3 或 Tencent COS,点击确认。
  4. 在弹出的对话框中输入 Access Key、Secret Key、Region 和 Bucket name。
  5. 点击下一步。凭证验证通过后将显示成功提示。

前端录入表单的实际字段定义在 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 源码中有完整镜像,便于脚本化运维与自动化验证。

登录后查看全文
Terminus