存储、备份与迁移问题

StarHub 以当前站点 Origin 为边界使用 IndexedDB。http://localhost:5173、GitHub Pages、另一个域名和无痕窗口是彼此独立的数据空间。

数据表速查

数据	表	v4 完整备份
仓库	repos	包含
分类注册表	tags	包含
仓库—分类关系	repoTags	通过每个分类的 repos 恢复
AI 任务与任务项	classificationTasks / classificationTaskItems	不包含
README 缓存	classificationReadmeCache	不包含
重点标记	repositoryHighlights	包含
分类迁移快照	categoryMigrationSnapshots	不包含

导出备份失败

1. 检查浏览器是否允许下载；
2. 保证有足够内存序列化上万个仓库；
3. 关闭其他 StarHub 标签页，等待同步和分类写入结束；
4. 保留 Console 错误但遮盖仓库私有信息；
5. 不要用截图代替 JSON 备份。

导入备份前

• 确认文件来自可信来源；
• 当前数据先另行导出；
• 使用设置页“完整备份导入”，不要误用“仅导入分类”；
• 导入完成后检查仓库数、分类数、重点数和若干实际关系；
• 刷新页面再次检查持久化结果。

完整备份导入会替换仓库、分类、关系、重点标记和分类迁移快照。当前已知限制：它不会清空旧的 AI 任务、任务项和 README 缓存。因此导入后不要直接恢复旧任务；应创建使用当前注册表版本的新任务。

仅导入分类为什么没有项目？

这是设计行为。“导入分类”只提取名称或正式注册表元数据，不导入备份中的 repos，不创建 repoTags，也不覆盖同名分类的颜色和 emoji。完整关系恢复必须使用完整备份导入。

分类迁移失败

正式注册表导入先生成新增、重命名、合并、更新和冲突预览。任何阻塞冲突都应禁止应用。成功迁移前自动创建快照，失败事务应回滚；若结果不符合预期，可在分类管理中撤销最近快照。系统只保留最近 10 个治理快照，不应把它当作长期备份。

分类数量或关系不对

不要直接修改 Dexie 表。先检查：

1. 是否处于搜索、空分类筛选或项目数排序；
2. 同名分类是否只是中英文名称或别名显示；
3. 合并预览中的目标分类是否正确；
4. repoTags 是否在事务失败后被回滚；
5. 用迁移前备份与快照恢复后重新执行。

浏览器提示配额不足

README 缓存、大量仓库和任务项会增加用量。先结束不再需要的任务并导出备份。当前界面尚未提供完整的 AI 缓存清理器，不能保证“清空全部数据”移除全部三张 AI 表；这是后续必须修复的问题。不要手动删除单张关系表，以免造成孤立数据。

换域名或设备后数据不见

这是浏览器同源隔离，不是 GitHub 数据被删除。回到原地址导出 v4 备份，再在新地址导入。AI 任务与 README 缓存不会迁移，AI Key 也不会进入备份，需要重新配置。

最后手段：清空站点数据

只有在备份已验证、应用无法启动且常规恢复失败时才使用浏览器站点数据清理。清理会删除本地整理结果且不可由 StarHub 服务器恢复。清理后重新登录只能恢复 GitHub Stars，不能从 GitHub 恢复分类、重点标记和人工审核记录。