Typecho 数据迁移指引

介绍

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

安装迁移插件

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

注意事项

通过 Typecho 后台【备份】功能导出的备份文件进行迁移，支持 .dat / .txt 文件。
当前开发与回归测试主要基于仓库中的 Typecho 1.3.0 后台备份样例。
当前主要支持迁移文章、页面、分类、标签、评论、附件。
主题、站点配置等 Typecho 特有内容不会迁移。
如果备份中的作者带有邮箱，导入时会优先按邮箱匹配现有 Halo 用户；未匹配到时会自动创建 guest 用户，以尽量保留文章、页面和评论的归属关系。
Halo 2 默认没有内置 Markdown 编辑器。如果后续需要重新编辑导入后的 Markdown 文章，需要额外安装 Markdown 编辑器插件。

准备工作

进入 Typecho 后台，在【控制台 -> 备份】中导出备份文件，下载生成的 .dat 或 .txt 文件。
建议同时从服务器备份 usr/uploads 目录，作为附件迁移备用（可选）。
建议先在本地环境完成一轮完整导入测试，再考虑在生产环境执行。这样更方便快速重试和定位问题，也能避免线上因频繁请求后端、上传附件而出现导入变慢或部分失败；本地验证通过后，还可以结合 Halo 的备份恢复能力更快完成线上恢复或回滚。

执行迁移

点击左侧菜单的迁移进入迁移页面。
在选择渠道步骤中，选择 Typecho，点击下一步。
选择从 Typecho 后台导出的备份文件（.dat / .txt）。
等待系统解析文章、页面、分类、标签、评论、作者归属及附件信息。
如果检测到本地附件：
- 选择 上传到 Halo 时，可选择 Typecho 站点根目录、usr 目录、usr/uploads 目录，或包含这些目录的任意上级目录。
- 选择 手动迁移 时：
  
  需要先将备份的 usr/uploads 目录中的所有文件（不包含 uploads 目录）放到 {Halo 工作目录}/attachments/migrate-from-typecho 中。
  
  然后在工作目录新建一个 application.yaml，写入以下内容：
```
halo:
  attachment:
    resource-mappings:
      - pathPattern: /usr/uploads/**
        locations:
          - migrate-from-typecho
```
确认数据概览无误后，进入下一步并开始迁移。
迁移完成后，建议优先抽样检查页面可见性、评论归属和附件引用是否符合预期。