鸿蒙端云实战:用 OBS Header 签名做一个「可断点、可取消」的照片备份

举报
yd_287458302 发表于 2026/11/07 11:58:54 2026/11/07
【摘要】 从鸿蒙实践中心的 OBS 云相册案例出发,拆解 OBS Header 签名(HMAC-SHA1)、Content-MD5 与 x-obs-forbid-overwrite、幂等判定、取消语义与分页列举,给出可断点、可取消的照片备份实现要点与安全建议。

`# 鸿蒙端云实战:用 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)}`;
}

几个实测出来的注意点:

  1. Date 必须是 GMT 格式(Wed, 12 Nov 2025 08:00:00 GMT),本地时间或 ISO8601 都会 403。案例里封装成 FormatUtil.formatGmt。
  2. CanonicalizedResource 要带桶名:列举是 /{bucket}/,单对象是 /{bucket}/photo_backup/xxx.jpg。
  3. 自定义头参与签名时必须按字典序、小写、带冒号和换行。案例上传时用了 x-obs-forbid-overwrite: true 防止并发覆盖,于是签名里必须显式带上 'x-obs-forbid-overwrite:true\n',请求头也得同步存在。
  4. 对象键的 URL 编码要保留 /:encodeURIComponent(key).replace(/%2F/g, '/'),否则 photo_backup/xxx.jpg 会被编码成 photo_backup%2Fxxx.jpg,签名和实际请求路径不一致。
  5. 域名用虚拟主机风格: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/ 前缀写」,泄露面会小很多。

八、怎么上手

  1. 在实践中心打开案例,一键进入云端环境(鸿蒙工程、编译链、模拟器都已就绪);
  2. 先跑通列举(LIST)——签名对了,列举就能返回 XML;
  3. 再跑通单文件 PUT,用 x-obs-forbid-overwrite 验证幂等;
  4. 最后接 BackupService 的状态机与取消逻辑;
  5. 想加功能,优先从 BackupRules 入手(比如按目录、按类型过滤),不要动签名层。

端云一体的项目,80% 的坑都在「协议细节」和「状态一致性」上。把这两件事拆干净,剩下的就是业务表达。


案例代码:https://gitcode.com/harmony-practice-center/HarmonyOS-APP-OBSCloudAlbum(MIT)
`

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。