Metabase Cloud 自定义域名CNAME 配置、Site URL 联动与邮件域名管理完整指南【免费下载链接】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 Cloud托管版中系统默认会为你的实例自动分配一个以metabaseapp.com结尾的域名形如yourcompany.metabaseapp.com。而本指南介绍的是在Pro / Enterprise 计划下通过 Metabase Store 为实例绑定自有域名Custom domain并理解这一操作如何联动影响实例的Site URL、邮件链接、SSO 回调与嵌入embedding场景。读完本文你将掌握添加自定义域名的完整操作路径、DNS CNAME 记录的配置方法、SSO 与邮件服务的配套调整以及修改 DNS 别名和自带 SMTP 服务器的具体入口。一、为什么默认域名不够用默认情况下Metabase Cloud 会为每个实例自动提供域名。对大多数内部使用场景默认域名已经够用但当你把 Metabase 作为面向客户的产品能力交付时通常需要白标White-labeling打磨当你在对 Metabase 做白标定制时自定义域名能进一步弱化 Metabase 品牌痕迹让最终用户感觉是在使用你自己的产品界面。品牌与内部工具一致性企业内部工具往往遵循统一的命名规律例如crm.yourcompany.com、ops.yourcompany.com为 Metabase 绑定stats.yourcompany.com一类的地址能让多个系统在视觉与域名上保持一致。注意自定义域名能力属于Pro 与 Enterprise 计划的范畴Starter 计划无法开启。因此后续所有操作都需在对应付费计划的 Store 账户中完成。二、先理解自定义域名与 Site URL 的关系设定自定义域名后Metabase 会自动更新实例的Site URL站点 URL。Site URL 是 Metabase 中非常核心的一个全局设置从源码的定义可见其重要性(defsetting site-url (deferred-tru (str This URL is used for things like creating links in emails, auth redirects, and in some embedding scenarios, so changing it could break functionality or get you locked out of this instance.)) ... :doc This URL is critical for things like SSO authentication, email links, embedding and more. Even difference with http:// vs https:// can cause problems. ...)以上定义位于 src/metabase/system/settings.clj其说明文本明确指出该 URL 用于邮件中的链接、认证重定向以及部分嵌入场景。同时源码对site-url做了防御性处理:setter在写入前会执行normalize-site-url规范化并且当新的 Site URL 不是https:开头时会自动关闭强制 HTTPS 重定向redirect-all-requests-to-https以避免自锁。:getter读取失败时不会抛异常而是记录错误并暂时返回nil在下一次请求时重置。也就是说在自托管版本里 Site URL 通常通过Admin Settings General手工设置见 General settings而 Metabase Cloud 上不允许你在管理后台直接修改Site URL——该设置只读正确做法就是通过本指南的添加自定义域名流程来更新它官方文档在 Site URL 一节也做了明确说明该功能仅对自托管版本可用Cloud 用户请参考自定义域名文档。Site URL 具体影响哪些功能从 Site URL 文档 与仓库中其他模块的引用可以确认Site URL 至少影响以下几类链路邮件与订阅/告警中的链接系统邮件密码重置、新人引导、看板订阅与告警通知中生成的跳转地址都基于 Site URL 拼接。相关实现散见于 channel/email/messages.clj、channel/urls.clj 等模块。SSO 认证回调SAML 的 URL the IdP should redirect back to 通常是{Site URL}/auth/sso例如站点 URL 为https://metabase.yourcompany.com时回调地址即https://metabase.yourcompany.com/auth/sso详见 SAML 配置OIDC 则要求 IdP 中的重定向 URI 为{site-url}/auth/sso/{key}/callback见 authenticating-with-oidc.md。Site URL 变更后这些由外部 IdP 保存的回调地址必须同步更新。嵌入Embedding无论是 全应用嵌入 还是 静态嵌入生成的 iframesrc或embedURL 都以 Site URL 为前缀例如metabase_site_url/embed/question/your_jwt_token?...。三、为你的 Metabase 添加自定义域名按照以下步骤操作登录你的Metabase Store 账户Metabase Cloud 的实例、订阅与计费都在 Store 中管理。进入Instances实例列表。找到要添加自定义域名的实例点击Settings。找到Custom domain自定义域名区块。输入你的自定义域名例如your.custom.domain。点击Update保存。这一步是关键——你需要让DNS 记录的管理者添加一条指向如下地址的CNAME 记录us-1.cd.metabaseapp.com于是你的 CNAME 记录大致形如CNAME your.custom.domain us-1.cd.metabaseapp.com请注意这条 CNAME 记录要配置在你自己托管 DNS 记录的地方域名服务商控制台等而不是填进 Metabase Store。如果你此前已经为 Metabase 配置了SSO例如 SAML 或 LDAP那么还需要回到身份提供商IdP的配置中把 return URL / 回调地址更新为包含新自定义域名的完整地址参见上文 Site URL 对 SSO 的影响以及 authenticating-with-saml.md 中/auth/sso回调的写法。CNAME 生效可能需要等待一段时间DNS 传播延迟是 DNS 本身的机制决定的Metabase 无法控制。生效后Metabase 会替你完成剩余工作确保自定义域名会把用户引导到你的 Metabase该域名已配置好SSL 证书可以通过 HTTPS 安全地访问实例metabase.com/cloud/login登录流程不受影响工作正常。另一个重要特性是原来自动分配的域名如yourcompany.metabaseapp.com依然可以访问。因此已有嵌入链接可以继续工作不必担心切换后旧地址立刻失效这为平滑迁移留出了缓冲时间。与区域切换change region的联动如果你后续在 Store 中把实例迁移到其他托管区域Region自定义域名场景下的切换耗时可能更长——最长可达24 小时。这一延迟同样来自 DNS 传播而非 Metabase 自身。因此官方建议把区域切换安排在用户使用率较低的时间段进行详见 Changing which region your Metabase is hosted in。如果在实例所在区域的 IP 白名单里做过过滤区域切换后还需同步更新各区域 IP 列表见 IP addresses to whitelist。四、修改你的 DNS 别名实例名称如果你只想调整实例的默认别名即metabaseapp.com之前的子域名部分而不想绑定完整自定义域名可以按如下流程操作登录 Metabase Store 账户。进入Instances。找到DNS AliasDNS 别名区块。输入新的别名。点击Update。例如把yourcompany.metabaseapp.com改为其他别名DNS 别名部分会替换但整体仍然归属于metabaseapp.com域之下。五、自定义 SMTP让 Metabase 从你自己的域名发信默认情况下Metabase Cloud 会替你托管并管理一台 SMTP 服务器也就是说你不需要自己配置发信服务即可使用订阅、告警等功能默认配置见 Set up email on Metabase Cloud。但如果你希望改变 Metabase 用于发送邮件所使用的发件人域名则需要自带自定义 SMTP 服务器Custom SMTP server属于 Pro / Enterprise 功能入口为Admin Settings Email Set up a custom SMTP server。常见的动机包括自定义发件人域名From domain例如配合白标化使用你自己的企业域避免邮件经由第三方服务商转发自主掌握 IP 信誉、日志、监控与审计。在 Cloud 实例上配置自定义 SMTP 时需要填写以下字段详见 email.md 的 Custom SMTP 章节字段说明SMTP HOST处理你邮件的 SMTP 服务器地址例如smtp.yourservice.comSMTP PORTSMTP 服务器用于外发邮件的端口。Cloud 仅支持加密端口465SSL、587TLS、2525STARTTLSSMTP SECURITY连接采用的加密协议SSL/TLS/STARTTLSSMTP USERNAMESMTP 账户用户名SMTP PASSWORDSMTP 账户密码配置完成后即可进入常规的邮件设置项进行进一步定制。需要注意的关键点是当 SMTP 服务器由 Metabase Cloud 托管时你无法修改发件人From地址邮件始终从 Metabase 的地址发出只有自带 SMTP 服务器后Metabase 才能从你自己的域名发信。你也可以随时在Cloud 托管的服务器与自定义 SMTP 服务器之间来回切换设置都可随时编辑。提示如果你同时使用自定义域名与自定义 SMTP建议让两者保持一致——域名指向统一的自有品牌域发件域名也使用同一域名从而让整个邮件链路跳转链接与发件人都呈现统一的品牌面貌。六、完整操作时序一览把以上内容串成一次完整的品牌化改造操作顺序在 Metabase Store 中为实例配置Custom domain并保存在 DNS 服务商处添加 CNAMEyour.custom.domain → us-1.cd.metabaseapp.com若配置过 SSO同步更新 IdP 侧 return URL / redirect URI 为新域名下的地址等 DNS 与 SSL 证书生效后用新域名验证 HTTPS 访问 5.可选在Admin Settings Email中配置自定义 SMTP绑定自有发件域名旧默认域名继续保留可逐步把历史嵌入链接与用户书签迁移到新域名。延伸阅读Metabase Cloud 总览Cloud 托管服务的文档索引含区域切换、IP 白名单等设置项入口Metabase Cloud 与自托管对比了解两种部署形态的能力边界General settingsSite URL 的手工配置入口仅自托管版本可用Cloud 用户请走自定义域名流程白标化 Metabase与自定义域名配套使用的视觉定制能力SMTP 邮件设置Cloud 托管 SMTP 与自带 SMTP 的完整字段说明site-url 设置项源码理解该设置为何会联动 HTTPS 重定向与认证回调。【免费下载链接】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），仅供参考