博客跨大版本全站迁移实录：进度全绿≠完成

一、事故现场：1272 项任务全绿，站点却是个空壳

先交代背景。我的个人博客在一台家用 NAS 上以容器方式运行了四年：176 篇文章、65 个分类、101 个标签，加上四年累积的附件与搜索引擎收录，全部存放在一个嵌入式关系数据库里。这次升级横跨两个大版本——旧版的模板引擎、数据模型、插件体系在新版中几乎全部重构，注定不是“点一下升级按钮”就能收场的操作。

官方迁移插件跑完的那一刻很有欺骗性：进度条 1272/1272 全绿，六个管理页面全部返回 HTTP 200。我长舒一口气打开首页——

• 主题是全新安装的默认主题，不是我用了很多年的自定义主题；
• 导航菜单只剩 4 条主题临时生成的默认项，15 条自建菜单全部消失；
• 文章列表页一半有摘要、一半空白；
• 配置了“交替图文”排版的封面图全部丢失。

“迁移成功”了，但迁过来的是一个空壳：老站还在 8090 端口安然运行，新站却没法见人。这类迁移的真实面貌是——工具负责把“内容”搬过去，而决定“这个站像不像你”的那一半——配置与呈现——默认没人管。整个过程由本机智能编程助手驱动执行，但每一步“修到什么程度才算好”的判断标准，必须由人先定义清楚。

二、问题拆解：为什么“全绿”不等于“完成”

把一个博客站从数据视角拆开，其实是两类完全不同的东西：

• 内容实体：文章、页面、分类、标签、评论、附件、图库、友链等。结构稳定、语义明确、与主题无关，天然适合批量搬运——迁移插件的 1272 项任务，全部落在这个象限。
• 配置实体：主题设置、菜单结构、每篇文章的摘要与封面、SEO 元数据、固定链接规则、用户与权限。它们强绑定具体主题与具体版本：键名因主题而异、模型因版本而异，跨大版本无法机械化映射，所以工具默认不迁。

这不是工具的缺陷，而是工具的边界。理解这条边界，才能把迁移预期从“跑一次插件”修正为“跑一次插件 + 半天到一天的配置重建”。本例中四类缺口的成因：

1. 主题设置：以键值对形式与主题标识强耦合，新版本设置模型重新注册后，老键没有落点，主题呈现整体回落默认；
2. 菜单：1.x 是“扁平列表 + 层级字段”，2.x 重构为“菜单组—菜单项”两级模型，插件按旧模型导出，新前端读不到，15 条菜单集体蒸发；
3. 摘要：旧版显式存储、新版字段策略变化，一半文章在新列表页抽不出摘要；
4. 封面：附件引用方式从路径字符串升级为媒体库引用，字段更名后引用悬空，封面全部丢失。

三、常规手段为何全部失效

在找到正确打法之前，先把四条“看起来可行”的路堵死：

1. 指望官方插件全包：插件任务组只覆盖内容实体，没有主题设置、站点选项、用户这类配置数据，菜单还只按旧模型导——边界之外无人负责；
2. 直接把旧版数据库文件拷进新容器：两个大版本的数据库在表结构、驱动、存储格式上三重不兼容，拷过去轻则起不来，重则数据损坏。跨大版本场景下，库级复制这条路根本不存在；
3. 人工在后台重录：176 篇文章 × 摘要 × 封面 × 15 条菜单，工作量导致人为错误率不可接受，而且事后无法系统性校验；
4. 装回旧版硬凑生产：目标就是新大版本，回退等于放弃升级的全部理由，问题只是被推迟到下一次。

四、方案：三段式“手术台”打法

总原则一句话：老站只读做“标准答案”，本地双实例做“考场”，修好的站用整站备份整体搬运。

阶段一：源站冻结与全量导出

• 老站容器全程不动、停止写入，保证数据快照一致；
• 通过导出能力生成全站 JSON（本例 9.4MB），作为唯一数据源；
• 为什么选 JSON 而不是数据库文件：它平台中立、人类可读、可脚本加工、可逐字段 diff。跨大版本迁移中，任何库级操作都不可靠，只有“导出 → 转换 → 导入”这条数据流是可控的。

// 导出包结构示意（简化）
{
  "posts":  [ { "id": 1, "title": "...", "excerpt": "...",
                "cover": "/upload/a.png", "categories": [], "tags": [] } ],
  "menus":  [ { "name": "主菜单", "items": [ { "label": "关于", "url": "/about" } ] } ],
  "options": { "theme": { "primaryColor": "#1e80ff" } },
  "attachments": []
}

阶段二：本地双实例对照修复（手术台）

在同一台机器的容器平台上拉起两个实例，同屏对照：

# 伪命令示意：老站对照 + 新站工作台
container run -d --name blog-old -p 8090:8090 -v ./old-site:/data 旧版本镜像
container run -d --name blog-new -p 8091:8090 -v ./new-site:/data 新版本镜像

执行节奏：

1. 新站先跑一遍官方迁移，得到“全绿但空壳”的基线；
2. 由智能编程助手把四类缺口逐个脚本化修复：
   • 菜单转换：写一个“旧扁平模型 → 新两级模型”的映射脚本，通过新版本的写入接口重放 15 条菜单；
   • 摘要回填：从 JSON 提取每篇的 excerpt，逐篇写回新字段；
   • 封面重建：建立“老附件路径 → 新媒体库地址”映射表，批量回填；
   • 主题设置重放：对键值对做一次键名翻译，再按新主题设置模型写入；
3. 修一轮、对照一轮：老站开左屏、新站开右屏，首页、列表页、详情页、菜单逐像素比对，修到“看不出差别”为止。

# 菜单模型转换伪代码（幂等，可反复重跑）
for group in load_json("old_menus.json"):
    new_group = api.create_menu_group(group["name"])
    for item in group["items"]:
        api.add_menu_item(new_group.id, label=item["label"], url=item["url"])

关键点：修复动作全部脚本化，不落在人工点后台上——一旦需要重来，重跑脚本即可，人的精力只留给验收与决策。

阶段三：整站打包与回迁生产

手术台上修好的站，用系统自带的“整站备份”能力打成一个 599.1MB 的压缩包：数据库 + 610MB 附件 + 主题 + 插件 + 修复后的全部配置，通过局域网直传到 NAS 生产环境（新站环境配置了不间断电源与双盘存储），恢复、冒烟、切流。

若有异地容灾需求，再把备份包归档一份到公有云的对象存储（如百度智能云对象存储），本地与云端各一份，符合 3-2-1 备份原则。

切流时守住 SEO 收录：

# 反向代理层伪配置：老链接 301 到新链接
route("/archives/:slug") -> redirect(301, "/posts/:slug")

• 生成“旧固定链接 → 新固定链接”对照表，在反向代理层统一 301；
• 老站容器不删，降级为只读对照源，保留 30 天观察期再下线；
• 观察搜索引擎抓取与索引恢复情况。

五、20 个高频坑位与解法

数据模型类（结构性差异）

1. 菜单模型重构：扁平转两级，必须“重放”而非“复制”；
2. 分类树层级丢失：父级字段映射错导致树变平铺、面包屑失效，导入后先抽查层级；
3. 封面字段更名：从路径字符串变为媒体库引用，需建映射表批量回填；
4. 摘要策略差异：显式存储与动态截断并存，空白项从导出 JSON 补齐；
5. 作者映射错位：老用户 ID 与新站对不上，文章作者显示异常，需先建用户再迁移内容；
6. 附件标识体系变化：老路径直接照搬会导致引用悬空，统一走媒体库重注册。

内容呈现类

1. 富文本内嵌绝对地址：域名或端口一变，文内图片与链接批量 404，需全量字符串替换；
2. 旧版特有标记语法在新版无对应解析器，渲染异常要提前抽样排查；
3. 自定义页面模板绑定丢失，“关于页”等回落默认模板，需逐页重绑；
4. 侧边栏与小组件配置不迁移，分类、标签云、公告模块需手动重配；
5. 每页 SEO 元数据（标题、描述）缺失，从导出数据单独回填；
6. RSS 输出地址与摘要策略变化，订阅端需要重新对齐。

系统配置类

1. 主题设置整体失效：键名与主题标识强耦合，做一次键名翻译再写入；
2. 固定链接规则变化：老 URL 批量 404，必须提前配好 301；
3. 评论与通知配置缺失：邮件提醒、第三方评论对接要重新验证；
4. 口令哈希算法升级：老口令不能直接复用，账号走重置流程。

环境运维类

1. 时区不一致：UTC 与本地时间差 8 小时，发布日期集体偏移，导入前后统一时区；
2. 端口与反向代理错位：容器内外端口映射、Cookie 作用域要同步调整；
3. 双实例并存时资源冲突：端口、数据卷、内存提前规划，避免互相污染；
4. 切流后不留回退通道：老站应只读保留观察期，而不是立即删除。

六、验收闭环：如何证明“迁移完成”

把验收标准前置写好，迁移才算有终点：

1. 数量核对：文章 176、分类 65、标签 101、评论与附件数量逐一比对；
2. 抽样 diff：随机抽 10 篇文章，正文、摘要、封面、归属分类标签、发布时间逐项与老站比对；
3. 菜单核对：15 条菜单逐条核对文案、链接与层级；
4. 功能回归：登录、评论、站内搜索、附件下载、RSS 输出全过一遍；
5. 死链扫描：全站爬一遍内部链接，目标 0 个 404；
6. 收录保护：抽查若干已被搜索引擎收录的老 URL，逐一验证 301 生效。

七、方法论沉淀

• “迁移完成”的定义权要握在自己手里：绿色进度条只对工具声明负责的部分生效，不对你的站点负责；
• 站点 = 内容 + 配置 + 呈现：工具只保第一项，后两项是真正的工程量；
• 跨大版本只有一条可靠路径：导出 → 转换 → 导入 → 修复 → 验收 → 备份 → 切流；
• 老站是最好的“标准答案”：双实例同屏对照，把验收从“凭感觉”变成“逐像素”；
• 智能编程助手的价值不在“替你迁移”，而在于把重复修复变成幂等脚本，让人专注验收与决策。

之所以敢说“一天内可完成”：内容搬迁交给工具（分钟级）、配置重建交给脚本（小时级）、人只做对照验收与切流决策。想清楚这条分工线，任何一次大版本搬迁都可以按这份作业复现。