酒馆用户数据云端备份与多端同步

本文介绍我的清绝咕咕助手 2.0 版本的新功能，利用 Git 和 GitHub 实现酒馆用户数据云端备份与多设备同步。适用于使用咕咕助手部署的 安卓 Termux、Windows 及 Linux Docker 酒馆。

介绍

• 数据安全：每一次提交都有记录，可以轻松回溯到任意时间点版本，防止本地数据损坏或丢失，从此本地酒馆想卸就卸，在哪重装就直接云端下载。
• 多平台同步：Git 作为中转站，实现多设备间数据的上传与下载。
• 免费与私密：GitHub 的免费私有仓库，没有空间和流量限制，确保数据隐私安全。
• 云酒馆自动备份： 如果不需要多平台同步，仅使用云酒馆，可以设为每日自动上传备份，避免服务器故障带来的损失。

如果需求云酒馆自动备份功能，因各种原因无法使用咕咕助手，或想要多一份保险更加稳妥，请查看： 《1panel 为重要目录配置每日自动备份》

可选：汉化 GitHub 界面

为了更方便地浏览 GitHub 网站，支持浏览器扩展功能的浏览器可以安装扩展和脚本，将界面显示为中文。

• 安装篡改猴 (Tampermonkey) 扩展：访问 Tampermonkey 官网 获取适合浏览器的版本。
• 安装油猴脚本：访问 GitHub 中文化插件 并点击安装。

一、初始配置（一次性）

初次使用需要先在 GitHub 创建仓库和令牌，然后在酒馆设备上进行配置。

步骤 1：准备 GitHub 仓库

1. 创建个人访问令牌 (Token)

   • 打开 新建个人访问令牌（经典） 页面。
   • 在 Note（备注） 处填写任意的备注，如 酒馆备份 。
   • 将 Expiration（有效期） 设置为 No expiration (无有效期)。
   • 在 Select scopes（选择作用域） 中，勾选 repo 权限。
   • 点击页面底部的 Generate token（生成令牌） 按钮。
   • 立即复制并妥善保存 生成的以 ghp_ 开头的令牌。此令牌仅显示一次，遗失后无法找回，只能重新生成。

     

2. 创建私有仓库 (Repository)

   • 访问 创建新仓库 页面。
   • 输入一个 英文 的 Repository name（仓库名称） ，如 sillytavern-backup 。
   • 将仓库可见性设置为 Private (私有)。
   • 点击开启 Add README 选项。
   • 点击 Create repository（创建仓库） 按钮。

     

3. 获取仓库地址

   • 创建好会跳转仓库页面。
   • 点击绿色的 Code（代码） 按钮，在 HTTPS 标签下，复制显示的仓库地址保存好。

     

步骤 2：配置客户端

安卓 Termux / Windows

1. 运行咕咕助手脚本，选择 2 数据同步 (Git 云端)。（初次进入此页面会要求配置身份，输入你的 github 账号名 和 邮箱，或者任意输入即可。）
2. 选择 1 管理同步配置 (仓库地址/Token)。
3. 选择 1 修改/设置同步信息，依次粘贴前面保存的 仓库地址 和 令牌。
4. 配置完成后，选择 2 备份到云端（上传） 进行测试。如果成功，刷新 GitHub 仓库页面应能看到已上传的文件。

Linux 云服务器 (Docker + 1Panel)

1. 在 1Panel 面板中，通过路径 容器 -> 编排 找到 SillyTavern 应用。

2. 点击对应的 编排目录 文件夹图标，直接进入 SillyTavern 的根目录。

3. 在根目录下，创建一个名为 .gugu 的新文件夹（已有就不用创建）。注意，文件夹名称以一个英文句号 . 开头。

4. 进入 .gugu 文件夹，在其中创建一个名为 git_sync.conf 的文件（已有就不用创建）。

5. 编辑 git_sync.conf 文件，将以下内容完整粘贴进去（已有就不用粘贴）：

   # --- 必填项 ---
   # 你的私有 Git 仓库地址
   REPO_URL="这里填仓库地址"
   # 用于认证的 Git 仓库访问令牌
   REPO_TOKEN="这里填令牌"
   
   # Git 提交时使用的作者信息 (建议填写 GitHub 用户名和邮箱，或随便填)
   GIT_USER_NAME="这里填用户名"
   GIT_USER_EMAIL="这里填邮箱"
   
   # --- 可选项 (高级同步规则，不懂可不填) ---
   # 是否同步 config.yaml 文件 (true / false)。默认为不同步。
   SYNC_CONFIG_YAML=""
   
   # 用户数据映射规则 ("本地用户名:云端用户名"，使用英文冒号分隔，默认用户名是 default-user)
   USER_MAP=""

6. 根据文件内的注释提示，将 REPO_URL、REPO_TOKEN、GIT_USER_NAME 和 GIT_USER_EMAIL 这四个必填项替换为自己的信息。

7. 下载脚本文件：

   • 海外下载：点击下载

   • 大陆下载：复制下面地址到浏览器打开，然后右键另存为。

     https://gitee.com/canaan723/st-tools/raw/main/dckr-sync-st.json

8. 在 1Panel 中，进入 计划任务 页面，导入刚刚下载的 dckr-sync-st.json 文件，会生成 咕咕助手【上传】 和 咕咕助手【恢复】 两条任务。

9. 保持任务状态为 已停止，需要时手动点击 执行 来触发上传或恢复操作。执行结果可在 报告 中查看。

如果想使用云酒馆自动备份请跳转后文的 场景三：云酒馆每日自动备份

二、常见使用场景

场景一：所有设备使用默认账号

这是最简单的情况。首先在数据最完整的设备上执行 上传 操作，然后在其他设备上执行 下载/恢复 操作，即可完成初次同步。之后，在更换设备使用前，记得先上传最新数据，更换设备后下载就可以了。

场景二：多用户模式下的特定账号同步

如果服务器上使用多用户模式，例如有 default-user、A、B 三个账号，而日常使用的是 A 账号，本地设备则是默认账号（default-user）。此时可以使用 用户映射 功能将两个用户文件夹对应到同一个 github 仓库文件夹以实现同步。

在服务器上，编辑 sillytavern/.gugu/git_sync.conf 文件，修改 USER_MAP 项：

# ...
# 用户数据映射规则 ("本地用户名:云端用户名"，使用英文冒号分隔，默认用户名是 default-user)
USER_MAP="A:default-user"

这样设置后，上传时会将服务器上 A 用户的数据同步到云端 default-user 目录下。本地设备无需任何额外配置，正常下载即可同步 A 用户的数据。

场景三：云酒馆每日自动备份

如果没有多端同步需求，即，仅使用云酒馆游玩，非常推荐设为自动备份。

1. 回到 1PANEL 面板中的计划任务页面，找到 咕咕助手【上传】 的任务，默认为 已停止（手动），我们需要把它改成自动。
2. 点击条目后面的 更多 按钮，点击 编辑。
3. 执行周期 改为 每天、4 小时 、0分钟 ，意为每日凌晨 4 点自动备份。
4. 失败重试次数 改为 3。
5. 点击 确认 按钮。
6. 点击 咕咕助手【上传】 任务的 已停止 按钮，改为 已启用，如图中显示一致即代表自动备份已经开启。

   

7. 点击 执行 按钮，进行一次手动备份，点击报告验证一下是否成功。

三、其他功能说明

导出扩展链接

由于不同设备存在网络环境差异，扩展安装地址也不一定相同，因此不做同步。此功能可导出当前已安装扩展的链接，方便查看或重新安装。

• 安卓/windows：在助手脚本中选择 2 数据同步 (Git 云端) -> 5 导出扩展链接。
• 云服务器：每次执行计划任务的报告末尾会附带扩展链接。

自动本地备份

在执行云端下载/恢复操作时，系统会自动对本地数据进行本地备份，以防万一。本地备份文件存储位置如下：

• 安卓：Termux 根目录下的 SillyTavern_Backups 文件夹。
• windows：咕咕助手脚本同目录下的 _SillyTavern_Backups 文件夹。
• 云服务器：酒馆根目录下的 _SillyTavern_Backups 文件夹。

查看配置文件

忘记仓库名和令牌的话可以看一下：

• 安卓：Termux 根目录下的 .config/ad-st/ 文件夹。
• windows：咕咕助手脚本同目录下的 .config 文件夹。
• 云服务器：酒馆根目录下的 .gugu 文件夹。

使用 GitHub 进行版本控制

GitHub 不仅是数据的中转站，更是一个强大的版本控制工具。通过网页界面，可以查看到每一次数据变动，并恢复到任意历史状态。

浏览和下载数据

1. 查看文件内容 在仓库主页，直接点击相应的文件或文件夹即可在线浏览。

   

2. 下载整个仓库 如果需要将所有数据一次性下载到本地，可以点击仓库主页绿色的 Code（代码） 按钮，然后选择 Download ZIP（下载 ZIP 压缩包）。

   

3. 操作单个文件 进入单个文件页面后，可以通过右上角的按钮进行 复制、下载 或 编辑 等操作。

   

查看与恢复历史版本

每一次上传操作都会在 GitHub 上留下一条提交记录 (Commit)。通过这些记录，可以精确地回溯数据。

1. 查看整个仓库的历史记录

   • 在仓库主页，点击上方带有数字的 Commits 链接，进入提交历史列表。

     

   • 在列表中，每一条记录都代表一次上传。点击记录右侧的 <> 按钮（查看此时间点的仓库），即可查看当时的时间点下整个仓库的文件状态。

     

   • 在这个历史视图中，同样可以下载整个仓库或浏览单个文件，但 无法直接编辑。

2. 查看单个文件的历史变动 如果只想查看某个特定文件的修改历史：

   • 首先，在仓库中找到并点击目标文件。
   • 在文件预览页面的右上角，点击 History（历史） 按钮。

     

   • 这里会列出所有与该文件相关的提交记录。点击任意一条记录，可以清晰地看到该次提交对文件所做的具体修改（绿色为新增内容，红色为删除内容）。

     

   • 在变动详情页面，点击右上角的 三个点 -> 查看文件，可以查看该文件在那个历史时间点的完整内容。

     

   • 同样可以复制、下载，但 无法直接编辑。

备份目录参考

基本就是找回 chats 里的内容比较多，聊天记录可以原样放回原位，也可以在酒馆的聊天管理里面导入。

📁 SillyTavern [酒馆根目录]
├── 📁 data [用户数据目录]
│   ├── 📁 _storage [用户账户信息（多用户账号、密码、是否是管理员身份）]
│   └── 📁 !default-user [用户个人数据（单用户模式下，多用户去找账号同名目录）]
│       ├── 📁 backgrounds [背景图]
│       ├── 📁 backups [快照备份]
│       ├── 📁 characters [角色卡]
│       ├── 📁 chats [聊天记录]
│       ├── 📁 extensions [个人前端扩展]
│       ├── 📁 OpenAI Settings [预设]
│       ├── 📁 QuickReplies [快速回复]
│       ├── 📁 themes [主题]
│       ├── 📁 user [用户设定]
│       ├── 📁 User Avatars [用户头像]
│       ├── 📁 vectors [向量数据]
│       ├── 📁 worlds [世界书]
│       ├── 📄 secrets.json [API密钥仓库]
│       ├── 📄 settings.json [用户配置文件（界面配置、开关、当前选择项）]
└── 📄 config.yaml [酒馆配置文件（网络与安全、登录体系、备份与性能）]