远程同步

概述

远程同步允许您在开发 Metabase 的一个集合中开发分析内容，并通过 Git 自动将其部署到只读的生产 Metabase。

远程同步仅同步您的仪表板、问题和模型—不包括您的数据或查询结果。 存储在 Git 中的是描述您分析内容的 YAML 文件。您的实际数据保留在数据库中，绝不会发送到 GitHub。

远程同步的工作原理

这是一个基本的远程同步工作流程

1. 在一个配置为读写模式的 Metabase 中创建一个仪表板。
2. 将其推送到 Git 分支。
3. 打开一个拉取请求以供审查。
4. 将 PR 合并到生产环境。
5. 您的配置为只读模式的 Metabase 会自动拉取更改。

我们将介绍设置远程同步、一个开发到生产的工作流程示例、分支管理以及其他一些零碎问题。

关键概念

远程同步有两种模式，适用于不同的角色:

• 读写模式：创建和编辑内容。您可以将更改推送到和从您的存储库拉取更改。多个 Metabase 实例可以以读写模式连接，每个实例在不同的分支上工作。
• 只读模式：为用户提供只读内容。只读实例仅拉取更改（通常是从您的主分支），并且不允许直接编辑同步的内容。您可以设置自动同步，每五分钟自动拉取一次已批准的更改。

仅跟踪同步的集合：连接到远程同步的每个 Metabase 都有一个特殊的与 Git 同步的集合。当您以读写模式连接时，Metabase 会创建一个名为“Synced Collection”（您可以重命名）的集合。此集合内的所有内容（包括子集合）都将进行版本控制并与您的存储库同步。

同步的集合必须是独立的：仪表板或问题所需的一切都必须在同步的集合内。同步集合外的内​​容不会同步到您的存储库或出现在其他 Metabase 实例中。

内容存储为 YAML 文件：远程同步将您的内容存储为 Git 存储库中的 YAML 文件。每个仪表板、问题、模型和文档都成为一个 YAML 文件，可以像代码一样在拉取请求中进行审查和版本控制。

远程同步不包括表元数据：列类型、描述和可见性设置不会同步。如果您需要版本化表元数据，请改用序列化。

设置远程同步

您需要是管理员才能设置远程同步。

1. 设置一个存储内容的存储库
2. 为开发创建个人访问令牌
3. 将您的开发 Metabase 连接到您的存储库
4. 将一个项目添加到您的同步集合
5. 将您的更改推送到您的存储库
6. 为生产创建个人访问令牌
7. 将您的生产 Metabase 连接到您的存储库

1. 设置一个存储内容的存储库

在将 Metabase 连接到 Git 存储库之前，请创建一个新的 GitHub 存储库。使用 README.md 初始化存储库。

2. 为开发创建个人访问令牌

为您的存储库创建一个 GitHub 精细化个人访问令牌，并具有以下权限

• 内容： 读写
• 元数据： 只读（必需）

生成后立即复制令牌。

3. 将您的开发 Metabase 连接到您的存储库

您可以将任何 Metabase 置于读写模式。我们还提供开发实例，您可用于远程同步或其他任何开发。

在您用于开发的 Metabase 实例中

1. 转到管理员设置 > 设置 > 远程同步。

2. 输入您的存储库 URL

   • 例如，https://github.com/your-org/your-repo。存储库必须已存在并至少包含一次提交。

3. 选择读写模式。

4. 添加您的访问令牌

   • 粘贴您之前创建的个人访问令牌（PAT）。确保令牌具有读写权限。Metabase 会在存储之前加密您的令牌。

5. 保存并测试连接

   • 点击“保存更改”。Metabase 将检查它是否可以访问您的存储库。如果连接失败，请确保您的令牌具有适当的权限且未过期。如果您复制令牌不正确，请生成一个新令牌。

4. 将一个项目添加到您的同步集合

当您首次以读写模式连接时，Metabase 会自动创建一个名为“Synced Collection”的同步集合—您添加到其中的任何内容都将被跟踪在 Git 中，并可以推送到您的存储库。

如果您愿意，可以重命名同步集合，并且可以在其中添加子集合来组织您的内容。

1. 在您的同步集合部分（在左侧边栏中查找）导航到“Synced Collection”。

2. 创建或移动内容到同步集合

   • 创建新内容： 点击“新建”并选择一个仪表板、问题或文档。将其保存到同步集合。
   • 移动现有内容： 将项目从其他集合拖放到同步集合，或使用项目菜单中的移动选项。

请记住，同步的集合必须是独立的。

5. 将您的更改推送到您的存储库

添加内容后，您将在同步集合上看到一个黄点，表示未提交的更改。

1. 点击左侧边栏同步集合旁边的向上箭头（推送）图标。

2. 输入一个描述性提交消息，说明您的更改（例如，“添加关于猛犸象种群的仪表板”）。

3. 点击“继续”以提交您的更改并推送到您的存储库。

检查您的存储库 — 您应该会看到该集合。

关于分支： 默认情况下，您正在推送到存储库的主分支。但是，您可以选择将开发工作推送到哪个分支，从而允许您在合并到生产 Metabase 拉取的分支之前打开拉取请求以供审查。有关创建和切换分支的详细信息，请参阅分支管理。

6. 为生产创建个人访问令牌

为您的存储库创建一个 GitHub 精细化个人访问令牌，并具有以下权限

• 内容： 只读
• 元数据： 只读（必需）

生成后立即复制令牌 — 您需要将其粘贴到您的生产 Metabase 中。

7. 将您的生产 Metabase 连接到您的存储库

在您的生产 Metabase 实例中

1. 转到管理员设置 > 设置 > 远程同步。

2. 输入您的存储库 URL

   • 使用与您的开发 Metabase 相同的存储库，例如，https://github.com/your-org/your-repo。

3. 选择只读模式。

4. 添加您的访问令牌

   • 粘贴您为该生产 Metabase 创建的只读个人访问令牌。

5. 保存并测试连接

   • 点击“保存更改”。Metabase 将验证它是否可以访问您的存储库。如果连接失败，请验证您的令牌是否具有适当的权限且未过期。

6. 同步您的内容

   • 点击“拉取更改”以立即从您的存储库同步内容。
   • 要使您的生产实例保持自动更新，请打开“与 Git 自动同步”开关。Metabase 将每五分钟从您的主分支拉取更改。

在只读模式下，同步的集合会出现在常规集合列表中，并带有一个特殊图标，表示它是版本化的且只读的。

此时，您应该已全部设置完毕。退出管理员设置，然后重新加载浏览器。您应该会在您的生产 Metabase 中看到您的同步集合。

一个开发到生产的工作流程示例

假设您的团队想要构建一个新的分析仪表板。以下是一个确保所有生产内容都经过审查的工作流程。

步骤 1：创建一个新分支

在您的开发 Metabase 中，点击同步集合部分的分支下拉列表，并创建一个新分支用于您的工作，例如 feature/megafauna-dashboard。

步骤 2：在您的开发 Metabase 中创建内容

创建一个名为“Megafauna Analytics”的仪表板，并添加一些问题。将问题保存到仪表板本身或同步集合中。将仪表板保存到同步集合。

步骤 3：推送到您的开发分支

1. 您应该会在同步集合上看到一个黄点（表示本地更改）。
2. 点击同步集合旁边的向上箭头（推送）图标。
3. 输入提交消息：“添加 Megafauna Analytics 仪表板”。
4. Metabase 将您的更改提交到您正在处理的分支，并将其推送到您的存储库。

步骤 4：创建一个拉取请求

在您的 Git 存储库中

1. 从您的分支 feature/megafauna-dashboard 向主分支 main 创建一个拉取请求。
2. 审查代表您的仪表板和问题的 YAML 文件的更改。
3. 一个懂行的人会批准并合并 PR。

步骤 5：生产环境自动更新

在您的生产 Metabase 实例中

1. 五分钟内，自动同步会检测到 main 分支上的新提交（您也可以手动导入更改）。
2. “Megafauna Analytics”仪表板及其所有问题都会出现在生产环境中。
3. 内容对用户是只读的（他们可以查看和使用它，但不能编辑）。

同步集合在读写模式下的工作原理

• UI 中的同步集合
• 移动和删除同步集合中的内容
• 同步集合中的项目不能依赖于其外部的项目

UI 中的同步集合

当您首次以读写模式连接时，Metabase 会创建一个名为“Synced Collection”的同步集合。您可以向其中添加项目和子集合。同步集合会显示其当前状态和视觉指示器：黄点表示未同步的本地更改需要提交，向上/向下箭头提供拉取和推送更改的同步控件。

在只读模式下，同步集合会出现在常规集合列表中（不在单独的“同步集合”部分），并带有一个特殊图标，表示它是版本化的且只读的。

移动和删除同步集合中的内容

删除内容会同步到生产环境： 当您在读写模式下从同步集合中删除内容并推送该更改时，内容在生产环境同步时也会被删除。这适用于将内容移出同步集合或完全删除它。

依赖于该项目的其他 Metabase 中的内容可能会中断，因为该依赖项将不再存在于同步集合中。

同步集合中的项目不能依赖于其外部的项目

为了让远程同步正常工作，同步的集合必须是独立的。仪表板或问题所需的一切都必须在同步的集合内。这包括

• 引用模型的查询
• 带有问题的仪表板
• 链接到其他内容的点击行为
• 选择来自其他查询或模型的值的筛选器
• 文档中的 @ 提及

例外：引用片段的查询无法同步，因为片段位于集合之外。

如果您尝试添加一个引用模型的查询，请确保模型也位于同步集合中。

使子集合出现在顶层

如果您使用 Metabase 进行嵌入，您可能希望同步内容出现在导航的顶层，而不是嵌套在同步集合下方。由于所有同步内容都必须在同步集合的子集合中，因此您可以使用权限来控制集合层次结构对不同组的显示方式。

1. 在您的开发 Metabase 中，在同步集合的子集合中组织内容。例如，您可能拥有 Synced Collection/Mammoth Statistics 和 Synced Collection/Giant Sloth Statistics。

2. 在您的生产 Metabase 中，为嵌入式组设置权限： 组应具有

   • 对同步集合本身的查看访问权限
   • 对同步集合内特定子集合的查看访问权限

对于具有这些权限的组，他们可以访问的子集合将出现在导航的顶层，就好像它们是根级别集合一样。他们将看不到您在开发 Metabase 中拥有的顶层同步集合。

在读写模式下看到的内容

Collections
└── Synced Collection
    ├── Mammoth Statistics
    ├── Giant Sloth Statistics

嵌入组在只读模式下看到的内容（无权访问同步集合，但有权访问 Mammoth Statistics 和 Giant Sloth Statistics）

Collections
├── Mammoth Statistics
└── Giant Sloth Statistics

Metabase 同步的内容

远程同步使用与Metabase CLI 序列化功能相同的序列化格式，将您的内容作为 YAML 文件存储在您的 Git 存储库中。

同步内容

• 仪表板及其卡片
• 问题（保存的查询和模型）
• 模型元数据（列描述、显示设置等）
• 文档
• 时间线和事件
• 集合结构和元数据

未同步内容

• 用户、组和权限
• 警报和订阅
• 代码片段
• 数据库连接
• 个人集合
• 表元数据（列类型、描述、可见性设置等）

分支管理

分支仅在读写模式下可用。

创建分支

您可以在 Metabase 中或直接在您的 Git 存储库中创建分支。在 Git 中创建的分支将在 Metabase 与您的存储库同步后出现在 Metabase 分支下拉列表中。

在创建分支之前，请将初始提交推送到您的主分支。

在 Metabase 中创建一个新分支

1. 点击同步集合部分的分支下拉列表。
2. 在搜索框中键入新分支的名称。
3. 按 Enter 键创建分支。

新分支是从您当前的提交创建的（而不是从远程的最新提交）。

切换分支

在左侧边栏的“同步集合”下，您会在同步集合名称旁边看到一个分支下拉列表

1. 点击分支下拉列表以查看可用分支。
2. 选择另一个分支以切换到它。

如果分支未显示，请确保它存在于您的 Git 存储库中，并且名称完全匹配（分支名称区分大小写）。

如果您有未同步的更改，Metabase 将显示一个对话框，询问您要如何处理

• 将更改推送到当前分支： 在切换之前提交您的更改。
• 创建一个新分支并推送到那里： 将您的工作保存到新分支，保持原始分支干净。
• 放弃这些更改： 丢弃您的未提交更改（无法撤销）。

对话框会向您显示确切的已更改项目，以便您做出明智的决定。

如果您切换模式（从读写到只读或反之），并且存在未推送的更改，系统将提示您保存或放弃它们。您不能在存在未提交的更改时切换到只读模式。

如果切换模式后更改未显示：请硬刷新您的浏览器（Cmd/Ctrl + Shift + R）。

将更改推送到 Git

您只能在远程同步设置为读写模式的 Metabase 中推送更改。

提交和推送您的更改

当您对同步集合中的项目进行更改时，您的同步集合上会出现一个黄点（表示未提交的更改）。要提交和推送您的更改

1. 点击左侧边栏同步集合名称旁边的向上箭头（推送）图标。
2. 输入一个描述性的提交消息，解释您的更改。
3. 点击“继续”将您的更改推送到 Git。

如果您看到“远程分支超前于本地”的消息，这意味着其他人从另一个读写模式的 Metabase 推送了更改。在再次推送之前，请拉取最新更改。

从 Git 拉取更改

您可以在读写模式或只读模式下拉取更改。

在读写模式下，您可以从 Git 存储库获取最新更改

1. 点击左侧边栏同步集合旁边的向下箭头（拉取）图标。
2. 查看显示的任何传入更改摘要。
3. 确认导入。
4. Metabase 使用 Git 中的最新内容更新您的集合。

拉取后更改未显示

• 验证您是否在正确的 istg 分支上。
• 硬刷新您的浏览器（Cmd/Ctrl + Shift + R）。
• 如果您遇到同步错误，请在同步对话框中查看错误消息，在 Git 存储库中手动解决冲突，然后再次拉取。

在只读模式下，转到管理员设置 > 设置 > 远程同步，然后点击拉取更改。

处理未同步的更改

如果您在尝试拉取或切换分支时存在本地未提交的更改，Metabase 将提示您进行选择

• 将更改推送到当前分支： 先提交您的更改，然后继续。
• 创建一个新分支并推送到那里： 将您的工作保存在新分支上。
• 放弃这些更改： 丢弃您的未提交更改以接受 Git 中的内容。

不确定时，请创建一个新分支并将更改推送到该分支。这样您就不会丢失任何工作。

自动拉取更改

在只读模式下，您可以设置 Metabase 以自动同步您主分支的更改。

1. 导航到管理员设置 > 设置 > 远程同步。
2. 启用“与 Git 自动同步”。

默认情况下，Metabase 将每五分钟拉取一次您指定分支上的任何更改（如果有）。您也可以根据需要手动同步。

禁用远程同步

要禁用远程同步，请转到管理员设置中的远程同步设置页面。

禁用远程同步

1. 转到管理员设置 > 设置 > 远程同步。
2. 点击禁用远程同步。
3. 在确认对话框中，点击禁用。

• 所有远程同步设置都将被清除，包括存储库 URL、访问令牌和分支信息。
• 您的同步集合及其内容将保留在您的 Metabase 中（不会被删除）。
• 同步的集合将成为一个常规集合，您可以像编辑任何其他集合一样编辑它。
• 稍后您可以重新启用远程同步，方法是重新连接到存储库，但是一旦您再次启用同步，在禁用后对集合所做的任何更改都可能被覆盖。

将现有内容迁移到远程同步

如果您已经在 Metabase 中拥有内容，您可以逐步采用远程同步。位于同步集合之外的内容不受影响 — 您可以在迁移内容到同步集合的过程中继续正常使用它。

确保您将任何依赖项（例如由问题引用的模型）移到同步集合中，因为同步内容必须是独立的。

如果您已经有一个包含已序列化 Metabase 数据的存储库

继续按原样操作。

如果您想完全切换到远程同步，我们建议从新存储库开始

1. 在您的 Metabase 实例中以读写模式签出一个新分支。
2. 使用序列化命令将您的数据导入到您的 Metabase 实例中，就像您平常做的那样。
3. 将您想要同步的内容移到同步集合中。
4. 将您的更改推送到新存储库。

远程同步不会同步表元数据，因此如果您导入和导出表元数据，您应该继续使用序列化。