NAS Docker 升级 Ghost 6:MariaDB 迁移到 MySQL 的排错实录
这次我把群晖 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、内存和磁盘资源并没有完全隔离。这里解决的是误写生产数据和生产文件的问题,不是让测试环境拥有一台独立服务器。
不在失败现场上反复修改
此前曾尝试批量转换旧测试库的排序规则,中途也出现过中断。一度看到部分表已经转换、部分表仍保留旧规则;后续查询时,状态又发生了变化。
这让我意识到,不能拿较早的一张查询结果,推断数据库现在仍然处于同样状态。
后来采用的做法是:
- 保留失败库、失败容器和日志。
- 从已保存的原始 SQL 备份,重新导入一个干净的测试 schema。
- 在新 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,也不执行整套迁移。它只在独立测试库中:
- 用一个新的探针表名生成实际 SQL。
- 创建两列及所需索引。
- 查询新旧四个字段的实际定义。
- 分别执行两条外键语句。
- 从
information_schema核实外键是否真的存在。 - 清理本次创建的探针表。
辅助程序中,查看编译结果的核心形式是:
// 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. 最后的生产切换:根据网站的更新频率做取舍
最初,我准备采用较严格的切换流程:
停止旧站写入
↓
制作新的数据库与内容备份
↓
重新导入候选库
↓
再执行完整迁移
↓
验证后开放新站
这条路线的优点是数据时间点更清楚,代价是需要更长的维护窗口。考虑到本次迁移本身就接近半小时,再加上导入和检查,停机时间会明显增加。
后来,我重新考虑了这个个人博客的实际情况:文章已经很久没有更新,业务并不需要为这次切换追求严格的停写时间点一致性。
当时新的停写备份已经完成,而当天的候选库也已经通过完整迁移、重启和功能抽查。最终选择:
- 取消新库重新导入这条慢路径,先恢复旧站。
- 复用当天已经验证通过的迁移副本。
- 使用停写阶段复制出的独立内容目录。
- 从原生产配置生成新版配置,保留域名、SMTP 和其他设置。
- 使用专用生产数据库账号启动候选容器,先检查本机访问。
- 停止旧容器,将原正式端口交给新版容器。
- 从公网再次检查页面、版本和样本图片。
这样,没有为相同的副本再执行一轮 114 个迁移,也没有改动原来的域名和 Tunnel 配置。
这个简化有适用条件
几个月没有写文章,并不能自动推出数据库完全没有变化。
期间仍可能产生会员注册、登录会话、资料修改、支付回调或设置调整。记录数量相同,也不能证明每一行数据都相同。
所以,这次提升已验证副本的选择,意味着接受较早快照与切换时点之间部分状态的差异。原数据库和新的停写备份仍然保留,便于回查。
对于持续注册会员、接收支付或频繁编辑内容的站点,不能直接照搬这一步。应按业务要求保留停写一致性流程,或采用经过验证的增量同步方案。
这次真正简化的是重复导入和重复迁移,并没有取消备份、关键检查和原环境保留。
12. 演练库升为生产后,必须完成“身份转换”
切换结束后,还有一件容易遗漏的事:之前叫作测试库的数据库,现在已经承载真实流量。
如果仍然保留旧测试账号的写入权限,未来误启动测试容器,就可能出现两个 Ghost 实例同时修改生产数据。
这次因此做了几项收尾:
- 为正式 Ghost 使用专用生产账号。
- 撤销旧测试账号对已提升数据库的权限。
- 停止测试容器,并关闭它们的自动重启。
- 将旧版 Ghost 保留为停止状态,避免重启后争抢正式端口。
- 保留旧 MariaDB、原内容目录和备份。
- 清楚记录当前正在使用的配置、内容目录及 MySQL 数据目录。
尤其要在文档中注明:带有 test、stage 或 candidate 字样的目录和库,一旦被提升为生产,就不能再当临时文件清理。
旧容器还在,不代表是随时可以直接切回的
新站一旦开始接收写入,旧 MariaDB 就不再自动包含这些后续变化。
此时如果只把入口切回旧容器,可能丢掉新库中的数据。
因此,我将“开放新站写入前的回退”和“开放后再回退”分开处理。后者需要先保留当前 MySQL 状态,再判断如何处理新增数据。
保留旧容器提供了恢复基础,但不会自动解决新旧数据库之间的数据差异。
13. 这次我会保留下来的经验
以后再做类似升级,我会先确定这些问题:
- 迁移实际连接的是哪个数据库,而不能根据文件名猜测。
- 新旧实例是否同时隔离数据库和内容目录。
- 字段的实际定义是什么,而不只看数据库默认值。
- 建表工具最终生成了什么 SQL。
- 同一迁移里是否还有第二组、第三组外键。
- 日志中的失败发生在迁移阶段,还是后续服务初始化阶段。
- 检查结果究竟证明了进程、数据库、页面,还是完整业务流程正常。
- 网站的更新频率是否值得为切换增加一轮长时间迁移。
最终,网站运行在 Ghost 6.78.0 和 MySQL 8.4 上,公网首页、后台页面、样本文章和图片检查通过,核心记录数量与切换前一致。
本次没有做真实支付、邮件发送和完整登录流程验证,也仍保留了固定版本下的 MySQL2 配置警告记录。
对我来说,这次升级最有价值的部分,是把“配置看起来正确”推进到“实际 SQL、实际字段和实际约束都得到验证”。弄清这一层之后,后面的切换流程才有条件根据站点规模做简化。