[Idea] 存储功能插件化

[ushaio]

相关模块 / Area

Mobile 客户端 / Mobile

需求与场景 / Need and use case

面向Desktop端，减轻应用压力

以插件形式满足多存储源存储的需求，如Google Driver、One Driver、FnOS等

---

Web端不考虑，暂时用当前能力

建议方案 / Proposed solution

TODO

替代方案 / Alternatives

No response

参考资料 / References

No response

参与贡献 / Contribution

• 我愿意参与讨论、测试或实现。 / I am willing to discuss, test, or implement this idea.

[ushaio]

ADR-0008: 桌面端存储源插件化

• 状态：提议
• 日期：2026-08-14
• 决策者：产品 + 桌面端开发
• 关联模块：desktop/storage/、desktop/services/upload.go、desktop/db/models.go

背景

桌面端需要支持 Google Drive、FnOS 以及未来更多存储系统。目前 desktop/storage/ 中的
local、s3、github provider 通过 switch 在编译期注册；StorageSource 也使用固定字段。
新增 provider 必须修改并重新发布桌面程序，无法由第三方独立扩展。

同时，桌面端大部分云端上传和删除操作仍经 ProxyClient 转发到 Web API，桌面本地资源库
desktop/local_library/ 则是独立的本地文件索引系统。本文只定义“桌面端云端/远程对象存储
适配”的插件边界，不把本地资源库索引和 Web 服务端 provider 混为一个插件系统。

决策

采用“外部进程插件 + JSON-RPC over stdio”的架构。桌面主进程负责插件生命周期、统一存储
抽象、凭据、传输、任务和 UI；插件负责具体服务的认证和对象操作。

不采用 Go plugin：跨平台 ABI 和 Go 版本兼容性不足，且插件崩溃会影响主进程。不在第一版
允许插件注入任意 React/HTML UI；配置页面由桌面端根据插件提供的 JSON Schema 渲染。

Wails App
  ├─ Plugin Manager
  ├─ Storage Core (统一上传/删除/扫描/重试)
  ├─ Credential Store
  └─ Wails API
       ├─ Google Drive plugin
       ├─ S3/R2 plugin
       └─ WebDAV/FnOS plugin

核心抽象

业务服务只依赖统一端口，不依赖 provider 名称：

type StoragePort interface {
    Upload(ctx context.Context, req UploadRequest) (ObjectInfo, error)
    Delete(ctx context.Context, req DeleteRequest) error
    Stat(ctx context.Context, sourceID, key string) (ObjectInfo, error)
    List(ctx context.Context, req ListRequest) (ListResult, error)
    Health(ctx context.Context, sourceID string) HealthResult
}

插件通过 manifest 声明能力，而不是由核心猜测能力：

object.put, object.get, object.delete, object.stat, object.list
resumable.upload, checksum, public-url, signed-url, oauth

无法提供永久 URL 的 provider 必须返回 URL 类型（public、signed、temporary 或
local），核心不能假定所有对象都有永久公开地址。

插件包和运行时

插件以带签名的 zip 分发：

manifest.json
bin/<platform>-<arch>/plugin
icon.png
signature.sig

manifest 至少包含 id、version、apiVersion、各平台可执行文件、能力列表和
configSchema。插件管理器负责安装、签名校验、启停、版本兼容、健康检查、崩溃隔离和日志。

JSON-RPC 初始方法：

plugin.getManifest
plugin.health
source.validate
source.authorize
object.put
object.delete
object.stat
object.list
object.getUrl

上传内容不直接编码进 JSON。Host 为每次传输创建带随机 ID 的临时文件/句柄，插件只获得该
句柄，避免暴露用户完整文件系统路径。所有请求必须支持超时、取消、请求 ID 和错误码。

存储源模型

现有固定 provider 字段逐步迁移为：

id
name
pluginId
pluginVersion
config (非敏感 JSON)
credentialRef (系统凭据库引用)
enabled
status
lastError
createdAt / updatedAt

Windows 使用 Credential Manager，macOS 使用 Keychain，Linux 使用 Secret Service。OAuth
refresh token、Access Key、Secret Key 不明文写入数据库，也不通过命令行参数传递。

照片中的 storageProvider 保留兼容一段时间，新增 pluginId 后以
pluginId + storageSourceId + storageKey 作为实际定位信息；迁移完成后再废弃旧字段。

Provider 适配原则

先实现通用协议，再实现私有 API：

1. S3/R2 作为通用对象存储插件。
2. WebDAV 作为通用文件存储插件。
3. Google Drive 作为需要 OAuth、分页和断点上传的专用插件。
4. 只有 FnOS 的标准协议无法覆盖其能力时，才开发 FnOS 专用插件。

FnOS 的具体插件方案必须先确认其是否支持 S3、WebDAV、SMB 或稳定的官方 HTTP API；不能
仅凭产品名称假设需要私有适配。

Google Drive 约束

Google Drive 插件需要 OAuth 2.0 Authorization Code + PKCE、refresh token、文件夹 ID、
resumable upload、分页 list、删除、429/5xx 重试和临时下载 URL。Google 的下载链接不能
默认作为永久 CDN URL 保存，storageKey 应保存 Drive file ID 或插件定义的稳定对象标识。

安全约束

• 默认插件进程不拥有任意文件系统访问权，只能使用 Host transfer handle。
• 安装包必须签名校验，插件版本和 API 版本必须兼容。
• 插件崩溃、超时或协议错误只能使当前 source 不可用，不能拖垮桌面主进程。
• 删除操作声明 object.delete 能力并进行明确确认。
• 记录插件 ID、版本、source ID、请求 ID、错误码和审计日志；不得记录 token。
• 网络请求设置超时、并发限制、大小限制和速率限制。

实施阶段

Phase 0：边界确认

• 确认插件只负责远程对象存储，不负责 local_library 的索引和组织。
• 确认桌面端与 Web 端是否共享 StorageSource 数据。
• 调查 FnOS 的标准协议、认证和 URL 语义。

Phase 1：统一核心接口

• 抽出 StoragePort 和统一错误/能力模型。
• 将现有 local、S3、GitHub provider 改为内置实现。
• 消除上传、删除、扫描业务中的 provider switch。
• 保留旧 StorageSource 字段的兼容读取。

Phase 2：插件运行时

• 新增 Plugin Manager 和插件目录。
• 实现 manifest、JSON-RPC stdio、传输句柄、超时、取消和崩溃恢复。
• 暂不允许任意插件 UI，先使用 JSON Schema 配置表单。

Phase 3：配置和凭据

• 将 StorageSource 迁移为 pluginId + config + credentialRef。
• 接入系统凭据存储和 OAuth 回调 Host。
• 增加插件安装、启停、测试连接和授权 API。

Phase 4：首个外部插件

• 优先实现 Google Drive，验证 OAuth、断点上传、临时 URL 和配额重试。
• 随后实现通用 WebDAV 或 S3 插件，再评估 FnOS 私有插件。

验证要求

每个插件必须通过统一 contract tests：

• validate、health、put、stat、list、delete；
• 大文件和断点上传；
• 超时、取消、崩溃重启；
• 429/5xx 重试和 URL 过期；
• 凭据隔离和数据迁移；
• 删除确认和审计日志。

备选方案

方案	结论	原因
Go plugin 动态库	否决	跨平台和 ABI 兼容性差，崩溃隔离困难
WASM/WASI	暂缓	沙箱好，但 OAuth、网络和大文件传输 Host API 成本较高
内置 provider 注册表	否决	仍需修改和发布主程序，无法实现第三方扩展
外部进程 JSON-RPC	采用	跨语言、跨平台、可隔离，适合首版和第三方 SDK

影响

正面影响：新增存储源无需修改桌面主业务；插件可以独立发布和升级；Google Drive、FnOS 等
差异较大的服务可以共享统一上传队列和错误处理。

代价：需要维护插件协议、签名、安装和版本兼容；外部进程带来 IPC、调试和分发复杂度；
跨 provider 的 URL、删除、扫描和一致性语义必须显式建模。

本 ADR 只批准架构方向，不代表立即实现所有 provider。下一步应先完成 Phase 0，并以五个
基础能力（validate、health、put、stat、delete）实现一个最小插件运行时。

[ushaio]

存储插件生成为应用插件，提高未来可扩展性