鸿蒙云相册端云一体实践:OBS 直传签名与断点续传设计

举报
yd_272402707 发表于 2026/11/14 00:19:44 2026/11/14
【摘要】 基于鸿蒙开发实践中心的 OBS 云相册案例,拆解客户端直传的四个关键点:V4 签名规范化、分片断点续传状态设计、备份映射表与短时效预览授权,并整理 5 个实际踩过的坑。

鸿蒙云相册端云一体实践:OBS 直传签名与断点续传设计

最近在鸿蒙开发实践中心跑通了「用 OBS 打造个人云相册」这个案例,从端侧 ArkTS 到云侧 OBS 的整条链路踩了不少坑。本文不复述案例步骤,而是把其中真正影响落地的东西拆开讲:为什么选择客户端直传、OBS 的 V4 签名到底怎么拼、断点续传的状态该怎么存,以及几个调试时最容易卡住的地方。

一、为什么不让服务端中转

最常见的做法是:端侧把图片传给业务服务器,服务器再转存 OBS。这样做的好处是 AK/SK 不出服务端,但缺点在相册场景里非常明显:

  1. 相册备份是典型的「大文件、高并发、弱网」场景,中转会让业务服务器承担全部带宽,成本随用户量线性上涨;
    1. 用户上传原图动辄几 MB,服务端中转意味着两次公网传输,耗时翻倍;

      1. 断点续传、并发上传都需要服务端维护会话状态,复杂度高。

      2. 因此案例采用的是「STS 临时凭证 + 客户端直传」:服务端只负责签发短时效的临时凭证,端侧拿到凭证后直接与 OBS 通信。责任边界很清楚:服务端管授权,OBS 管存储,端侧管上传编排。

    2. 二、V4 签名:把 CanonicalRequest 拼对

  2. OBS 兼容 S3 的签名体系,核心是把请求要素规范化后做两级 HMAC。很多同学在这一步失败,原因通常不是算法写错,而是规范化字符串和真实请求不一致。
    第一步是构造 CanonicalRequest:
function buildCanonicalRequest(
  method: string,
  objectKey: string,
  query: string,
  headers: Record<string, string>,
  payloadHash: string
): string {
  const canonicalUri = '/' + objectKey.split('/').map(encodeRfc3986).join('/');
  const sortedKeys = Object.keys(headers).map(k => k.toLowerCase()).sort();
  const canonicalHeaders = sortedKeys
    .map(k => `${k}:${headers[k].trim().replace(/\s+/g, ' ')}\n`)
    .join('');
  const signedHeaders = sortedKeys.join(';');
  return [method, canonicalUri, query, canonicalHeaders, signedHeaders, payloadHash].join('\n');
}

这里有三个容易忽略的点:

  • URI 编码必须用 RFC3986,空格要编码成 %20 而不是 +,中文对象名要先做 UTF-8 编码再逐字节转义;
    • 头部的 key 要全部小写并排序,值要去掉首尾空白、把连续空白压成一个空格;

      • payloadHash 必须是请求体的 SHA256,PUT 空体时是空字符串的 SHA256,而不是空串本身。

      • 第二步是拼 StringToSign 并逐级派生密钥:

    • async function signV4(
        secretKey: string,
        dateStamp: string,
        region: string,
        service: string,
        canonicalRequest: string
      ): Promise<string> {
        const stringToSign = [
          'AWS4-HMAC-SHA256',
          amzDate,
          `${dateStamp}/${region}/${service}/aws4_request`,
          sha256Hex(canonicalRequest)
        ].join('\n');
      
        const kDate = await hmac(('AWS4' + secretKey), dateStamp);
        const kRegion = await hmac(kDate, region);
        const kService = await hmac(kRegion, service);
        const kSigning = await hmac(kService, 'aws4_request');
        return bytesToHex(await hmac(kSigning, stringToSign));
      }
      

      最终请求头里带 Authorization: AWS4-HMAC-SHA256 Credential=.../..., SignedHeaders=..., Signature=...。调试时建议把 canonicalRequest 原文打印出来,和 OBS 返回的错误信息逐项比对,比盲猜快得多。

      三、断点续传:状态要存「可恢复的最小集合」

      案例里做的是整文件 PUT,但真实相册一定会遇到大视频。我的做法是按 5 MB 分片,端侧维护一个上传会话:

      interface UploadSession {
        objectKey: string;
        uploadId: string;
        totalParts: number;
        completed: Map<number, string>; // partNumber -> etag
        fileSize: number;
        mtime: number;
      }
      

      用 Preferences 持久化时要注意,Map 不能直接序列化,需要转成 Array<[number, string]>。恢复时先调 ListParts 拿到服务端已存在的分片,再和本地记录做交集,避免重复上传。

      断点续传真正难的不是重传,而是一致性:分片 ETag 必须按服务端返回值记录,不能自己算;CompleteMultipartUpload 时要把分片按 partNumber 升序排列;上传失败重试要区分可重试错误(5xx、超时)和不可重试错误(403 签名失效、404 桶不存在)。

      四、备份记录与云端预览

      端侧用 RDB 存「本地相册 assetId → objectKey」的映射,字段包括文件大小、最后修改时间、上传状态。这样做有两个好处:

      • 增量备份只需要比对 mtime 和 size,不用每次全量扫描;

        • 删除、重命名等操作可以通过映射表做级联处理,不会产生孤儿对象。

        • 预览环节不建议把桶设为公共读。更稳妥的做法是后端签发短时效的预签名 GET URL,端侧用 Image 组件直接加载。如果只在自己的账号内预览,也可以走临时凭证直连。

      • 五、几个实际踩过的坑

      1. 设备时间偏差:V4 签名有效期默认 15 分钟,设备时钟偏差超过这个范围会直接 403。上线前建议做一次服务端时间校准。
        1. Content-Type 不参与签名但影响回显:上传时如果不带正确的 Content-Type,浏览器预览会变成下载。
          1. 中文对象名:直接用原始字符串拼 URL 一定失败,必须先 encodeRfc3986 再拼接。
            1. 并发上传数:鸿蒙端 http 模块的并发能力有限,建议控制在 3~4 路,超了反而因为排队导致整体变慢。

              1. 失败重试要退避:固定间隔重试在弱网下会放大服务端压力,指数退避加抖动更稳。

              2. 六、小结

            2. 这个案例的价值不在于「把照片传上去」,而在于把端云一体的几个关键决策讲清楚了:授权与存储分离、签名规范化、上传状态可恢复、预览走短时效授权。把这四点做扎实,换成别的对象存储也基本能平移。

          2. 如果你也在做鸿蒙端云项目,建议先用小文件把签名链路跑通,再上分片和断点续传,排查问题的成本会低很多。
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

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

全部回复

上滑加载中

设置昵称

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

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

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