NetSarang：用户数据文件夹迁移
本文以 Xshell 8 与 Xftp 8 为例，介绍 NetSarang 系列产品用户数据文件夹的作用、默认位置与迁移方法。迁移的典型动机包括统一目录命名、更换磁盘、接入云盘同步、重装系统前备份等。核心结论只有一条：数据文件夹的路径登记在注册表中，迁移必须"先搬家、再改登记"——只在资源管理器里改名，应用下次启动会按旧路径找不到数据，随即静默新建一个空白目录，所有会话从界面上"消失"（数据并未丢失，只是被留在了原地）。
一、用户数据文件夹是什么
NetSarang 各产品（Xshell、Xftp、Xmanager、Xlpd）不把配置散落在安装目录，而是集中存放在当前用户的"用户数据文件夹"（User Data Folder）中，首次安装时可自行指定，此后可在应用内随时更改。以 8.x 为例，用户数据文件夹下的典型内容如下：
| 目录 / 文件 | 内容 |
|---|---|
| Xshell\Sessions | 会话文件（.xsh）与会话文件夹定义（.xshf、folder.cnf） |
| Xshell\Logs、applog | 会话日志与程序运行日志 |
| Xshell\Scripts | 脚本文件（Screen / Session 两类） |
| Xshell\ColorScheme Files | 终端配色方案（.scs） |
| Xshell\HighlightSet Files | 关键字高亮集（.hls） |
| Xshell\QuickButton Files | 快捷按钮集（.qbl） |
| Xshell\CustomKeyMap.ckm、buttonlist.ini、Xshell.ini | 键盘映射、按钮栏与主配置 |
| Xftp\Sessions、LocalBookmark.ini、Xftp.ini | Xftp 会话、本地书签与主配置 |
| Common\MasterPassword.mpw、Credential | 主密码与凭据（两产品共享） |
| SECSH\HostKeys、UserKeys | 已接受的主机公钥与用户密钥 |
| Themes | 终端主题 |
用户数据文件夹的默认位置随版本演进：
| 版本 | 用户数据文件夹默认位置（当前用户下） |
|---|---|
| 4.x 及以前 | %APPDATA%\NetSarang |
| 5.x | 文档\NetSarang |
| 6.x | 文档\NetSarang Computer\6 |
| 7.x | 文档\NetSarang Computer\7 |
| 8.x | 文档\NetSarang Computer\8 |
注意 6.x 以后的目录层级：用户数据文件夹是"文档\NetSarang Computer\8"这一层，其下再按产品分 Xshell、Xftp 子目录，Common、SECSH、Themes 为共享目录。部分机器（加入域或启用了文件夹重定向）"文档"实际指向其他路径，动手前建议先在应用内确认真实位置，不要凭记忆猜。
二、涉及应用与路径登记机制
Xshell 与 Xftp 是两个独立产品，却共用同一个用户数据文件夹：官方套装 Xshell Plus 的设计即源于此，两产品指向同一路径时自动共享会话与凭据。因此迁移往往一次操作、两处生效，涉及的应用就是这两个（装了几个改几个，Xmanager、Xlpd 同理）。
路径的唯一登记处是注册表：
HKCU\Software\NetSarang\Common\<主版本号>\UserData → UserDataPath（REG_SZ）应用只在启动时读取该值。由此得到两条重要性质：
- 资源管理器改名无效：文件夹改名不会同步注册表，应用按旧路径找不到数据时不报错，而是静默新建空白目录——这是"会话集体消失"的最常见原因，且极易被误判为数据丢失。
- 配置文件不绑定路径：ini、会话、密钥等文件内部不记录数据文件夹的绝对路径（已在 8.0 验证），因此整个目录可以整体复制到任意位置，只需改注册表一处。
三、迁移操作
3.1 迁移前准备
- 退出全部 NetSarang 应用：更改数据文件夹前软件必须关闭，否则修改不生效甚至写入错乱；
- 备份两样东西：注册表 NetSarang 项、数据目录本身（见 3.3 第 2 步）；
- 规划好新路径，避开正在同步的云盘冲突区与含特殊字符的路径。
3.2 方法一：官方向导（推荐）
在两产品内分别操作：菜单"工具 → 更改用户数据文件夹"，按向导选择新的用户数据文件夹路径；下一步时不要勾选"删除原始文件夹"（保留原目录即保留回滚源），确认完成后重启应用。
由于两产品共用登记项，任一产品内修改对两者同时生效；仍建议分别打开确认会话列表正常。此方法由软件自行完成目录初始化与登记改写，适合日常使用。
3.3 方法二：手动迁移（适合脚本化、无交互环境）
# 1. 确认应用已全部退出（无输出即通过）
Get-Process Xshell, Xftp -ErrorAction SilentlyContinue
# 2. 备份注册表（数据目录保持原地不动，天然就是回滚源）
reg export "HKCU\Software\NetSarang" "D:\backup\NetSarang.reg" /y
# 3. 复制数据到新位置（源版本号目录 8 随大版本变化）
Copy-Item "$env:USERPROFILE\Documents\NetSarang Computer\8" "D:\NetSarang Files\8" -Recurse
# 4. 改写登记路径（等价于向导的最终效果）
Set-ItemProperty "HKCU\Software\NetSarang\Common\8\UserData" -Name "UserDataPath" -Value "D:\NetSarang Files\8"
# 5. 验证登记值
(Get-ItemProperty "HKCU\Software\NetSarang\Common\8\UserData").UserDataPath说明：第 4 步中的"8"是主版本号，随大版本变化；部分受限环境禁止调用 reg.exe，可改用注册表编辑器"文件 → 导出"，或用 .NET 注册表 API 自行序列化。新旧路径若已有同名版本号目录，应先比对内容再决定合并还是替换，切忌盲目覆盖。
3.4 回滚
随时将 UserDataPath 改回原值即可瞬间恢复；只要按上述步骤"复制而非移动"，数据文件自始至终未被删除，原目录就是最后的兜底。
四、迁移后验证清单
| 检查项 | 预期结果 |
|---|---|
| 会话管理器 | 分组与会话齐全（含子文件夹，如按项目分的组） |
| 保存的密码 | 同机同用户迁移直接有效，无需重输 |
| 主机密钥 | 首次连接不再弹出主机密钥确认（SECSH\HostKeys 随迁） |
| Xftp | 会话、本地书签、传输配置在位 |
| 程序日志 | 新 applog 日志写入新目录，证明启动时已按新路径加载 |
| 最近打开记录 | 可能残留旧路径，属界面历史记录，打开新位置会话后自动更新，无需处理 |
关于密码的边界：会话中保存的密码按机器与用户绑定加密，同一台电脑、同一个 Windows 用户下迁移后直接可用；若换电脑，须在两台机器设置相同的主密码（Master Password），并通过"文件 → 导出 / 导入"（.xts 文件）迁移，否则密码需手工重输——这是防会话文件被盗后直接利用的安全设计，不是故障。
五、常见问题
1. 改名后会话全部消失，数据丢了吗？
没有丢。应用按注册表旧路径新建了空白目录，原数据仍在旧文件夹中。恢复方法：把 UserDataPath 改回原路径，或按本文方法把数据正式迁到新路径。
2. applog 里的旧日志不见了？
正常现象。应用每次启动会做日志轮转（旧 .log 转存或清理），只保留最近若干份，不影响任何功能数据。
3. 升级大版本后数据如何衔接？
安装 Xshell 8 / Xftp 8 时会自动导入 7 的用户数据（会话、配置等），无需手工迁移。另注意 Version 7 免费授权已停止支持，免费用户需升级到 8 才能继续使用。
4. 想把数据文件夹放进云盘同步？
官方建议尽量保持默认路径；确有必要多设备同步时，用方法一的向导修改，并确保同一时刻只有一个设备在写，避免配置互相覆盖。