从云相册案例看 HarmonyOS 应用直传 OBS 的设计要点

举报
yd_286131434 发表于 2026/11/12 11:00:26 2026/11/12
【摘要】 结合鸿蒙实践中心「用OBS打造个人云相册app」案例,梳理客户端直传对象存储时的凭证边界、分片与断点续传、重试幂等设计,并给出 ArkTS 侧实现要点与六条排错清单。

写在前面

今天在鸿蒙开发实践中心看了「用OBS打造个人云相册app」这个案例,它把照片与视频备份到华为云 OBS,涉及 Header 签名、逐文件上传、备份记录与云端预览。案例偏「跑通流程」,而真正落到产品里,最容易出问题的是上传链路的设计。这篇把客户端直传对象存储的几个关键决策整理成一份对照笔记。

一、先决定:谁持有长期密钥

方案 做法 主要问题
客户端内置 AK/SK App 自己签名请求 密钥随安装包分发,等同于公开,必须禁止
服务端中转文件 文件先传业务服务器再转发 OBS 带宽与临时存储成本翻倍,大文件易超时
服务端签发 + 客户端直传 服务端只下发临时凭证或预签名 URL,文件直传 OBS 推荐:密钥不出服务端,流量不经过业务服务器

结论很直接:长期密钥永远留在服务端,客户端拿到的是短时间、窄权限的授权——限定到某个对象键、某个桶、某个有效期。

二、一次上传的完整链路

  1. 客户端先算好文件元信息(大小、类型、校验值),向业务服务端申请上传凭证;
  2. 服务端校验用户身份与配额,生成带过期时间的授权,并返回对象键(objectKey);
  3. 客户端用该授权直传 OBS;
  4. 上传成功后回调服务端写「备份记录」,再由服务端读取对象生成预览链接。

这里有个容易忽略的顺序:记录要以后端确认对象存在为准,不能只信客户端上报的「上传成功」。否则网络抖动时会出现「相册显示已备份、实际对象不存在」。

三、大文件与弱网:可靠性靠四件事

  • 分片上传:超过阈值(例如 8~16 MB)改走分片,单片失败只重传单片;
  • 断点续传:把 uploadId、已完成片号与 ETag 持久化在本地,App 重启后能接着传;
  • 并发控制:并发数固定(3~5),避免占满连接、拖垮前台 UI;
  • 重试与幂等:只对可重试错误(超时、5xx)做指数退避,对象键由服务端统一分配,重试不会产生重复对象。

下面的代码只表达结构,具体 SDK 调用以官方文档为准:

async function uploadFile(file: FileLike, getTicket: () => Promise<Ticket>) {
  const ticket = await getTicket()             // 服务端签发,短期有效
  const parts = split(file, 8 * 1024 * 1024)  // 按固定大小切片
  const done = await restoreProgress(file.id)  // 读本地断点记录
  for (const p of parts) {
    if (done.has(p.index)) continue
    await withRetry(() => putPart(ticket, p))  // 指数退避重试
    await saveProgress(file.id, p.index)
  }
  await completeUpload(ticket)                 // 通知合并
  await confirmWithServer(ticket.objectKey)    // 后端确认后写记录
}

四、ArkTS 侧的三个实现细节

  1. 别把大文件整体读进内存:用文件描述符按偏移读取分片,ArrayBuffer 用完及时释放;
  2. 上传任务放到后台:页面退出要能取消请求,避免生命周期结束后回调打到已销毁的状态变量上;
  3. 进度与状态分离:进度百分比高频更新用轻量状态,「是否完成 / 是否失败」这类低频状态单独管理,减少整页重绘。

五、排查清单

  1. 403 / 签名不匹配:先看参与签名的 Header 与请求实际发送的是否一致(尤其 Content-Type 与自定义元数据),再看客户端与服务端时钟偏差;
  2. 上传成功但预览 404:对象键或桶名拼错,或回调记录早于对象落库;
  3. 跨域报错:桶的 CORS 规则要允许对应来源、方法与需要的 Header;
  4. 大文件失败、小文件正常:通常是分片阈值、单请求超时或内存占用问题;
  5. 出现重复对象:对象键由客户端随机生成且重试时重新生成,应改为服务端统一分配;
  6. 弱网下卡死:缺超时与取消,重试没有上限。

小结

对象存储的接入难点不在「调通上传接口」,而在凭证边界、可靠性设计和状态一致性这三件事。把这三层理清,再回头看案例里的具体实现会顺畅很多。后续打算把 HarmonyOS 上断点续传的落地过程单独写一篇,也欢迎在评论区交流踩过的坑。

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

评论(0)

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

全部回复

上滑加载中

设置昵称

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

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

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