从云相册案例看 HarmonyOS 应用直传 OBS 的设计要点
【摘要】 结合鸿蒙实践中心「用OBS打造个人云相册app」案例,梳理客户端直传对象存储时的凭证边界、分片与断点续传、重试幂等设计,并给出 ArkTS 侧实现要点与六条排错清单。
写在前面
今天在鸿蒙开发实践中心看了「用OBS打造个人云相册app」这个案例,它把照片与视频备份到华为云 OBS,涉及 Header 签名、逐文件上传、备份记录与云端预览。案例偏「跑通流程」,而真正落到产品里,最容易出问题的是上传链路的设计。这篇把客户端直传对象存储的几个关键决策整理成一份对照笔记。
一、先决定:谁持有长期密钥
| 方案 | 做法 | 主要问题 |
|---|---|---|
| 客户端内置 AK/SK | App 自己签名请求 | 密钥随安装包分发,等同于公开,必须禁止 |
| 服务端中转文件 | 文件先传业务服务器再转发 OBS | 带宽与临时存储成本翻倍,大文件易超时 |
| 服务端签发 + 客户端直传 | 服务端只下发临时凭证或预签名 URL,文件直传 OBS | 推荐:密钥不出服务端,流量不经过业务服务器 |
结论很直接:长期密钥永远留在服务端,客户端拿到的是短时间、窄权限的授权——限定到某个对象键、某个桶、某个有效期。
二、一次上传的完整链路
- 客户端先算好文件元信息(大小、类型、校验值),向业务服务端申请上传凭证;
- 服务端校验用户身份与配额,生成带过期时间的授权,并返回对象键(objectKey);
- 客户端用该授权直传 OBS;
- 上传成功后回调服务端写「备份记录」,再由服务端读取对象生成预览链接。
这里有个容易忽略的顺序:记录要以后端确认对象存在为准,不能只信客户端上报的「上传成功」。否则网络抖动时会出现「相册显示已备份、实际对象不存在」。
三、大文件与弱网:可靠性靠四件事
- 分片上传:超过阈值(例如 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 侧的三个实现细节
- 别把大文件整体读进内存:用文件描述符按偏移读取分片,ArrayBuffer 用完及时释放;
- 上传任务放到后台:页面退出要能取消请求,避免生命周期结束后回调打到已销毁的状态变量上;
- 进度与状态分离:进度百分比高频更新用轻量状态,「是否完成 / 是否失败」这类低频状态单独管理,减少整页重绘。
五、排查清单
- 403 / 签名不匹配:先看参与签名的 Header 与请求实际发送的是否一致(尤其 Content-Type 与自定义元数据),再看客户端与服务端时钟偏差;
- 上传成功但预览 404:对象键或桶名拼错,或回调记录早于对象落库;
- 跨域报错:桶的 CORS 规则要允许对应来源、方法与需要的 Header;
- 大文件失败、小文件正常:通常是分片阈值、单请求超时或内存占用问题;
- 出现重复对象:对象键由客户端随机生成且重试时重新生成,应改为服务端统一分配;
- 弱网下卡死:缺超时与取消,重试没有上限。
小结
对象存储的接入难点不在「调通上传接口」,而在凭证边界、可靠性设计和状态一致性这三件事。把这三层理清,再回头看案例里的具体实现会顺畅很多。后续打算把 HarmonyOS 上断点续传的落地过程单独写一篇,也欢迎在评论区交流踩过的坑。
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱:
cloudbbs@huaweicloud.com
- 点赞
- 收藏
- 关注作者
评论(0)