从 0.19 升级到 1.0

从 0.19 升级到 1.0 后，第一次启动会比平时慢，搜索会短暂不可用，原来的配对设备也会被清空。这些都是升级过程的一部分，不代表资料丢失。

升级前一分钟检查

1. 让所有 0.19 设备完成最后一次同步。
2. 确认重要文字、图片和文件至少在一台设备上可以打开；特别重要的文件另存一份。
3. 记录现有设备名称，方便升级后逐台重新配对。
4. 完全退出所有设备上的 UniClipboard。
5. 保留 0.19 安装包，直到所有设备升级完成。

多设备用户应一次只升级一台。先确认第一台的历史记录完整，再升级下一台。

推荐升级顺序

1. 先升级一台资料完整、你能直接操作的电脑。
2. 等这台电脑完成备份和搜索重建，确认历史记录可以打开。
3. 升级第二台设备。
4. 两台设备都显示 1.0 后，重新配对并测试双向同步。
5. 确认成功后，再逐台升级和配对其余设备。

尚未升级的 0.19 设备可以继续保留自己的本地资料，但它不能与已经升级的 1.0 设备配对或同步。

正常升级

1. 从官方发布页下载适合当前系统和处理器的 1.0 安装包。
2. 完全退出 UniClipboard，包括托盘或菜单栏中的后台进程。
3. 按原来的安装方式覆盖安装。Windows 便携版应替换程序，但保留原来的 data 文件夹。
4. 启动 UniClipboard，只打开一个实例，并让它完成首次升级。

覆盖安装不会主动删除历史记录。首次启动期间不要卸载应用、删除数据目录或切回 0.19。

第一次启动会发生什么

第一次启动依次完成三件事。

1. 备份原有资料

应用会先复制并验证 0.19 的本机资料，因此这次启动会比平时慢。资料越多，所需时间越长。在备份完成前，不要强制退出、关机或同时启动第二个 UniClipboard。

升级备份与正在使用的数据目录分开保存：

如果使用了自定义配置名称，目录名会在 desktop 后增加对应后缀。Windows 便携版的升级备份仍保存在上述系统目录中，不在便携版的 data 文件夹里。

升级完成后，可以在 设置 → 存储 → 升级备份 查看备份的版本、时间和大小。应用最多保留最近 5 份。

2. 重建搜索索引

进入主界面后，历史记录已经可以使用，但搜索不会立即可用。应用正在根据已有历史重新建立搜索索引，通常约 10 秒 完成。

在这段时间里：

• 历史记录仍然存在，可以浏览和复制；
• 搜索可能显示“正在重建”，或暂时没有结果；
• 不需要手动重建，也不要因为搜索为空而清除资料。

可以在 设置 → 存储 → 搜索索引 查看状态。显示“就绪”后再检查搜索结果。

3. 清空旧配对设备列表

升级完成后，0.19 建立的配对关系不会继续保留。设备列表为空是预期结果，不代表本机历史被删除。

请在其他设备也升级到 1.0 后重新配对。旧设备不会自动重新出现。

重新配对所有设备

先在两台设备的“关于”页面确认它们都运行 1.0，然后决定哪台设备负责发出邀请。

在第一台设备上发出邀请

1. 打开 设备 页面。
2. 点击左下角的 邀请设备。
3. 弹窗会要求输入升级前使用的原空间口令。输入后点击 确认并生成邀请码。
4. 将新生成的一次性邀请码交给要加入的设备。

如果已经忘记原口令，点击弹窗中的 忘记原口令？重置口令：

1. 输入并再次确认一个新的空间口令。
2. 点击 重置口令。本机历史和本地资料会保留。
3. 保存好这个新口令；接下来每台加入的设备都必须输入同一个新口令。
4. 重置完成后，应用会继续生成邀请码。重置前生成的旧邀请码将不能再用。

在其他设备上加入

1. 在另一台已经升级到 1.0 的设备上打开 设备 页面。
2. 点击左下角的 加入其他空间。
3. 输入第一台设备刚生成的邀请码。
4. 输入与第一台设备相同的空间口令。如果第一台设备刚重置过口令，这里必须输入重置后的新口令。
5. 点击 切换，等待加入完成。切换期间不要退出应用。
6. 配对成功后，用一小段新文字测试两个方向的同步。
7. 确认成功后，再按同样方式处理下一台设备；每台设备都需要新的邀请码。

详细操作见配对与同步。

如何确认升级成功

• “关于”页面显示 1.0；
• 原有历史、收藏、标签、图片和文件可以打开；
• 设置 → 存储 → 搜索索引 在约 10 秒后显示“就绪”；
• 旧设备列表已清空，并且可以与另一台 1.0 设备重新配对；
• 两台 1.0 设备可以双向同步新文字；
• 退出并重新打开应用后，以上结果仍然正常。

如果看起来卡住了

一直停在首次启动

资料较多时，备份可能明显超过平时的启动时间。先保持设备接通电源并继续等待。不要连续重启，也不要同时打开第二个实例。

如果应用明确报错或重复退出，停止重试，保留升级备份和日志，然后导出诊断信息。

提示“恢复本机资料”

这表示系统保存的密钥缺失或无法使用，并不等于历史已被删除。在支持口令恢复的新版中：

1. 输入创建空间时使用的原加密口令，不是电脑登录密码。
2. 输错口令不会删除资料，可以重新输入。恢复完成前，历史、剪贴板监听和设备同步暂不可用。
3. 恢复成功后，检查原有历史是否可读，复制一段新文字确认能保存，再退出并重新打开一次。
4. 如果提示旧密钥不完整、资料无法读取或无法保存密钥，停止清理和重置，保留原资料及升级备份，联系作者协助处理。

如果提示后台服务启动失败、需要重启，请选择 重启后台服务，不要反复输入口令。资料会保留；重启后仍失败，或一直停在恢复页面，请保留资料并联系作者协助检查。

口令恢复需要本机保留完整的加密恢复资料。如果旧密钥在升级生成这份资料之前已经丢失，只有口令也可能无法恢复旧历史。不要自行删除系统钥匙串来尝试修复。

普通“解锁”页只遮住内容和管理设置，后台仍可工作；“恢复本机资料”页则需要先恢复密钥，后台才能恢复工作。旧版本若没有恢复页，请先保留资料并联系作者，不要用重置代替恢复。

搜索超过一分钟仍不可用

先确认历史记录是否可以浏览，然后前往 设置 → 存储 → 搜索索引 查看状态。历史正常但索引仍未就绪时，重启应用一次；仍无改善再导出诊断信息。

不要删除历史或数据目录来修复搜索。

设备列表为空

这是 0.19 升级到 1.0 后的正常结果。确认另一台设备也已升级到 1.0，然后重新配对。

两台设备无法配对

先检查两端版本。只要有一台仍是 0.19，就停止排查网络，先把它升级到 1.0。两端都是 1.0 仍失败时，保持两台设备在线，从两端分别导出诊断信息。

历史记录看起来缺失

1. 立即停止复制新内容，不要清空历史、重置空间或删除资料。
2. 确认使用的是原来的用户账户和安装方式。Windows 便携版应继续使用原 data 文件夹。
3. 完全退出并重新打开一次，等待首次升级完成。
4. 查看 设置 → 存储 → 升级备份，但不要删除或手动修改备份。
5. 资料仍缺失时，保留现场并寻求帮助。不要让 0.19 打开已经升级过的数据目录。

回退到 0.19

不要直接用 0.19 打开已经升级到 1.0 的数据目录。新版资料可能已改变，旧版不一定能安全读取。

安全回退需要完整的升级前资料、与它配套的系统安全存储，以及原 0.19 安装包。应用建立的升级备份主要用于保护升级过程，不能单独保证完整回退。

如果没有验证过的完整系统备份，请停止自行回退，保留成功升级的设备和升级备份，并寻求帮助。清空资料、重置空间和删除备份都只能作为最后手段。

导出诊断信息和寻求帮助

能打开应用时，选择 设置 → 通用 → 导出日志。命令行可用时也可以运行：

uniclip debug export-logs

提交问题时，请说明操作系统和设备类型、升级前后的 Desktop 版本、卡在备份/搜索重建/重新配对的哪一步、问题发生时间，以及参与配对的每台设备版本。

将说明和诊断压缩包提交到 GitHub Issues。不要公开空间口令、邀请码或个人剪贴内容。

最后兜底：删除旧数据并全新安装

如果已经确认不再保留这台设备上的旧数据：

1. 完全退出 UniClipboard，并保存现有升级备份和诊断日志。
2. 卸载当前版本。
3. 按紧急重置（最后手段）清除应用数据和系统中保存的 UniClipboard 凭据。
4. 重新安装 1.0，创建一个新空间，或使用另一台 1.0 设备生成的新邀请码加入现有空间。
5. 用一小段新文字测试双向同步，确认正常后再处理其他设备。

如果不确定该删除哪些内容，请停在第 1 步，通过 mkdir700@gmail.com 或 GitHub Issues 求助。

最终检查清单

• 所有设备在升级前完成了最后一次同步。
• 第一台设备完成资料备份，原有历史可以打开。
• 搜索索引在约 10 秒后恢复为“就绪”。
• 已确认旧配对列表被清空是预期行为。
• 参与配对的设备都已升级到 1.0。
• 所有设备按顺序重新配对，并完成双向同步测试。
• 升级备份和 0.19 安装包仍然保留。