尧图网页设计 
Metabase 配置文件初始化指南用 config.yml 实现启动时的用户、数据库与设置自动配置【免费下载链接】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 自托管self-hostedPro/Enterprise 版提供的启动时从配置文件加载能力展开讲解如何通过放置一份config.yml让实例在每次启动时自动完成用户账号、数据库连接、API Key 以及任意 Admin 设置Settings的创建与更新。读完本文你将掌握配置文件的标准结构、各分节users/databases/api-keys/settings的完整字段写法、环境变量模板引用与特殊字符转义技巧并能结合仓库源码理解其底层执行顺序与覆盖语义从而在自动化部署与开发环境中稳定复现这套初始化方案。功能定位与适用前提配置文件初始化是 Metabase 企业版Enterprise EditionJAR 特有的能力适用于自托管的 Pro 与 Enterprise 订阅。其功能开关名为:config-text-file需要携带带有该 feature 的 Premium Token 才能使用settings分节是唯一例外见下文Settings 分节。从仓库源码看该功能被刻意做成了 EE 专属的分层结构在开源版核心侧src/metabase/core/config_from_file.clj 只是一个 shim它先探测企业命名空间metabase-enterprise.advanced-config.file是否存在存在才调用其boot-initialize!否则静默跳过。这解释了为什么该功能只在 EE JAR 中生效。真正的实现位于 enterprise/backend/src/metabase_enterprise/advanced_config/file.clj并由同一目录下的file/{users,databases,settings,api_keys}.clj四个子模块分别负责各分节的初始化。加载时机被设计在应用数据库就绪、驱动插件初始化完成之后源码注释明确说明This logic is meant to be executed after the application database is set up and driver plugins have been initialized由启动引导流程统一触发。需要特别注意配置文件的覆盖语义每当 Metabase 重启并加载配置文件时配置文件中的设置都会覆盖你在 Metabase 界面Admin Settings中对这些设置做过的任何修改。这一语义与环境变量截然不同环境变量设置的键是不可变更的硬编码真值源即使是在应用内的 Admin 界面也无法修改而配置文件中的设置本质上等价于你在 Admin Settings 中做的写入因此被 UI 修改后、再次重启会被文件重新覆盖。配置文件的查找位置与顶层结构文件查找路径Metabase 启动时按以下优先级寻找配置文件对应 file.clj 中的path函数逻辑由环境变量MB_CONFIG_FILE_PATH显式指定的路径若已设置则只尝试该路径当前工作目录即运行 metabase.jar 所在的目录下名为config.yml的文件当前工作目录下名为config.yaml的文件。源码会对这些候选路径逐一检查是否存在找到了会以洋红色日志打印 Found config file at path ...否则会提示 No config file found ... 并按常规流程启动。顶层version与config配置文件整体被拆成version和config两部分version: 1 config: settings: - ... users: - ... databases: - ... api-keys: - ...version是一个必填键它只是供你维护配置文件版本使用的便利字段。源码file.clj规定当前版本只接受1.0 ~ 1.999含两端范围内的数字超出范围 spec 校验会直接失败。它并非语义化版本而是简单的浮点版本号Metabase 45 引入了 1.0 规格未来向后兼容的演进使用 1.x破坏性变更才会推进到 2.0。分节的初始化顺序config下的四个合法分节另有分节方法注册在 interface 中并非按书写顺序执行。源码的sort-by-initialization-orderfile.clj强制把settings分节排在最前面执行其余分节users、databases、api-keys随后按原顺序处理。这样设计是因为 settings 可能影响后续分节的执行例如关闭同步、设置站点名等。此外还有一个容易被忽略的细节每个分节的 spec 校验发生在模板展开之前这是为了避免在日志的 spec 错误信息里泄露环境变量中的敏感值见 file.clj 与 interface 中section-spec的注释。Users 分节启动时创建/更新用户一个 Metabase 实例中第一个被创建的用户是管理员。配置文件中第一个列出的用户并不一定就是管理员如果该实例已经完成过初始化有人已首次登录设置过则首位用户按普通用户加载只有当实例尚未 setup源码用setup/has-user-setup判断时配置文件中创建的第一个用户才会被强制提升为管理员。此外你随时可以通过is_superuser: true显式把一个用户指定为管理员。在下面的例子中假设该 Metabase 尚未完成首次设置那么firstexample.com与adminexample.com都会是管理员——前者因为它是列表中第一个用户后者因为它带is_superuser: true标记version: 1 config: users: - first_name: First last_name: Person password: metabot1 email: firstexample.com - first_name: Normal last_name: Person password: metabot1 email: normalexample.com - first_name: Admin last_name: Person password: metabot1 is_superuser: true email: adminexample.com如果该 Metabase 已完成过初始化已存在首位用户那么firstexample.com将被加载为一个普通用户。从源码实现users.clj可以确认以下几点行为必填字段为first_name、last_name、password、emailconfig-file-spec中四个字段全部req-unis_superuser属于可选键。邮件会先被统一转为小写再入库与:model/User层的统一行为一致。密码不直接写入 User 表而是通过auth-identity/set-password!存入独立的 AuthIdentity——所以绝不要在业务代码中把明文密码交给 User 模型。若目标 email 已存在则更新已有用户且login_attributes采取合并保留策略不会整表覆盖。若 email 不存在则创建新用户创建与密码写入被包在同一个事务中保证二者原子落地。Databases 分节启动时创建/更新数据源连接每个 database 条目要求至少提供name、engine、details三个键见 databases.clj可选键还包括settings、is_stub、is_sample以及 uploads 相关配置。下面是一个同时创建管理员账号和一条 PostgreSQL 连接的新实例示例version: 1 config: users: - first_name: Cam last_name: Era password: 2cans3cans4cans email: camexample.com databases: - name: test-data (Postgres) engine: postgres details: host: localhost port: 5432 user: dbuser password: {{ env POSTGRES_TEST_DATA_PASSWORD }} dbname: test-data要确定某个数据库引擎可以填写哪些details键直接对照 Metabase 界面中添加数据库表单里展示的字段即可源码 spec 对details只约束为map?具体字段交由连接层校验。关于databases分节的执行语义databases.clj连接探测除非条目标记为is_stub: true占位桩Metabase 会先尝试用details连接一次目标数据库失败则直接抛异常终止——这就保证了配置文件不会把你写坏的库静默入库。按 engine name 匹配已有库若已存在同名同引擎的数据库则以配置文件中的details等字段更新该条目即文档所说的已存在的数据库会被配置内容更新。不存在则新建新建的库默认会触发一次sync-database!同步受config-from-file-sync-databases设置控制详见后文。is_sample: true这是重建内置 Sample Database 的专用写法要求name必须是官方样例库名且engine必须为h2否则抛错其details会被忽略因为样例库始终使用随包附带的 H2 文件sample-data/extract-and-sync-sample-database!。条目内的delete键是面向托管服务的内部删除标记取值为固定的DELETE_WITH_DEPENDENTS:name魔法字符串源码注释明确它是subject to breaking changes的内部功能普通部署不应依赖。在数据库上启用文件上传uploads你可以在同一条 database 记录里追加以下三个键来配置数据上传功能uploads_enabledBoolean是否允许向该库上传。uploads_schema_nameString上传表所在 schema。uploads_table_prefixString上传表前缀。version: 1 config: users: - first_name: Cam last_name: Era password: 2cans3cans4cans email: camexample.com databases: - name: test-data (Postgres) engine: postgres details: host: localhost port: 5432 user: dbuser password: {{ env POSTGRES_TEST_DATA_PASSWORD }} dbname: test-data uploads_enabled: true uploads_schema_name: uploads uploads_table_prefix: uploads_更多细节可参见 uploads 使用文档。API keys 分节用配置文件固化 API Key配置文件可以用来创建 API Key。这对自动化部署以及让 API Key 跨环境保持稳定非常有用——例如 CI 脚本、数据同步任务可以在每次启动后都拿到同一个 key而无需人工到界面复制。version: 1 config: users: - first_name: Cam last_name: Era password: 2cans3cans4cans email: camexample.com api-keys: - name: Admin API key group: admin creator: camexample.com key: mb_firsttestapikey - name: All Users API key group: all-users creator: camexample.com key: mb_secondtestapikey也可以用一个环境变量来注入 API Key 的取值api-keys: - name: ENV API Key key: {{env API_KEY_FROM_ENV}} creator: adminexample.com group: admin关于模板引用详见下一节在 config.yml 中引用环境变量。API Key 的格式要求与生成你在配置里提供的key必须满足格式mb_ Base64 串即mb_后跟字母与数字最短 12 个字符、最长 254 个字符。精确地说必须匹配正则mb_[A-Za-z0-9/]。源码校验api_keys.clj同时要求长度落在 11254配合mb_前缀后即文档所述的 12254 语义并匹配该正则。可以用openssl rand生成合规的 keyecho mb_$(openssl rand -base64 32)输出形如mb_aDqk1Tc4ZotWb2TyjHY71glALKlBg75dLgmSufWGLcAPI Key 分节的行为约定creator必须是管理员要么你的实例里已存在至少一个管理员账号要么就在本配置文件的users分节里新增一个带管理员权限的账号。group只能二选一admin或all-users。配置文件把可选分组限定在这两个因为它们是 Metabase 在初始化阶段总是存在的内建分组。源码用perms/admin-group与perms/all-users-group解析出对应的 group-id。key 的权限跟随其所属group而不是它的creator。同名 Key 不会被覆盖如果 Metabase 发现已有与配置中同名的 API Key它会保留现有 Key跳过创建并打印日志。这意味着若你后来在 UI 里重新生成了某个 key那么重启加载配置文件也不会覆盖这个新 key配置里写的旧key自然就失效了。如果想用配置文件强制覆盖需要先在 UI 中删除现有 key再重启加载若想同时保留两个 key则需要在配置文件里给新 key 改名。Key 前缀必须全局唯一源码会先对 key 计算前缀并检查api-key-prefix-exists?若前缀已被占用会直接抛错。另外要区分两个容易混淆的概念api-keys分节真正创建 API Key而settings分节里也有一个名为api-key的设置键那个并不会创建任何 Key它只是用于在鉴权/notify端点的请求头时做字符串匹配详见环境变量文档中MB_API_KEY的说明。在 config.yml 中引用环境变量如上文示例所示配置文件支持以模板标签的形式引用环境变量setting: {{ env POSTGRES_TEST_DATA_PASSWORD }}注意模板必须被引号包裹。如果去掉引号YAML 解析器就无法把它识别为待 Metabase 展开的字符串模板Metabase 也就不会用环境变量值去替换它。模板展开的底层机制很有意思源码file.clj复用了 SQL 查询中解析模板参数的那套代码metabase.lib.parameters.parse把{{env SOME_VAR}}形式解析为 EDN 后再按类型分发展开。这带来两个推论目前env是唯一受支持的模板类型expand-parsed-template-form的 default 分支会对未知类型抛错未来可以按需扩展。由于底层兼容可选模板语法某些场景下你也能得到类似的容错行为。模板中的变量名解析对大小写不敏感且lisp-case/snake_case写法均可用它底层走environ.core/env因此也支持 Java 系统属性把属性名中的点换成斜杠或下划线即可例如{{env user-dir}}可读取系统属性user.dir。同时需要注意Metabase 不支持递归展开。如果某个环境变量的值本身又引用了另一个环境变量比如值里包含{{env ...}}解析不会逐层展开结果只会令你困惑——请避免这种用法。含有特殊字符的值三重花括号转义当某个值本身含有双花括号}}或{{时YAML 解析器会误以为它是一个待展开的模板。此时必须改用三重花括号包裹指示配置解析器按字面值处理。例如密码为MetaPa$$123{{需要写成password: {{{ MetaPa$$123{{ }}}注意这里同样保留外层引号。展开逻辑对应源码中的正则分支file.clj命中^\{\{\{(.)\}\}\}$的字符串会被原样 trim 后作为字面值返回不再走模板解析。关闭数据库创建时的自动同步当你要从一份序列化导出serialization export加载数据模型时通常不希望调度器自动去同步数据库以免干扰你预期的元数据状态。要关闭初始数据库同步可以在settings列表中写入config-from-file-sync-databases并设为false。注意该设置项必须出现在databases列表之前version: 1 config: settings: config-from-file-sync-databases: false databases: - name: my-database engine: postgres details: ...该设置与同步逻辑的对应关系清晰体现在 databases.clj新建数据库后仅当config-from-file-sync-databases为真时才会把sync-database!任务提交到后台为假时则打印 Sync on database creation when initializing from file is disabled. Skipping sync.。此设置在配置模板中的默认值是true。小提示官方文档正文里曾出现单数写法config-from-file-sync-database但代码、官方示例与配置模板中实际使用的键均为复数形式config-from-file-sync-databases请以复数形式为准。Settings 分节任意 Admin 设置在settings分节中你可以指定任意 Admin 设置。它由 settings.clj 逐键处理已注册的设置直接set!未注册的键只会打一条 warning 并跳过。键的命名转换规则settings 分节的键与环境变量之间存在固定的命名转换关系。环境变量是尖叫蛇形 MB_前缀MB_NAME_OF_VARIABLE对应到配置文件则转换为小写连字符形式name-of-variable例如要把MB_EMAIL_FROM_NAME写进config.ymlversion: 1 config: settings: config-from-file-sync-databases: false email-from-name: Stampy von Mails-a-lot databases: - name: my-database engine: h2 details: ...任何 Admin 设置都能在配置文件中设置可设置的完整清单见配置文件模板它逐项列出了当前实例所有可配置设置及其默认值也可以对照环境变量文档查找不过要注意并非所有环境变量都能通过配置文件设置两者能力范围并不完全等价。如何生成当前版本的配置模板配置模板文档由仓库内脚本实时生成。进入仓库顶层目录后执行clojure -M:doc:ee config-template即可重新生成 docs/configuring-metabase/config-template.md。模板中自上而下给出了users、databases、api-keys、settings四个分节的完整示例其中 settings 条目附带了默认值——模板注释建议删掉或注释掉你不打算设置的那些键。一个容易被忽略的特殊点settings 分节是唯一豁免项从源码的启动校验逻辑file.clj可以看到除settings分节外其余每个分节在执行前都会校验premium-features/enable-config-text-file?未携带对应 feature 的 Token 会直接抛错而settings分节是唯一的例外源码注释写的是 the lone carve-out — you may need it toinstallthe token。也就是说即使实例尚无可用的 Premium Tokensettings分节仍可先执行——这为你通过配置文件安装/写入premium-embedding-token等设置预留了入口。让新实例从配置文件启动由于从配置文件加载属于 Pro/Enterprise 功能对全新安装而言需要先用环境变量MB_PREMIUM_EMBEDDING_TOKEN为 Metabase 提供许可证 TokenMB_PREMIUM_EMBEDDING_TOKEN[your token] java --add-opens java.base/java.nioALL-UNNAMED -jar metabase.jar将上面命令中的[your token]替换为你的实际 Token并把config.yml放在运行该命令的工作目录下或用MB_CONFIG_FILE_PATH指向文件Metabase 即会在启动完成后按文件内容完成用户、数据库、API Key 与设置的初始化。你会在日志中看到类似 Initializing users from config file... 与 Done initializing from file. 的提示可用于确认加载成功。小结与常见坑位速查关注点结论覆盖语义配置文件中的设置在每次重启时覆盖 UI 中做出的修改环境变量则不受影响且不可被 UI 修改文件位置运行 JAR 目录下的config.yml/config.yaml或用MB_CONFIG_FILE_PATH指定版本号version必填当前支持1.0~1.999初始化顺序settings最先执行其次为 users/databases/api-keys 等其他分节首位用户仅在实例尚未 setup 时自动成为管理员否则需显式is_superuser: true数据库按 enginename 匹配更新新建会默认同步除非先声明config-from-file-sync-databases: falseAPI Key格式mb_[A-Za-z0-9/]长度 12~254同名 Key 跳过不覆盖prefix 必须唯一环境变量写法{{ env VAR }}务必带引号不支持递归展开特殊字符含{{/}}的值用三重花括号{{{ ... }}}包成字面量如需继续深入可以继续阅读仓库内的配置文件模板、环境变量参考或直接阅读 EE 实现源码 file.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Metabase 配置文件初始化指南：用 config.yml 实现启动时的用户、数据库与设置自动配置
Metabase 配置文件初始化指南用 config.yml 实现启动时的用户、数据库与设置自动配置【免费下载链接】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 自托管self-hostedPro/Enterprise 版提供的启动时从配置文件加载能力展开讲解如何通过放置一份config.yml让实例在每次启动时自动完成用户账号、数据库连接、API Key 以及任意 Admin 设置Settings的创建与更新。读完本文你将掌握配置文件的标准结构、各分节users/databases/api-keys/settings的完整字段写法、环境变量模板引用与特殊字符转义技巧并能结合仓库源码理解其底层执行顺序与覆盖语义从而在自动化部署与开发环境中稳定复现这套初始化方案。功能定位与适用前提配置文件初始化是 Metabase 企业版Enterprise EditionJAR 特有的能力适用于自托管的 Pro 与 Enterprise 订阅。其功能开关名为:config-text-file需要携带带有该 feature 的 Premium Token 才能使用settings分节是唯一例外见下文Settings 分节。从仓库源码看该功能被刻意做成了 EE 专属的分层结构在开源版核心侧src/metabase/core/config_from_file.clj 只是一个 shim它先探测企业命名空间metabase-enterprise.advanced-config.file是否存在存在才调用其boot-initialize!否则静默跳过。这解释了为什么该功能只在 EE JAR 中生效。真正的实现位于 enterprise/backend/src/metabase_enterprise/advanced_config/file.clj并由同一目录下的file/{users,databases,settings,api_keys}.clj四个子模块分别负责各分节的初始化。加载时机被设计在应用数据库就绪、驱动插件初始化完成之后源码注释明确说明This logic is meant to be executed after the application database is set up and driver plugins have been initialized由启动引导流程统一触发。需要特别注意配置文件的覆盖语义每当 Metabase 重启并加载配置文件时配置文件中的设置都会覆盖你在 Metabase 界面Admin Settings中对这些设置做过的任何修改。这一语义与环境变量截然不同环境变量设置的键是不可变更的硬编码真值源即使是在应用内的 Admin 界面也无法修改而配置文件中的设置本质上等价于你在 Admin Settings 中做的写入因此被 UI 修改后、再次重启会被文件重新覆盖。配置文件的查找位置与顶层结构文件查找路径Metabase 启动时按以下优先级寻找配置文件对应 file.clj 中的path函数逻辑由环境变量MB_CONFIG_FILE_PATH显式指定的路径若已设置则只尝试该路径当前工作目录即运行 metabase.jar 所在的目录下名为config.yml的文件当前工作目录下名为config.yaml的文件。源码会对这些候选路径逐一检查是否存在找到了会以洋红色日志打印 Found config file at path ...否则会提示 No config file found ... 并按常规流程启动。顶层version与config配置文件整体被拆成version和config两部分version: 1 config: settings: - ... users: - ... databases: - ... api-keys: - ...version是一个必填键它只是供你维护配置文件版本使用的便利字段。源码file.clj规定当前版本只接受1.0 ~ 1.999含两端范围内的数字超出范围 spec 校验会直接失败。它并非语义化版本而是简单的浮点版本号Metabase 45 引入了 1.0 规格未来向后兼容的演进使用 1.x破坏性变更才会推进到 2.0。分节的初始化顺序config下的四个合法分节另有分节方法注册在 interface 中并非按书写顺序执行。源码的sort-by-initialization-orderfile.clj强制把settings分节排在最前面执行其余分节users、databases、api-keys随后按原顺序处理。这样设计是因为 settings 可能影响后续分节的执行例如关闭同步、设置站点名等。此外还有一个容易被忽略的细节每个分节的 spec 校验发生在模板展开之前这是为了避免在日志的 spec 错误信息里泄露环境变量中的敏感值见 file.clj 与 interface 中section-spec的注释。Users 分节启动时创建/更新用户一个 Metabase 实例中第一个被创建的用户是管理员。配置文件中第一个列出的用户并不一定就是管理员如果该实例已经完成过初始化有人已首次登录设置过则首位用户按普通用户加载只有当实例尚未 setup源码用setup/has-user-setup判断时配置文件中创建的第一个用户才会被强制提升为管理员。此外你随时可以通过is_superuser: true显式把一个用户指定为管理员。在下面的例子中假设该 Metabase 尚未完成首次设置那么firstexample.com与adminexample.com都会是管理员——前者因为它是列表中第一个用户后者因为它带is_superuser: true标记version: 1 config: users: - first_name: First last_name: Person password: metabot1 email: firstexample.com - first_name: Normal last_name: Person password: metabot1 email: normalexample.com - first_name: Admin last_name: Person password: metabot1 is_superuser: true email: adminexample.com如果该 Metabase 已完成过初始化已存在首位用户那么firstexample.com将被加载为一个普通用户。从源码实现users.clj可以确认以下几点行为必填字段为first_name、last_name、password、emailconfig-file-spec中四个字段全部req-unis_superuser属于可选键。邮件会先被统一转为小写再入库与:model/User层的统一行为一致。密码不直接写入 User 表而是通过auth-identity/set-password!存入独立的 AuthIdentity——所以绝不要在业务代码中把明文密码交给 User 模型。若目标 email 已存在则更新已有用户且login_attributes采取合并保留策略不会整表覆盖。若 email 不存在则创建新用户创建与密码写入被包在同一个事务中保证二者原子落地。Databases 分节启动时创建/更新数据源连接每个 database 条目要求至少提供name、engine、details三个键见 databases.clj可选键还包括settings、is_stub、is_sample以及 uploads 相关配置。下面是一个同时创建管理员账号和一条 PostgreSQL 连接的新实例示例version: 1 config: users: - first_name: Cam last_name: Era password: 2cans3cans4cans email: camexample.com databases: - name: test-data (Postgres) engine: postgres details: host: localhost port: 5432 user: dbuser password: {{ env POSTGRES_TEST_DATA_PASSWORD }} dbname: test-data要确定某个数据库引擎可以填写哪些details键直接对照 Metabase 界面中添加数据库表单里展示的字段即可源码 spec 对details只约束为map?具体字段交由连接层校验。关于databases分节的执行语义databases.clj连接探测除非条目标记为is_stub: true占位桩Metabase 会先尝试用details连接一次目标数据库失败则直接抛异常终止——这就保证了配置文件不会把你写坏的库静默入库。按 engine name 匹配已有库若已存在同名同引擎的数据库则以配置文件中的details等字段更新该条目即文档所说的已存在的数据库会被配置内容更新。不存在则新建新建的库默认会触发一次sync-database!同步受config-from-file-sync-databases设置控制详见后文。is_sample: true这是重建内置 Sample Database 的专用写法要求name必须是官方样例库名且engine必须为h2否则抛错其details会被忽略因为样例库始终使用随包附带的 H2 文件sample-data/extract-and-sync-sample-database!。条目内的delete键是面向托管服务的内部删除标记取值为固定的DELETE_WITH_DEPENDENTS:name魔法字符串源码注释明确它是subject to breaking changes的内部功能普通部署不应依赖。在数据库上启用文件上传uploads你可以在同一条 database 记录里追加以下三个键来配置数据上传功能uploads_enabledBoolean是否允许向该库上传。uploads_schema_nameString上传表所在 schema。uploads_table_prefixString上传表前缀。version: 1 config: users: - first_name: Cam last_name: Era password: 2cans3cans4cans email: camexample.com databases: - name: test-data (Postgres) engine: postgres details: host: localhost port: 5432 user: dbuser password: {{ env POSTGRES_TEST_DATA_PASSWORD }} dbname: test-data uploads_enabled: true uploads_schema_name: uploads uploads_table_prefix: uploads_更多细节可参见 uploads 使用文档。API keys 分节用配置文件固化 API Key配置文件可以用来创建 API Key。这对自动化部署以及让 API Key 跨环境保持稳定非常有用——例如 CI 脚本、数据同步任务可以在每次启动后都拿到同一个 key而无需人工到界面复制。version: 1 config: users: - first_name: Cam last_name: Era password: 2cans3cans4cans email: camexample.com api-keys: - name: Admin API key group: admin creator: camexample.com key: mb_firsttestapikey - name: All Users API key group: all-users creator: camexample.com key: mb_secondtestapikey也可以用一个环境变量来注入 API Key 的取值api-keys: - name: ENV API Key key: {{env API_KEY_FROM_ENV}} creator: adminexample.com group: admin关于模板引用详见下一节在 config.yml 中引用环境变量。API Key 的格式要求与生成你在配置里提供的key必须满足格式mb_ Base64 串即mb_后跟字母与数字最短 12 个字符、最长 254 个字符。精确地说必须匹配正则mb_[A-Za-z0-9/]。源码校验api_keys.clj同时要求长度落在 11254配合mb_前缀后即文档所述的 12254 语义并匹配该正则。可以用openssl rand生成合规的 keyecho mb_$(openssl rand -base64 32)输出形如mb_aDqk1Tc4ZotWb2TyjHY71glALKlBg75dLgmSufWGLcAPI Key 分节的行为约定creator必须是管理员要么你的实例里已存在至少一个管理员账号要么就在本配置文件的users分节里新增一个带管理员权限的账号。group只能二选一admin或all-users。配置文件把可选分组限定在这两个因为它们是 Metabase 在初始化阶段总是存在的内建分组。源码用perms/admin-group与perms/all-users-group解析出对应的 group-id。key 的权限跟随其所属group而不是它的creator。同名 Key 不会被覆盖如果 Metabase 发现已有与配置中同名的 API Key它会保留现有 Key跳过创建并打印日志。这意味着若你后来在 UI 里重新生成了某个 key那么重启加载配置文件也不会覆盖这个新 key配置里写的旧key自然就失效了。如果想用配置文件强制覆盖需要先在 UI 中删除现有 key再重启加载若想同时保留两个 key则需要在配置文件里给新 key 改名。Key 前缀必须全局唯一源码会先对 key 计算前缀并检查api-key-prefix-exists?若前缀已被占用会直接抛错。另外要区分两个容易混淆的概念api-keys分节真正创建 API Key而settings分节里也有一个名为api-key的设置键那个并不会创建任何 Key它只是用于在鉴权/notify端点的请求头时做字符串匹配详见环境变量文档中MB_API_KEY的说明。在 config.yml 中引用环境变量如上文示例所示配置文件支持以模板标签的形式引用环境变量setting: {{ env POSTGRES_TEST_DATA_PASSWORD }}注意模板必须被引号包裹。如果去掉引号YAML 解析器就无法把它识别为待 Metabase 展开的字符串模板Metabase 也就不会用环境变量值去替换它。模板展开的底层机制很有意思源码file.clj复用了 SQL 查询中解析模板参数的那套代码metabase.lib.parameters.parse把{{env SOME_VAR}}形式解析为 EDN 后再按类型分发展开。这带来两个推论目前env是唯一受支持的模板类型expand-parsed-template-form的 default 分支会对未知类型抛错未来可以按需扩展。由于底层兼容可选模板语法某些场景下你也能得到类似的容错行为。模板中的变量名解析对大小写不敏感且lisp-case/snake_case写法均可用它底层走environ.core/env因此也支持 Java 系统属性把属性名中的点换成斜杠或下划线即可例如{{env user-dir}}可读取系统属性user.dir。同时需要注意Metabase 不支持递归展开。如果某个环境变量的值本身又引用了另一个环境变量比如值里包含{{env ...}}解析不会逐层展开结果只会令你困惑——请避免这种用法。含有特殊字符的值三重花括号转义当某个值本身含有双花括号}}或{{时YAML 解析器会误以为它是一个待展开的模板。此时必须改用三重花括号包裹指示配置解析器按字面值处理。例如密码为MetaPa$$123{{需要写成password: {{{ MetaPa$$123{{ }}}注意这里同样保留外层引号。展开逻辑对应源码中的正则分支file.clj命中^\{\{\{(.)\}\}\}$的字符串会被原样 trim 后作为字面值返回不再走模板解析。关闭数据库创建时的自动同步当你要从一份序列化导出serialization export加载数据模型时通常不希望调度器自动去同步数据库以免干扰你预期的元数据状态。要关闭初始数据库同步可以在settings列表中写入config-from-file-sync-databases并设为false。注意该设置项必须出现在databases列表之前version: 1 config: settings: config-from-file-sync-databases: false databases: - name: my-database engine: postgres details: ...该设置与同步逻辑的对应关系清晰体现在 databases.clj新建数据库后仅当config-from-file-sync-databases为真时才会把sync-database!任务提交到后台为假时则打印 Sync on database creation when initializing from file is disabled. Skipping sync.。此设置在配置模板中的默认值是true。小提示官方文档正文里曾出现单数写法config-from-file-sync-database但代码、官方示例与配置模板中实际使用的键均为复数形式config-from-file-sync-databases请以复数形式为准。Settings 分节任意 Admin 设置在settings分节中你可以指定任意 Admin 设置。它由 settings.clj 逐键处理已注册的设置直接set!未注册的键只会打一条 warning 并跳过。键的命名转换规则settings 分节的键与环境变量之间存在固定的命名转换关系。环境变量是尖叫蛇形 MB_前缀MB_NAME_OF_VARIABLE对应到配置文件则转换为小写连字符形式name-of-variable例如要把MB_EMAIL_FROM_NAME写进config.ymlversion: 1 config: settings: config-from-file-sync-databases: false email-from-name: Stampy von Mails-a-lot databases: - name: my-database engine: h2 details: ...任何 Admin 设置都能在配置文件中设置可设置的完整清单见配置文件模板它逐项列出了当前实例所有可配置设置及其默认值也可以对照环境变量文档查找不过要注意并非所有环境变量都能通过配置文件设置两者能力范围并不完全等价。如何生成当前版本的配置模板配置模板文档由仓库内脚本实时生成。进入仓库顶层目录后执行clojure -M:doc:ee config-template即可重新生成 docs/configuring-metabase/config-template.md。模板中自上而下给出了users、databases、api-keys、settings四个分节的完整示例其中 settings 条目附带了默认值——模板注释建议删掉或注释掉你不打算设置的那些键。一个容易被忽略的特殊点settings 分节是唯一豁免项从源码的启动校验逻辑file.clj可以看到除settings分节外其余每个分节在执行前都会校验premium-features/enable-config-text-file?未携带对应 feature 的 Token 会直接抛错而settings分节是唯一的例外源码注释写的是 the lone carve-out — you may need it toinstallthe token。也就是说即使实例尚无可用的 Premium Tokensettings分节仍可先执行——这为你通过配置文件安装/写入premium-embedding-token等设置预留了入口。让新实例从配置文件启动由于从配置文件加载属于 Pro/Enterprise 功能对全新安装而言需要先用环境变量MB_PREMIUM_EMBEDDING_TOKEN为 Metabase 提供许可证 TokenMB_PREMIUM_EMBEDDING_TOKEN[your token] java --add-opens java.base/java.nioALL-UNNAMED -jar metabase.jar将上面命令中的[your token]替换为你的实际 Token并把config.yml放在运行该命令的工作目录下或用MB_CONFIG_FILE_PATH指向文件Metabase 即会在启动完成后按文件内容完成用户、数据库、API Key 与设置的初始化。你会在日志中看到类似 Initializing users from config file... 与 Done initializing from file. 的提示可用于确认加载成功。小结与常见坑位速查关注点结论覆盖语义配置文件中的设置在每次重启时覆盖 UI 中做出的修改环境变量则不受影响且不可被 UI 修改文件位置运行 JAR 目录下的config.yml/config.yaml或用MB_CONFIG_FILE_PATH指定版本号version必填当前支持1.0~1.999初始化顺序settings最先执行其次为 users/databases/api-keys 等其他分节首位用户仅在实例尚未 setup 时自动成为管理员否则需显式is_superuser: true数据库按 enginename 匹配更新新建会默认同步除非先声明config-from-file-sync-databases: falseAPI Key格式mb_[A-Za-z0-9/]长度 12~254同名 Key 跳过不覆盖prefix 必须唯一环境变量写法{{ env VAR }}务必带引号不支持递归展开特殊字符含{{/}}的值用三重花括号{{{ ... }}}包成字面量如需继续深入可以继续阅读仓库内的配置文件模板、环境变量参考或直接阅读 EE 实现源码 file.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考