NAS Docker 升级 Ghost 6:MariaDB 迁移到 MySQL 的排错实录

分享
NAS Docker 升级 Ghost 6:MariaDB 迁移到 MySQL 的排错实录
Photo by Sasun Bughdaryan / Unsplash

这次我把群晖 NAS 上的 Ghost 从 6.42.0 升级到了 6.78.0,同时将数据库从 MariaDB 10.11 迁移到 MySQL 8.4。

最终网站恢复正常,原来的文章、会员和后台账号数量也与升级前一致。但过程并不是“换一个 Docker 镜像,再导入 SQL”这么简单。

真正卡住升级的,是一个容易被忽略的问题:旧表和新表看起来都使用 utf8mb4,外键列也都是 varchar(24),但实际排序规则不同,MySQL 仍然拒绝建立外键。

更绕的一点是:我已经把数据库默认排序规则改成了旧表使用的规则,新表却没有按预期继承。

这篇文章记录如何定位这个问题、怎样验证修复,以及最后如何根据个人博客的更新频率,简化生产切换。

文中的域名、路径、库名和账号均为示例,不对应真实部署。代码片段用于解释排查方法,不是一键升级脚本。版本相关结论限定于本文实测环境。

1. 先确认:配置里的 mysql,不一定是 MySQL 服务端

原来的 Ghost 配置中,数据库客户端类型是:

{
  "database": {
    "client": "mysql"
  }
}

但实际连接的是 NAS 上的 MariaDB 套件。

这里的 mysql 表示客户端连接类型,不能据此判断服务端究竟是 Oracle MySQL 还是 MariaDB。应连接数据库后确认:

SELECT VERSION();

我这次同时做了两个变化:

项目 原环境 目标环境
Ghost 6.42.0 6.78.0
数据库服务端 MariaDB 10.11 MySQL 8.4
运行方式 Docker Ghost + NAS 数据库套件 Docker Ghost + Docker MySQL

Ghost 官方将 MySQL 8 列为生产环境支持的数据库,并建议 MariaDB 用户迁移到 MySQL 8。这也是这次调整数据库的背景。Ghost 官方数据库支持说明

但这不意味着把旧库导入 MySQL 后,所有后续迁移就会自动兼容。旧库保留下来的字段定义,仍然需要检查。

2. 第一条线索:外键字段“不兼容”

新版 Ghost 启动后进入数据库迁移,随后退出。关键错误是:

ER_FK_INCOMPATIBLE_COLUMNS
errno: 3780

Referencing column 'member_id' and referenced column 'id'
are incompatible.

出问题的迁移要创建:

members_current_subscription

最初日志只暴露了这一组关系:

members_current_subscription.member_id
    → members.id

继续检查迁移源码后,发现同一张表还有第二组外键:

members_current_subscription.subscription_id
    → members_stripe_customers_subscriptions.id

因此,排查范围不能只停留在 members.id。两组关系都需要检查。

不能只看 varchar(24)

这次两个父表的 id 都是:

varchar(24)
utf8mb4
utf8mb4_general_ci
NOT NULL
PRIMARY KEY

而新迁移中的两个字段,同样定义为长度 24 的字符串。

不过,对于非二进制字符串外键,MySQL 要求两端的字符集和排序规则一致。只看到类型、长度相同,还不足以判断兼容。MySQL 外键约束要求

我用下面这类查询检查实际定义:

-- 先确认连接的是独立测试库。
SELECT DATABASE();

SELECT
    TABLE_NAME,
    COLUMN_NAME,
    COLUMN_TYPE,
    CHARACTER_SET_NAME,
    COLLATION_NAME,
    IS_NULLABLE,
    COLUMN_KEY
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
  AND (
    (
      TABLE_NAME IN (
        'members',
        'members_stripe_customers_subscriptions'
      )
      AND COLUMN_NAME = 'id'
    )
    OR
    (
      TABLE_NAME = 'members_current_subscription'
      AND COLUMN_NAME IN ('member_id', 'subscription_id')
    )
  );

这里有一个实际困难:迁移失败后,Ghost 可能已经回滚并删除新表。此时查询不到子表字段,并不能证明子表定义没有问题。

这也是后面需要单独做建表探针的原因。

3. 在继续试错之前,先把数据库和内容目录一起隔离

早期尝试中,新旧 Ghost 虽然连接了不同数据库,却曾经挂载同一个 content 目录。

这仍然不能算是完整的测试隔离。

Ghost 的内容目录除了图片和主题,还可能包含日志、导出文件、缓存或其他运行数据。新版启动、迁移或主题初始化时,都可能写入它。

后来我把结构调整为:

原生产环境
  旧 Ghost
  ├── 原 MariaDB
  └── 原 content 目录

升级验证环境
  新 Ghost
  ├── 独立 MySQL schema
  ├── 独立 content 副本
  ├── 独立配置与数据库账号
  └── 独立访问入口

数据库和内容目录都独立后,才有条件放心验证迁移。

需要注意,独立 schema 仍可能共用同一个 MySQL 实例,所以 CPU、内存和磁盘资源并没有完全隔离。这里解决的是误写生产数据和生产文件的问题,不是让测试环境拥有一台独立服务器。

不在失败现场上反复修改

此前曾尝试批量转换旧测试库的排序规则,中途也出现过中断。一度看到部分表已经转换、部分表仍保留旧规则;后续查询时,状态又发生了变化。

这让我意识到,不能拿较早的一张查询结果,推断数据库现在仍然处于同样状态。

后来采用的做法是:

  1. 保留失败库、失败容器和日志。
  2. 从已保存的原始 SQL 备份,重新导入一个干净的测试 schema。
  3. 在新 schema 中复现问题,不继续修改原失败现场。

这样每次验证都有清楚的起点,不会把先前的修改结果误认为修复本身有效。

4. 最容易误判的一步:数据库默认 general_ci,新表为什么还是 0900?

我最初的判断是:旧表使用 utf8mb4_general_ci,只要让测试数据库默认也使用它,新表就会继承相同规则。

例如:

CREATE DATABASE ghost_candidate
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_general_ci;

这个判断少考虑了一层:Ghost 交给数据库的最终建表 SQL,可能已经显式指定了字符集。

实际调用链

在本次 Ghost 镜像中,调用路径可以概括为:

迁移文件中的 addTable
    ↓
Ghost schema commands.createTable
    ↓
Knex TableBuilder / MySQL TableCompiler
    ↓
实际 CREATE TABLE 与 ALTER TABLE SQL
    ↓
MySQL 创建字段并检查外键

迁移文件本身没有显式指定排序规则。字段生成工具把这两列交给了类似下面的调用:

tableBuilder.string(columnName, 24);

但 Ghost 的 MySQL2 配置处理会设置:

connection.charset = utf8mb4

本次使用的 Knex 3.3.0 在编译 MySQL 建表 SQL 时,会读取连接配置中的字符集和排序规则。逻辑可简化为:

建表 charset:优先表级设置,其次连接配置
建表 collate:优先表级设置,其次连接配置

于是,实际生成的 SQL 不要完全省略字符集的建表语句,而应该是:

CREATE TABLE ghost_fk_probe (
    member_id VARCHAR(24) NOT NULL,
    subscription_id VARCHAR(24) NOT NULL,
    PRIMARY KEY (member_id)
) DEFAULT CHARACTER SET utf8mb4;

注意最后只有字符集,没有 COLLATE。

显式字符集改变了默认值的选择路径

MySQL 的规则是:建表时指定 CHARACTER SET 而省略 COLLATE,会选择该字符集的默认排序规则;只有表级相关选项都未指定时,才按数据库默认值继承。MySQL 表字符集与排序规则

这次实例中的实际值是:

检查项 实际值
数据库默认排序规则 utf8mb4_general_ci
连接会话排序规则 utf8mb4_general_ci
default_collation_for_utf8mb4 utf8mb4_0900_ai_ci
新建探针列的实际排序规则 utf8mb4_0900_ai_ci

也就是说:

数据库默认 general_ci、会话默认 general_ci,都没有阻止这条带显式字符集的 SQL 建出 0900 列。

这就是为什么只执行 ALTER DATABASE ... COLLATE ...,没有解决这次问题。

它改变的是数据库默认值,也不会自动重写现有表和列。

5. 不能只靠推测,要用实际建表工具验证两组外键

弄清调用链后,我没有直接改生产表,也没有再次对全部旧表做批量转换。

验证方法是:使用同一个固定版本的 Ghost 镜像,单独运行 Node 辅助程序,加载实际的 Ghost 建表工具和迁移字段定义。

辅助程序不启动完整 Ghost,也不执行整套迁移。它只在独立测试库中:

  1. 用一个新的探针表名生成实际 SQL。
  2. 创建两列及所需索引。
  3. 查询新旧四个字段的实际定义。
  4. 分别执行两条外键语句。
  5. 从 information_schema 核实外键是否真的存在。
  6. 清理本次创建的探针表。

辅助程序中,查看编译结果的核心形式是:

// commands、knex 和 migrationSpec 来自目标版本的实际模块。
// probeTable 必须是独立测试库中尚不存在的新表名。
const builder = commands.createTable(probeTable, knex, migrationSpec);
const statements = builder.toSQL();

console.log(statements.map(statement => statement.sql));

这里的 toSQL() 只编译,不执行。看到预期 SQL 之后,仍需要在隔离库实际执行,并检查最终字段和外键;仅凭打印结果不能证明 MySQL 会接受它。
整个验证保持 foreign_key_checks=1,没有关闭外键检查来绕过错误。

探针引用的是测试库中的真实父表,避免只用两个手写演示表,漏掉实际字段属性差异。

第一次验证结果很明确:

外键关系 子列排序规则 父列排序规则 结果
member_id → members.id 0900_ai_ci general_ci 3780
subscription_id → 订阅表.id 0900_ai_ci general_ci 3780

两组外键都会失败。第一条报错,并不代表第二条关系没有问题。

6. 本次成功的配置,以及驱动警告

这次采用的办法,是在独立配置中显式加入:

database.connection.collate = utf8mb4_general_ci

配置片段如下,所有值均为示例:

{
  "database": {
    "client": "mysql",
    "connection": {
      "host": "mysql-service",
      "port": 3306,
      "database": "ghost_candidate",
      "user": "ghost_app",
      "password": "<replace-with-your-own-secret>",
      "charset": "utf8mb4",
      "collate": "utf8mb4_general_ci"
    }
  }
}

这只是 database 配置片段,不能用它覆盖整个生产配置文件。 原来的 URL、SMTP、发件人、隐私选项和其他设置都需要保留。

修改后,用同一套实际工具生成的 SQL 变成了:

CREATE TABLE ghost_fk_probe (
    member_id VARCHAR(24) NOT NULL,
    subscription_id VARCHAR(24) NOT NULL,
    PRIMARY KEY (member_id)
) DEFAULT CHARACTER SET utf8mb4
  COLLATE utf8mb4_general_ci;

再次检查,四个相关字段的字符集和排序规则一致,两条外键都实际创建成功。

这个前后对比很重要:没有改父表,没有转换整个数据库,改变的是新表 SQL 中明确写出的排序规则。

这不是一个可以隐藏警告的“万能修复”

本次配置同时产生了 MySQL2 的提示:

Ignoring invalid configuration option passed to Connection: collate

原因在于:Knex 使用了这个属性生成 DDL,但它也被传给 MySQL2;当前驱动将其视为未知配置项,发出警告后继续运行,并提示未来版本可能报错。

因此,我对结果的表述是:

它在本次固定 Ghost、Knex 和 MySQL2 版本组合中通过了验证,但不能把它包装成跨版本通用的官方配置。

这次生产最终沿用了这个经过演练的配置,并固定镜像。以后更换镜像或驱动,仍需要重新验证。

对于长期维护方案,还应结合目标版本的官方文档,在独立副本中评估排序规则归一化。Ghost 官方文档也提供了向 utf8mb4_0900_ai_ci 统一的 MySQL 5 升级方案;那与本文保留旧规则的处理路径不同,不能未经验证就混用。

7. 迁移锁报错,不等于“删掉锁就能继续”

在失败现场中,还出现过:

MigrationsAreLockedError

这时最不应该做的,就是看到 locked=1 便直接删除锁记录。

需要先确认:

  • 是否还有迁移进程在运行。
  • 是否有多个 Ghost 实例连接同一库。
  • 上一次迁移已经执行到哪一步。
  • 新表、列、索引和迁移历史是否处于一致状态。

我的处理是保留原失败库,让干净测试库从原备份重新开始。干净库里的锁原本就是释放状态,不需要手工清锁。

两组外键验证通过后,再启动完整 Ghost 迁移。

本次最终执行了 114 个增量迁移文件,数据库从原来的 81 张表,变成了 104 张基础表和 1 个视图。

这台设备上的迁移耗时接近半小时。有些迁移文件包含多次建表或重建表操作,所以“已完成迁移文件数”可能长时间不变,但日志仍持续推进。

我主要看迁移日志、数据库活动和后续结果,没有因为计数暂时不动就中断容器。

8. 数据库迁移完成,应用仍可能启动失败

这次还有一个很容易混淆的节点。

所有增量迁移已经完成,数据库锁也已释放,但 Ghost 随后在初始化业务服务时退出。关键错误是:

Cannot run Ghost without SSL when Stripe is connected.

原因是:克隆库保留了 Stripe 连接设置,而我最初给隔离站点配置的是 HTTP 地址。

检查对应版本的成员服务初始化代码后,确认这个组合会触发 HTTPS 要求。

因此,这次故障要分成两层:

层次 当时的实际状态
数据库迁移 已完成
迁移锁 已释放
Ghost 业务服务初始化 因测试 URL 的 HTTP 配置失败

我没有重新导入数据库,也没有再执行一轮迁移,而是给隔离站点增加真实的 HTTPS 测试入口,再次启动。

Ghost 随后直接报告数据库就绪,没有重跑迁移。

这一步让我更重视日志中的阶段区别:“容器退出”不一定意味着数据库迁移没有成功。

9. 群晖 Docker 的端口和网络,也要实际验证

隔离环境使用了内部 Docker 网络,用来限制 Ghost 应用直接外连。测试入口则通过独立的 HTTPS 代理提供。

在本次群晖环境中,出现过一种情况:容器创建配置里明明写着端口映射,但连接实际失败,运行时也没有形成预期的端口发布。

最后采用的测试结构是:

NAS 本机测试入口
    ↓
HTTPS 代理
    ├── 独立入口网络
    └── 内部测试网络
            ├── Ghost
            └── MySQL

只有代理连接入口网络,Ghost 应用仍保留在内部网络中;测试入口仅绑定本机地址,没有接入正式域名。

这是本次环境的实测处理方式,不应扩展成“所有 Docker internal 网络的端口行为都完全一样”。

排查时,需要同时看创建配置、实际运行状态和真实连接结果。Docker 的端口发布地址也应显式检查,避免原本只打算本机访问的测试服务被发布到所有接口。Docker 端口发布说明

另外,连接内部和普通网络的代理本身可能具有外连能力。不能因为应用网络叫作 internal,就宣称所有组件都完全无法出网。Docker Compose 网络说明

隔离造成的外部调用失败,要与迁移失败区分

测试期间,Stripe 外连和部分远程图片尺寸探测失败过。首页也因此出现过数秒的等待。

这使一个过短的首页探测超时看起来像“服务没启动”。

后来我用不依赖文章图片的后台页面判断启动是否就绪,再单独给首页更长的检查时间。

但这也不能反过来解释成“所有错误都可以忽略”:

  • 数据库迁移要单独验证。
  • 本地图片服务要实际取回文件检查。
  • 远程图片、支付和邮件,要作为另外的功能范围确认。

10. 我如何确认迁移真的完成

“Docker 显示 running”只是进程状态,不能单独作为升级成功的依据。

这次验收包含了以下几层:

层次 验证方法
实际版本 在容器内读取正在使用的 Ghost package.json
迁移状态 调用该版本的 KnexMigrator.isDatabaseOK()
迁移锁 确认已经释放
外键 查询两条正式外键、引用目标和 CASCADE 规则
字段 核对四个相关列的类型、字符集、排序规则及索引
核心数据 对照升级前的文章、会员、后台用户记录数
HTTP 服务 检查首页、后台页面和样本公开文章
文件服务 请求样本本地图片,并对比 SHA256
再次启动 正常重启后直接进入 ready,未重复执行迁移

其中 isDatabaseOK() 是本次版本内部使用的检查方法,调用路径应以所用版本源码为准,不应当作永远稳定的外部运维 API。

图片校验可以用这类方法辅助完成:

# 下列文件名仅为示例。
sha256sum local-image.jpg
sha256sum downloaded-image.jpg

哈希相同,证明的是该样本的响应字节与源文件一致,不代表所有图片、页面布局和远程图片都已经通过验证。

同样,后台登录页返回 200,不等于已经完成后台登录;会员数量没变,也不等于会员登录、邮件投递和支付流程全部正常。

这些范围需要分别记录。

11. 最后的生产切换:根据网站的更新频率做取舍

最初,我准备采用较严格的切换流程:

停止旧站写入
    ↓
制作新的数据库与内容备份
    ↓
重新导入候选库
    ↓
再执行完整迁移
    ↓
验证后开放新站

这条路线的优点是数据时间点更清楚,代价是需要更长的维护窗口。考虑到本次迁移本身就接近半小时,再加上导入和检查,停机时间会明显增加。

后来,我重新考虑了这个个人博客的实际情况:文章已经很久没有更新,业务并不需要为这次切换追求严格的停写时间点一致性。

当时新的停写备份已经完成,而当天的候选库也已经通过完整迁移、重启和功能抽查。最终选择:

  1. 取消新库重新导入这条慢路径,先恢复旧站。
  2. 复用当天已经验证通过的迁移副本。
  3. 使用停写阶段复制出的独立内容目录。
  4. 从原生产配置生成新版配置,保留域名、SMTP 和其他设置。
  5. 使用专用生产数据库账号启动候选容器,先检查本机访问。
  6. 停止旧容器,将原正式端口交给新版容器。
  7. 从公网再次检查页面、版本和样本图片。

这样,没有为相同的副本再执行一轮 114 个迁移,也没有改动原来的域名和 Tunnel 配置。

这个简化有适用条件

几个月没有写文章,并不能自动推出数据库完全没有变化。

期间仍可能产生会员注册、登录会话、资料修改、支付回调或设置调整。记录数量相同,也不能证明每一行数据都相同。

所以,这次提升已验证副本的选择,意味着接受较早快照与切换时点之间部分状态的差异。原数据库和新的停写备份仍然保留,便于回查。

对于持续注册会员、接收支付或频繁编辑内容的站点,不能直接照搬这一步。应按业务要求保留停写一致性流程,或采用经过验证的增量同步方案。

这次真正简化的是重复导入和重复迁移,并没有取消备份、关键检查和原环境保留。

12. 演练库升为生产后,必须完成“身份转换”

切换结束后,还有一件容易遗漏的事:之前叫作测试库的数据库,现在已经承载真实流量。

如果仍然保留旧测试账号的写入权限,未来误启动测试容器,就可能出现两个 Ghost 实例同时修改生产数据。

这次因此做了几项收尾:

  • 为正式 Ghost 使用专用生产账号。
  • 撤销旧测试账号对已提升数据库的权限。
  • 停止测试容器,并关闭它们的自动重启。
  • 将旧版 Ghost 保留为停止状态,避免重启后争抢正式端口。
  • 保留旧 MariaDB、原内容目录和备份。
  • 清楚记录当前正在使用的配置、内容目录及 MySQL 数据目录。

尤其要在文档中注明:带有 test、stage 或 candidate 字样的目录和库,一旦被提升为生产,就不能再当临时文件清理。

旧容器还在,不代表是随时可以直接切回的

新站一旦开始接收写入,旧 MariaDB 就不再自动包含这些后续变化。

此时如果只把入口切回旧容器,可能丢掉新库中的数据。

因此,我将“开放新站写入前的回退”和“开放后再回退”分开处理。后者需要先保留当前 MySQL 状态,再判断如何处理新增数据。

保留旧容器提供了恢复基础,但不会自动解决新旧数据库之间的数据差异。

13. 这次我会保留下来的经验

以后再做类似升级,我会先确定这些问题:

  • 迁移实际连接的是哪个数据库,而不能根据文件名猜测。
  • 新旧实例是否同时隔离数据库和内容目录。
  • 字段的实际定义是什么,而不只看数据库默认值。
  • 建表工具最终生成了什么 SQL。
  • 同一迁移里是否还有第二组、第三组外键。
  • 日志中的失败发生在迁移阶段,还是后续服务初始化阶段。
  • 检查结果究竟证明了进程、数据库、页面,还是完整业务流程正常。
  • 网站的更新频率是否值得为切换增加一轮长时间迁移。

最终,网站运行在 Ghost 6.78.0 和 MySQL 8.4 上,公网首页、后台页面、样本文章和图片检查通过,核心记录数量与切换前一致。

本次没有做真实支付、邮件发送和完整登录流程验证,也仍保留了固定版本下的 MySQL2 配置警告记录。

对我来说,这次升级最有价值的部分,是把“配置看起来正确”推进到“实际 SQL、实际字段和实际约束都得到验证”。弄清这一层之后,后面的切换流程才有条件根据站点规模做简化。

阅读更多

为了平凡的生活

为了平凡的生活

为了翻拣垃圾的孩子,和他们的梦想。 为了那些枯萎的树木, 为了那些如纸牌般倒塌的危楼。 为了那些安眠药, 和那些漫长而失眠的夜晚。 为了那些被困在原地的人, 为了改变那些腐朽而停滞的头脑。 为了那些被加速的人生, 为了恐慌,焦虑,和没有尽头的比较。 为了那些被迫接受的规则, 为了那些被强加的指令, 为了那些看不见的手, 我们成长, 成功, 不断向前。 加速学习, 加速工作, 加速赚钱, 加速消费, 加速体验, 加速衰老。 好像停下来, 就会落在后面。 我想慢下来。 想要一份普通的工作, 不用害怕失去。 想让孩子好好长大, 让老人慢慢变老。 想在傍晚回家, 吃一顿晚饭。 想让夜晚只是夜晚, 而不是焦虑、失眠和安眠药。 想让树长在那里, 而不是倒在推土机经过的地方。 想让房子能够站得住, 住进去,可以安心睡觉。 想让一个人活着, 不需要不停证明自己活得有价值。 我们曾经以为, 生活应该越来越精彩。 后来发现, 真正难得的是它能够保持正常。 没有突然坍塌的房子, 没有突然失去的工作, 没有突然降临的疾病,