数据迁移操作指南
本页面介绍数据目录迁移的实际操作流程。如需了解技术实现细节，请参阅基础实现。
查找应用关联的数据目录
- 在 AppPorts 主窗口切换到「数据目录」标签。
- 左侧面板会显示所有已安装的应用。
- 使用顶部工具栏在「工具目录 / 应用数据」之间切换；查看应用数据时，点击某个应用后，右侧面板会显示该应用在
~/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/ | 应用名称 |
工具目录（Dot-Folder）
AppPorts 可自动识别常见开发工具在用户目录下创建的 dot-folder：
- 在「数据目录」标签中切换到「工具目录」子标签。
- 页面会列出所有已识别的工具目录及其大小。
- 每个目录都会显示优先级徽章（推荐/可选）和当前状态。
如果本地工具目录已不存在，但当前外部存储的规范位置仍有 AppPorts 管理的目录，列表会显示为「待接回」。切换外部存储后，AppPorts 会重新扫描工具目录并刷新该状态；普通文件不会被识别为可接回目录。
详细支持列表请参阅工具目录识别。
目录迁移（自定义文件夹）
「目录迁移」标签用于迁移任意用户文件夹，适合将大型项目、模型、素材库或工具缓存移动到外部存储。
- 在主窗口切换到「目录迁移」。
- 点击「本地文件夹」标题栏的「+」按钮。
- 选择要迁移的本地文件夹，再选择外部存储中的目标根目录。
- AppPorts 会把外部目标设为
目标根目录/本地文件夹名，保存配置并开始迁移。
为避免递归复制、误迁移系统目录或接管错误路径，目录迁移会执行以下校验：
- 本地文件夹必须位于当前用户目录下，不能是整个用户目录。
- 本地路径本身及其上级路径不能是符号链接。
- 本地文件夹不能与已管理的数据目录或目录迁移项存在包含关系。
- 外部目标根目录必须是文件夹，且不能位于当前用户目录内。
- 外部最终目标不能位于本地文件夹内部，本地文件夹也不能位于外部最终目标内部。
迁移后，本地面板显示原始路径状态，外部面板显示外部副本状态。可在外部面板中选择项目执行「接回文件夹」或「还原文件夹」；移除配置只会从目录迁移列表中删除记录，不会自动删除真实数据。
迁移操作
单个目录迁移
- 在数据目录列表中找到要迁移的目录。
- 点击右侧的「迁移」按钮。
- AppPorts 会执行以下步骤：
- 将目录复制到外部存储。
- 写入托管链接元数据。
- 删除本地原始目录。
- 创建符号链接。
自动重签名
数据目录页顶部工具栏提供「迁移后重签名」开关。开启后，数据目录迁移会自动触发关联应用的签名操作：
- 迁移前：备份关联应用的外部真实路径的原始签名，而不是备份本地入口壳。
- 迁移完成后：对外部真实应用执行 Ad-hoc 重签名。该过程以静默模式运行，失败时不弹窗。
对于已链接应用，AppPorts 会自动解析 Stub Portal 壳或符号链接背后的真实应用路径，确保签名变更作用于实际应用包，而不是本地入口壳。
容器数据迁移确认
迁移 Containers 或 Group Containers 相关应用数据时，AppPorts 会在迁移前确认是否在完成后重签名。选择「同意重签名」会执行上述备份与 Ad-hoc 重签名；选择「不同意，仅迁移」则只迁移数据目录。
批量迁移
- 在工具目录列表中勾选多个目录。
- 点击底部的「批量迁移」按钮。
- AppPorts 会按顺序逐个执行迁移。
优先级建议
数据目录按优先级分为三级：
- 重要（
critical）：迁移后必须正常工作，影响应用核心功能 - 推荐（
recommended）：占用空间大，迁移收益高 - 可选（
optional）：空间较小或可重建
建议优先迁移标记为「推荐」的目录。
恢复操作
- 在数据目录列表中找到已迁移的目录（状态为「已链接」）。
- 点击右侧的「恢复」按钮。
- AppPorts 会执行以下步骤：
- 删除本地符号链接。
- 将数据从外部存储复制回本地。
- 删除外部目录（尽力而为）。
如果恢复或接续迁移时发现外部目标已存在，AppPorts 会检查 .appports-link-metadata.plist。只有 metadata 与当前源路径、目标路径和目录类型完整匹配时，才会自动接回或恢复；否则会提示目标冲突并保留现有目录。
处理异常状态
待规范
目录由 AppPorts 管理，但外部路径不在规范位置。点击「规范化」按钮后，AppPorts 会将外部数据移动到规范路径并重建符号链接。
待接回
外部存储上的数据目录仍在，但本地符号链接已丢失。点击「重新链接」按钮后，AppPorts 会重新创建符号链接。接回只适用于外部目标仍是目录的情况；如果外部目标被普通文件占用，AppPorts 会停止操作并保留现有文件。
现有软链
这是非 AppPorts 创建的用户自定义符号链接。可选择「接管」，由 AppPorts 写入托管链接元数据，并将其纳入管理。
日志上下文
数据目录操作（迁移、恢复、规范化、重新链接）的日志中会自动包含关联应用的上下文信息：
| 字段 | 说明 |
|---|---|
app_name | 关联应用名称 |
app_status | 应用状态（已链接、本地等） |
app_is_resigned | 应用是否已被重签名 |
app_bundle_id | 应用的 Bundle ID（基于真实路径读取） |
app_real_path | 应用的真实外部路径 |
这些字段可在导出诊断包时帮助更精确地定位问题。
树形视图
对于包含子目录的数据目录（如 Application Support 下的多个应用目录），AppPorts 提供树形分组视图：
- 父目录左侧显示展开/折叠箭头。
- 子目录显示层级缩进。
- 每个节点独立显示大小和状态。
- 可对单个子目录执行迁移或恢复操作。