企业官网建设流程全解析

Metabase 自托管迁移至 Metabase Cloud 全流程实战（Metabase 49 及以下版本）

【免费下载链接】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 官方迁移指南 guide-pre-50.md 为核心，面向运行 Metabase 49 及以下版本的自托管用户，系统讲解如何把现有实例（含全部问题、仪表盘、用户与设置）平滑迁移到 Metabase Cloud。读完本文，你将掌握迁移前的环境检查与备份要领、Store 迁移脚本的执行细节（JAR / Docker / Heroku 三种部署形态）、迁移后的 SSO 与嵌入配置收尾，并理解迁移脚本背后的应用数据库快照机制在仓库源码中的实现依据。

适用前提：如果你运行的是 Metabase 50 及以上版本，请直接参考新版迁移指南 guide.md（新版流程已内嵌到 Metabase 管理界面，无需在 Store 执行脚本）；若希望从 Metabase Cloud 迁回自托管，可参考 cloud-to-self-hosted.md。

迁移原理：为什么一切数据都能“原样带走”

Metabase 的运行时数据（问题、仪表盘、集合、用户、权限、设置项等）全部存放在单一的应用数据库（Application Database）中，而不是散落在多个文件里。这一点在 backing-up-metabase-application-data.md 中有明确说明：“Metabase 使用单个 SQL 数据库保存所有运行时应用数据”。因此，迁移的本质就是把应用数据库的数据完整上传到 Metabase Cloud 的新实例，这正是旧版迁移脚本所做的工作。

从仓库源码可以印证这一机制：cloud_migration/settings.clj 中定义了migration-dump-file（迁移 dump 文件）与migration-dump-version（迁移 dump 对应的 Metabase 版本号）两个内部设置，其中migration-dump-version的注释明确指出“This will cause the restore to fail on cloud unless you also setmigration-dump-fileto a dump from that version”，说明迁移上传的内容本质上是带版本标识的应用数据库快照，Metabase Cloud 端会按版本还原该快照。同时，该文件还定义了read-only-mode设置，注释说明它是“Boolean indicating whether a Metabase instance is in read-only mode with regards to its app db”，即迁移期间实例进入只读模式的开关——这解释了为什么旧版指南要求你在迁移前彻底关闭自托管实例。

迁移前准备

了解 Metabase Cloud 的局限

迁移前应通读 limitations.md，确认现有部署不依赖以下受限能力，否则迁移后功能会受影响：

确认访问权限与环境

执行迁移需要两个前提：

1. Shell 访问权限：能够登录到自托管 Metabase 所在服务器（JAR 进程或 Docker 容器所在主机）。
2. 外网访问：自托管环境需要能够访问互联网，以便下载迁移脚本并上传应用数据。

预留停机窗口

迁移期间实例不可用，应提前通知用户并尽量安排在非工作时间。旧版迁移流程通常不超过 15 分钟。

关闭自托管 Metabase 实例

在生成快照之前，必须彻底停止 Metabase：

• JAR 部署：停止 JAR 进程（CTRL-C、关闭终端，或停止对应 systemd 等服务）。
• Docker 部署：停止对应容器。

这样做的目的是防止用户在迁移期间继续创建问题或仪表盘，导致实例与应用数据库快照处于不一致状态。

备份应用数据库

为防万一，迁移前务必备份应用数据库，详见 backing-up-metabase-application-data.md。该文档给出的几种备份方式可直接复用：

• H2 默认库 + Docker：docker cp metabase:/metabase.db/metabase.db.mv.db ./
• H2 默认库 + JAR：停止进程后直接复制metabase.db.mv.db文件妥善保管
• 自托管 PostgreSQL：使用pg_dump等 PostgreSQL 官方备份方式
• Amazon RDS：建议开启 RDS 自动备份

正式迁移：从 Metabase Store 发起

第一步：创建 Metabase Cloud 实例

如果还没有 Metabase Cloud 实例，先在 Metabase Store 注册一个14 天免费试用实例作为迁移目标；已有实例可直接跳过本步。

第二步：在 Store 中发起迁移并获取脚本

登录 Metabase Store 账户，点击Initiate Migration。系统会根据你的部署形态生成一条迁移命令，用于下载并执行迁移脚本：

• Metabase JAR：一条命令；
• Docker：另一条命令（通常直接复用当前容器的环境变量）。

第三步：按部署形态设置应用数据库环境变量

执行迁移脚本前，需要让脚本能够访问你的应用数据库。不同部署形态的做法不同：

MB_DB_CONNECTION_URI是 JDBC 风格的连接 URI，在 environment-variables.md 中有完整说明：它可替代MB_DB_HOST等大部分MB_DB_*变量，尤其适用于需要携带特定连接字符串参数的场景；连接类型要求与MB_DB_TYPE一致。你也可以使用MB_DB_TYPE、MB_DB_HOST、MB_DB_PORT、MB_DB_DBNAME、MB_DB_USER、MB_DB_PASS等变量组合来指定应用数据库连接，例如参考 migrating-from-h2.md 中的完整示例：

export MB_DB_TYPE=postgres export MB_DB_CONNECTION_URI="jdbc:postgresql://<host>:5432/metabase?user=<username>&password=<password>" migration_script.sh

第四步：在自托管环境中执行迁移脚本

重要警告：如果你已经在 Metabase Cloud 试用实例中创建了任何问题或仪表盘，上传自托管应用数据后，这些内容会被覆盖。因此建议迁移前保持云端实例为空。

脚本会将自托管实例的应用数据上传到新的 Metabase Cloud 实例。一切顺利时，脚本会输出Done!。若中途出错，按脚本提示逐步处理；仍无法解决时，可向 Metabase 官方支持求助排查。

Heroku 部署的特殊步骤

Heroku 属于托管平台，无法直接登录服务器，需要借助 heroku.md 的补充流程：

1. 安装 Heroku CLI，通过heroku ps:exec --app your-metabase-app-name-in-heroku（替换为你的应用名）使用 SSH 隧道（Heroku Exec）进入运行 Metabase 的 dyno；首次执行可能需要重启 dyno（输入y确认）。
2. 设置MB_DB_CONNECTION_URI：在 Heroku 应用的Settings → Config Vars中复制DATABASE_URL，然后在 Shell 中执行：

export MB_DB_CONNECTION_URI=YOUR_DATABASE_URL_GOES_HERE

3. 执行迁移脚本：在同一个 Shell 会话中运行：

curl -s long-metabase-migration-script-url | bash

迁移后的收尾工作

上传成功后，Metabase Cloud 会在几分钟内自动完成收尾与重启，届时即可登录新实例，所有问题与仪表盘应与原自托管实例完全一致。接下来还需处理以下事项：

更新 SSO 相关配置

• Google Sign-in 用户：登录 Google Developers Console，将新的 Metabase Cloud URL 添加到 Google Auth Client ID 的Authorized JavaScript Origins中。
• 使用 SAML SSO 的 Pro/Enterprise 客户：需要到身份提供商（IdP）处更新Redirect URL与Base URL为新的 Metabase Cloud URL，否则 IdP 仍会把用户重定向到已关闭的旧实例。具体配置参考 authenticating-with-saml.md。

告知团队新的访问地址

确认一切正常后，将新的 Metabase Cloud URL 告知团队成员；用户可像往常一样登录并继续工作。如果 Metabase 被嵌入到应用中，务必同步更新代码中的 URL。

清理旧的托管服务

如果你是通过第三方服务自托管的，记得取消相关订阅与存储资源（例如旧备份占用的存储），避免产生不必要的费用。

迁移期间与之后的只读与版本行为

从仓库源码看，新版迁移流程（Metabase 50+）会在实例内部先进入read-only-mode只读模式（定义于 cloud_migration/settings.clj），迁移期间用户仍可查看问题与仪表盘，但不能新建内容；而本指南针对的旧版本（v49 及以下）则通过“直接关闭实例”达到同等目的。此外在版本处理上（详见新版指南 guide.md）：若 Metabase Cloud 当前版本高于你的自托管版本，迁移后会自动升级；若云端默认版本等于或低于你的版本，则保持原有版本。

常见问题

• 迁移脚本在哪获取？登录 Metabase Store 账户，点击Initiate Migration后按部署形态（JAR / Docker / Heroku）获取对应命令。
• 迁移需要多长时间？通常不超过 15 分钟，建议安排在非工作时间。
• 迁移失败怎么办？按脚本输出的提示逐步排查；确认MB_DB_CONNECTION_URI等连接变量无误，且自托管环境能正常访问外网。仍无法解决时联系 Metabase 官方支持。
• 迁移前忘了备份？强烈建议按备份指南先完成备份再执行迁移，以防意外导致数据丢失。

【免费下载链接】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