# 使用 Dropbox 云同步

把你的库项目和设置备份到你自己的 Dropbox，并在其他电脑上打开。同步哪些内容、如何处理冲突和删除，以及每条消息的含义。

云同步会在你自己的 Dropbox 中保存一份库项目和设置的副本。在另一台电脑上连接同一个 Dropbox，把项目下载到那里，两台电脑就会让它们保持同步。

打开**设置 → 数据存储 → 云同步**来进行设置。

## 开始之前

- 你需要一个 Dropbox 账户。免费的 Dropbox Basic 账户有 2 GB 空间。
- 云同步适用于 macOS、Windows 和 Linux。
- Oleafly 只在打开时同步，包括最小化或窗口被隐藏的时候。Oleafly 关闭时不会同步任何内容。
- Oleafly 直接与 Dropbox 通信，中间没有 Oleafly 服务器。

## 连接 Dropbox

1. 打开**设置 → 数据存储 → 云同步**，选择**连接 Dropbox**。
2. 浏览器会打开 Dropbox 的登录和授权页面。在那里登录并授权 Oleafly。
3. Oleafly 完成连接后，浏览器会显示“你已连接”。如果你授权后出了问题，浏览器会显示登录没有完成，Oleafly 则会说明发生了什么。

你是在 Dropbox 自己的页面上登录的，所以 Oleafly 永远看不到你的 Dropbox 密码。

### 如果浏览器无法交还给 Oleafly

你授权之后，Dropbox 会把浏览器带到你电脑上的一个本地地址（127.0.0.1），Oleafly 从那里获取登录信息。如果这样不起作用，请选择**登录有问题？粘贴代码**。Dropbox 会显示一个代码。复制它并粘贴到 Oleafly 中。

### Oleafly 能访问什么

- Oleafly 只能打开你 Dropbox 中它自己的应用文件夹 `Apps/Oleafly`。它看不到你 Dropbox 里的其他任何文件。
- 它只向 Dropbox 申请四项权限，不会多要。`account_info.read` 用来显示你的电子邮件地址和已用空间。`files.metadata.read`、`files.content.read` 和 `files.content.write` 让它能列出、读取和写入自己文件夹中的文件。
- 登录使用带 PKCE 的 OAuth。
- 在 macOS 和 Windows 上，登录令牌保存在操作系统的钥匙串中。在 Linux 上，或在钥匙串不可用时，它保存在 Oleafly 数据文件夹中的加密文件里。
- 令牌从不同步。每台电脑各自连接。

### 云同步卡片

连接之后，卡片会显示：

- Dropbox 账户的电子邮件地址。
- 一个显示你的 Dropbox 已用多少空间的圆环。随着 Dropbox 渐满，它会从绿色变为黄色、橙色和红色，达到 80% 时为红色。
- **在这台电脑上同步**，即在这里开启或关闭同步的开关。
- **自动同步**，让 Oleafly 自行同步的开关。
- 这台电脑的名称。点击它可重命名这台电脑。
- **项目**列表。
- **高级**，其中有**断开连接**。

## 同步哪些内容

### 项目

你库中的每个项目都会同步，包括它的文件，也包括主文档所在的编译文件夹。Oleafly 会悄悄地把下面这些从每个项目中排除：

- 构建输出，例如 `.aux` 和 `.log` 文件以及编译出的主 PDF。你在 Git 中跟踪的构建文件，例如结果日志，仍会备份到你的 Dropbox。
- Python 的 `__pycache__` 文件夹
- `.git` 文件夹
- Oleafly 自己的工作文件夹
- 编辑器产生的临时文件
- `.DS_Store` 等系统文件

另外有几类内容也不同步，项目所在的行会把它们列为已跳过并给出原因：符号链接、`node_modules` 和 `.venv` 文件夹、大于 16 GB 的文件，以及[名称并非在每台电脑上都能使用](#renames-and-file-names)的文件。

你从电脑上其他位置的文件夹打开的项目（[就地打开的文件夹](/docs/library/#folders-opened-in-place)）不会同步。项目列表会告诉你有多少个这样的项目。

Git 历史和[检查点](/docs/checkpoints/)不会同步。

### 项目详情

每个项目的 `project.json` 也会同步，所以它的名称、主文档、引擎、封面颜色和其他详情都会跟随它。有几项详情属于某一台电脑，会留在那里：

- 导出路径
- 项目是否被隐藏
- TeX 宏包规格
- 检查点捕获策略
- 它是从哪个项目派生出来的

### 笔记

每篇个人[笔记](/docs/notes/)都像库项目一样同步，项目内的笔记则随该项目的文件一起同步。如果一篇个人笔记在两台电脑上都有更改，另一台电脑上的版本会作为冲突副本保存在该笔记的文件夹中，例如 `note (Laptop 2026-10-14).md`，笔记菜单中的**比较冲突副本**可以让你保留其中一个版本。项目内的笔记会在项目的 `notes` 文件夹里紧挨着它生成冲突副本，与其他任何项目文件一样。

### 设置

你的应用设置会同步，包括 AI 指令、AI 人设和你的自定义词典。有些设置留在每台电脑上，例如**自动同步**是否开启、LaTeX 的**默认编译引擎**、终端的 **Shell** 和 **Shell 路径**、“集成”中的 **Computer Use**、“实验功能”中的**研究任务**开关，以及“研究”中的**默认允许任务命令访问网络**。这样一来，代理不会仅仅因为你在别处开启了桌面应用，就在另一台电脑上也获得它；没有安装 TeX 的电脑，在另一台电脑使用 latexmk 时也会继续使用 Tectonic。

AI 对话、密码、API 密钥和其他机密信息永远不会同步。

## 你的 Dropbox 里有什么

所有内容都放在 `Apps/Oleafly` 文件夹中：

```text
Apps/Oleafly/
├── projects/
│   └── <project id>/
│       ├── files/          the project's files, under their own names
│       └── version.json    which version of each file belongs to the project
└── settings/
    └── settings.json       your synced settings
```

项目文件保留自己的名称，所以你可以从 Dropbox 打开它们。不支持手动编辑或移动 `Apps/Oleafly` 中的文件。Oleafly 把该文件夹中的一切都视为不受信任的内容并进行检查。

## 一轮同步是如何进行的

每一轮都经历相同的步骤：

1. Oleafly 询问 Dropbox 自上一轮以来哪些项目发生了变化。没有变化时，这只需要一次请求。
2. 它扫描这台电脑上每个项目的文件。它能很快识别出未更改的文件，而不必重新读取它们。
3. 对每个文件，它比较三个版本：这台电脑上的、Dropbox 中的，以及双方上次一致认可的版本。由此判断是哪一方发生了变化。
4. 它把你其他电脑的更改下载到一个临时位置，并对照为该文件记录的指纹（哈希）检查每个文件。只有通过之后，文件才会进入项目。如果你在扫描之后又在这台电脑上更改了该文件，Oleafly 会先不动它，等到下一轮。
5. 它上传这台电脑上的更改，然后把 Dropbox 自己的校验和与它发送的内容进行比较。
6. 它保存项目的版本记录，并检查在此期间没有其他电脑保存过记录。如果有，这一轮会用较新的记录重新运行，这样任何一台电脑的工作都不会丢失。
7. 最后，它把你在这台电脑上删除的文件从 Dropbox 中移除。

## Oleafly 何时同步

**自动同步**默认开启，除非你把它关掉。开启时，Oleafly 会在你保存文件几秒后同步，也会在另一台电脑更改了你的 Dropbox 后不久同步。在这些时刻之间，它每 5 分钟检查一次，Oleafly 窗口被隐藏时则每 15 分钟检查一次。第一轮在 Oleafly 启动约 20 秒后运行，对设置的更改在你做出后约 3 秒同步。关闭**自动同步**后，Oleafly 会在你选择**立即同步**时同步，另外在你连接、重新打开**在这台电脑上同步**，或重新打开某个项目的开关时同步一次。

如果一轮失败，例如因为你处于离线状态，Oleafly 会在 30 秒后重试，每次失败后等待得更久，最长 5 分钟，窗口被隐藏时最长 15 分钟。一旦某一轮成功，它就会回到正常的计划。你的电脑重新联网时，它也会同步。

**立即同步**会马上运行一轮，并显示一条带有结果的消息。自动运行的轮次从不显示弹窗。它们的状态显示在“项目”部分：“上次同步”及其时间、“正在同步你的项目”，或描述某个问题的一行文字。

当有事情需要你处理时，例如 Dropbox 已满、某个项目已暂停、出现冲突副本或需要做出设置选择，“设置”按钮上会出现一个琥珀色的小圆点。此时设置会直接打开云同步，让你先看到问题所在。

## 冲突

如果同一个文件在两次同步之间在两台电脑上都发生了变化，Oleafly 会保留两个版本。这台电脑的版本保留原名。另一台电脑的版本保存在它旁边，名称由写入它的电脑和日期构成，例如 `ch1 (Laptop 2026-10-14).tex`。同一天的第二次冲突会在名称后加一个数字。在你选择**忽略**之前，项目所在的行会一直列出这些冲突副本。

打开两个文件，保留你想要的内容，并删除不需要的副本。

`project.json` 从不产生冲突副本。它的字段会合并。每台电脑的更改都会保留，如果两台电脑更改了同一个字段，则以这台电脑的值为准。

### 未保存的编辑是安全的

同步绝不会覆盖在编辑器中打开且有未保存更改的文件。来自你其他电脑的更改会等待。你保存之后，下一轮会像对待其他编辑一样对待你的编辑，所以如果双方都更改了文件，你会得到一个冲突副本。

你没有更改过的已打开文件，会在另一台电脑的更改到达时立即在编辑器中更新。如果更改在你编辑时到达，编辑器会提示文件在磁盘上发生了变化，你可以选择**重新加载**或**保留我的版本**。新文件和冲突副本会出现在文件树中，在另一台电脑上删除的文件会在这里关闭。

### 重命名与文件名

只更改文件名的大小写，算作重命名而不是删除。

Oleafly 会跳过下面这些文件，并把它们列在项目所在的行下：

- 名称并非在每台电脑上都能使用的文件，例如名称中带有 `:`，或名称像 `CON.tex`
- 名称与同一文件夹中另一个名称只有大小写之别的文件。已经在同步的那个文件会继续同步。

这个列表还会显示 Oleafly 在这里无法读取，或无法下载或上传的文件。下载失败的文件会在一小时后重试，如果文件发生变化则更早。

## 删除文件

当你在一台电脑上删除文件时，它在你的其他电脑上也会被删除。在那里，文件会进入系统的废纸篓或回收站，如果系统没有这些，则进入 Oleafly 自己的垃圾文件夹。你可以从那里找回它。

Dropbox 中缺少某条记录，永远不会导致电脑上的文件被删除。如果有人手动删除了 Dropbox 中某个项目的文件夹，Oleafly 会重新上传该项目。如果 Dropbox 中某个项目的记录里没有它的 `project.json`，Oleafly 会重新上传该文件，而不是删除它。

### 防止一次删除大量文件的保护

如果一台电脑上一次性删除了某个项目一半以上的文件，并且数量超过 20 个，Oleafly 不会把这次删除传递出去。如果项目中的每个文件都被删除，情况也一样。移动或重命名文件夹不算，因为文件仍然存在。项目会显示“已暂停以保护你的文件”，并给出两个选择：

- **恢复这些文件**会从 Dropbox 还原文件。
- **也从 Dropbox 删除**在你确认后，也会把它们从 Dropbox 中删除。你的其他电脑随后也会失去它们。

同样的检查也适用于相反的情况。如果项目在 Dropbox 中的记录里突然缺少许多文件，例如记录是从旧版本还原的，Oleafly 不会在这台电脑上删除它们。项目会显示“已暂停以保护你的文件”，并给出两个选择：

- **放回 Dropbox**会把这台电脑上的文件重新上传。
- **也在这里删除**在你确认后，会把它们移到这台电脑的回收站。

## 项目列表

你库中的每个项目都有一行，显示它的大小和上次同步的时间。

- 它的开关用于在这台电脑上同步该项目，或在这里暂停它。
- 只存在于 Dropbox 中的项目有一个下载按钮。**全部下载**会下载所有这样的项目，但位于这台电脑回收站中的项目除外。下载的项目会出现在你的库中。
- 如果项目在这台电脑的回收站中，下载它会从回收站恢复它，而不是生成第二个副本。下一次同步会带来别处所做的更改。
- 从 Dropbox 下载的项目会以受限模式打开，直到你在那台电脑上信任它。你会看到与[就地打开的文件夹](/docs/library/#folders-opened-in-place)相同的信任提示。

### 从 Dropbox 移除项目

要释放空间，请在项目所在行的 **…** 菜单中选择**从 Dropbox 移除**。这会删除该项目在 Dropbox 中的副本。项目仍保留在这台电脑上，并在这里停止同步。你的其他电脑保留它们的副本，并显示“已从 Dropbox 移除”及这台电脑的名称。

重新打开该项目的开关，即可再次上传它。

只存在于 Dropbox 中的项目，它们的菜单中也有**从 Dropbox 移除**。这会把它们从你的 Dropbox 中删除，因此之后你无法在这台电脑上下载它们。已经拥有它们的电脑会保留它们的副本。

如果 Dropbox 无法立即删除该文件夹，项目仍会显示为已移除，Oleafly 会在之后的某次同步中完成删除。

## 存储空间与已满的 Dropbox

云同步卡片上的圆环显示你的 Dropbox 已用多少空间，并在达到 80% 时变红。免费的 Dropbox Basic 账户有 2 GB 空间。

当你的 Dropbox 已满时，上传会停止，但下载仍然可用。横幅会告知你，每个无法上传的项目也会显示这一点。空间已满期间，Oleafly 会在上传之前检查还剩多少空间，所以它绝不会发送放不下的文件。要腾出空间，请执行下列任一操作：

- 为大型项目关闭同步。
- 从 Dropbox 移除项目。
- 在 Dropbox 中释放空间。

一旦有了空间，同步会自行继续。

## 离线与被中断的同步

离线时，你的编辑会保留在电脑上，不会丢失任何内容。连接恢复后，同步会继续。

如果一轮在中途停止，例如因为网络中断或你关闭了 Oleafly，下一轮会完成这项工作。较长的首次备份每 200 个文件或 256 MB 就会保存一次进度，所以不会从头再来。关闭**在这台电脑上同步**会停止正在运行的一轮。

当 Git 命令正在更改项目的文件时，例如在终端中执行检出或拉取，这一轮会等待，下次再试。在 Windows 上，被其他程序打开的文件会在几分钟后重试。

当 Dropbox 要求 Oleafly 放慢速度，或出现临时错误时，Oleafly 会自行重试。

如果这台电脑的磁盘空间不足，下载会等待，直到你腾出一些空间。上传会继续。

## 设置同步

一台电脑第一次连接时，Oleafly 会把它的设置与你 Dropbox 中的设置进行比较。如果不同，它会询问一次：“Oleafly 应该使用哪些设置？”请选择**使用 Dropbox 的设置**或**保留这台电脑的设置**。如果你关闭了对话框，它不会自己再出现。同样的两个选择会留在云同步卡片上，在你选择之前不会覆盖任何内容。

之后，设置会自动合并：

- 不同电脑上对不同设置所做的更改都会保留。
- 如果两边都更改了同一项设置，则以这台电脑的值为准。
- 列表，例如你词典中的单词，会合并在一起。AI 人设会逐个合并，因此在两台电脑上都编辑过的人设仍然只是一个人设。

要自己从 Dropbox 载入设置，请打开**设置 → 通用 → 导入**并选择**从云端导入**。你会看到与导入设置文件时相同的检查步骤。

## 电脑与账户

### 为这台电脑命名

每台电脑都有一个名称。它起初是这台电脑的主机名。点击云同步卡片上的名称即可更改。你的其他电脑会在冲突副本和“已从 Dropbox 移除”的提示中显示它。

### 断开连接

打开**高级**，选择**断开连接**并确认。这台电脑上的同步会停止，Oleafly 对你 Dropbox 的访问权限也会被移除。你的项目会保留在这台电脑和你的 Dropbox 中。如果此时 Oleafly 无法连接到 Dropbox，它仍会在这里断开连接并告诉你，你可以自行在 Dropbox 的已连接应用中移除 Oleafly。

### 切换到另一个 Dropbox 账户

连接另一个 Dropbox 账户会从头开始。不会与旧账户进行任何比较，也不会因此删除任何内容。

### 访问权限结束时

如果 Oleafly 的访问权限结束，例如因为你在 Dropbox 的已连接应用中移除了 Oleafly，卡片会显示“Dropbox 访问已结束。请重新连接以继续同步。”请选择**重新连接**。

### 另一台电脑上有更新的 Oleafly

如果另一台电脑运行着更新版本的 Oleafly，并以较新的格式保存了某个项目，旧版本会停止同步该项目，并请你[更新 Oleafly](/docs/updates/)。

## 安全检查

- 来自 Dropbox 的每个文件在替换任何内容之前，都会对照它记录的指纹进行检查。
- 来自 Dropbox 的任何内容都不会写入 `.git`、项目文件夹之外，或通过符号链接写入。
- 来自 Dropbox、但这个版本的 Oleafly 无法打开的 `project.json`，永远不会替换这台电脑上的那一份。
- 你曾信任其在编译时运行 shell 命令的项目，在文件从 Dropbox 到达后，下次编译前会再次询问，和 Git 拉取之后一样。
- Oleafly 把 `Apps/Oleafly` 中的一切都视为不受信任的内容并进行检查。
- Oleafly 不会为你 Dropbox 中的文件添加端到端加密。它们和其他任何文件一样存储在你的 Dropbox 中。

## 故障排除

| 消息或症状 | 处理方法 |
| --- | --- |
| 浏览器没有交还给 Oleafly | 选择**登录有问题？粘贴代码**，并粘贴 Dropbox 显示的代码。 |
| “Dropbox 访问已结束。请重新连接以继续同步。” | 选择**重新连接**，并在浏览器中授权 Oleafly。 |
| “Oleafly 应该使用哪些设置？” | 选择**使用 Dropbox 的设置**或**保留这台电脑的设置**。关闭对话框可稍后在云同步卡片上决定。不会覆盖任何内容。 |
| “已暂停以保护你的文件” | 许多文件在这里或 Dropbox 中被一次性删除。要保留它们，请选择**恢复这些文件**或**放回 Dropbox**；如果你确实想删除它们，请选择**也从 Dropbox 删除**或**也在这里删除**。 |
| 出现 `ch1 (Laptop 2026-10-14).tex` 这样的文件 | 这是来自以其命名的那台电脑的冲突副本。比较这两个文件，保留你想要的内容并删除另一个。 |
| 项目所在行显示有文件被跳过 | 打开列表查看每个文件及原因。重命名那些名称并非在每台电脑上都能使用，或与另一个名称冲突的文件。 |
| “设置”按钮上有一个琥珀色圆点 | 云同步需要你注意。打开设置并阅读云同步卡片。 |
| “Oleafly 无法读取你的 Dropbox 中的副本，因此此项目没有在同步。” | 选择**用这台电脑上的副本替换**。只存在于 Dropbox 副本中的内容将会丢失，所以请先检查你的其他电脑。 |
| “Oleafly 无法读取你的 Dropbox 中的设置。” | 选择**使用这台电脑的设置**来替换它们。 |
| “这台电脑的磁盘空间不足。” | 释放磁盘空间。同步会自行继续。 |
| “此项目有超过 100,000 个文件，数量过多，无法同步。” | 把项目不需要的文件移出它的文件夹。 |
| “已从 Dropbox 移除”及某台电脑的名称 | 那台电脑把项目从 Dropbox 中移除了。你这里的副本是安全的。打开该项目的开关即可再次上传它。 |
| “你的 Dropbox 已满。” | 为大型项目关闭同步、从 Dropbox 移除项目，或在 Dropbox 中释放空间。下载仍然可用，一旦有了空间，同步会自行继续。 |
| “你的 Dropbox 已达到本月的上传上限。” | Dropbox 会限制部分账户每月的上传量。你的编辑会保留在这台电脑上，等 Dropbox 再次允许上传后就会上传。 |
| “无法连接到 Dropbox。Oleafly 会重试。” | 检查你的网络连接。你的编辑会保留在这台电脑上，重新联网后 Oleafly 会同步。 |
| “此项目由较新版本的 Oleafly 同步。请更新 Oleafly 以继续同步它。” | 在这台电脑上[更新 Oleafly](/docs/updates/)。 |
| 下载的项目以受限模式打开 | 在你了解其中内容之后，在这台电脑上信任它。 |
| 什么都不同步 | 检查**在这台电脑上同步**是否已开启，以及项目的开关是否已开启。Oleafly 只在打开时同步。如果**自动同步**已关闭，请选择**立即同步**。 |

改用 Git 来迁移项目？请参阅 [GitHub 同步](/docs/github-sync/)。关于 Oleafly 在你电脑上保存的所有内容，请参阅[你的文件和数据](/docs/where-your-data-lives/)。
