GitHub 同步——把 userdata.json 存到你自己的仓库

为什么选 GitHub

如果你有 GitHub 账号（Chaldea 作者就在 GitHub），可以利用 GitHub 仓库做数据备份：

• 完全可控：数据存在你自己的仓库里，Chaldea 服务器宕机也不影响
• 版本历史：GitHub 自动保留文件历史，能回退到任意版本
• 跨设备同步：任何设备登录 GitHub 账号就能拉取最新数据

设置步骤

前置

1. 你有一个 GitHub 账号
2. 创建一个空的私有仓库（推荐私有，因为里面有你的游戏数据）
3. 创建一个 GitHub Personal Access Token（PAT），勾选 repo 权限

在 Chaldea 里配置

设置 → 应用数据 → 用户数据管理 → GitHub 同步：

1. 输入 GitHub Token
2. 输入仓库名称（格式：用户名/仓库名）
3. 输入文件路径（默认 userdata.json，不需要改）
4. 测试连接 → 确认成功
5. 保存

同步操作

配置好后，GitHub 同步的按钮会出现在用户数据管理页面：

• 上传到 GitHub：把本地 userdata.json 推到仓库
• 从 GitHub 下载：把仓库里的版本拉到本地
• 清除 SHA：解决同步冲突用

SHA 校验机制

GitHub 同步有一个 SHA（哈希）校验机制：

• 每次上传 / 下载时，Chaldea 会计算本地文件和仓库文件的 SHA 值
• 如果 SHA 匹配 → 正常同步
• 如果 SHA 不匹配 → 同步失败

为什么会不匹配

典型场景：

• 设备 A 刚上传了版本 X
• 设备 B 修改了本地数据但没先下载版本 X
• 设备 B 尝试上传 → SHA 不匹配（设备 B 的版本是旧的 + 修改，不是版本 X + 修改）
• 同步失败

怎么解决

两种方式：

方式一：先下载再上传（推荐）

• 设备 B 先从 GitHub 下载最新版本
• 在下载的基础上修改数据
• 再上传

方式二：清除 SHA 强制覆写

• 在 GitHub 同步设置里点"清除 SHA"
• 然后再上传 / 下载
• 这次 Chaldea 不做 SHA 校验，直接覆写

⚠️ 清除 SHA 前确认一下——你要覆写的方向对不对（是用本地覆写服务器，还是用服务器覆写本地）。覆写方向错了会丢失数据。

和在线备份同时用

完全可以同时开启在线备份和 GitHub 同步：

• 在线备份：速度快、适合日常
• GitHub 同步：可靠性高、当在线备份不可用时兜底

两者互不干扰——你可以上午用在线备份同步，下午用 GitHub 再存一份。

GitHub Token 安全警告

Chaldea 的 GitHub Token 以明文存在本地设置里（settings.json）。这意味着：

• 不要把 settings.json 也备份到 GitHub 仓库（会泄露 Token）
• 如果设备被盗，攻击者可能拿到 Token
• 建议 Token 权限只勾选 repo，不要开额外权限

仓库里存了什么

GitHub 仓库里只会有一个 userdata.json 文件（默认路径）。如果想存更多东西：

• 可以手动把 backup/ 目录里的每日备份也复制到仓库
• Chaldea 的 GitHub 同步只处理你配置的那个文件路径