Metabase Embedding SDK CLI 快速开始指南一条命令在本地跑通嵌入式数据看板【免费下载链接】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 Modular Embedding SDK 提供的 CLI 快速开始工具展开讲解如何用一条命令自动完成「本地 Docker 启动 Metabase → 连接数据库 → 生成嵌入式看板 → 生成 React 示例组件」的完整链路。读完本文你将掌握npx metabase/embedding-sdk-reactlatest start的使用方法、每一步背后的实际行为包括源码级实现细节并能在自己的 React 应用中嵌入第一张带主题切换、用户切换能力的分析看板。注意CLI 默认基于 API Key 的接入方式仅用于本地快速体验不适用于生产环境。生产环境接入需要 Pro/Enterprise 许可并通过 JWT 完成 SSO 认证。前置条件开始之前请确认你的本机环境满足以下要求Docker必须已安装并处于运行状态CLI 会通过 Docker 启动 Metabase并在前置检查阶段探测 Docker 是否可用。Node.js 20.x LTS 或更高版本用于运行npx命令与生成的前端组件。许可证可选仅当你想体验多租户multi-tenancy数据隔离能力时才需要 Metabase Pro/Enterprise 许可。数据库可选可以是你自己应用正在使用的数据库也可以不提供直接使用 Metabase 自带的 Sample Database。你不需要预先准备一个运行中的 Metabase——CLI 会替你在 Docker 中启动一个全新的 Metabase 实例。这一点在 CLI 启动时的提示信息中也有明确说明参见 messages.ts该工具不能连接已有的 Metabase 实例只能全新拉起一个。一条命令启动 CLI 快速开始进入你的 React 应用根目录执行npx metabase/embedding-sdk-reactlatest start命令解析入口在 cli.ts它使用commander注册了start子命令描述为 downloads and starts a local Metabase instance实际执行逻辑位于 actions/start.ts——执行前会先清空终端并捕获诸如用户强制中断force closed the prompt等异常情况。这条命令会以交互式问答的方式引导你完成整个配置流程。整体工作流如下前置检查Prereq check数据库连接可选Metabase 启动与初始化权限设置与多租户可选React 组件生成在你的应用中看到嵌入的 Metabase从源码角度看整个流程被拆解为一个个可独立执行的步骤并在 run.ts 中以CLI_STEPS数组的形式串联执行。每一步都有runIf条件守卫例如「询问租户列」「设置权限」仅在连接了自己数据库且持有有效许可时才执行「生成 Express 服务器」仅在持有许可时执行步骤之间通过共享的CliState传递数据如 API Key、数据库 ID、选中的表、看板信息等。完整步骤顺序如下showMetabaseCliTitle → checkIfReactProject → checkSdkAvailable → checkIsDockerRunning → checkIfDockerContainerExists → generateCredentials → startLocalMetabaseContainer → generateCredentialsFile → pollMetabaseInstance → setupMetabaseInstance → createApiKey → askIfHasDatabase → addDatabaseConnection → pickDatabaseTables → createModelsAndXrays → setupLicense → setupEmbeddingSettings → askForTenancyColumns → setupPermissions → generateReactComponentFiles → generateExpressServerFile → showPostSetupSteps前置检查CLI 会先确认三件事工具启动后会依次检查是否在 React 应用顶层目录运行CLI 会查找当前目录的package.json找不到时会提示 Please run this command from the root of your project同时校验package.json中是否包含 React 18 或 React 19 依赖版本不支持时会提示参考 SDK 文档或改用官方示例工程相关提示见 messages.ts。是否已安装 SDK如果没有安装metabase/embedding-sdk-reactCLI 会替你安装并作为依赖写入你的package.json对应 steps/check-sdk-available.ts 与 steps/install-sdk.ts。已安装时会直接显示 SDK vX found 并跳过安装。Docker 是否运行CLI 会分别检查 Docker 守护进程是否可用、是否存在已创建的容器steps/check-docker-running.ts、steps/check-docker-container-exist.ts。数据库连接可选决定看板的数据来源前置检查通过后CLI 会询问你是否已有数据库需要连接用方向键在 Yes / No 之间选择选择 No推荐新手工具将使用 Metabase 自带的 Sample Database 来创建要嵌入的看板。此时 CLI 会直接使用内置示例数据库SAMPLE_DB_ID 1见 constants/database.ts并自动选中PEOPLE、ORDERS、PRODUCTS三张表见 constants/config.ts 中的SAMPLE_DATABASE_SELECTED_TABLES无需手动挑选。选择 YesCLI 会列出它支持的常用数据库引擎供你选择。从源码看展示给用户的引擎白名单包括PostgreSQL、MySQL、SQL Server、BigQuery、Snowflake、Redshift、MongoDB、Athenaconstants/database.ts 的CLI_SHOWN_DB_ENGINES。随后提示你输入该数据库的host、port、用户名、密码并根据引擎类型动态补充字段如 PostgreSQL 的认证方式、BigQuery 的project-id与service-account-json、Athena 的region/workgroup/s3_staging_dir、MongoDB 的连接串等见同一文件中的CLI_SHOWN_DB_FIELDS。连接成功后工具会列出数据库中的 schema 和表要求你挑选 13 张表用于生成嵌入看板。若你希望体验多租户数据隔离请务必选择一张包含用户 ID 列的表。选表交互遵循 inquirer 的 checkbox 惯例空格选中/取消a全选i反转选择回车确认校验逻辑见 steps/pick-database-tables.ts0 张或超过 3 张都会提示重新选择。选完表后Metabase 会对这些表执行X-ray自动生成一组仪表盘用于嵌入。对应源码 steps/create-models-and-xrays.tsCLI 会先创建名为 Our models 的集合为每张选中表创建一个 Model再逐个对 Model 执行 X-ray 生成看板串行创建以避免重复生成 Automatically Generated Dashboards 集合。Metabase 设置Docker 拉起实例并完成初始化数据库信息确认后CLI 会询问管理员邮箱用于创建 Metabase 第一个管理员账号。该邮箱不必是真实邮箱——工具不会配置 SMTP 服务器这个邮箱只用于登录 CLI 创建的 Metabase 实例。密码由 CLI 随机生成见 steps/generate-credentials.ts邮箱会做格式校验。在 Docker 中启动 Metabase这一步需要等待一会儿。你可以用docker ps查看容器状态。关于 Docker 容器的实现细节见 constants/config.ts 与 steps/start-local-metabase-container.ts镜像metabase/metabase-enterprise:latest容器名固定为metabase-enterprise-embedding默认端口3366映射到容器内 3000 端口若该端口被占用CLI 会在 30003500 之间随机换一个可用端口启动时会注入一组环境变量见 constants/env.tsMB_SITE_NAMEMetabase Embedding SDK Demo、MB_EMBEDDING_APP_ORIGINhttp://localhost:*、MB_ENABLE_EMBEDDINGtrue、MB_EMBEDDING_HOMEPAGEvisible以及一个固定的MB_SETUP_TOKEN用于自动化初始化如果容器已存在但处于 exited 状态CLI 会用docker start直接复用若容器配置被手动改动过CLI 会报错并提示先执行docker rm -f metabase-enterprise-embedding后重试见 messages.ts。等待实例就绪并初始化CLI 会轮询http://localhost:3366/api/health最多等待约 5 分钟直到返回 200steps/poll-metabase-instance.ts。就绪后通过/api/setup用你提供的邮箱创建管理员账号steps/setup-metabase-instance.ts并调用/api/api-key生成一个 API Key归属于 All Users 组steps/create-api-key.ts。SDK 将使用这个 API Key 完成对嵌入看板的认证。初始化完成后登录凭据会写入当前目录的METABASE_LOGIN.json文件含邮箱、密码、URL并自动加入.gitignore见 steps/generate-credentials-file.ts。权限设置与多租户可选行级安全 JWT如果你持有Pro/EE 许可可申请 Metabase Pro 自托管免费试用CLI 可以进一步为你配置多租户权限选择租户隔离列如果你连接了自己的数据库CLI 会逐表询问用于数据隔离的列例如customer_id这类用户 ID 列。跳过则意味着该表所有行对所有用户可见选中的列将用于设置行级安全Row-level security让用户只能看到租户值与其 SSO 用户属性匹配的行交互说明见 steps/ask-tenancy-columns.ts。生成权限组与沙箱CLI 会创建Customer A、Customer B、Customer C三个权限组constants/config.ts 中的SANDBOXED_GROUP_NAMES并调用 Metabase 的权限 API 完成三件事见 steps/setup-permission/setup-permission.ts在 All Users 组中封锁示例数据库与业务数据库的访问权限为每个客户组配置基于列的沙箱VIEW_DATA设为SANDBOXED选中表/BLOCKED未选中表CREATE_QUERIES设为QUERY_BUILDER选中表/NO下载权限同理权限图生成逻辑见 utils/get-permission-groups.ts 与 utils/get-tenancy-isolation-sandboxes.ts配置JWT group mapping/api/setting/jwt-group-mappings把 SSO 中的组映射到上述权限组。启用嵌入与 JWT 设置CLI 会通过/api/setting写入嵌入相关设置steps/setup-embedding-settings.tsenable-embeddingtrue、embedding-homepagevisible持有许可时还会启用jwt-enabled、jwt-group-sync、jwt-user-provisioning-enabled?并写入一个硬编码的 JWT 共享密钥ffff...ffff见 constants/config.ts供生成的演示后端签发 JWT 使用。生成 mock Express 服务器CLI 会询问保存位置默认./mock-server生成一个用于签发 JWT 的示例后端并自动执行npm install安装依赖。生成的服务器基于 Express默认端口4477可用PORT环境变量覆盖内置了三个演示用户aliceexample.com、bobexample.com、charlieexample.com分属 Customer A/B/C 三组见 constants/hardcoded-users.ts提供两条路由完整代码由 snippets/express-server-snippet.ts 生成GET /sso/metabase根据会话中的用户信息签发 10 分钟有效的 JWT包含邮箱、姓名、权限组以及租户属性如customer_idPOST /switch-user切换当前会话用户模拟不同租户登录。你需要在另一个终端会话中启动这个 mock servercd mock-server npm run start提示如果你选择使用 Sample Database则不会配置 JWT SSO 与沙箱CLI 仍会生成一个 mock 后端用于演示但不会配置权限隔离参见 messages.ts 中的SETUP_PRO_LICENSE_MESSAGE_WITH_SAMPLE_DATABASE。React 组件生成拿到可直接运行的示例接下来CLI 会为你的 React 应用生成示例组件文件。默认保存到./src/components/metabaseNext.js 项目会按src目录约定自动调整你也可以在提示时改成其他目录如./src/analytics。生成的代码会自动适配项目类型TypeScript 项目生成.tsx/.tsJavaScript 项目生成.jsx/.js并附带analytics.css与统一导出的index文件见 steps/generate-component-files.ts。生成的核心组件包括组件作用AnalyticsDashboard嵌入 Metabase 看板的看板组件基于 SDK 的InteractiveDashboard支持看板切换、新建问题、主题切换AnalyticsPage将 Provider 与看板打包在一起的页面组件方便你快速验证ThemeSwitcher在浅色 / 深色主题间切换的演示组件UserSwitcher在多个假用户之间切换演示多租户下的不同数据视图仅在启用多租户时生成AnalyticsProvider提供主题、用户等演示状态React ContextEmbeddingProvider用演示主题与认证配置包裹MetabaseProvider这些组件的实际模板可在源码中查看snippets/embedding-provider-snippet.tsMetabaseProvider的authConfig组装逻辑。无许可时使用 API Key 认证apiKey: your-api-key启用多租户时则改为通过 mock server 的/sso/metabase获取 JWT。同时还内置了 light / dark 两套示例主题色板。snippets/analytics-dashboard-snippet.tsAnalyticsDashboard内部通过InteractiveDashboardwithTitle、withDownloads渲染看板并通过key{email}在用户切换时强制重载保证每次切换用户都能看到该租户自己的数据还内置了InteractiveQuestion questionIdnew支持「新建问题」。snippets/analytics-provider-snippet.ts 与 snippets/user-switcher-snippet.ts用户切换通过POST http://localhost:4477/switch-user调用 mock server随后刷新页面完成重新登录。等你体验完这些功能后就可以删除这些演示文件开始实现你自己的主题定制与用户管理逻辑。将组件接入你的 React 应用1. 添加 import在你的客户端应用中添加导入。参考 docs/embedding/sdk/snippets/quickstart-cli/example.tsximport { AnalyticsPage } from ./components/metabase/analytics-page;请确保from路径真实有效——如果你的应用目录结构不同可能需要把组件移动到新目录例如./src/analytics再调整导入路径。2. 渲染组件把AnalyticsPage /放到应用中的某个页面里例如function App() { return ( div classNameApp style{{ width: 1200px, height: 800px }} AnalyticsPage / /div ); } export default App;注意示例中的AnalyticsPage已经替你包好了 Provider。在真实应用中你需要把MetabaseProvider单独添加到应用根部的App组件或你放置其他 Provider 的位置——CLI 生成的文件只是演示性质AnalyticsPage对应的模板见 snippets/analytics-page-snippet.ts内部由AnalyticsProvider→EmbeddingProvider→AnalyticsDashboard三层组成。见证成果嵌入的看板出现在你的应用中启动你的应用并访问添加了AnalyticsPage /的页面你应当能看到嵌入的 Metabase 看板未启用多租户时看板展示你选择表对应的 X-ray 分析结果启用了多租户时通过UserSwitcher在 Alice / Bob / Charlie 之间切换可以直观地看到不同「客户」只能看到自己租户范围内的数据行——这正是沙箱Sandboxing与 JWT SSO 协同工作的效果。同时CLI 创建的 Metabase 实例运行在http://localhost:3366登录凭据记录在项目根目录的METABASE_LOGIN.json文件中你可以随时进入该 Metabase 管理后台查看工具替你创建的看板、模型、权限组与沙箱配置。进一步阅读如果希望体验更接近真实生产环境、基于 JWT 认证的完整接入流程可以参考 Quickstart with sample app and JWT。需要了解 API Key 的完整管理方式可阅读 People and groups: API keys。想深入理解行级安全与数据沙箱的底层概念可阅读 Permissions: Row and column security。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考