# DBX 配置云同步

> 使用 WebDAV、GitHub Gist、Gitee 或 GitLab Snippets 同步 DBX 连接、设置和保存的 SQL。

Source: https://dbxio.com/cn/docs/cloud-sync

Language: zh-CN

Relative links resolve against https://dbxio.com/cn/docs/cloud-sync.



DBX 可以把连接配置、界面设置和保存的 SQL 组成一个快照。桌面端可通过 WebDAV 或私有代码片段同步，Web/Docker 可通过 WebDAV 同步，并在另一个 DBX 实例恢复。

云同步备份的是 DBX 配置，不会读取或备份连接中的业务数据库。表结构和数据请使用 

[数据库导出](/cn/docs/database-export)

；Desktop 定时 MySQL/PostgreSQL 备份请使用 

[数据库备份](/cn/docs/database-backup)

。

在 **设置 → 同步** 中选择同步方式：

* **WebDAV**：适合已有 NAS、Nextcloud、坚果云或其他 WebDAV 服务的用户，支持定时自动上传。
* **GitHub / Gitee / GitLab 代码片段**：通过私有代码片段保存快照，GitLab 支持企业自托管实例。目前仅桌面端显示，且需要手动上传和下载，不自动合并。

## 同步哪些内容

| 项目                                             | 默认行为            |
| ---------------------------------------------- | --------------- |
| 数据库连接及普通连接参数                                   | 同步              |
| 侧边栏布局、固定节点                                     | 同步              |
| 保存的 SQL 库                                      | 同步              |
| 桌面和编辑器设置                                       | 同步              |
| 数据库密码、SSH 密码、代理密码、HTTP 隧道 Token、连接串、AI API Key | 默认不同步；可以选择加密后同步 |
| JDBC 驱动、插件和本地文件                                | 不同步             |

下载会用远端快照替换本地连接元信息和保存的 SQL。恢复前请确认代码片段 ID 或 WebDAV 路径正确。

## GitHub Gist

### 创建访问令牌

推荐使用 GitHub **Fine-grained personal access token**：

[打开 GitHub Fine-grained token 创建页面](https://github.com/settings/personal-access-tokens/new)

### 打开令牌设置

登录 GitHub，进入 **Settings → Developer settings → Personal access tokens → Fine-grained tokens**。

### 创建令牌

点击 **Generate new token**，设置名称和有效期。

### 设置权限

在 **Account permissions** 中找到 **Gists**，选择 **Read and write**。不需要授予仓库权限。

### 保存令牌

创建后立即复制令牌。GitHub 只会完整显示一次。

也可以使用 Classic token，但只应勾选 `gist` scope，不要授予无关权限。

### 首次上传

### 选择平台

打开 **设置 → 同步 → 代码片段**，平台选择 **GitHub Gist**。

### 填写令牌

将访问令牌粘贴到 **访问令牌**。建议勾选 **加密保存在本机**。

### 创建 Gist

将 **代码片段 ID** 留空，点击 **上传**。DBX 会创建私有 Gist，并自动保存返回的 ID。

DBX 会在 Gist 中保存一个经过**代码片段加密密码**加密的 `dbx-sync.json` 文件。该密码保护完整快照，片段链接本身不会暴露连接信息、SQL 或设置；历史明文片段仍可下载一次以便迁移。

旧版本创建的明文片段不能安全地原地迁移：更新同一个 Gist 不会删除历史修订。请使用 **迁移旧版代码片段** 操作。DBX 会先将已有的远端快照加密写入新片段并保存新 ID，然后重新读取旧片段后才删除它；如果另一台设备已更新旧内容，则停止自动删除并提示手动清理。若旧快照包含已加密的敏感信息，请输入其原敏感信息同步密码以完成删除前验证。请轮换旧片段中可能已经暴露的凭据。

### 在另一台设备恢复

1. 打开该私有 Gist，从地址栏复制 ID。地址通常类似 `https://gist.github.com/<实际用户名>/<gist-id>`，最后一段就是 ID。也可以直接访问 `https://gist.github.com/<gist-id>`，GitHub 会跳转到包含实际用户名的地址。
2. 在新设备填写相同的 GitHub 令牌和 Gist ID。
3. 点击 **测试**，确认令牌和 ID 可访问。
4. 点击 **下载** 并确认恢复。

## Gitee 代码片段

### 创建私人令牌

[打开 Gitee 私人令牌页面](https://gitee.com/profile/personal_access_tokens)

### 打开私人令牌页面

登录 Gitee，进入 **设置 → 私人令牌**。

### 生成新令牌

点击 **生成新令牌**，填写描述。

### 设置权限

只勾选代码片段（`gists`）相关权限。如果界面只提供合并权限，选择能够读写代码片段的最小权限。

### 保存令牌

生成后立即复制令牌，并存放在密码管理器中。

### 上传与恢复

1. 在 **设置 → 同步 → 代码片段** 中选择 **Gitee 代码片段**。
2. 输入私人令牌。首次上传时将代码片段 ID 留空，DBX 会创建私有代码片段并保存 ID。
3. 在其他设备恢复时，填写同一个代码片段 ID，然后点击 **下载**。

Gitee 代码片段中同样使用 `dbx-sync.json` 文件。

## GitLab Snippets（包括私有化实例）

1. 在 GitLab **User Settings → Access Tokens** 创建个人访问令牌，授予 `api` 权限；不要把令牌放在实例地址里。
2. 在桌面端 **设置 → 同步 → 代码片段** 选择 **GitLab Snippets**，输入公司的 GitLab 根地址（例如 `https://gitlab.example.com` 或内网 `http://gitlab.internal`，默认 `https://gitlab.com`）。不接受含账号密码、查询参数或片段的地址。修改地址后，失焦或按 Enter 才会切换实例。
3. 输入令牌和代码片段加密密码；首次上传时留空 ID，DBX 创建仅自己可见的个人 Snippet。后续上传更新同一 ID 对应的 `dbx-sync.json`；在另一台设备输入相同实例、令牌、ID 和加密密码后手动下载。

GitLab Snippets 不是 GitLab 仓库文件同步。不同实例的本地令牌、ID 和迁移待清理记录互相隔离；上传和下载不会自动合并。旧明文 DBX 快照须使用 **迁移旧版代码片段**，DBX 先创建加密的新 Snippet，再核对并删除旧 Snippet。如果发现旧内容已变化或清理失败，旧 Snippet 仍须手动处理。

HTTP 会明文传输 GitLab 访问令牌，即使快照内容已加密。只在可信内网使用 HTTP，优先为私有化 GitLab 配置 HTTPS。

## 同步密码与敏感信息

GitHub Gist、Gitee 和 GitLab 代码片段始终使用**代码片段加密密码**加密整个快照。该密码不会上传或保存，也无法找回；它与可选敏感信息的同步密码相互独立。

默认快照不会包含数据库密码等密钥。如果需要在新设备直接恢复密码：

1. 开启 **上传时包含加密敏感信息**。
2. 输入单独的 **敏感信息同步密码**。
3. 上传快照。
4. 在另一台设备开启 **下载时恢复加密敏感信息** 并输入同一密码；保持关闭即可保留本地密码。

同步密码使用 **Argon2id** 派生密钥，并使用 **AES-256-GCM** 加密。访问令牌只会使用设备密钥加密保存在本机，永远不会写入 `dbx-sync.json`。

两种密码都无法找回。加密代码片段没有代码片段加密密码就无法恢复；WebDAV 中不含加密敏感信息的快照仍可不使用同步密码恢复。

## WebDAV

填写 WebDAV 服务地址、用户名、应用密码和远端快照路径。默认路径为 `DBX/sync/snapshot.json`。

部分 WebDAV 服务（如中国科技云）只允许特定客户端应用访问，会按 User-Agent 拦截未知客户端。遇到这类限制时，在 User-Agent 输入框填写服务允许的客户端标识（例如 `Zotero/7.0.15`）；默认留空，表示不发送 User-Agent。

Web/Docker 模式下，WebDAV 请求由 DBX 服务端发起，因此不受浏览器 CORS 限制；WebDAV 应用密码会加密保存在当前 DBX 实例中，不会写入同步快照。

WebDAV 支持定时自动上传。自动上传只在对应 DBX 客户端保持打开时执行；Web/Docker 使用时需保持至少一个 DBX 页面打开。下载始终需要手动确认，避免远端快照意外覆盖当前实例的数据。

## 常见问题

### HTTP 401 或 403

令牌无效、已过期，或没有代码片段读写权限。重新创建最小权限令牌后再测试。

### HTTP 404

代码片段 ID 不正确，或者当前令牌无权访问该私有代码片段。

### 首次上传后在哪里找 ID

DBX 会自动保存 ID。也可以在 GitHub Gist 或 Gitee 代码片段页面的地址栏中查看。

### 多台设备可以同时自动同步吗

代码片段同步目前只支持手动上传和下载，不会自动合并两台设备上的修改。上传前建议先下载最新快照，避免覆盖另一台设备刚上传的版本。