Metabase 会话过期机制完全指南MAX_SESSION_AGE、MB_SESSION_TIMEOUT 与 MB_SESSION_COOKIES 配置详解【免费下载链接】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/metabaseMetabase 的会话Session是登录态得以跨标签页、跨页面保持的核心机制而如何让会话按预期过期、何时强制登出用户直接关系到系统的安全性与用户体验。本文以 Metabase 官方文档 changing-session-expiration.md 为主体骨架结合当前仓库的会话中间件、Cookie 处理与定时清理任务的源码实现系统讲解会话过期相关的三组配置绝对会话上限MAX_SESSION_AGE、不活跃超时MB_SESSION_TIMEOUT与强制会话 CookieMB_SESSION_COOKIES。读完本文你将掌握每种过期方式的适用场景、精确的配置语法与参数取值范围并理解它们在底层是如何协同生效的。会话的生命周期Metabase 如何维持登录态当用户通过邮箱密码或 SSO 登录时Metabase 会创建一个会话使其在切换标签页、刷新页面的过程中保持登录状态。从 src/metabase/server/middleware/session.clj 的命名空间文档可以看到认证的两条主要路径会话Session认证登录成功后自动写入名为metabase.SESSION的 Cookie该 Cookie 为 HttpOnly 属性前端代码无法读取全应用嵌入full-app embedding场景下则为metabase.EMBEDDED_SESSION。此外请求头X-Metabase-Session也可用于认证此时两个 Cookie 会被忽略。API Key 认证通过X-Api-Key请求头匹配数据库中的 API Key适用于服务端自动化调用场景与会话过期机制无关。会话可以通过以下三种方式结束这也是本文后续三个章节的主题关闭浏览器受 Cookie 类型与MB_SESSION_COOKIES影响达到绝对会话年龄上限MAX_SESSION_AGE从登录时刻开始计时持续不活跃达到超时窗口MB_SESSION_TIMEOUT从最后一次活动时刻开始计时。需要特别说明的是手动清除浏览器 Cookie 或缓存会立即结束会话这一行为不受上述任何设置的约束。设定绝对会话上限MAX_SESSION_AGE语义与默认值MAX_SESSION_AGE控制一个会话从登录时刻起最多可以存活多少分钟。例如用户打开了数百个标签页且数月未重启浏览器只要达到MAX_SESSION_AGE就会被登出——即便登录时勾选了Remember me记住我复选框也无法豁免因为该上限是强制性的。类型整数默认值20160即 14 天见 src/metabase/cmd/resources/other-env-vars.md设置方式仅支持环境变量。上述文档明确写道MAX_SESSION_AGE只能通过环境变量设置无法通过配置文件config文件修改。配置示例以分钟为单位设置自定义值例如让会话在 24 小时后过期# 会话在 24 小时后过期 MAX_SESSION_AGE1440 java --add-opens java.base/java.nioALL-UNNAMED -jar metabase.jar该设置对所有人一视同仁不区分浏览器行为或活动模式。当安全策略要求用户按可预测的周期重新登录时例如每 24 小时或每周强制重新认证一次应使用此配置。底层生效机制MAX_SESSION_AGE在源码中的生效路径分为三层Cookie 有效期在 src/metabase/request/cookies.clj 中会话 Cookie 的Max-Age默认值由(* 60 (config/config-int :max-session-age))计算分钟换算为秒。也就是说即使浏览器不关闭Cookie 本身也会在到达上限后过期。服务端校验在 src/metabase/server/middleware/session.clj 中每次请求解析会话时会传入(config/config-int :max-session-age)由应用数据库查询判断会话是否已过期详见 src/metabase/server/db.clj 中的会话用户信息查询。定时清理Metabase 内置的 SessionCleanup 任务每天凌晨 2 点cron 表达式0 0 2 * * ? *运行一次删除超出MAX_SESSION_AGE、超过自身expires_at、或超过不活跃阈值的会话记录见 src/metabase/session/task/session_cleanup.clj。其底层 SQL 位于 src/metabase/session/db.clj。注意MAX_SESSION_AGE不是空闲/不活跃超时。若将其设为 15 分钟用户每 15 分钟就必须重新登录或重新认证一次无论期间是否活跃。控制不活跃多久后登出应使用MB_SESSION_TIMEOUT。按不活跃时长登出MB_SESSION_TIMEOUT功能定位与授权前提MB_SESSION_TIMEOUT控制会话在不活跃多长时间后结束。例如用户早上打开 Metabase用了一小时之后一整天都在其他工具中工作一旦不活跃时间超过设定窗口就会被登出。该功能属于Metabase 付费版EE特性在 src/metabase/premium_features/settings.clj 中定义了enable-session-timeout-config?并映射到特性令牌:session-timeout-config。对应地测试 test/metabase/server/middleware/session_test.clj 验证了未启用该付费特性时即便设置了session-timeout会话也不会因此过期。两种配置方式方式一管理员界面。进入Admin管理后台Authentication认证Overview概览页面配置。需要说明的是界面中只能以**分钟minutes或小时hours**为单位指定超时时间。方式二环境变量。使用 JSON 格式的字符串单位支持seconds秒、minutes分钟、hours小时# 不活跃 2 小时后登出 MB_SESSION_TIMEOUT{amount:120,unit:minutes} java --add-opens java.base/java.nioALL-UNNAMED -jar metabase.jar环境变量相较界面配置多支持unit:seconds这在与测试、自动化脚本对齐时更为灵活。参数校验规则从 src/metabase/request/settings.clj 的session-timeout设置定义可以确认以下规则值必须是 JSON 对象形如{amount:120,unit:minutes}unit只能是seconds、minutes、hours三者之一amount必须为正数amount-must-be-positive且不能达到 100 年amount-must-be-less-than-100-years校验失败时通过 API 或界面设置会返回 HTTP 400并附带明确的错误信息环境变量方式下则记录警告并回退为nil即不启用超时。此外src/metabase/request/cookies.clj 中的session-timeout-seconds函数将所有单位统一换算为秒并强制最小值 60 秒——这是为了防止管理员误设过短的时间导致用户把自己锁在门外。对应测试见 test/metabase/request/cookies_test.clj 与 test/metabase/request/settings_test.clj。什么算活跃这一点直接影响实际效果官方文档给出了两条关键行为开启自动刷新auto-refresh的仪表盘即使在后台标签页中也会持续产生请求因此计入活跃能不断刷新不活跃计时器定时告警scheduled alerts与仪表盘订阅dashboard subscriptions是服务端任务不会重置用户的不活跃计时器——它们本质上与用户是否在线无关。从实现上看src/metabase/server/middleware/session.clj 的maybe-update-session-activity!会更新会话的last_active_at字段并做了节流throttle处理以避免每个请求都触发数据库写入。清理任务删除空闲会话时使用的是COALESCE(last_active_at, created_at)——即优先以最后活跃时间、缺失时回退到创建时间来判断空闲时长见 src/metabase/session/db.clj。提示仅当启用了会话超时即MB_SESSION_TIMEOUT已配置时活跃度跟踪才会被激活。MAX_SESSION_AGE与MB_SESSION_TIMEOUT如何协同当两者同时配置时会话在先到达的那个限制处结束——无论用户是否活跃绝对年龄上限都会在MAX_SESSION_AGE分钟后来临而如果用户在达到年龄上限之前就长时间不活跃则会先被MB_SESSION_TIMEOUT登出。维度MAX_SESSION_AGEMB_SESSION_TIMEOUT计时起点登录时刻最后一次活跃时刻默认值20160 分钟14 天未配置无限期配置位置仅环境变量管理界面或环境变量授权要求所有版本付费版EE特性适用场景定期强制重新认证共享工作站、遗忘的打开标签页正是由于这种互补性MB_SESSION_TIMEOUT特别适合共享工作站、容易遗留的打开标签页以及任何长时间闲置会话构成安全隐患的场景即使不活跃超时窗口内用户一直开着浏览器MAX_SESSION_AGE也始终是兜底的绝对上限。强制所有人使用会话 CookieMB_SESSION_COOKIES行为差异默认情况下登录页的Remember me复选框是勾选状态因此会话使用持久 Cookie可以跨浏览器关闭与重启存活取消勾选后关闭浏览器即结束会话。MB_SESSION_COOKIEStrue会改变这一默认行为# 强制使用会话 Cookie关闭浏览器即登出且移除登录页的 Remember me 复选框 MB_SESSION_COOKIEStrue java --add-opens java.base/java.nioALL-UNNAMED -jar metabase.jar设置后登录页的Remember me复选框会被移除所有用户统一采用会话 Cookiesession cookie浏览器关闭即登出但MAX_SESSION_AGE与MB_SESSION_TIMEOUT仍然生效——从不关闭浏览器的用户同样可能被年龄上限或不活跃窗口登出。底层实现在 src/metabase/session/settings.clj 中session-cookies设置默认值为false其文档注释明确指出用户登录会话总会按MAX_SESSION_AGE默认 2 周定义的时长过期。这会覆盖登录时的 Remember me 复选框。Cookie 是否持久化的判断逻辑位于 src/metabase/request/cookies.clj 的use-permanent-cookies?函数若MB_SESSION_COOKIES已设置一律禁用持久 Cookie返回false否则回退到登录请求体中的remember字段即用户是否勾选了 Remember me。结合 src/metabase/request/cookies.clj 的set-session-cookies可以看到只有当启用持久 Cookie 时响应才会附带Max-Age指令没有Max-Age和Expires的 Cookie 属于会话 Cookie浏览器关闭即被删除。同时正常会话 Cookie 会附加HttpOnly、SameSite默认lax等属性HTTPS 请求下还会附加Secure标志。浏览器会话恢复的例外需要留意许多浏览器支持**会话恢复session restore**功能——启动时自动重新打开上次的标签页。当会话恢复处于启用状态时浏览器表现得像从未关闭过一样会话 Cookie 会跨浏览器重启持续存在。这一点通常可以在浏览器设置中配置因此MB_SESSION_COOKIEStrue的实际效果取决于终端用户的浏览器行为无法被服务端完全强制。三个配置的完整对照配置项作用类型/单位默认值配置位置版本要求MAX_SESSION_AGE绝对会话寿命上限整数分钟2016014 天仅环境变量所有版本MB_SESSION_TIMEOUT不活跃超时登出JSON单位支持 seconds/minutes/hours未配置不启用管理界面仅分钟/小时或环境变量含秒付费版EEMB_SESSION_COOKIES强制使用会话 Cookie关闭浏览器即登出布尔值false环境变量所有版本配置建议与验证方式什么时候用哪种可以参考以下思路合规驱动的固定周期重新认证如每 24 小时→MAX_SESSION_AGE安全敏感的共享设备、无人值守终端 →MB_SESSION_TIMEOUT配合MAX_SESSION_AGE兜底公共电脑或访客场景希望关掉浏览器就登出→MB_SESSION_COOKIEStrue。如何验证配置生效配置完成后可观察以下可验证信号会话 Cookie 的Max-Age与metabase.TIMEOUTCookie 的Expires值见 src/metabase/request/cookies.clj 的set-session-timeout-cookie该 Cookie 在每次请求时按请求时间重新计算过期时刻Metabase 日志中 SessionCleanup 任务的执行记录以及应用数据库core_session表中被清理的行数接口层可通过管理后台 APIPUT /api/setting/session-timeout设置超时非法值如负数、超 100 年会返回 HTTP 400对应的校验测试覆盖在 test/metabase/request/settings_test.clj。综上会话过期配置的核心要点可以概括为MAX_SESSION_AGE划定会话的绝对寿命MB_SESSION_TIMEOUT治理不活跃会话MB_SESSION_COOKIES约束关闭浏览器这一动作——三者各司其职又彼此兜底构成了 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Metabase 会话过期机制完全指南：MAX_SESSION_AGE、MB_SESSION_TIMEOUT 与 MB_SESSION_COOKIES 配置详解
Metabase 会话过期机制完全指南MAX_SESSION_AGE、MB_SESSION_TIMEOUT 与 MB_SESSION_COOKIES 配置详解【免费下载链接】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/metabaseMetabase 的会话Session是登录态得以跨标签页、跨页面保持的核心机制而如何让会话按预期过期、何时强制登出用户直接关系到系统的安全性与用户体验。本文以 Metabase 官方文档 changing-session-expiration.md 为主体骨架结合当前仓库的会话中间件、Cookie 处理与定时清理任务的源码实现系统讲解会话过期相关的三组配置绝对会话上限MAX_SESSION_AGE、不活跃超时MB_SESSION_TIMEOUT与强制会话 CookieMB_SESSION_COOKIES。读完本文你将掌握每种过期方式的适用场景、精确的配置语法与参数取值范围并理解它们在底层是如何协同生效的。会话的生命周期Metabase 如何维持登录态当用户通过邮箱密码或 SSO 登录时Metabase 会创建一个会话使其在切换标签页、刷新页面的过程中保持登录状态。从 src/metabase/server/middleware/session.clj 的命名空间文档可以看到认证的两条主要路径会话Session认证登录成功后自动写入名为metabase.SESSION的 Cookie该 Cookie 为 HttpOnly 属性前端代码无法读取全应用嵌入full-app embedding场景下则为metabase.EMBEDDED_SESSION。此外请求头X-Metabase-Session也可用于认证此时两个 Cookie 会被忽略。API Key 认证通过X-Api-Key请求头匹配数据库中的 API Key适用于服务端自动化调用场景与会话过期机制无关。会话可以通过以下三种方式结束这也是本文后续三个章节的主题关闭浏览器受 Cookie 类型与MB_SESSION_COOKIES影响达到绝对会话年龄上限MAX_SESSION_AGE从登录时刻开始计时持续不活跃达到超时窗口MB_SESSION_TIMEOUT从最后一次活动时刻开始计时。需要特别说明的是手动清除浏览器 Cookie 或缓存会立即结束会话这一行为不受上述任何设置的约束。设定绝对会话上限MAX_SESSION_AGE语义与默认值MAX_SESSION_AGE控制一个会话从登录时刻起最多可以存活多少分钟。例如用户打开了数百个标签页且数月未重启浏览器只要达到MAX_SESSION_AGE就会被登出——即便登录时勾选了Remember me记住我复选框也无法豁免因为该上限是强制性的。类型整数默认值20160即 14 天见 src/metabase/cmd/resources/other-env-vars.md设置方式仅支持环境变量。上述文档明确写道MAX_SESSION_AGE只能通过环境变量设置无法通过配置文件config文件修改。配置示例以分钟为单位设置自定义值例如让会话在 24 小时后过期# 会话在 24 小时后过期 MAX_SESSION_AGE1440 java --add-opens java.base/java.nioALL-UNNAMED -jar metabase.jar该设置对所有人一视同仁不区分浏览器行为或活动模式。当安全策略要求用户按可预测的周期重新登录时例如每 24 小时或每周强制重新认证一次应使用此配置。底层生效机制MAX_SESSION_AGE在源码中的生效路径分为三层Cookie 有效期在 src/metabase/request/cookies.clj 中会话 Cookie 的Max-Age默认值由(* 60 (config/config-int :max-session-age))计算分钟换算为秒。也就是说即使浏览器不关闭Cookie 本身也会在到达上限后过期。服务端校验在 src/metabase/server/middleware/session.clj 中每次请求解析会话时会传入(config/config-int :max-session-age)由应用数据库查询判断会话是否已过期详见 src/metabase/server/db.clj 中的会话用户信息查询。定时清理Metabase 内置的 SessionCleanup 任务每天凌晨 2 点cron 表达式0 0 2 * * ? *运行一次删除超出MAX_SESSION_AGE、超过自身expires_at、或超过不活跃阈值的会话记录见 src/metabase/session/task/session_cleanup.clj。其底层 SQL 位于 src/metabase/session/db.clj。注意MAX_SESSION_AGE不是空闲/不活跃超时。若将其设为 15 分钟用户每 15 分钟就必须重新登录或重新认证一次无论期间是否活跃。控制不活跃多久后登出应使用MB_SESSION_TIMEOUT。按不活跃时长登出MB_SESSION_TIMEOUT功能定位与授权前提MB_SESSION_TIMEOUT控制会话在不活跃多长时间后结束。例如用户早上打开 Metabase用了一小时之后一整天都在其他工具中工作一旦不活跃时间超过设定窗口就会被登出。该功能属于Metabase 付费版EE特性在 src/metabase/premium_features/settings.clj 中定义了enable-session-timeout-config?并映射到特性令牌:session-timeout-config。对应地测试 test/metabase/server/middleware/session_test.clj 验证了未启用该付费特性时即便设置了session-timeout会话也不会因此过期。两种配置方式方式一管理员界面。进入Admin管理后台Authentication认证Overview概览页面配置。需要说明的是界面中只能以**分钟minutes或小时hours**为单位指定超时时间。方式二环境变量。使用 JSON 格式的字符串单位支持seconds秒、minutes分钟、hours小时# 不活跃 2 小时后登出 MB_SESSION_TIMEOUT{amount:120,unit:minutes} java --add-opens java.base/java.nioALL-UNNAMED -jar metabase.jar环境变量相较界面配置多支持unit:seconds这在与测试、自动化脚本对齐时更为灵活。参数校验规则从 src/metabase/request/settings.clj 的session-timeout设置定义可以确认以下规则值必须是 JSON 对象形如{amount:120,unit:minutes}unit只能是seconds、minutes、hours三者之一amount必须为正数amount-must-be-positive且不能达到 100 年amount-must-be-less-than-100-years校验失败时通过 API 或界面设置会返回 HTTP 400并附带明确的错误信息环境变量方式下则记录警告并回退为nil即不启用超时。此外src/metabase/request/cookies.clj 中的session-timeout-seconds函数将所有单位统一换算为秒并强制最小值 60 秒——这是为了防止管理员误设过短的时间导致用户把自己锁在门外。对应测试见 test/metabase/request/cookies_test.clj 与 test/metabase/request/settings_test.clj。什么算活跃这一点直接影响实际效果官方文档给出了两条关键行为开启自动刷新auto-refresh的仪表盘即使在后台标签页中也会持续产生请求因此计入活跃能不断刷新不活跃计时器定时告警scheduled alerts与仪表盘订阅dashboard subscriptions是服务端任务不会重置用户的不活跃计时器——它们本质上与用户是否在线无关。从实现上看src/metabase/server/middleware/session.clj 的maybe-update-session-activity!会更新会话的last_active_at字段并做了节流throttle处理以避免每个请求都触发数据库写入。清理任务删除空闲会话时使用的是COALESCE(last_active_at, created_at)——即优先以最后活跃时间、缺失时回退到创建时间来判断空闲时长见 src/metabase/session/db.clj。提示仅当启用了会话超时即MB_SESSION_TIMEOUT已配置时活跃度跟踪才会被激活。MAX_SESSION_AGE与MB_SESSION_TIMEOUT如何协同当两者同时配置时会话在先到达的那个限制处结束——无论用户是否活跃绝对年龄上限都会在MAX_SESSION_AGE分钟后来临而如果用户在达到年龄上限之前就长时间不活跃则会先被MB_SESSION_TIMEOUT登出。维度MAX_SESSION_AGEMB_SESSION_TIMEOUT计时起点登录时刻最后一次活跃时刻默认值20160 分钟14 天未配置无限期配置位置仅环境变量管理界面或环境变量授权要求所有版本付费版EE特性适用场景定期强制重新认证共享工作站、遗忘的打开标签页正是由于这种互补性MB_SESSION_TIMEOUT特别适合共享工作站、容易遗留的打开标签页以及任何长时间闲置会话构成安全隐患的场景即使不活跃超时窗口内用户一直开着浏览器MAX_SESSION_AGE也始终是兜底的绝对上限。强制所有人使用会话 CookieMB_SESSION_COOKIES行为差异默认情况下登录页的Remember me复选框是勾选状态因此会话使用持久 Cookie可以跨浏览器关闭与重启存活取消勾选后关闭浏览器即结束会话。MB_SESSION_COOKIEStrue会改变这一默认行为# 强制使用会话 Cookie关闭浏览器即登出且移除登录页的 Remember me 复选框 MB_SESSION_COOKIEStrue java --add-opens java.base/java.nioALL-UNNAMED -jar metabase.jar设置后登录页的Remember me复选框会被移除所有用户统一采用会话 Cookiesession cookie浏览器关闭即登出但MAX_SESSION_AGE与MB_SESSION_TIMEOUT仍然生效——从不关闭浏览器的用户同样可能被年龄上限或不活跃窗口登出。底层实现在 src/metabase/session/settings.clj 中session-cookies设置默认值为false其文档注释明确指出用户登录会话总会按MAX_SESSION_AGE默认 2 周定义的时长过期。这会覆盖登录时的 Remember me 复选框。Cookie 是否持久化的判断逻辑位于 src/metabase/request/cookies.clj 的use-permanent-cookies?函数若MB_SESSION_COOKIES已设置一律禁用持久 Cookie返回false否则回退到登录请求体中的remember字段即用户是否勾选了 Remember me。结合 src/metabase/request/cookies.clj 的set-session-cookies可以看到只有当启用持久 Cookie 时响应才会附带Max-Age指令没有Max-Age和Expires的 Cookie 属于会话 Cookie浏览器关闭即被删除。同时正常会话 Cookie 会附加HttpOnly、SameSite默认lax等属性HTTPS 请求下还会附加Secure标志。浏览器会话恢复的例外需要留意许多浏览器支持**会话恢复session restore**功能——启动时自动重新打开上次的标签页。当会话恢复处于启用状态时浏览器表现得像从未关闭过一样会话 Cookie 会跨浏览器重启持续存在。这一点通常可以在浏览器设置中配置因此MB_SESSION_COOKIEStrue的实际效果取决于终端用户的浏览器行为无法被服务端完全强制。三个配置的完整对照配置项作用类型/单位默认值配置位置版本要求MAX_SESSION_AGE绝对会话寿命上限整数分钟2016014 天仅环境变量所有版本MB_SESSION_TIMEOUT不活跃超时登出JSON单位支持 seconds/minutes/hours未配置不启用管理界面仅分钟/小时或环境变量含秒付费版EEMB_SESSION_COOKIES强制使用会话 Cookie关闭浏览器即登出布尔值false环境变量所有版本配置建议与验证方式什么时候用哪种可以参考以下思路合规驱动的固定周期重新认证如每 24 小时→MAX_SESSION_AGE安全敏感的共享设备、无人值守终端 →MB_SESSION_TIMEOUT配合MAX_SESSION_AGE兜底公共电脑或访客场景希望关掉浏览器就登出→MB_SESSION_COOKIEStrue。如何验证配置生效配置完成后可观察以下可验证信号会话 Cookie 的Max-Age与metabase.TIMEOUTCookie 的Expires值见 src/metabase/request/cookies.clj 的set-session-timeout-cookie该 Cookie 在每次请求时按请求时间重新计算过期时刻Metabase 日志中 SessionCleanup 任务的执行记录以及应用数据库core_session表中被清理的行数接口层可通过管理后台 APIPUT /api/setting/session-timeout设置超时非法值如负数、超 100 年会返回 HTTP 400对应的校验测试覆盖在 test/metabase/request/settings_test.clj。综上会话过期配置的核心要点可以概括为MAX_SESSION_AGE划定会话的绝对寿命MB_SESSION_TIMEOUT治理不活跃会话MB_SESSION_COOKIES约束关闭浏览器这一动作——三者各司其职又彼此兜底构成了 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
