Ghost 数据迁移指引

介绍

本指引提供了从 Ghost 迁移至 Halo 2.x 的方案。

安装迁移插件

在 Halo 后台的应用市场中搜索 站点迁移，安装并启用。

注意事项

目前通过 Ghost 后台导出的 JSON 文件进行迁移。
当前开发与回归测试主要基于仓库中的 Ghost 6.28.0 导出样例。
当前主要支持迁移文章、页面、标签。主题、站点设置等 Ghost 特有能力不会迁移。
Ghost 导出的 JSON 不包含独立附件表，系统会从文章、页面和标签封面中的本地媒体链接自动识别附件。
如果 Ghost 导出中包含作者邮箱，导入时会优先按邮箱匹配现有 Halo 用户；未匹配到时会自动创建 guest 用户，以尽量保留内容归属。

准备工作

进入 Ghost 后台的 Settings -> Import/Export，点击 Content & settings，下载导出的 JSON 文件。
如果站点中使用了本地图片或文件，建议同时从服务器备份 Ghost 的 content 目录，至少保留 content/images 和 content/files 作为附件迁移备用（可选）。
建议先在本地环境完成一轮完整导入测试，再考虑在生产环境执行。这样更方便快速重试和定位问题，也能避免线上因频繁请求后端、上传附件而出现导入变慢或部分失败；本地验证通过后，还可以结合 Halo 的备份恢复能力更快完成线上恢复或回滚。

执行迁移

点击左侧菜单的迁移进入迁移页面。
在选择渠道步骤中，选择 Ghost，点击下一步。
选择从 Ghost 后台导出的 JSON 文件。
等待系统解析文章、页面、标签、作者归属及本地媒体引用。
如果检测到本地媒体资源：
- 选择 上传到 Halo 时，可选择 Ghost 的 content 目录、content/images / content/files 子目录，或包含这些目录的任意上级目录。
- 选择 手动迁移 时：
  
  需要先将备份的 content 目录完整放到 {Halo 工作目录}/attachments/migrate-from-ghost 中，也就是最终目录中需要保留 content/images 和 content/files 这一层级结构。
  
  然后在工作目录新建一个 application.yaml，写入以下内容：
```
halo:
  attachment:
    resource-mappings:
      - pathPattern: /content/images/**
        locations:
          - migrate-from-ghost
      - pathPattern: /content/files/**
        locations:
          - migrate-from-ghost
```
确认数据概览无误后，进入下一步并开始迁移。
迁移完成后，建议优先抽样检查文章封面、正文图片和标签封面是否都已正确解析。