把云端也纳入可视化:TreeMap连接Google Drive/Dropbox/OneDrive
把云端也纳入可视化:TreeMap连接Google Drive/Dropbox/OneDrive
TreeMap 是一款跨平台的磁盘空间可视化工具,可以把硬盘里的每一个字节画成 Treemap 方块图。它的云端功能更让 Google Drive、Dropbox、OneDrive 云盘扫描 也纳入同一张可视化地图——只读取元数据、绝不下载文件内容,删除也只进云盘自身的回收站。本文带你一步步完成连接与使用。
为什么要把云盘画进磁盘地图
硬盘快满时,你往往先想到本地文件,却忘了同步客户端里躺着几十 GB 的"在线文件"。TreeMap 的处理很诚实:
- All storage(全部存储)面板:在 Dashboard 里把本机磁盘和已连接的云盘放在同一个列表,每行显示已用/配额,并带一个 Scan 按钮,把云盘账号直接扫进 Treemap。
- "Not on this computer" 提示行:扫描本地文件夹时,TreeMap 会单独标出其中属于云端占位(online-only)文件的字节数——它们计入文件夹大小,但并不占你本地磁盘的空间,避免你"删了半天却没腾出空间"。
连接云盘的完整步骤(3 分钟)
第一步:创建你自己的免费 API 应用
TreeMap 采用 Bring your own app keys 模式:在对应服务商的开发者控制台创建一个免费应用(OAuth client),Redirect URI 填 http://127.0.0.1:53682/oauth/callback,然后记下 Client ID(Google Drive 还需要 Client Secret)。
三家服务商在代码里统一由 providers.ts 管理,参数对比如下:
| 服务商 | 是否需要 Client Secret | 删除去向 |
|---|---|---|
| Google Drive | 是 | Google Drive trash |
| Dropbox | 否 | Dropbox 已删除文件(可在官网恢复期内找回) |
| OneDrive | 否 | OneDrive recycle bin |
第二步:在设置中粘贴 Client ID
打开应用 Settings → Cloud accounts(设置面板文案见 110-modal-settings.html),填入 Client ID 后点击连接。若浏览器授权后没有自动跳回,页面提供了一个粘贴框,手动粘贴重定向 URL 或授权码即可(实现位于 cloudRoutes.ts 的 /api/cloud/connect/manual)。
第三步:OAuth 授权,令牌只留在本机
授权走标准 OAuth 2.0 授权码 + PKCE 流程,由一个监听固定端口的本机回环服务器接收回调;令牌写入应用数据目录下的 cloud-tokens.json,绝不离开这台电脑。自动续期、账户标签捕获都在 oauth.ts 中完成。
一键扫描:云盘变成一张可交互的地图
点击 All storage 里的 Scan 后,后端通过各家的 metadata API 拉取完整文件树(Google Drive 用 Drive v3 分页列表、Dropbox 用 list_folder、OneDrive 用 Graph delta,分页与重试策略见 providers.ts 中的 retryDelayMs),扫描进度以 cloud://gdrive 这类根路径注册为一次普通扫描。这意味着:
- ✅ Treemap / Sunburst / Circles / Voronoi / Disk City / Grid 全部可用,搜索高亮照常工作
- ✅ Trends 与时间滑块:云盘扫描同样保存快照,历史对比"免费"可用
- ✅ 配额信息有 5 分钟缓存,不会反复轰炸服务商接口
能做什么、不能做什么(设计上的克制)
删除 = 进服务商自己的回收站。选中文档后执行删除,TreeMap 调用对应 API 把文件移入云端回收站(/api/cloud/trash 路由会先校验路径必须位于本次云盘扫描根内,并写审计日志),然后更新地图上的尺寸——和本地"只进回收站"的安全原则完全一致。
同时,以下功能对云盘扫描明确关闭并给出原因(判断逻辑在 120-cloud-accounts.js 的 isCloudScan()):
- 🔒 重复文件检测:需要读取文件内容,而云盘扫描绝不下载内容
- 🔒 Live 实时监听:云盘账号无法流式推送变更
- 🔒 Offload 迁移:把文件拷到另一块盘是纯本地磁盘概念
隐私与数据安全摘要
- 只传元数据:文件名、大小、路径——文件内容一个字节都不会被下载
- 本地优先:未连接任何账号时,零云代码运行、零网络请求(
/api/cloud/status只读本地文件) - 令牌不出机器:访问令牌存于本地 JSON,断连按钮一键清除
- 失败诚实:429/5xx 会带退避重试,权限类 403 直接报错不重试;测试覆盖见 cloud.test.ts
想深入了解整体架构,可阅读 README.md 与 src/services/cloud/ 目录下的三个核心模块:providers(三家接口适配)、oauth(授权与令牌)、cloudScan(云扫描注册与删除)。


