【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 Functions：AI 转发、校验和业务逻辑；
• Cloud Storage：用户壁纸与图标；
• Remote Config：预置站点与功能开关。

Serverless 不等于“没有后端”，而是不用自己维护服务器进程。数据规则、鉴权、限流和错误恢复仍然必须设计。

二、本地数据与云数据如何分工

建议将数据按性质划分：

数据	本地	云端
当前身份、主题、语言	Preferences 缓存	可选同步
自定义网址	RDB 本地副本	Cloud DB 主同步源
图标与壁纸	本地缓存	Cloud Storage
AI 密钥	禁止保存	Cloud Function 环境变量
角色预置	应用内置兜底	Remote Config 动态版本

应用应保持“离线优先”：先从本地数据库渲染，再后台拉取云端变更。网络不可用不应让首页变成空白。

三、云端网址模型

现有 UrlItem 已经包含同步所需的基础字段：

interface UrlItem {
  id: string;
  title: string;
  url: string;
  icon?: string;
  categoryId: string;
  sort: number;
  createdAt: number;
  updatedAt: number;
}

接入云端后建议增加：

interface CloudUrlItem extends UrlItem {
  ownerId: string;
  deletedAt?: number;
  deviceId: string;
  version: number;
}

ownerId 用于数据隔离，deletedAt 支持删除墓碑同步，version 或服务端更新时间用于冲突判断。直接物理删除会让离线设备不知道某条数据已被删掉。

四、同步状态机

一条本地修改可以经历以下状态：

LOCAL_DIRTY → SYNCING → SYNCED
                    ↘ FAILED → 等待重试

新增、编辑和删除先写本地并标记 DIRTY，UI 立即更新；同步任务在网络可用时批量上传。成功后记录云版本，失败则指数退避。这样用户操作不依赖网络往返。

五、冲突解决不能只看“谁最后上传”

最简单的 Last Write Wins 会丢失另一个设备的修改。网址模型可以按字段或场景定义规则：

• 标题与 URL：使用更新时间较新的版本；
• 排序：使用独立排序版本，避免编辑标题覆盖顺序；
• 删除：墓碑通常优先，防止已删除记录复活；
• 图标：上传成功后再提交新资源地址；
• 无法自动合并时保留冲突副本，让用户选择。

所有时间比较应尽量使用服务端时间，不能完全信任设备时钟。

六、账号与数据隔离

每条云记录都必须绑定已认证用户 ID，查询和写入规则同时校验 ownerId。客户端传来的 ownerId 不能直接信任，云函数应从认证上下文得到真实用户身份。

游客模式可继续使用本地数据。用户首次登录时需要决定：

1. 将本地收藏合并进云端；
2. 使用云端覆盖本地；
3. 检测重复 URL 后合并并保留最近编辑。

这个流程最好给用户明确预览，避免一次登录导致收藏消失。

七、AI 请求通过 Cloud Function 中转

客户端问题
  ↓ Auth Token
云函数：鉴权 → 限流 → 内容校验 → 调用 AI
  ↓ 清洗后的结果
客户端渲染

云函数应设置：单用户频率、每日配额、最大输入长度、模型超时和追踪 ID。第三方 API Key 只放服务端机密配置，不进入仓库、不写入 agconnect-services.json，也不返回客户端。

八、AGC 配置与签名

项目包名必须与 AGC 控制台完全一致。平台导出的 agconnect-services.json 放在约定的 rawfile 目录，真实配置不应随意公开。真机调试还需要正确导入证书、密钥库和 Profile。

接入时建议按小步验证：

1. 先确认签名和真机安装；
2. 再完成 AGC SDK 初始化；
3. 单独验证登录；
4. 单独验证一条 Cloud DB 读写；
5. 最后接入本地同步队列。

不要一次加入所有服务，否则错误很难定位。

九、迁移阶段

推荐按以下顺序演进：

1. 将页面对 Preferences 的直接依赖收敛到 Repository；
2. 自定义网址从 JSON 迁移到本地 RDB；
3. 加入游客/登录状态；
4. 接入 Cloud DB，只做单向下载验证；
5. 实现上传、删除墓碑和重试队列；
6. 增加冲突测试与多设备测试；
7. 最后开启默认同步。

十、总结

云同步不是把本地 JSON 上传一次，而是一套长期运行的数据协议。离线副本、同步状态、删除墓碑、身份隔离、冲突策略与密钥安全缺一不可。借助 AGC 可以减少基础设施维护，但仍要把业务边界设计清楚。沿着 Repository → RDB → Cloud DB 的路线演进，能够最大限度保护现有 ArkUI 页面和用户数据。🚀