文章

搞个自用 mac 版华为云盘软件

1 个月前

目录(11 节)
  1. 为什么要自用
  2. 技术路径
  3. 一条依赖都没有
  4. 认证:授权码 + PKCE,回调打回 127.0.0.1
  5. 传输:20 MiB 是那条线,308 不是错误
  6. 访达集成:最像「系统级」的一部分,也最费劲
  7. 签名:免费证书 7 天过期,于是搞了个取舍
  8. 渲染器自己造:因为 macOS 不认电子书
  9. 它现在会干什么
  10. 一些不太好意思讲的取舍
  11. 现在

事情的起因是一次换手机。

以前用 iPhone,手机和 Mac 之间隔空投送一下,照片文件就飞过去了,方便到让人以为这是天经地义的。后来换了华为手机,这条传送带就断了——华为云盘有,官方客户端却只有 Windows 版,macOS 的没有。想在 Mac 上看个云盘里的 PDF,只能开浏览器登录网页版,一层层点进去,下载,再去下载文件夹里把刚才那个东西翻出来,看完删掉。一天循环三次,人就会开始琢磨点别的办法。

rclone 有 huaweidrive 后端,能挂载能同步,很好。但它是「把远端变成命令行里的一个路径」的工程,而我的需求是「我就想看一眼那个 PDF」——用起重机开啤酒瓶盖,不划算。

于是就有了这个东西:一个自用的、原生的 macOS 华为云盘客户端。现在 0.14.4,用户一名,需求评审会由该名用户在自己脑子里开,通常三秒钟结束。

为什么要自用

先说清楚它不是什么:它不是产品。没有官网、没有更新检查、没有「请阅读以下协议共 87 屏」。它就是一个能双击打开的窗口,加上两万六千行 Swift 在背后干活——关掉窗口就安静地缩回菜单栏。

「自用」这个定位带来一个副作用:功能的取舍标准只有一个——我自己会不会用。于是它长出了一堆在云盘软件里看起来不太对劲的东西,比如在云盘里看书(后面会讲)。没人能投诉我,这就是自用最大的好处。

技术路径

一条依赖都没有

SwiftUI + AppKit,零第三方依赖,用 swiftc 直接编译成一个可执行文件。不依赖 rclone,不依赖任何官方 SDK,也不依赖 CocoaPods、SwiftPM 或者谁的 Package.resolved 明天会不会突然解析失败。

./build.sh --local     # 不依赖 Apple 账号、不会过期的本地签名(含访达集成)
./build.sh --plain     # 只出主应用,不含扩展;最快,不需要证书

官方 SDK 是给服务端集成用的,我这种「一个人、一台 Mac、一个云盘」的场景用不上。真正有用的是接口行为说明书——rclone 的 huaweidrive.go 就躺在 references/ 里,专门用来对答案。

认证:授权码 + PKCE,回调打回 127.0.0.1

OAuth 走标准的授权码流程加 PKCE,回调地址是本机回环:

http://127.0.0.1:53683/

端口写死在代码里,改端口要同步改华为开发者平台上的登记,两边差一个字都会失败,而且失败得很安静。被自己坑过之后,我写了个脚本核对版本号有没有漂移——能自动核对的事情就绝对不要靠记性。

传输:20 MiB 是那条线,308 不是错误

20 MiB 以内的文件一把直传;超过就走官方的分片续传。这条协议里最有意思的一处是:308 不是错误,是「继续」。

每片 PUT 完,服务端回 308 表示收下了、接着发。我一开始把它落到通用错误映射上,于是界面会认真地告诉你「接口要求跳转,请检查区域设置」——把「还缺数据」翻译成「你区域配错了」,误导性拉满。本机有个 924 MB 的 mkv 就在这上面卡过一次,每次重试都重走同一条路,直到我把分片循环改成以服务端回来的 Range 为准推进偏移,而不是按自己发出去多少字节记账。

访达集成:最像「系统级」的一部分,也最费劲

这部分用的是 NSFileProviderReplicatedExtension,也就是把云盘做成一个 File Provider 域,挂进访达侧栏,文件按需下载、改完自动上传、云端变化按增量游标同步。

访达侧栏「位置」里多出一个华为云盘,点进去就是云端目录

费劲的地方不在于「能跑起来」,而在于要按 Apple 的语义对齐,而这些语义大都是一次性的、写成文档但很容易读漏的:

  • 目录枚举一次只能发一批(批大小按系统建议值,没给就 200),Apple 的原话是要「几秒内答完一页」;没有游标时必须明确结束这一轮,否则枚举会原地打转。
  • 工作集(working set)不碰网络,内容来自 App Group 里的磁盘索引。以前每次枚举工作集都从根开始把整个盘走一遍,那是这套实现最大的性能问题。
  • 索引落盘时不能回头读 self.index——闭包里再调一个会读它的 persist() 就是重叠访问,Swift 的独占性检查会直接把扩展进程打掉。25 份真机崩溃报告全落在 persist() 上,它一崩,云端变化就再也进不了访达。这个 bug 现在有名字,叫「0.12.1 修的那个」。
  • 目录列表不完整、或者云端有访达表达不了的文件名时,宁可报错也不猜。猜错的表现不是「少一个文件」,是「误删本地文件」。

顺带一提,访达侧栏那个「已与 iCloud 同步」的小徽章,第三方扩展拿不到——它是 iCloud 专属实现,反查 Finder 二进制能看到符号名里就写着 iCloud。写在这里,是为了防止未来的我照着它去实现。

签名:免费证书 7 天过期,于是搞了个取舍

访达集成靠 App Group 这个沙盒授权,而它只存在于签名构建里;免费 Apple ID 的描述文件 7 天过期,之后 app 双击即被杀。于是有一条「先不签名地编、再用 ad-hoc 加精简授权手工签」的本地路径,它拿不到 keychain-access-groups,主应用和访达扩展就改用 App Group 容器里的一个文件共用登录态。

代价写得很清楚,也不打算美化:凭据从「钥匙串加密」变成「0600 明文文件」。保护来自沙盒,不是加密——以你的身份执行的进程照样读得到。写这一段的目的是以后忘了别怪自己。

渲染器自己造:因为 macOS 不认电子书

这一条是「自用」的直接产物。我想在云盘里存网文直接看,结果 qlmanage -m 列出的生成器里没有任何一个能渲染 epub / mobi / azw3——系统那条路对电子书是死的。

那就自己拆容器:epub 是 zip,mobi 一族是 PalmDB,正文是被压缩过的老式 HTML。目录和正文分开加载——一本 28 MB 的中文网文 epub 有 1415 章,全解开要两三百 MB 常驻内存,而我一次只看一章。所以章节在模型里只是一个位置,翻到那章才解。实测打开 0.04 s,翻一章 1–3 ms。中文书按惯例给了首行缩进两个全角空格,这个细节没人要求,但少了就是不对。

它现在会干什么

主窗口就是一个正常的文件管理器:左侧三个入口,右侧列表或图标网格,顶部导航、搜索和「筛选当前文件夹」。

华为云盘主窗口:左边三个侧栏入口(我的云盘 / 传输记录 / 回收站),右边是文件列表,顶部是导航与搜索

具体的清单大致是这些:

  • 浏览、搜索、排序:全盘搜索或当前文件夹内搜索,可按类型与时间过滤;列表与图标网格两种视图。
  • 备注:读写云端项目自己的 description 字段,简介栏显示,⌘⇧E 编辑,留空即清除。用云端字段而不是本地数据库,换台机器备注还在。
  • 上传下载:文件与整个文件夹都可传;20 MiB 以内直传,超过走分片续传;下载分块 + 断点续传,传输记录里能「在访达中显示」已完成的项目。
  • 文件操作:重名处置、移动、复制(服务器端复制,不下载再上传)、重命名、批量重命名(查找替换 / 前后缀 / 序号,带预览与重名拦截)、删除到回收站、恢复、彻底删除、清空回收站,⌥⌘Z 撤销删除。
  • 清理中心:全盘按类型统计占用、列出最占空间的位置、最大的文件、空文件夹,以及重复文件——重复的判定是 sha256 和大小都相同才算,只发列表请求,不下载内容。

存储分析:总占用、文件与文件夹数量、按类型分布、最占空间的位置

  • 预览:快速查看、缩略图、在线预览,带总量上限的磁盘缓存。
  • 应用内读书:.epub / .mobi / .azw / .azw3 点开就能读,目录侧栏(带封面)、正文重排、插图、字号可调,记住上次读到第几章。
  • 播放记忆:应用内播过的位置按文件 id 记在本机,下次打开就接着上次看。只看了几秒的不记,看到结尾的清掉、下次从头。
  • 传输编排:并发闸门、上下行分别限速、暂停与继续、队列插队、定时开始。续传存档跨重启有效,启动后自动继续未完成的传输。

设置里的「传输」:上/下行限速、同时传输数量、下载重名处置

  • 菜单栏常驻与通知:窗口收起来也能看见进度,Dock 角标跟着传输变,传完发系统通知。
  • 外观:浅色 / 深色 / 自动,即时生效,跨重启记住。
  • 访达集成:一键启用或停用,云端变化按增量游标同步,设置里能看到最近检查成功时间、索引进度、系统报告的待同步数量;停用会保留已经下载和还没上传的文件。

设置里的「同步与后台」:访达集成状态、自动刷新、传输完成通知、登录自启等开关

  • 缓存可控:单文件预览上限、缓存总量上限(超出按最久未用清理)、续传存档条数与一键清空——清空都不会动云端。

设置里的「存储」:预览缓存占用、单个文件预览上限、缓存总量上限、续传存档条数

一些不太好意思讲的取舍

删功能比加功能难。 0.13.x 一口气下架了三样:收藏、最近修改、智能文件夹。都能用,但各自维护着一份要跟着增量变更流走的本地索引——自用软件里,没人用的功能和坏掉的功能没有区别,留着只会让未来的自己以为下一版会修。删掉之后侧栏干净了,⌘⇧S 和 ⌘⇧K 也空出来了。

「保留下载」拿不到,别照着实现。 访达右键那个「保留下载」只有 iCloud 有,第三方复制式扩展既没有对应 API,手工写扩展属性也不被采纳;setTagData 和 setFavoriteRank 则是 iOS 专用,macOS 上就是没有。彩色标签和「最近使用」只能由应用自己维护。

测试跑在自建的模拟网络上。 好处是不碰真实账号也能覆盖绝大多数逻辑;坏处是模拟网络发现不了服务端的怪癖——比如无序游标会返回空列表加一个假游标。所以另有一个只读探针脚本对着真实账号跑,不写不改不删,也不打印任何令牌。这种事只能拿真接口验。

提交前的一条命令:

./check.sh              # 版本号核对 + 测试 + 免签名构建
./check.sh --fileprovider   # 再跑一次 Xcode 工程构建,核对扩展真的产出了

其中一部分检查是读源码和配置的静态检查:图标名能不能解析、每个 Picker 的选项是不是都带了 .tag、挂令牌的出口是不是只有一个、两份 entitlements 里有没有 App Group 和联网授权。这几样写错的共同点是——不会让任何代码变红,只会让「设置里能点,访达里没有」。所以它们必须被脚本盯着。

现在

它就在菜单栏上待着,一个云朵图标,同步的时候变成转圈的箭头。没有更新检查,没有遥测,没有「您的意见对我们很重要」。想改就改,改完 ./build.sh --local 一遍,三分钟之后新版本就躺在那儿了。

写给自己的软件有个好处:需求永远清楚,评审永远通过,而且第一个用户和唯一用户是同一个人——这人还挺好说话的,只要别把 308 当错误就行。