HarmonyOS 鸿蒙Next 6 如何加密存储 + 云端同步扣子智能体的对话记录？

鸿蒙 6 实现扣子智能体对话记录的沙箱加密存储 + 分布式 / 云端同步，核心是「AES-256 加密 + 鸿蒙安全密钥存储 + 分布式 KV 同步 + 云端增量同步」，既保证本地数据安全，又实现跨设备 / 云端的数据一致性，以下是完整实战方案：

一、核心思路

1. 密钥安全：通过鸿蒙Keystore生成 AES-256 密钥（非硬编码），绑定设备 / 用户身份，防止密钥泄露；
2. 本地加密存储：对话记录经 AES 加密后存入鸿蒙沙箱KVStore（持久化），应用退后台 / 重启不丢失；
3. 分布式同步：基于鸿蒙distributedData实现多鸿蒙设备间加密记录的实时同步，处理同步冲突；
4. 云端同步：加密后的记录通过后端接口实现增量同步（仅传变更数据），下载后本地解密，避免明文传输。

二、前置权限配置（module.json5）

需声明以下权限，否则同步 / 加密 / 存储会失败：

{
  "module": {
    "requestPermissions": [
      { "name": "ohos.permission.INTERNET" }, // 云端同步
      { "name": "ohos.permission.DISTRIBUTED_DATASYNC" }, // 分布式同步
      { "name": "ohos.permission.WRITE_USER_DATA" }, // 沙箱存储
      { "name": "ohos.permission.MANAGE_SECURE_SETTINGS" } // 安全密钥存储
    ]
  }
}

三、核心实现代码（完整实战版）

1. 工具类：密钥管理（AES 密钥生成 / 获取）

import keystore from '@ohos.security.keystore';
import crypto from '@ohos.crypto';

// 密钥管理工具类
class KeyManager {
  // 生成/获取AES-256密钥（绑定设备，仅当前应用可访问）
  async getAesKey(): Promise<crypto.Key> {
    const keyAlias = 'kouzi_chat_aes_key';
    try {
      // 尝试获取已存在的密钥
      return await keystore.getKey(keyAlias);
    } catch (err) {
      // 不存在则生成新密钥
      const keySpec = {
        algorithm: keystore.Algorithm.AES,
        keySize: 256,
        purpose: [keystore.KeyPurpose.ENCRYPT, keystore.KeyPurpose.DECRYPT],
        secureLevel: keystore.SecureLevel.SOFTWARE // 无TEE则用SOFTWARE，有则用TEE
      };
      return await keystore.generateKey(keyAlias, keySpec);
    }
  }
}
const keyManager = new KeyManager();

2. 工具类：对话记录加密 / 解密

// 加密/解密工具类
class CryptoUtil {
  // AES-256-CBC加密（IV向量随机，保证每次加密结果不同）
  async encrypt(data: string): Promise<string> {
    const key = await keyManager.getAesKey();
    // 生成随机IV向量（16字节，CBC模式要求）
    const iv = crypto.randomBytes(16);
    const cipher = crypto.createCipher('aes-256-cbc', key, iv);
    // 加密数据 + 拼接IV（解密时需要）
    const encrypted = cipher.update(data, 'utf8', 'base64') + cipher.final('base64');
    return `${iv.toString('base64')}:${encrypted}`;
  }

  // 解密
  async decrypt(encryptedData: string): Promise<string> {
    const key = await keyManager.getAesKey();
    const [ivBase64, encrypted] = encryptedData.split(':');
    const iv = Buffer.from(ivBase64, 'base64');
    const decipher = crypto.createDecipher('aes-256-cbc', key, iv);
    return decipher.update(encrypted, 'base64', 'utf8') + decipher.final('utf8');
  }
}
const cryptoUtil = new CryptoUtil();

3. 本地沙箱存储 + 分布式同步

import distributedData from '@ohos.distributedData';
import preferences from '@ohos.data.preferences';

// 对话记录管理类
class ChatRecordManager {
  private kvStore: distributedData.KVStore | null = null;
  private userId = 'user_123'; // 替换为实际用户ID

  // 初始化分布式KVStore（沙箱存储+多设备同步）
  async init() {
    const kvManager = await distributedData.createKVManager({
      context: getContext(this),
      bundleName: getContext(this).applicationInfo.name
    });
    // 创建分布式KVStore，数据自动同步到同账号设备
    this.kvStore = await kvManager.getKVStore('kouzi_chat_records', {
      createIfMissing: true,
      encrypt: false, // 已手动加密，无需KVStore自带加密
      syncable: true // 开启分布式同步
    });
    // 监听分布式数据变更（其他设备改记录，当前设备即时更新）
    this.kvStore.on('dataChange', async (change) => {
      for (const entry of change.entries) {
        if (entry.key === `chat_${this.userId}`) {
          const decrypted = await cryptoUtil.decrypt(entry.value as string);
          console.log('分布式同步记录：', decrypted);
          // 更新UI显示
          this.updateChatUI(JSON.parse(decrypted));
        }
      }
    });
  }

  // 保存对话记录（加密+存储+同步）
  async saveRecord(record: { query: string; answer: string; time: number }) {
    if (!this.kvStore) await this.init();
    // 1. 获取已有记录
    const oldEncrypted = (await this.kvStore.get(`chat_${this.userId}`)) as string || '[]';
    const oldRecords = JSON.parse(await cryptoUtil.decrypt(oldEncrypted));
    // 2. 追加新记录
    const newRecords = [...oldRecords, record];
    // 3. 加密并存储
    const encrypted = await cryptoUtil.encrypt(JSON.stringify(newRecords));
    await this.kvStore.put(`chat_${this.userId}`, encrypted);
  }

  // 获取本地加密记录（解密后返回）
  async getRecords() {
    if (!this.kvStore) await this.init();
    const encrypted = (await this.kvStore.get(`chat_${this.userId}`)) as string || '[]';
    return JSON.parse(await cryptoUtil.decrypt(encrypted));
  }

  // 更新UI（伪代码，按需实现）
  updateChatUI(records: any[]) { /* 刷新对话列表 */ }
}
const chatManager = new ChatRecordManager();

4. 云端同步（对接后端接口）

import http from '@ohos.net.http';

// 云端同步工具类
class CloudSyncUtil {
  private cloudUrl = 'https://your-server.com/chat/sync'; // 替换为实际后端接口
  private token = 'user_cloud_token'; // 用户云端鉴权token

  // 增量上传加密后的对话记录
  async uploadRecords(records: any[]) {
    const httpClient = http.createHttp();
    try {
      // 仅上传新增记录（对比本地最后同步时间）
      const lastSyncTime = await this.getLastSyncTime();
      const newRecords = records.filter(r => r.time > lastSyncTime);
      if (newRecords.length === 0) return;

      // 加密后上传（本地已加密，云端仅存密文，更安全）
      const encrypted = await cryptoUtil.encrypt(JSON.stringify(newRecords));
      const res = await httpClient.request(this.cloudUrl, {
        method: http.RequestMethod.POST,
        header: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${this.token}`
        },
        extraData: JSON.stringify({
          userId: 'user_123',
          records: encrypted,
          lastSyncTime
        })
      });
      // 更新本地最后同步时间
      await this.setLastSyncTime(Date.now());
      return JSON.parse(new TextDecoder().decode(res.result));
    } finally {
      httpClient.destroy();
    }
  }

  // 从云端下载记录（解密后合并到本地）
  async downloadRecords() {
    const httpClient = http.createHttp();
    try {
      const lastSyncTime = await this.getLastSyncTime();
      const res = await httpClient.request(`${this.cloudUrl}?userId=user_123&lastSyncTime=${lastSyncTime}`, {
        method: http.RequestMethod.GET,
        header: { 'Authorization': `Bearer ${this.token}` }
      });
      const data = JSON.parse(new TextDecoder().decode(res.result));
      if (data.records) {
        // 解密云端记录并合并到本地
        const decrypted = await cryptoUtil.decrypt(data.records);
        const cloudRecords = JSON.parse(decrypted);
        const localRecords = await chatManager.getRecords();
        // 去重合并
        const merged = [...localRecords, ...cloudRecords].filter((v, i, a) => 
          a.findIndex(t => t.time === v.time) === i
        );
        // 保存合并后的记录
        await chatManager.saveRecord({} as any); // 触发本地存储更新
      }
    } finally {
      httpClient.destroy();
    }
  }

  // 获取/设置最后同步时间（沙箱存储）
  async getLastSyncTime() {
    const prefs = await preferences.getPreferences(getContext(this), 'sync_config');
    return prefs.get('last_sync_time', 0) as number;
  }
  async setLastSyncTime(time: number) {
    const prefs = await preferences.getPreferences(getContext(this), 'sync_config');
    await prefs.put('last_sync_time', time);
    await prefs.flush();
  }
}
const cloudSync = new CloudSyncUtil();

5. 调用示例（完整流程）

// 1. 初始化
await chatManager.init();

// 2. 保存扣子智能体对话记录
const chatRecord = {
  query: '这张图里有什么',
  answer: '图片中有一只猫',
  time: Date.now()
};
await chatManager.saveRecord(chatRecord);

// 3. 云端同步（应用启动/后台恢复时触发）
await cloudSync.uploadRecords(await chatManager.getRecords());
await cloudSync.downloadRecords();

四、实战避坑点

1. 密钥安全：

   • 禁止硬编码密钥，必须用Keystore生成 / 存储，且密钥别名绑定用户 / 设备；
   • 有 TEE（可信执行环境）的设备，将secureLevel设为TEE，进一步提升密钥安全性。

2. 分布式同步：

   • 需确保多设备登录同一鸿蒙账号，且开启 “分布式数据同步” 开关；
   • 同步冲突处理：按时间戳合并记录，避免多设备同时修改导致数据覆盖。

3. 内存 / 性能：

   • 对话记录过多时，分页存储（如按天拆分），避免单次加密 / 解密大数组导致内存溢出；
   • 云端同步用增量同步（仅传新增记录），减少流量和耗时。

4. 异常兜底：

   • 密钥丢失时，提供 “重置加密” 功能（清空本地记录，重新生成密钥）；
   • 网络中断时，云端同步失败的记录暂存本地，网络恢复后自动重试。

5. 合规性：

   • 存储用户对话记录需获取隐私授权，云端同步需告知用户数据传输方式；
   • 加密算法优先用鸿蒙系统自带的crypto模块，避免自定义算法导致安全漏洞。