鸿蒙端云实战:用 OBS Header 签名做一个「可断点、可取消」的照片备份
`# 鸿蒙端云实战:用 OBS Header 签名做一个「可断点、可取消」的照片备份
鸿蒙(HarmonyOS)端的备份功能,难的不是调通一次上传,而是让它在弱网、误触取消、重复扫描相册这些真实场景里依然稳定:不重复上传、不丢记录、进度可解释。
「鸿蒙开发实践中心」里有一个案例正好把这件事完整做了一遍:HarmonyOS-APP-OBSCloudAlbum,基于 ArkTS + 华为云 OBS 构建个人云相册。这篇文章把它最值得抄的几个设计拆开讲,并且指出一个上手时最容易踩的坑——OBS 的 Header 签名。
一、整体链路
UI(pages/Index.ets)
└─ BackupService 调度、进度、取消、记录落盘
├─ MediaScanner 扫描本地相册
├─ BackupRules 幂等判定(要不要传)
└─ ObsClient 签名 + HTTP(PUT / GET / LIST)
└─ 华为云 OBS
分层的价值在于:ObsClient 只管协议,BackupService 只管状态机,BackupRules 只管「这个文件到底要不要传」。三者解耦之后,取消、重试这些逻辑才不会互相污染。
二、签名是唯一的拦路虎
OBS 的 Header 签名算法本身不复杂,难在拼串要精确:
StringToSign = HTTP-Verb + "\n"
+ Content-MD5 + "\n"
+ Content-Type + "\n"
+ Date + "\n"
+ CanonicalizedHeaders
+ CanonicalizedResource
Signature = Base64( HMAC-SHA1( SK, StringToSign ) )
Authorization: OBS <AK>:<Signature>
案例里用 ArkTS 的 @ohos.security.cryptoFramework 实现 HMAC-SHA1:
private async hmacSha1(key: string, data: string): Promise<string> {
const mac = await cryptoFramework.createMac('SHA1');
const symKey = await cryptoFramework.createSymKeyGenerator('HMAC')
.convertKey({ data: this.stringToUint8(key) });
await mac.init(symKey);
await mac.update({ data: this.stringToUint8(data) });
const raw = await mac.doFinal();
return this.base64Encode(raw.data);
}
拼串的地方没有偷懒:
private async sign(verb: string, contentType: string, contentMd5: string,
date: string, canonicalizedResource: string, canonicalizedHeaders: string = ''): Promise<string> {
const stringToSign: string = verb + '\n' + contentMd5 + '\n' + contentType + '\n' +
date + '\n' + canonicalizedHeaders + canonicalizedResource;
return `OBS ${this.config.accessKey}:${await this.hmacSha1(this.config.secretKey, stringToSign)}`;
}
几个实测出来的注意点:
- Date 必须是 GMT 格式(
Wed, 12 Nov 2025 08:00:00 GMT),本地时间或 ISO8601 都会 403。案例里封装成FormatUtil.formatGmt。 - CanonicalizedResource 要带桶名:列举是
/{bucket}/,单对象是/{bucket}/photo_backup/xxx.jpg。 - 自定义头参与签名时必须按字典序、小写、带冒号和换行。案例上传时用了
x-obs-forbid-overwrite: true防止并发覆盖,于是签名里必须显式带上'x-obs-forbid-overwrite:true\n',请求头也得同步存在。 - 对象键的 URL 编码要保留
/:encodeURIComponent(key).replace(/%2F/g, '/'),否则photo_backup/xxx.jpg会被编码成photo_backup%2Fxxx.jpg,签名和实际请求路径不一致。 - 域名用虚拟主机风格:
host = ${bucket}.${endpoint},请求时同时设置Host头。
三、上传:Content-MD5 与「不允许覆盖」
上传走 PUT,代码里做了两件很关键的事:
// 十六进制 MD5 → 16 字节 → Base64(OBS 要的是 Base64,不是 Hex)
const digest = new Uint8Array(16);
for (let i = 0; i < 16; i++) digest[i] = parseInt(md5Hex.substring(i * 2, i * 2 + 2), 16);
const contentMd5 = this.base64Encode(digest);
const authorization = await this.sign('PUT', contentType, contentMd5, date,
`/${this.config.bucket}/${this.encodeKey(objectKey)}`, 'x-obs-forbid-overwrite:true\n');
- Content-MD5 是 Base64 的 16 字节摘要,直接把 Hex 字符串塞进去必然签名失败;
x-obs-forbid-overwrite: true让服务端拒绝覆盖同名对象。配合「先查本地记录、再查云端」的策略,多端同时备份也不会互相写坏文件。
四、断点与幂等:只认「五个字段全一致」
一个经常被忽略的问题:相册每次扫描都会给出新的 uri,但文件其实没变。案例的做法是把「是否已备份」拆成两道判断。
static matches(entry: PhotoBackupEntry, record: PhotoBackupEntry, destination: string): boolean {
return record.destinationId === destination && record.localUri === entry.localUri &&
record.size === entry.size && record.modifiedAt === entry.modifiedAt && entry.modifiedAt > 0 &&
/^[a-f0-9]{32}$/i.test(entry.md5 || '') && (record.md5 || '').toLowerCase() === entry.md5.toLowerCase();
}
destinationId(endpoint + bucket)、localUri、size、modifiedAt、md5 五个字段全一致才算「传过」。少任何一个都可能把「同名不同内容」的照片误判成已备份。云端侧还有一道 sameContent:用对象的 ETag 与本地 MD5 比对。
注意:普通 PUT 的 ETag 等于对象 MD5,但分片上传的 ETag 是
MD5(分片MD5)-分片数,不能直接和本地 MD5 比较。真要用分片,得走x-obs-*相关头并改写比对逻辑。
五、取消与一致性
备份动辄几百个文件,用户随时会点取消。案例的处理是:
- 用一个
cancelled标志,在每个文件的边界处检查,而不是在传输中途硬中断; - 每个文件传输成功后立即提交本地记录,即使取消与完成并发也不回滚;
- 状态里区分
running/cancelling/message,UI 能解释「正在取消」而不是卡死。
这段逻辑看着平淡,但它是「取消后重新点备份不会重复上传」的前提。
六、列举对象:分页与权限取舍
列举用 max-keys=1000 + marker 游标,并做三重保护:页数上限 1000、IsTruncated 必须合法、NextMarker 不能与上一页相同(防死循环)。
有意思的是 getStorageInfo——它没有调用 GET /?storageinfo(那是桶级操作,需要额外桶读权限),而是列举对象本地累加 Size。对于只申请了对象读写权限的账号,这个折中很实用,代价是对象多时首次统计稍慢。
七、一个必须提醒的安全点
这个案例把 AK/SK 存在了 preferences 里(obs_config)。作为教学案例没问题,但生产环境建议改成:
- 用 HUKS 加密存储密钥,或
- 不落 AK/SK,改由服务端签发 STS 临时凭证,按需下发、限时失效、限定前缀权限。
再配合「桶策略只允许 photo_backup/ 前缀写」,泄露面会小很多。
八、怎么上手
- 在实践中心打开案例,一键进入云端环境(鸿蒙工程、编译链、模拟器都已就绪);
- 先跑通列举(LIST)——签名对了,列举就能返回 XML;
- 再跑通单文件 PUT,用
x-obs-forbid-overwrite验证幂等; - 最后接
BackupService的状态机与取消逻辑; - 想加功能,优先从
BackupRules入手(比如按目录、按类型过滤),不要动签名层。
端云一体的项目,80% 的坑都在「协议细节」和「状态一致性」上。把这两件事拆干净,剩下的就是业务表达。
案例代码:https://gitcode.com/harmony-practice-center/HarmonyOS-APP-OBSCloudAlbum(MIT)
`
- 点赞
- 收藏
- 关注作者
评论(0)