数据迁移操作指南

本页介绍数据目录迁移的实际操作。技术实现见基础实现。

查找应用关联的数据目录

1. 在 AppPorts 主窗口切换到「数据目录」标签。
2. 顶部在「工具目录 / 应用数据」之间切换。
3. 查看应用数据时，在左侧选一个应用，右侧列出它在 ~/Library/ 下关联的目录。

AppPorts 按应用的 Bundle ID 或名称匹配下面这些位置：

扫描路径	匹配方式	迁移方式
~/Library/Application Support/	Bundle ID 或应用名称	符号链接
~/Library/Preferences/	Bundle ID 或应用名称	符号链接
~/Library/Containers/	Bundle ID	挂载迁移
~/Library/Group Containers/	Bundle ID	挂载迁移
~/Library/Caches/	Bundle ID 或应用名称	符号链接
~/Library/WebKit/	Bundle ID	符号链接
~/Library/HTTPStorages/	Bundle ID	符号链接
~/Library/Application Scripts/	Bundle ID	符号链接
~/Library/Logs/	应用名称	符号链接
~/Library/Saved Application State/	应用名称	符号链接

容器目录为什么不同，见挂载迁移。

工具目录

AppPorts 会识别常见开发工具在用户目录下建的目录（~/.npm、~/.gradle 等）：

1. 在「数据目录」标签中切换到「工具目录」。
2. 列表显示已识别的目录、大小、优先级和状态。

本地目录不存在、但外置盘的规范位置还有 AppPorts 管理的目录时，显示为「待接回」。支持列表见工具目录识别。

目录迁移（自定义文件夹）

「目录迁移」标签用于迁移用户目录下的任意文件夹，适合大型项目、模型、素材库。

1. 切换到「目录迁移」。
2. 点「本地文件夹」标题栏的「+」。
3. 选本地文件夹，再选外置盘上的目标根目录。目标是 目标根目录/文件夹名。

校验规则：本地文件夹必须在用户目录下且不能是用户目录本身；路径及其上级不能是符号链接；不能与已管理的目录互相包含；外部目标不能在用户目录内，也不能与本地文件夹互相包含。

迁移后本地面板显示原路径状态，外部面板显示副本状态，可执行「接回」或「还原」。移除配置只删记录，不删数据。

符号链接迁移

适用于容器之外的所有目录。

1. 找到目录，点「迁移」。
2. AppPorts 复制到外置盘，写入管理标记，把原目录改名为安全备份，在原路径建符号链接，最后清理备份。
3. 迁移完成后状态变为「已链接」。

迁移后重签名

数据目录页顶部有「迁移后重签名」开关，默认关。开启后，迁移完成会对关联应用执行 Ad-hoc 重签名，只用于处理迁移后弹「已损坏」的情况；沙盒应用会跳过。通常不需要开，详见重签名与崩溃防护。

挂载迁移

适用于 Containers 和 Group Containers 下的目录，按钮显示为「挂载迁移」。

1. 确认外置盘是 APFS，退出关联应用。
2. 点「挂载迁移」，看清确认框里的三条提示后继续。
3. AppPorts 在外置盘建一个卷，复制数据，把卷挂到原目录上。
4. 完成后状态为「已挂载」。第一次打开应用时系统弹授权框，点允许。

完整说明见挂载迁移。

还原

符号链接迁移的目录（状态「已链接」）：点「还原」，AppPorts 把数据复制回本地，删除符号链接，再删除外置盘副本。

挂载迁移的目录（状态「已挂载」或「待挂载」）：点「还原」，AppPorts 把卷上的数据复制回本地，卸载并删除卷。外置盘需保持连接。

两种还原都先复制、后切换，中途失败不会丢数据。

处理异常状态

状态	含义	操作
待规范	AppPorts 管理的链接，但外部路径不在规范位置	「整理」，把外部数据移到规范路径并重建链接
待接回	外置盘上的数据还在，本地链接丢了	「接回」，重建符号链接
现有软链	不是 AppPorts 建的符号链接	「链接详情」，可选择纳入管理
待挂载	挂载迁移的卷在线但没挂上	「挂载」
外置盘未连接	找不到挂载迁移的数据卷	连上外置盘，AppPorts 会自动接回

接回和整理只对目录有效；外部目标被普通文件占用时 AppPorts 会停下并保留那个文件。

日志上下文

数据目录操作的日志会带上关联应用的信息，便于诊断：

字段	说明
app_name	关联应用名称
app_status	应用状态
app_is_resigned	应用是否已被重签名
app_bundle_id	真实应用的 Bundle ID
app_real_path	真实应用路径

挂载迁移的操作还会记录卷名、Volume UUID 和 diskutil 命令的输出。

树形视图

包含子目录的数据目录以树形显示：父目录左侧有展开箭头，子目录缩进，每个节点独立显示大小、状态和操作按钮。