从 1.x 或 Preview 迁移到 2.0
NyaTerm 2.0 使用 GPUI 原生桌面界面。请下载与操作系统、CPU 架构一致的安装包；以下流程不承诺跨架构原位升级。Windows 最低要求为 Windows 10，不支持旧版的 Windows 7 使用场景。
迁移前备份
完全退出 NyaTerm 后，复制完整数据目录和相关密钥文件到独立位置。稳定安装版通常使用用户目录中的 .nyaterm/；便携版使用程序旁的 data/。备份整个便携目录可以一并保留程序、标记及密钥文件。保留原来的安装包。
已设置主密码时，另导出一份 .nya 加密备份。备份导出不能代替退出应用后的完整目录副本。不要将密钥、凭据或真实数据提交到问题报告。
Windows 便携版
- 退出 NyaTerm，备份整个旧版便携目录。
- 下载同架构的完整 2.0 便携 ZIP，先解压到临时目录。
- 将解压后的程序文件完整复制到旧目录，覆盖同名文件；保留旧
data/和密钥，不用新包内容覆盖它们。 - 一并复制
nyaterm-rdp-helper.exe、nyaterm-vnc-helper.exe、MCP 程序及完整 ConPTY 目录。不能只替换NyaTerm.exe。 - 启动并检查版本、连接、凭据和主密码，再测试 RDP/VNC。
1.x 便携版的内置更新器不能完成此次迁移。 它使用文件白名单且不会部署新 helper；出现更新错误时请使用上述手动流程。2.0 便携版后续更新支持完整程序包替换并保留数据。
Windows MSI 与 NSIS 安装版
旧 MSI 用户先备份，使用 Windows 的“已安装的应用”卸载旧版，再安装同架构的 2.0 -setup.exe。不要选择删除用户数据的选项。启动后核对配置、快捷方式、安装目录和卸载记录，避免保留两个容易混淆的安装入口。
MSI 到 NSIS 不承诺自动迁移，也不能把 EXE 当作 MSI 更新包运行。旧 NSIS 的原位升级需要相应版本的验收；在确认支持前，可使用相同的备份、卸载、安装流程。
macOS 与 Linux
macOS 手动安装的用户退出应用后替换 /Applications/NyaTerm.app，保留用户数据目录。Homebrew 用户使用 brew upgrade --cask nyaterm。
Linux AppImage 用户退出后替换同架构 AppImage 并保留可执行权限。deb/rpm 用户使用对应包管理器更新完整软件包，避免手动替换包管理器拥有的单个文件。
GPUI 的内置更新通过签名清单检查版本，并提供下载及安装操作；适用于受支持的 Windows NSIS/便携版、macOS 手动安装的应用包和 Linux AppImage。Homebrew、deb/rpm 及无法识别的安装方式使用包管理器或手动更新。
Preview 转为 Stable
Preview 与 Stable 使用独立应用身份和数据目录（.nyaterm-preview/ 与 .nyaterm/）。在 Preview 中设置主密码并导出 .nya 备份，安装 Stable 后通过备份恢复导入，再重启验证。不要直接合并两个数据目录，也不要假定 Preview 自动切换到稳定频道。
验证与恢复
检查连接、密码及私钥凭据、主密码、已知主机、OTP、备份恢复和云同步。先确认本地数据正常，再恢复自动同步；不要让测试实例写入生产同步副本。
升级异常时完全退出程序，恢复迁移前的程序及完整数据副本。不要只换回 1.x 可执行文件并让它打开已被 2.0 写入的数据。确认恢复和日常使用正常后，再清理备份。