# 云同步

将文件夹、灵感库（Prompts）等数据同步到您的个人云端。所有受支持的浏览器都可使用 Google Drive；Safari 直装版还可选择 iCloud。

## 功能特点

- **多端同步**：利用 Google Drive 或 iCloud，在多台设备上同步配置。
- **全面覆盖**：支持同步文件夹（Gemini、AI Studio、ChatGPT、Claude、DeepSeek、Kimi）、提示词库、星标、分支、时间线层级、高亮、个性化设置和插件配置，以及 ChatGPT、Claude、DeepSeek 上的时间线星标与层级。
- **数据安全**：数据存储在您自己的 Google Drive 或 iCloud 私有数据库中，不经过 Voyager 服务器。
- **灵活同步**：支持手动上传、下载合并数据。

## 如何使用

1. 打开 Gemini、AI Studio、ChatGPT、Claude、DeepSeek 或 Kimi 页面，再点击浏览器工具栏中的 Voyager 图标，打开设置面板。**云同步** 区域只在这些网站上显示，各网站的文件夹分别同步。
2. 找到 **云同步** 区域。
3. Safari 可选择 **Google Drive** 或 **iCloud**；其他浏览器使用 Google Drive。
4. 将 **同步模式** 切换为 **手动**。默认是 **已禁用**，切到手动后才会出现同步按钮。
5. Safari 上使用 Google Drive 时，点击 **连接 Google Drive**，通过 Voyager 应用登录；其他浏览器没有单独的登录按钮，第一次点击 **上传到云端** 或 **从云端下载合并** 时会弹出 Google 授权窗口。iCloud 只需确保 Mac 已登录 iCloud。
6. 点击 **上传到云端**，或点击 **从云端下载合并** 将云端数据合并到本机。**覆盖下载** 会先确认，再只替换云端有且能读取的数据；云端缺失或无法识别的数据保持不变，结果里会列出。完成后可立即撤销。

使用 iCloud 时，**删除 iCloud 备份** 会清除 iCloud 中所有 Voyager 备份，Mac 上的本地数据不受影响。

同步为手动触发，不会在后台自动上传。切换服务不会自动搬运数据，也不会同时写入两个服务；切换后请手动上传一次。

## 在面板里同步

<GuideOp>

[Voyager 面板](/guide/panel) 顶栏的云图标打开 **云同步**，不用离开对话就能用 Google Drive 同步。还没连接时，点 **连接 Google Drive**；第一次连接后会先合并云端和本地，不会覆盖任何一边。

- **选择网站**：**通用**（提示词 · 设置 · 插件）和每个网站各占一行。关掉某一行的开关，这台设备同步时就跳过它；给一个支持的网站授权访问后，它会自动加入。
- **状态**：每行显示 **已同步**、**本地较新**、**云端较新**、**未上传** 或 **无法读取**。主按钮 **同步 N 项** 一次处理所有待同步的行。
- **云端有数据**：这台设备没开、但云端有数据的网站会单独列出，点 **启用** 跳到 **网站** 分页打开它。
- **更多**：菜单里有 **全部上传到云端**、**全部从云端合并**、**恢复上一版** 和 **断开 Google Drive**。**恢复上一版** 会先确认，再把开着的行在云端放回上一版。

</GuideOp>

## 同步内容

Voyager 会把不同类型的数据保存为独立备份，避免某一类数据覆盖其他内容。Google Drive 中是 JSON 文件；iCloud 中保存于 Voyager 的私有 CloudKit 数据库：

- `gemini-voyager-settings.json`：跨设备的个性化设置，例如会话排序、文件夹字号、颜色和输入行为。
- `gemini-voyager-plugins.json`：插件安装、启用状态及插件内部设置。插件所需的网站权限仍需在每台设备上单独授权。
- 文件夹（Gemini、AI Studio、ChatGPT、Claude、DeepSeek、Kimi 各自独立）、提示词、星标、分支、时间线层级和高亮分别使用各自的同步文件；高亮内容仅在开启高亮云同步后上传。
- ChatGPT、Claude、DeepSeek 上的时间线星标与层级按网站分别保存。

窗口坐标、面板位置、导出按钮位置、缓存、访问令牌、设备 ID 和临时任务状态不会写入个性化设置文件。

**启用硬隔离（Hard Isolation）** 不再写入云端的设置文件；浏览器自带的同步（例如 Chrome 同步）仍会在登录同一浏览器个人资料的电脑之间同步它。

### 星标数据与同步限制

上传云同步备份时，星标消息会包含您标记的**用户提示词全文**（每条最多 16 KiB UTF-8），并保存到您自己的 Google Drive 或 iCloud；星标备份不保存模型回答。旧的 v1 备份仍只保留预览，新的 v2 备份包含提示词全文及删除记录。

删除记录保留 180 天。旧版 Voyager 不识别这些记录，可能显示或重新上传已删除的星标；新版会拦截时间戳未更新的旧副本。明确重新加星或删除记录到期后，星标可能恢复。长期离线和设备时钟偏差也会影响删除传播。

同步会合并并检查写入结果，最多尝试三次，但不是跨设备的原子事务；并发上传仍可能覆盖其他设备的写入。保留缺失数据的设备再次同步可修复这种情况，否则无法保证恢复。部分上传失败不会撤销已成功的写入，请再次同步完成修复。

### 💡 极速同步

最简单的方法是点击左侧侧边栏**文件夹区域标题栏**上的云图标，在菜单中选择“上传到云端”或“从云端同步”。

<GuideShot src="/assets/cloud-sync-zh.png" alt="云同步快捷按钮" :width="440" />

::: warning
**安全建议：双重保护**  
虽然云同步提供了极大的便利，但为了您的数据万无一失，我们强烈建议您定期通过**本地文件方式**手动备份核心数据。

1. **文件夹**：打开文件夹区域的菜单，选择“导入/导出文件夹”，再点击“导出文件夹”，即可保存所有文件夹和对话归属。
2. **提示词**：在提示词管理器中点击“导出”，保存您的提示词库。
   :::

## 同步保护

<GuideFacts>
<GuideFact title="上传确认">

如果上传会让云端文件明显变小（本机完全没有云端已有的某类数据，或云端至少 4 项而本机不到一半），或者 Voyager 读不懂云端文件，会先询问：**改为从云端合并**、**仍然上传** 或 **取消**。只有云端文件能读取时才提供合并。

</GuideFact>
<GuideFact title="覆盖下载只替换云端已有的数据">

**覆盖下载** 会保留云端缺失或 Voyager 无法识别的数据类型，并在结果里列出。云端插件列表为空时，不会清空您的插件。

</GuideFact>
<GuideFact title="下载后立即撤销">

**从云端下载合并** 或 **覆盖下载** 之后，只要设置面板还开着，结果行里就有 **撤销**。文件夹区域的云同步提示也提供撤销，约 10 秒，鼠标停在上面时会一直保留。撤销会还原那次下载改动的内容，之后您自己做的修改会保留。只能撤销最近一次下载。

</GuideFact>
<GuideFact title="Google Drive 中的历史副本">

上传替换某个文件之前，Voyager 会把被替换的版本保存在 Drive 的同一文件夹里，命名为 `<文件名>.backup-<UTC 时间>.json`，例如 `gemini-voyager-folders.backup-2026-10-29-031100.json`。每个文件保留最近 3 份，更早的会移到 Drive 回收站。在面板的云同步菜单里选 **恢复上一版**，就能把云端放回上一版。iCloud 同样保留每类数据被替换的最近 3 个版本。

</GuideFact>
<GuideFact title="所有设备都请更新">

开启 **启用硬隔离（Hard Isolation）** 后，新版 Voyager 按账号邮箱命名各账号的 Drive 文件。如果某台设备仍在使用 Voyager 2.2.1，且最初是在带编号的地址（gemini.google.com/u/1）上使用该账号，它在更新之前看不到新版上传的内容。Chrome 应用商店的更新通常几天内送达，Safari 会更久。

</GuideFact>
</GuideFacts>

## 云同步与手动备份

| 方面     | 手动备份（导出/导入）  | 云同步                                 |
| -------- | ---------------------- | -------------------------------------- |
| 频率     | 想起来时再操作         | 一键按需同步                           |
| 数据位置 | 电脑上的本地文件       | 您的 Google Drive 或私有 iCloud 数据库 |
| 跨设备   | 需要手动传输文件       | 登录同一云端账户的设备即可使用         |
| 合并方式 | 替换，或需要手动合并   | 智能合并，不会产生重复数据             |
| 隐私     | 文件只保存在您的电脑上 | 保存在您的个人云端账户中               |

## 工作原理

1. **服务提供方**：Google Drive 使用权限受限的 `drive.file` 范围，因此 Voyager 只能访问它自己创建的文件。在 Safari 上，iCloud 使用应用自己的私有 CloudKit 数据库，不会向 Voyager 暴露 Apple ID 令牌。
2. **上传**：点击 **上传到云端** 时，Voyager 会把文件夹、提示词、星标、分支、时间线层级、个性化设置和插件配置分别写成独立的备份文件，保存到所选服务中。开启高亮云同步后，高亮数据也会一并上传。
3. **下载并合并**：在另一台设备上点击 **从云端下载合并** 时，Voyager 会读取这些文件并按数据类型合并：新的文件夹和提示词会被添加且不产生重复，云端偏好会被恢复，插件条目则按插件 ID 合并。
4. **没有后台同步**：同步是手动、按需进行的，Voyager 绝不会在您没有明确操作的情况下同步。

## 支持的平台

Google Drive 同步可在电脑上的 Chrome、Edge、Firefox 和 Safari 中使用，也可在带 Google 登录的安卓浏览器（例如 Edge）中使用；Firefox for Android 无法打开 Google 登录窗口，暂不支持。iCloud 同步仅在 Safari 直装版中可用，使用 Mac 上登录的 iCloud 账户。