公开缓存备份格式与迁移

普通缓存、上传缓存和浏览器账号导出是三种不同的对象。本页解释如何保存、检查、迁移和恢复，不把它们混成一个“万能备份”。

三种对象的区别

对象	由什么生成	主要用途	删除/恢复风险
普通缓存备份	缓存备份接口/网页	完整账号数据留档和恢复	恢复可能覆盖当前数据
上传缓存快照	机台或上传缓存页面	网络波动时暂存待上传数据	上传可能产生重复或覆盖
浏览器账号导出	账号选择器	迁移本地账号条目	泄露可能暴露登录入口

普通备份不是上传快照列表；浏览器导出也不是服务端数据备份。恢复前必须先确认对象类型。

文件命名

推荐使用不包含凭据的文件名：

<ACCOUNT_ALIAS>_<OBJECT_KIND>_<YYYYMMDD-HHmm>_<CLIENT_VERSION>.json

例如：

account-a_normal-backup_20260910-1030_vX.json
account-a_upload-snapshot-index_20260910-1035_vX.json

账号别名必须是脱敏别名。不要把用户名、完整机台编号、Token、二维码或访问码放进文件名。

普通备份流程

1. 验证目标 Token；
2. 打开缓存页面；
3. 下载当前备份；
4. 在本地计算文件大小和哈希；
5. 在受保护位置保存原文件；
6. 记录账号别名、时间、版本和来源；
7. 需要分享时只分享哈希和结构摘要。

下载后不要直接编辑原文件。先复制到工作副本，修改前保留只读原件。

备份对象检查

语法检查

const text = await file.text();
let data;
try {
  data = JSON.parse(text);
} catch {
  throw new Error('备份不是有效 JSON');
}

语法有效仍需继续检查来源、账号和字段结构。空对象、截断文件和错误账号的 JSON 都可能语法有效。

结构检查

检查：

• 顶层是否为页面要求的对象；
• 关键容器是否为对象/数组；
• 数字是否为有限值；
• 时间字段是否可解释；
• 记录数组是否有合理长度；
• 未知字段是否保留；
• 是否出现另一个账号的明显标识。

检查器只做报告，不要自动删除无法识别的字段。

预览和确认

恢复前向用户显示：

• 文件名和导出时间；
• 脱敏后的账号别名；
• 记录/成绩/相片/配置的数量摘要；
• 文件大小和结构状态；
• 当前账号与备份账号是否匹配；
• 恢复可能覆盖哪些范围。

预览页面不要显示 Token、密码、访问码、私钥、完整地址或完整服务 JSON。确认按钮应明确写“恢复当前账号缓存”，不能只写“确定”。

恢复前保护

恢复前必须再下载当前状态，至少保留：

1. 当前普通缓存；
2. 当前上传缓存索引；
3. 重要相片；
4. 当前配方原值；
5. 当前客户端和服务地址摘要。

如果当前状态不能下载，先停止恢复并联系管理员。不要在没有回滚点时连续恢复多个文件。

恢复后的验证

恢复接口返回成功后按顺序验证：

1. 重新读取配方；
2. 刷新游玩记录；
3. 刷新成绩；
4. 读取相片列表；
5. 刷新上传缓存；
6. 用页面筛选或时间范围确认记录归属；
7. 记录返回的 count 和页面实际可见结果。

页面索引可能异步建立。恢复成功后立即看不到记录，不要再次恢复或清空当前数据；先刷新、重新登录并等待同步。

跨版本迁移

跨版本时采用“读取完整对象、只改必要字段、保留未知字段”的策略。不要把旧文件先转换成只包含当前 UI 字段的精简 JSON。

迁移前记录：

• 原始文件哈希；
• 原服务/客户端版本；
• 目标版本；
• 发生过的字段转换；
• 是否删除了无法迁移的字段以及原因。

如果目标版本拒绝对象，保存错误消息和未修改的原文件，交给管理员确认，不要靠删除字段盲试。

上传缓存快照

上传缓存快照的名称必须来自服务列表。下载快照后保存原始内容，不要把 data 解析后只保留网页当前显示的曲目。

上传前：

1. 刷新快照列表；
2. 确认当前 Token 和目标访问码；
3. 重新确认账号别名；
4. 提交一次；
5. 超时后读取列表和记录；
6. 只有确认未成功才重试。

不要通过重复游玩制造更多待上传数据来“测试上传”。

浏览器账号导出

浏览器导出只迁移账号入口和本地元数据，不等于服务端缓存备份。导入后：

• 逐条验证账号；
• 检查用户/机台类型；
• 检查本地名称和排序；
• 不要在公共设备长时间保留导出文件；
• 不要把导出文件上传到群文件或公开网盘。

导入失败时保留原设备账号列表，不要先删除原条目再重试。

备份的保留与清理

至少保留：

• 大版本更新前的一份；
• 恢复前的一份；
• 恢复后验证通过的一份；
• 发生异常前最近一次正常使用的一份。

问题关闭后清理临时工作副本、聊天转存和下载目录中的敏感副本。长期备份按设备锁屏、加密磁盘或离线介质保护。

备份故障矩阵

现象	先检查	不要做
JSON 无法解析	文件是否完整、编码是否正确	手动删除不懂的字符
恢复按钮禁用	是否选择文件、结构是否通过	直接改浏览器状态
恢复成功但页面空	账号、索引、同步队列	连续恢复更多文件
条数明显不对	来源、时间范围、压缩/截断	合并两个账号
上传超时	列表、记录、Token	自动重复上传
相片不见	列表接口和账号	把浏览器缩略图当备份
导入后账号错位	本地名称、类型、验证结果	删除原设备条目