Skip to content

feat(storage): 支持 Google Drive 作为管理员托管存储后端 #128

Description

@AptS-1547

背景

AsterDrive 需要支持 Google Drive 作为一种底层存储后端:由管理员授权并配置一个 Google Drive 账号或共享盘目录,把它作为统一存储池使用。普通用户上传到 AsterDrive 的文件仍然走现有文件链路、配额链路和 storage_policy 选择逻辑,只是最终 blob 落点可以是 Google Drive。

这和“用户连接自己的 Google Drive 后导入 / 同步文件”不是同一个需求。文件导入、远端目录浏览、用户级外部连接件会在后续单独 issue 中设计,本 issue 只处理 Google Drive 作为 storage_policy.driver_type 下存储后端的能力。

目标

新增 Google Drive storage driver,使管理员可以通过一个 Google Drive 账号或共享盘空间创建存储策略,并让 AsterDrive 将内部 blob 写入该 Google Drive 存储池。

该 driver 的语义应与 Local / S3 / Tencent COS 等底层存储后端一致:

  • AsterDrive 仍然拥有内部文件、blob、配额、分享、缩略图、垃圾箱和物理删除等生命周期语义
  • Google Drive 只作为 blob 存储落点,不作为用户外部文件系统暴露给普通用户
  • 普通用户不需要也不应该授权自己的 Google Drive 账号
  • 管理员 OAuth 凭据只用于后端服务端访问,不暴露给浏览器或普通用户

范围

  • 新增 DriverType::GoogleDrive 或等价的 Google Drive storage driver 类型
  • 支持管理员完成 Google Drive OAuth 授权,并把授权结果绑定到某个存储策略或待创建存储策略
  • 支持配置 Google Drive 存储池参数,例如:
    • 根目录 / root folder id
    • 是否使用共享盘 / shared drive id
    • 是否使用 appDataFolder 或普通 Drive 目录
    • 上传策略,默认应支持 resumable upload
  • 支持 storage driver 基础能力:
    • 写入 blob
    • 读取 blob
    • 删除 blob
    • 存在性 / 元数据检查(如现有 trait 需要)
    • 存储策略连通性测试
  • 支持大文件上传到 Google Drive 时的流式或分段/可恢复上传路径,避免把完整文件一次性读入内存
  • 支持 Google Drive API 错误到 AsterDrive 稳定错误语义的映射,例如:
    • 管理员授权失效,需要重新授权
    • 权限不足
    • 远端对象不存在
    • API 限流
    • 临时网络或服务错误
  • Google Drive 中由 AsterDrive 创建的对象应带有可识别的应用元数据或命名约定,避免误删非 AsterDrive 管理的文件
  • 删除 blob 时只删除 AsterDrive 管理的 Google Drive 对象,不应误操作管理员账号中的其他文件
  • 前端管理后台提供最小可用入口:
    • 创建 / 编辑 Google Drive 存储策略
    • 发起管理员 OAuth 授权
    • 查看授权状态
    • 重新授权
    • 测试连接

非目标

  • 本 issue 不做用户级 Google Drive 外部连接件
  • 本 issue 不做浏览用户 Google Drive 远端目录
  • 本 issue 不做从 Google Drive 选择文件 / 文件夹导入到 AsterDrive
  • 本 issue 不做定时同步、单向同步或双向同步
  • 本 issue 不支持普通用户各自绑定 Google Drive 账号作为个人存储空间
  • 本 issue 不要求完整处理 Google Docs / Sheets / Slides 原生文档导入或导出转换;这些属于后续导入 / 同步类需求
  • 本 issue 不要求前端直传 Google Drive;管理员 OAuth token 不应下发给浏览器

建模建议

Google Drive 在本 issue 中应建模为底层 storage driver,而不是 external connector。

推荐边界:

  • 长期配置属于 storage policy
    • driver type
    • root folder / shared drive / appDataFolder 等 driver options
    • 加密后的管理员 refresh token 或凭据引用
  • 临时 OAuth flow 可以单独建表
    • state hash
    • PKCE verifier
    • target policy id 或创建中的临时上下文
    • expires_at
    • consumed_at
  • 不应新增面向普通用户的 google_drive_connections(owner_user_id, ...) 作为主模型;那是未来“用户外部连接件 / 导入 / 同步”方向的模型

如果需要新增凭据存储结构,应明确它和现有 storage_policy.access_key / secret_key / options 的关系,并说明 token 加密、轮换和重新授权策略。

存储路径建议

Google Drive 没有 S3 那种天然 object key 语义,核心对象身份是 file id。实现时需要明确 file_blobs.storage_path 与 Google Drive file id / 应用元数据之间的映射策略。

可选方向:

  • 保持 storage_path 为 AsterDrive 内容寻址路径,通过 Google Drive appProperties 或等价元数据记录该路径,并在 driver 内解析到 file id
  • 或让 put 后返回 Google Drive file id 作为实际 storage_path,但这会影响现有 driver trait 和 blob 创建链路,需要更谨慎评估

本 issue 倾向优先选择对现有 blob 模型侵入较小的方案。

验收标准

  • 管理员可以创建 Google Drive 类型的存储策略
  • 管理员可以完成 Google Drive OAuth 授权,并看到授权 / 连接状态
  • Google Drive 存储策略可以通过后台连接测试
  • 普通用户上传文件时,若命中 Google Drive 存储策略,文件内容可以成功写入 Google Drive 存储池
  • 用户可以正常下载命中 Google Drive 存储策略的文件
  • 文件删除、垃圾箱清理或 blob ref_count 归零后的物理删除能够正确清理对应 Google Drive 对象
  • 大文件上传不会要求把完整文件一次性缓冲到内存
  • 管理员 token 失效、权限不足、对象不存在、API 限流、临时错误等场景有稳定错误语义和可理解的管理后台反馈
  • 普通用户无法看到或获取管理员 Google Drive OAuth token
  • 文档或 PR 说明中明确写清:本功能是管理员托管 storage backend,不是用户 Google Drive 导入 / 同步连接件

Metadata

Metadata

Assignees

Labels

Help WantedExtra attention is neededPriority: LowLow priority issueRustPull requests that update Rust codeStorage DriverTypeScriptPull requests that update JavaScript code

Type

No type

Fields

No fields configured for issues without a type.

Projects

Relationships

None yet

Development

No branches or pull requests

Issue actions