【OpenHarmony/HarmonyOs 】从本地 MVP 到云同步AGC Serverless 架构演进方案前言LinkOS 链界目前以 Preferences 保存身份、设置和自定义网址优点是离线可用、实现快速。但当用户希望手机、平板和 2in1 设备共享收藏时就需要账号、云数据库、云函数和文件存储。本文给出一条从本地 MVP 平滑演进到 AGC Serverless 的设计路线。☁️说明本文是基于现有项目结构的演进方案。仓库已经预留 AGC 配置位置但 Cloud DB、Auth 和 Cloud Functions 尚未完成真实接入。一、为什么选择 Serverless对于个人导航和入口管理应用自建服务器意味着域名、证书、部署、扩容、数据库备份和安全补丁。AGC Serverless 可以把常见能力拆开Auth Service用户身份Cloud DB结构化数据与多端同步Cloud FunctionsAI 转发、校验和业务逻辑Cloud Storage用户壁纸与图标Remote Config预置站点与功能开关。Serverless 不等于“没有后端”而是不用自己维护服务器进程。数据规则、鉴权、限流和错误恢复仍然必须设计。二、本地数据与云数据如何分工建议将数据按性质划分数据本地云端当前身份、主题、语言Preferences 缓存可选同步自定义网址RDB 本地副本Cloud DB 主同步源图标与壁纸本地缓存Cloud StorageAI 密钥禁止保存Cloud Function 环境变量角色预置应用内置兜底Remote Config 动态版本应用应保持“离线优先”先从本地数据库渲染再后台拉取云端变更。网络不可用不应让首页变成空白。三、云端网址模型现有UrlItem已经包含同步所需的基础字段interface UrlItem {id:string; title:string; url:string; icon?:string; categoryId:string;sort:number; createdAt:number; updatedAt:number; }接入云端后建议增加interfaceCloudUrlItemextendsUrlItem{ ownerId:string; deletedAt?: number; deviceId:string; version: number; }ownerId用于数据隔离deletedAt支持删除墓碑同步version或服务端更新时间用于冲突判断。直接物理删除会让离线设备不知道某条数据已被删掉。四、同步状态机一条本地修改可以经历以下状态LOCAL_DIRTY →SYNCING→SYNCED↘ FAILED → 等待重试新增、编辑和删除先写本地并标记 DIRTYUI 立即更新同步任务在网络可用时批量上传。成功后记录云版本失败则指数退避。这样用户操作不依赖网络往返。五、冲突解决不能只看“谁最后上传”最简单的 Last Write Wins 会丢失另一个设备的修改。网址模型可以按字段或场景定义规则标题与 URL使用更新时间较新的版本排序使用独立排序版本避免编辑标题覆盖顺序删除墓碑通常优先防止已删除记录复活图标上传成功后再提交新资源地址无法自动合并时保留冲突副本让用户选择。所有时间比较应尽量使用服务端时间不能完全信任设备时钟。六、账号与数据隔离每条云记录都必须绑定已认证用户 ID查询和写入规则同时校验ownerId。客户端传来的 ownerId 不能直接信任云函数应从认证上下文得到真实用户身份。游客模式可继续使用本地数据。用户首次登录时需要决定将本地收藏合并进云端使用云端覆盖本地检测重复 URL 后合并并保留最近编辑。这个流程最好给用户明确预览避免一次登录导致收藏消失。七、AI 请求通过 Cloud Function 中转客户端问题 ↓ AuthToken云函数鉴权 → 限流 → 内容校验 → 调用 AI ↓ 清洗后的结果 客户端渲染云函数应设置单用户频率、每日配额、最大输入长度、模型超时和追踪 ID。第三方 API Key 只放服务端机密配置不进入仓库、不写入agconnect-services.json也不返回客户端。八、AGC 配置与签名项目包名必须与 AGC 控制台完全一致。平台导出的agconnect-services.json放在约定的 rawfile 目录真实配置不应随意公开。真机调试还需要正确导入证书、密钥库和 Profile。接入时建议按小步验证先确认签名和真机安装再完成 AGC SDK 初始化单独验证登录单独验证一条 Cloud DB 读写最后接入本地同步队列。不要一次加入所有服务否则错误很难定位。九、迁移阶段推荐按以下顺序演进将页面对 Preferences 的直接依赖收敛到 Repository自定义网址从 JSON 迁移到本地 RDB加入游客/登录状态接入 Cloud DB只做单向下载验证实现上传、删除墓碑和重试队列增加冲突测试与多设备测试最后开启默认同步。十、总结云同步不是把本地 JSON 上传一次而是一套长期运行的数据协议。离线副本、同步状态、删除墓碑、身份隔离、冲突策略与密钥安全缺一不可。借助 AGC 可以减少基础设施维护但仍要把业务边界设计清楚。沿着 Repository → RDB → Cloud DB 的路线演进能够最大限度保护现有 ArkUI 页面和用户数据。
【OpenHarmony/HarmonyOs 】从本地 MVP 到云同步：AGC Serverless 架构演进方案
【OpenHarmony/HarmonyOs 】从本地 MVP 到云同步AGC Serverless 架构演进方案前言LinkOS 链界目前以 Preferences 保存身份、设置和自定义网址优点是离线可用、实现快速。但当用户希望手机、平板和 2in1 设备共享收藏时就需要账号、云数据库、云函数和文件存储。本文给出一条从本地 MVP 平滑演进到 AGC Serverless 的设计路线。☁️说明本文是基于现有项目结构的演进方案。仓库已经预留 AGC 配置位置但 Cloud DB、Auth 和 Cloud Functions 尚未完成真实接入。一、为什么选择 Serverless对于个人导航和入口管理应用自建服务器意味着域名、证书、部署、扩容、数据库备份和安全补丁。AGC Serverless 可以把常见能力拆开Auth Service用户身份Cloud DB结构化数据与多端同步Cloud FunctionsAI 转发、校验和业务逻辑Cloud Storage用户壁纸与图标Remote Config预置站点与功能开关。Serverless 不等于“没有后端”而是不用自己维护服务器进程。数据规则、鉴权、限流和错误恢复仍然必须设计。二、本地数据与云数据如何分工建议将数据按性质划分数据本地云端当前身份、主题、语言Preferences 缓存可选同步自定义网址RDB 本地副本Cloud DB 主同步源图标与壁纸本地缓存Cloud StorageAI 密钥禁止保存Cloud Function 环境变量角色预置应用内置兜底Remote Config 动态版本应用应保持“离线优先”先从本地数据库渲染再后台拉取云端变更。网络不可用不应让首页变成空白。三、云端网址模型现有UrlItem已经包含同步所需的基础字段interface UrlItem {id:string; title:string; url:string; icon?:string; categoryId:string;sort:number; createdAt:number; updatedAt:number; }接入云端后建议增加interfaceCloudUrlItemextendsUrlItem{ ownerId:string; deletedAt?: number; deviceId:string; version: number; }ownerId用于数据隔离deletedAt支持删除墓碑同步version或服务端更新时间用于冲突判断。直接物理删除会让离线设备不知道某条数据已被删掉。四、同步状态机一条本地修改可以经历以下状态LOCAL_DIRTY →SYNCING→SYNCED↘ FAILED → 等待重试新增、编辑和删除先写本地并标记 DIRTYUI 立即更新同步任务在网络可用时批量上传。成功后记录云版本失败则指数退避。这样用户操作不依赖网络往返。五、冲突解决不能只看“谁最后上传”最简单的 Last Write Wins 会丢失另一个设备的修改。网址模型可以按字段或场景定义规则标题与 URL使用更新时间较新的版本排序使用独立排序版本避免编辑标题覆盖顺序删除墓碑通常优先防止已删除记录复活图标上传成功后再提交新资源地址无法自动合并时保留冲突副本让用户选择。所有时间比较应尽量使用服务端时间不能完全信任设备时钟。六、账号与数据隔离每条云记录都必须绑定已认证用户 ID查询和写入规则同时校验ownerId。客户端传来的 ownerId 不能直接信任云函数应从认证上下文得到真实用户身份。游客模式可继续使用本地数据。用户首次登录时需要决定将本地收藏合并进云端使用云端覆盖本地检测重复 URL 后合并并保留最近编辑。这个流程最好给用户明确预览避免一次登录导致收藏消失。七、AI 请求通过 Cloud Function 中转客户端问题 ↓ AuthToken云函数鉴权 → 限流 → 内容校验 → 调用 AI ↓ 清洗后的结果 客户端渲染云函数应设置单用户频率、每日配额、最大输入长度、模型超时和追踪 ID。第三方 API Key 只放服务端机密配置不进入仓库、不写入agconnect-services.json也不返回客户端。八、AGC 配置与签名项目包名必须与 AGC 控制台完全一致。平台导出的agconnect-services.json放在约定的 rawfile 目录真实配置不应随意公开。真机调试还需要正确导入证书、密钥库和 Profile。接入时建议按小步验证先确认签名和真机安装再完成 AGC SDK 初始化单独验证登录单独验证一条 Cloud DB 读写最后接入本地同步队列。不要一次加入所有服务否则错误很难定位。九、迁移阶段推荐按以下顺序演进将页面对 Preferences 的直接依赖收敛到 Repository自定义网址从 JSON 迁移到本地 RDB加入游客/登录状态接入 Cloud DB只做单向下载验证实现上传、删除墓碑和重试队列增加冲突测试与多设备测试最后开启默认同步。十、总结云同步不是把本地 JSON 上传一次而是一套长期运行的数据协议。离线副本、同步状态、删除墓碑、身份隔离、冲突策略与密钥安全缺一不可。借助 AGC 可以减少基础设施维护但仍要把业务边界设计清楚。沿着 Repository → RDB → Cloud DB 的路线演进能够最大限度保护现有 ArkUI 页面和用户数据。
