Metabase H2 应用数据库故障排查与迁移生产数据库实战指南

Metabase H2 应用数据库故障排查与迁移生产数据库实战指南

【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase

Metabase 默认使用内置的 H2 文件型数据库作为"应用数据库"（app database）来保存用户、问题（Question）、仪表盘等全部元数据。H2 便于本地快速上手，但并不适合生产环境，一旦遭遇文件损坏、迁移失败、Liquibase 锁残留、加载超时等问题，往往会让实例无法正常启动。本文基于仓库中的官方排障文档 docs/troubleshooting-guide/loading-from-h2.md，结合load-from-h2、migrate release-locks等命令的源码实现，系统梳理 H2 应用数据库各类典型故障的识别方法与处置步骤，帮助你准确判断"当前是否在用 H2"、正确完成 H2 → PostgreSQL/MySQL 的迁移，并掌握锁清理、损坏恢复与超时调优的实操手段。

一、先弄清背景：什么是 Metabase 的应用数据库

Metabase 自身运行所需的所有元数据——用户账号、保存的问题、仪表盘、集合、权限设置等——都存放在一个独立的 SQL 数据库中，官方称之为"应用数据库"（application database，简称 app database）。它与你通过 Metabase 连接并分析的业务数据库是两回事：业务库里的数据不受应用数据库故障影响，但应用数据库一旦丢失，你在 Metabase 里积累的全部配置和内容都会随之消失。

默认情况下，Metabase 启动时会自动创建并使用内置的 H2 数据库，即当前目录下的metabase.db.mv.db文件。H2 是纯磁盘文件型数据库，对文件系统错误（如磁盘损坏、文件未能正确落盘）非常敏感，因此官方明确不推荐将其用于生产环境。仓库源码 src/metabase/cmd/load_from_h2.clj 中的注释也印证了这一点：load-from-h2被定位为"从 H2 升级到『真正的』数据库"的工具（"Intended as a tool for upgrading from H2 to a 'real' database"）。

从源码结构看，所有命令行操作都注册在 src/metabase/cmd/core.clj 中，通过java ... -jar metabase.jar <command>或clojure -M:run <command>两种方式触发。本文涉及的两个核心命令定义如下：

• migrate：执行数据库迁移，可选方向包括up、force、down、down-force、print、release-locks；
• load-from-h2：把现有 H2 数据库中的数据转移到由环境变量指定的新 MySQL 或 Postgres 数据库。

二、如何确认自己是否正在使用 H2

根因：许多故障只存在于 H2 场景，因此排障的第一步是确认当前应用数据库类型。

处置步骤：

1. 以管理员身份登录 Metabase，进入Admin Panel（管理面板），打开Tools（工具）标签页，向下滚动到 "Diagnostic Info"（诊断信息），查看其返回的 JSON 中application-database字段的值。
2. 更直接的方式是调用诊断 API。迁移文档 docs/installation-and-operation/migrating-from-h2.md 指出，管理员可调用GET /api/bug-reporting/details，返回结果形如：

{ "application-database": "h2" }

只要该字段不是postgres或mysql，就说明你仍在使用内置 H2 数据库。关于诊断信息的获取与日志查看方式，可进一步参考 docs/troubleshooting-guide/diagnostic-info.md。

3. 若确认是 H2 且实例要用于生产，请参考 docs/installation-and-operation/migrating-from-h2.md 迁移到更健壮的应用数据库；如果打算迁移到 Metabase Cloud，则可参阅 docs/cloud/migrate/guide.md。

三、从 H2 迁移到 PostgreSQL/MySQL 失败：load-from-h2与.mv.db后缀陷阱

根因：你试图用load-from-h2命令把应用数据库从 H2 迁往 PostgreSQL 或 MySQL/MariaDB 等生产级数据库，但传入的数据库文件名有误，导致命令报错，典型报错信息为：

Command failed with exception: Unsupported database file version or invalid file header in file <YOUR FILENAME>

这条报错的产生机制在源码中有明确对应：命令分发入口 src/metabase/cmd/core.clj 的run-cmd会捕获命令执行抛出的异常，并以Command failed with exception: <message>的格式输出；而 src/metabase/cmd/load_from_h2.clj 在解析文件名时会拼接;IFEXISTS=TRUE并交给 src/metabase/cmd/copy/h2.clj 的h2-data-source建立数据源，文件头无法识别时即会抛出上述异常。

处置步骤：

1. 先复制一份导出的 H2 数据库文件留作备份（备份方法见 docs/installation-and-operation/backing-up-metabase-application-data.md）。在完成备份之前不要继续任何操作，以防迁移过程出现意外导致数据丢失。
2. 检查导出的 H2 数据库文件是否名为metabase.db.mv.db。
3. 关键点：H2 会自动为命令行中指定的数据库路径追加.mv.db扩展名。因此传给load-from-h2的路径不能包含.mv.db后缀。这一点在源码 src/metabase/cmd/copy/h2.clj 的add-file-prefix-if-needed中也有体现：它会把以.mv.db结尾的路径去掉扩展名后再使用。例如，要把导出的 H2 数据导入 PostgreSQL，命令应形如：

export MB_DB_TYPE=postgres export MB_DB_DBNAME=metabase export MB_DB_PORT=5432 export MB_DB_USER=<username> export MB_DB_PASS=<password> export MB_DB_HOST=localhost java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar load-from-h2 /path/to/metabase.db # 不要带上 .mv.db

也可使用连接串形式的等价写法（来自 docs/installation-and-operation/migrating-from-h2.md）：

export MB_DB_TYPE=postgres export MB_DB_CONNECTION_URI="jdbc:postgresql://<host>:5432/metabase?user=<username>&password=<password>" java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar load-from-h2 /path/to/metabase.db

迁移到 MySQL 时，还可以用 JVM 参数替代环境变量：

java -DMB_DB_TYPE=mysql -DMB_DB_CONNECTION_URI="jdbc:mysql://<host>:3306/metabase?user=<username>&password=<password>" -jar metabase.jar load-from-h2 metabase.db

重要约束：

• 迁移过程是一次性操作，且整个迁移过程中必须使用同一版本的 Metabase：执行迁移命令的 Metabase 版本、最后一次写入 H2 文件的版本、以及生产环境将要运行的版本必须一致。只有迁移成功后才考虑升级。
• Metabase 期望目标数据库是全新的空库：命令会自动在目标库中创建表结构并把 H2 数据搬进去。
• 迁移完成后，用同样的连接参数（去掉load-from-h2部分）正常启动 Metabase，例如：

export MB_DB_TYPE=postgres export MB_DB_CONNECTION_URI="jdbc:postgresql://<host>:5432/metabase?user=<username>&password=<password>" java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

• 迁移期间应先停掉正在运行的 Metabase 实例，避免迁移过程中产生新数据导致不一致。

迁移时的加密密钥注意点

从源码 src/metabase/cmd/load_from_h2.clj 可以看到，load-from-h2还会检查数据加密状态：

• 如果 H2 数据库是用某个密钥加密的，而当前环境的MB_ENCRYPTION_SECRET_KEY与之一致或未设置，命令会直接报错（The H2 database is encrypted with a different key ...）；
• 如果目标数据未加密，但当前环境设置了MB_ENCRYPTION_SECRET_KEY，迁移过程会自动对落库数据进行加密。

也就是说，迁移 H2 之前若配置过加密密钥，请确保密钥正确。

Docker 容器场景的迁移

如果你是用 Docker 运行的 Metabase，迁移路径为（详见 docs/installation-and-operation/migrating-from-h2.md）：

1. 确认能连接目标应用数据库；
2. 先把 H2 文件从容器中复制出来备份：docker cp metabase:/metabase.db/metabase.db.mv.db ./；
3. 停止现有 Metabase 容器；
4. 在与 H2 文件同目录下放置同版本的 Metabase JAR；
5. 用上述load-from-h2命令执行迁移（迁移完成后进程会自动退出）；
6. 用新应用数据库启动新容器：

docker run -d -p 3000:3000 \ -e "MB_DB_TYPE=postgres" \ -e "MB_DB_DBNAME=<your-postgres-db-name>" \ -e "MB_DB_PORT=5432" \ -e "MB_DB_USER=<db-username>" \ -e "MB_DB_PASS=<db-password>" \ -e "MB_DB_HOST=<your-database-host>" \ --name metabase metabase/metabase

7. 确认 H2 文件已有安全备份后，再移除旧容器。

备选方案：序列化快照

如果你使用的是 Pro 或 Enterprise 版本，可以使用序列化（Serialization）功能为应用数据库做快照。当你希望在新实例中预置问题和仪表盘时，序列化尤其有用。

四、试图降级（Downgrade）：Metabase 不支持

根因：Metabase 不支持降级，即回退到更早的应用版本。如果你在升级后想退回旧版，直接替换版本通常会导致启动失败或数据不兼容。

处置步骤：

1. 关闭 Metabase。
2. 恢复你在升级前为应用数据库制作的备份副本。
3. 恢复你想要回退到的旧版 JAR 文件或旧版容器镜像。
4. 重新启动 Metabase。

这也是"升级前务必备份应用数据库"这一原则的由来，备份操作详见 docs/installation-and-operation/backing-up-metabase-application-data.md。

五、应用数据库被锁：liquibase ... Could not acquire change log lock

根因：Metabase 在启动时会对应用数据库执行 Liquibase 迁移，如果上一次运行异常退出，变更日志锁（change log lock）没有正常释放，下次启动就会失败，报错形如：

liquibase.exception.DatabaseException: liquibase.exception.LockException: Could not acquire change log lock.

处置步骤：

1. 在 Metabase 所在服务器上打开终端，手动释放锁：

java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar migrate release-locks

2. 命令执行完毕后，正常方式重启 Metabase（不要带migrate release-locks参数）。

这一行为在源码中有明确实现：命令入口 src/metabase/cmd/core.clj 中migrate命令支持release-locks方向；在 src/metabase/app_db/setup.clj 中，:release-locks分支会调用liquibase/force-release-locks!强制释放锁。值得注意的是，该文件中的注释提到：现在迁移在事务内执行，锁残留问题通常不应再出现，此命令只是作为兜底手段保留。此外，release-migration-locks!函数体现了超时释放逻辑：进程会先等待一段时间让迁移锁自然释放，超时后才强制清理，这也解释了为什么锁问题大多与异常中断有关。

六、应用数据库损坏：H2 文件修复流程

根因：H2 的可靠性不如生产级数据库管理系统，应用数据库文件本身可能损坏。这会导致应用数据库中的数据丢失，但不会损坏 Metabase 所连接的业务数据库中的数据。

处置步骤：损坏导致的报错信息各异，但多数日志消息会提到h2。一个典型的损坏场景与报错如下（使用 H2 自带的RunScript工具导出 SQL 时）：

myUser@myIp:~$ java --add-opens java.base/java.nio=ALL-UNNAMED -cp metabase.jar org.h2.tools.RunScript -script whatever.sql -url jdbc:h2:~/metabase.db Exception in thread "main" org.h2.jdbc.JdbcSQLException: Row not found when trying to delete from index """"".I37: ( /* key:7864 */ X'5256470012572027c82fc5d2bfb855264ab45f8fec4cf48b0620ccad281d2fe4', 165)" [90112-194] at org.h2.message.DbException.getJdbcSQLException(DbException.java:345) [etc]

如何修复：并非所有 H2 错误都可恢复——这正是官方反复强调"使用 H2 时务必为应用数据库文件制定备份策略"的原因。

如果你运行的是较新版本且使用 H2，应用数据库存放在metabase.db.mv.db。请在 Metabase 实例所在服务器上打开终端，依次执行以下四条命令尝试恢复损坏的 H2 文件：

java -cp metabase.jar org.h2.tools.Recover mv metabase.db.mv.db metabase-old.db.mv.db touch metabase.db.mv.db java --add-opens java.base/java.nio=ALL-UNNAMED -cp target/uberjar/metabase.jar org.h2.tools.RunScript -script metabase.db.h2.sql -url jdbc:h2:`pwd`/metabase.db

各命令的作用：

• 第一条：调用 H2 自带的Recover工具，从损坏文件中尽力抽取数据并生成恢复脚本（通常输出为metabase.db.h2.sql）；
• 第二条：把损坏的原始文件改名保留，防止覆盖；
• 第三条：创建一个全新的空数据库文件；
• 第四条：用RunScript把恢复出的 SQL 脚本灌入新数据库。

恢复是否成功取决于损坏程度，若Recover阶段已无法导出有效数据，则只能依靠备份恢复。此外，仓库中还提供了dump-to-h2命令（src/metabase/cmd/core.clj）用于把当前应用数据库导出为 H2 文件，配合--keep-existing可避免覆盖已有文件，可作为日常备份手段之一。

七、Windows 10 上启动报 "Unable to connect to Metabase DB"

根因：在 Windows 10 的某些环境下，Metabase JAR 需要具备创建本地文件（即应用数据库文件）的权限。直接运行 JAR 时会看到如下报错：

Exception in thread "main" java.lang.AssertionError: Assert failed: Unable to connect to Metabase DB.

处置步骤：

1. 右键点击 Metabase 的 JAR 文件（注意是 JAR 文件本身，不是应用数据库文件）。
2. 选择 "Properties"（属性）。
3. 勾选 "Unblock"（解除锁定）。

这是因为从网络或某些来源下载的文件会被 Windows 标记为"来自其他计算机"，从而阻止其创建本地文件；解除锁定后即可正常写盘。

八、应用数据库加载超时：默认 5 秒限制

根因：使用 H2 作为应用数据库时，如果数据库文件过大，无法在默认的 5 秒超时时间内完成加载，启动控制台会出现 "Timeout" 字样。

处置步骤（按优先级）：

1. 首选：改用 PostgreSQL 等生产级数据库作为应用数据库。这不仅解决加载超时，也从根本上规避 H2 的可靠性问题。
2. 进入Admin Panel，调大应用数据库的超时设置。
3. 将 Metabase 迁移到更快的服务器（尤其是磁盘更快的服务器）。

九、预防优于修复：备份与生产库选型

综合全文可见，围绕 H2 的所有故障几乎都可以归结为一个共同建议：尽早把应用数据库迁移到生产级数据库，并始终保留备份。官方推荐顺序为：

• PostgreSQL（最低版本 14，首选）；
• MySQL（最低版本 8.4.0，需utf8mb4_unicode_ci排序规则、utf8mb4字符集及innodb_large_prefix=ON，这些均为默认值）；
• MariaDB（最低版本 10.6.0，要求同上）。

关于连接配置的完整说明（MB_DB_TYPE、MB_DB_HOST、MB_DB_PORT、MB_DB_DBNAME、MB_DB_USER、MB_DB_PASS、MB_DB_CONNECTION_URI等环境变量）参见 docs/configuring-metabase/environment-variables.md 与 docs/installation-and-operation/configuring-application-database.md。

备份方面：若仍在使用 H2，Docker 场景用docker cp metabase:/metabase.db/metabase.db.mv.db ./导出文件；JAR 场景则停止服务后直接复制metabase.db.mv.db并妥善保管。迁移完成后保留旧 H2 文件作为"保险"也不失为一个好习惯。相关排障总入口可参见 docs/troubleshooting-guide/index.md。

十、故障速查对照表

以上所有结论均以当前仓库中的官方文档与源码实现为依据，涉及的关键文件包括：docs/troubleshooting-guide/loading-from-h2.md、docs/installation-and-operation/migrating-from-h2.md、src/metabase/cmd/load_from_h2.clj、src/metabase/cmd/core.clj、src/metabase/cmd/copy/h2.clj 与 src/metabase/app_db/setup.clj。建议读者在实际操作前，先对照第二小节确认自己的应用数据库类型，再按对应章节逐步处理。

【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase