---
url: https://eoht.net/notes/tabby-sync.md
description: >-
  使用 cloud-settings-sync 和 GitHub Gist 同步 Tabby
  配置，说明插件字段、首台上传与其他设备下载的方向选择、同步范围、加密和冲突恢复。
---

# Tabby 配置同步：cloud-settings-sync 与 GitHub Gist {#sync-tabby-settings-with-gist}

本文使用 [niceit/tabby-cloud-sync-settings](https://github.com/niceit/tabby-cloud-sync-settings) 插件，其 npm 包名为 `terminus-cloud-settings-sync`。以下按上游 `1.8.0` 源码核对；截图来自旧版，按钮名称和布局可能不同。先确认两台设备使用兼容的 Tabby 与同一插件版本，不要同时让其他同步机制修改同一份配置。

同步前分别备份每台设备的 `config.yaml`：从 Tabby 设置确认配置文件实际位置，退出应用后复制到私人备份目录，再重新打开。保留这份独立备份，即使插件也会创建备份。

## 安装插件 {#install-cloud-settings-sync-plugin}

到 Tabby 的扩展界面搜索 `cloud-settings-sync`，核对作者和上述项目后安装，按提示重启。首次连接前暂时关闭自动同步，先确定哪台设备保存完整配置。

![Tabby =688x](https://i.eoht.net/docs/202404281755529.webp "安装插件")

## 新建 GitHub Token {#create-github-token}

访问 <Pill icon="oui:token-key" name="GitHub Token 设置" link="https://github.com/settings/tokens" />，创建带有效期的 classic Token，只勾选 `gist` 权限。本教程的授权目标是 Gist，无需额外授予仓库 `repo` 权限。`gist` 权限可读写该账户的 Gist，并非只授权某一个 Gist，参见 [GitHub 权限说明](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps)。

令牌只填入本机插件设置，不放进截图、分享的配置或公开仓库。第二台设备可使用同一 GitHub 账户另外创建的 `gist` Token，便于单独撤销设备权限。

![Tabby =688x](https://i.eoht.net/docs/202404281757509.webp "新建 Github token")

![Tabby =688x](https://i.eoht.net/docs/202404281758078.webp "勾选 gist 保存")

## 配置 cloud-settings-sync {#configure-cloud-settings-sync}

![Tabby =688x](https://i.eoht.net/docs/202404281801350.webp "配置 cloud-settings-sync")

### 字段与同步范围 {#sync-fields-and-scope}

| 设置 | 填写方式 |
| --- | --- |
| 云服务 | 选择 `Gists`，具体平台选择 `GitHub` |
| 名称 | 本机用于辨认的名称，可选；不要将它当作 Gist ID |
| Access Token | 具备 `gist` 权限且未过期的令牌 |
| Gist ID | 首台新建时留空；其他设备填首台创建的同一个 ID，不填整段 URL |
| 开启同步 | 完成首次方向选择和验证后开启 |
| 同步间隔 | 自动检查的间隔；不代表每次都上传或都下载 |

插件会读取并加密整个 `config.yaml`，包括其中保存的设置和连接配置，并不是只挑选外观等字段。文件中存在的敏感值也会进入同步内容；外部私钥文件、外部程序与系统钥匙串不在这份文件的复制范围，换机后需要另行配置，不能假定 SSH 登录凭据已经可用。

新建 Gist 的实现使用 `public: false`，即 **Secret Gist**。[Secret Gist 只是未公开列出，持有链接的人仍可读取](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists)。`1.8.0` 提供自定义加密口令；未设置时仍可使用兼容旧版的固定密钥加密，不能将它视为私人保密措施。首次上传前在 Security 设置自己的加密口令，并在其他设备使用同一口令；妥善保存，丢失后无法依靠重置 Token 解密已有内容。

### 首台设备：本机上传到云端 {#upload-first-device}

1. 选择保存完整配置的设备，完成备份与加密设置。
2. 选择 GitHub，填写 Token，Gist ID 留空，点击“测试连接”。ID 为空时，这一步会创建一个带占位文件的 Gist，不只是只读连接测试。
3. 确认测试成功、ID 已回填，然后点击“保存设置”。
4. 首次同步会让你选择方向。此时选 **从本地同步 / Sync from local**，把本机配置上传到这个新 Gist；不要下载尚未初始化的占位内容。
5. 按提示重启。使用插件中的“查看”打开 Gist，确认文件已变为插件的加密内容、更新时间对应本次操作，再开启自动同步。

给插件使用单独的 Gist，不要与代码片段混用：当前上传实现会更新所选 Gist 中的文件内容。

### 其他设备：云端下载到本机 {#download-other-devices}

1. 先备份第二台设备的配置，安装同一插件并设置同一自定义加密口令。
2. 选择 GitHub，填写可访问该 Gist 的 Token，以及首台生成的 Gist ID。不要留空，否则会创建另一个 Gist。
3. 测试成功后保存，首次方向选择 **从云端同步 / Sync from cloud**。这个动作会替换本机配置，不能把仍需保留的本机设置留到覆盖后再处理。
4. 重启后检查一个不敏感的设置和连接名称是否与首台一致，再单独验证外部密钥路径等设备相关配置。

### 冲突、失败与停用 {#sync-conflicts-and-recovery}

正常自动同步会判断哪一端发生变化；两台设备同时修改时，不应靠连续点击同步来决定保留哪份。`1.8.0` 的冲突处理会保留本地 `config.yaml.backup` 与云端 `config.yaml.conflict-*` 快照，并报告冲突，不会自动逐字段合并。

遇到冲突先在各设备关闭同步，另存当前配置和快照，再选定一份完整配置作为基准。恢复到一台设备并检查后，重新设置首次同步，明确从本地上传；其他设备再从云端下载。整个过程中保留独立备份，避免备份文件被后续同步替换。

测试失败时检查 Token 有效期和权限、Gist ID 与所属账户、网络以及插件日志；解密失败时核对口令和版本，不要用空白本机配置覆盖远端。移除插件中的同步设置不会删除云端 Gist。停止使用后可在 GitHub 撤销对应 Token，并单独决定是否删除 Gist。

字段、方向与范围核对依据：[Gist 设置界面](https://github.com/niceit/tabby-cloud-sync-settings/blob/main/src/components/sub-components/gist/gist-settings.component.ts)、[Gist 同步实现](https://github.com/niceit/tabby-cloud-sync-settings/blob/main/src/utils/cloud-components/gist.ts)、[配置读取与加密](https://github.com/niceit/tabby-cloud-sync-settings/blob/main/src/utils/settings-helper.ts)。