Metabase 如何用 Guest Embeds 在不需要 Metabase 账号的情况下嵌入仪表板？

Metabase 如何用 Guest Embeds 在不需要 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

如果你的目标是把 Metabase 的仪表板嵌入自己的应用页面，又不想为每个查看者都创建一个 Metabase 账号，那么 Guest Embeds 就是对应的方案。它允许在不做 SSO 登录的前提下嵌入问题、仪表板和文档：Metabase 不会为每个查看者创建会话，因此请求必须是带有 JWT 签名才安全——Metabase 只有在请求携带用「你的应用与 Metabase 之间共享的密钥」签名的 JWT 时才会加载嵌入内容。JWT 中同时包含要加载的资源引用（例如嵌入项的 ID）以及参数值。

「Guest」只是指认证方式，与数据新鲜度无关：guest embed 中的仪表板和图表始终展示数据库中的实时数据。本文以嵌入仪表板为主线，给出从 Metabase 后台启用、发布嵌入，到前端组件和后端签名 JWT 的完整操作路径，以及用 locked parameters 按查看者限定数据、配置 JWT 自动刷新这两个可选分支。

在 Metabase 中开启 guest embedding

进入方式取决于你使用的 Metabase 版本：

• OSS：Admin > Embedding
• Starter/Pro/Enterprise：Admin > Embedding > Guest embeds

打开Enable guest embeds开关。

创建并发布 guest embed

1. 打开你要嵌入的仪表板（也可以按 Ctrl/Cmd+K 打开命令面板，输入 "New embed"）。
2. 点击Share图标。
3. 选择Embed。
4. 在Authentication下选择Guest。
5. 可选：自定义嵌入的外观。
6. 可选：为每个参数设置可见性。
7. 点击Publish。
8. 复制向导生成的代码片段，加入你的应用。

前端：加载 embed.js 并放置仪表板组件

把嵌入脚本和配置加到你的 HTML 中。YOUR_METABASE_URL需要替换成你的 Metabase 实例地址：

<script defer src="YOUR_METABASE_URL/app/embed.js"></script> <script> window.metabaseConfig = { isGuest: true, instanceUrl: "YOUR_METABASE_URL", // Optional. Set this if you want the embed to fetch a fresh JWT // when the current one expires. See "Refreshing the JWT" below. // guestEmbedProviderUri: "/your/apps/endpoint", }; </script>

然后添加对应组件。仪表板使用metabase-dashboard，问题使用metabase-question：

<!-- For dashboards --> <metabase-dashboard token="YOUR_JWT_TOKEN" with-title="true" with-downloads="false" initial-parameters='{"category":["Gizmo"]}' ></metabase-dashboard> <!-- For questions --> <metabase-question token="YOUR_JWT_TOKEN"></metabase-question>

token属性是必需的，值为你的服务器签发的 JWT。文档明确警告：不要把一个固定的 JWT 粘在 HTML 里长期留着——token 会过期，嵌入最终会失效。做法是每次页面加载时在你的服务器上新签一个 token 并渲染到token属性，或者配置guestEmbedProviderUri（见下文）让嵌入自行获取和刷新 token。

常用组件属性（不同嵌入类型支持的属性不同，guest embed 的选项比 SSO 嵌入少，完整列表见仪表板组件参考和问题组件参考）：

属性	说明
token	必需。你的服务器签发的 JWT。
with-title	显示或隐藏标题，"true"/"false"。
with-downloads	开启或关闭下载，"true"/"false"（仅在 Pro 和 Enterprise 方案中可用）。
initial-parameters	初始参数值的 JSON 字符串（非受控），例如'{"category":["Gizmo"]}'。
parameters	参数值的 JSON 字符串（受控）。
auto-refresh-interval	仅仪表板。自动刷新间隔（秒）。
custom-context	转发给你的guestEmbedProviderUri端点，字段名为customContext。

后端：用嵌入密钥签名 JWT

你的服务器负责生成用于认证嵌入请求的 JWT。文档给出的 Node.js 示例如下（需要npm install jsonwebtoken或写入 package.json）：

const jwt = require("jsonwebtoken"); const METABASE_SECRET_KEY = "YOUR_METABASE_SECRET_KEY"; const payload = { resource: { dashboard: 10 }, // or { question: 5 } for questions params: {}, exp: Math.round(Date.now() / 1000) + 10 * 60, // 10 minute expiration }; const token = jwt.sign(payload, METABASE_SECRET_KEY);

两点需要替换：

• YOUR_METABASE_SECRET_KEY：你的嵌入密钥。在Admin > Embedding（Pro/Enterprise 方案在Guest embeds标签页）中可以看到。该密钥被所有 guest embed 共享，任何拿到它的人都能访问所有嵌入产物，务必保管好；如果重新生成密钥，需要同步更新服务器代码。
• resource: { dashboard: 10 }中的10是顺序 ID，即该仪表板 URL 中的数字。Pro 和 Enterprise 方案可以改用 entity IDs，它们在你把内容从一台 Metabase 序列化（例如从 staging 到生产）到另一台时保持不变。

可选：用 locked parameters 按查看者限定数据

如果同一仪表板要给不同的人看不同范围的数据（例如每个客户只看自己的数据），把参数设为Locked：对最终用户隐藏，值由你的服务器通过 JWT 传入，而不是由查看者设置。

1. 在嵌入设置中把参数设为Locked。
2. 在服务器端把参数值放进 JWT 的params。
3. 发布（Publish）该条目。

例如锁定category参数时，服务器代码为：

const jwt = require("jsonwebtoken"); const METABASE_SECRET_KEY = "YOUR_METABASE_SECRET_KEY"; const payload = { resource: { dashboard: 10 }, params: { category: ["Gadget"], // Set the locked parameter value to Gadget }, exp: Math.round(Date.now() / 1000) + 10 * 60, // 10 minute expiration }; const token = jwt.sign(payload, METABASE_SECRET_KEY);

客户端代码与普通 guest embed 相同，不需要额外属性——参数值由 JWT 决定。最终用户看不到 "category" 过滤器，但仪表板只显示 "Gadget" 类别的数据（或你在params中传入的任意值）。

维护 locked parameters 时有几条规则来自文档：

• JWT 必须包含所有已发布的 locked parameters。一旦发布了带 locked parameter 的仪表板，签名 JWT 时必须包含该参数的名字；漏掉时 Metabase 会拒绝请求并记录日志：You must specify a value for :<parameter-name> in the JWT（例如参数为category时是You must specify a value for :category in the JWT）。
• 想对某个 token 关闭锁定过滤，在 JWT 中为该参数传空数组[]：

const payload = { resource: { dashboard: 10 }, params: { category: [], // locked filter is bypassed for this token }, exp: Math.round(Date.now() / 1000) + 10 * 60, };

• 多个 locked parameters 之间以AND组合，不是OR；只想应用其中一部分时，对其余参数传[]。
• 锁定的参数会先于展示过滤数据，因此它同时会限制同一页面上其他可编辑过滤控件的可选值（例如锁定 State 为 "Vermont" 后，City 下拉框只会出现 Vermont 的城市），无需手动把两个过滤器关联起来。
• 如果 locked parameter 关联的过滤器又关联了 SQL 问题，JWT 中只能传单个值。

由于 Metabase 不渲染 locked parameters 为过滤器控件，你还可以用它驱动自己构建的自定义过滤组件：用户在你的组件里改值后，在服务器重新签一个带更新params的 JWT，替换到 web 组件的token属性上，嵌入就会用新的锁定值重新请求数据。

可选：配置 guestEmbedProviderUri 自动刷新 JWT

guest embed 的 JWT 带exp过期时间。token 过期后，嵌入无法加载新数据，且查看者之前做的过滤选择在下一次请求时会重置。要在不刷新页面的情况下保持嵌入可用，可以在你的服务器上配置一个 token 端点，按需签发新的 JWT：

<script> window.metabaseConfig = { isGuest: true, instanceUrl: "YOUR_METABASE_URL", guestEmbedProviderUri: "/api/metabase-guest-token", }; </script>

需要 token 时，嵌入会向guestEmbedProviderUri发送POST请求，请求体包含 cookie（因此你可以用应用自身的会话认证），JSON 体如下：

{ "entityType": "dashboard", "entityId": 10, "customContext": "..." }

字段	说明
entityType	"dashboard"或"question"。
entityId	你设置在组件上的仪表板或问题的 ID。
customContext	可选。你在custom-context属性上设置的字符串或对象。

响应是一个只含jwt字段的 JSON 对象：

{ "jwt": "YOUR_NEWLY_SIGNED_JWT" }

两种用法：

• 刷新：HTML 中预渲染一个初始 JWT 并配置guestEmbedProviderUri，token 过期时嵌入调用端点换新 token。注意刷新发生在过期后下一次数据请求时，而不是后台定时器；空闲的嵌入不会发起刷新请求。
• 无 JWT 初始化：省略token属性，改用dashboard-id（或question-id），嵌入在加载时调用同一端点获取第一个 JWT：

<metabase-dashboard dashboard-id="10"></metabase-dashboard>

文档给出的 Express 端点示例（其中认证与授权逻辑仅为示例）：

const jwt = require("jsonwebtoken"); const METABASE_SECRET_KEY = "YOUR_METABASE_SECRET_KEY"; app.post("/api/metabase-guest-token", (req, res) => { // Authenticate using your app's existing session. const user = req.session?.user; if (!user) { return res.status(403).json({ error: "Not signed in" }); } const { entityType, entityId, customContext } = req.body; // Authorize the request. The browser picks the entityType and entityId, so // check them against your own rule before signing for them. // This is just an example if (!userCanView(user, entityType, entityId)) { return res.status(403).json({ error: "Not allowed" }); } const payload = { resource: { [entityType]: entityId }, params: paramsFor(user, customContext), exp: Math.round(Date.now() / 1000) + 10 * 60, // 10 minute expiration }; res.json({ jwt: jwt.sign(payload, METABASE_SECRET_KEY) }); });

由于请求携带应用自身的会话 cookie，这个端点可以：对未登录你的应用的访客返回403拒绝签发；对访客不应看到的仪表板/问题拒签（entityType和entityId来自浏览器，不做校验就签发的端点会让任何登录访客拿到任意已发布条目的 token）；以及按访客计算不同的params。同一页面嵌入同一仪表板多次时，用custom-context属性区分是哪一个副本在请求 token，端点据此返回不同的锁定参数。

结果验证与故障判断

按文档描述的机制，嵌入的判定路径是：web 组件把 token 发给 Metabase → Metabase 用你的密钥校验 JWT 签名 → 校验通过则返回嵌入内容；未通过则不加载。据此可以核对：

• 正常：JWT 有效时页面中渲染出仪表板，展示的是数据库实时数据；
• 参数缺失：JWT 漏掉某个 locked parameter 时，Metabase 拒绝请求并在日志中输出You must specify a value for :<parameter-name> in the JWT，按参数名检查你的 payload；
• token 过期：写死在 HTML 里的固定 JWT 到期后嵌入停止工作，这是预期现象，改用每次页面加载新签 token 或guestEmbedProviderUri解决。

限制与边界

• Guest embed 是只读的，且无法使用以下功能：行级和列级安全、数据库路由、钻取（Drill-through）、用量分析、查询构建器、AI 聊天、自定义可视化。需要这些能力时改用 Modular embedding with SSO。
• OSS 和 Starter 方案的 guest embed（图表和仪表板）会显示 "Powered by Metabase" 横幅，移除需要升级到 Pro 或 Enterprise。
• 关闭下载（with-downloads）仅 Pro/Enterprise 可用；OSS/Starter 的外观定制只有浅色/深色主题，Pro/Enterprise 有更细粒度的外观选项。
• guest 嵌入的仪表板上，自定义目的地只能使用URL选项，外部 URL 会在新标签页打开；除非过滤器是锁定的，否则过滤器值可以传递到外部 URL。
• 使用 Modular Embedding SDK 时，若也要用 guest 认证，仍然需要在 Metabase 中打开该条目并完成发布；且应用的同一页面只能有一种认证类型（不能一个页面里既有一个 guest 认证的问题又有一个 SSO 认证的问题）。
• 跨域：认证文档明确 guest embeds 跨域工作，无需额外配置（CORS 设置仅适用于 authenticated embeds）。

如果要取消嵌入，打开该条目的Share > Embed，选择Guest embedding后点击Unpublish；管理员可以在Admin > Embedding（Pro/Enterprise 在Guest embeds标签页）查看所有已嵌入条目的列表。

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