企业官网建设流程全解析

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 的故障排查体系围绕“先收集信息、再分层定位、最后定向修复”展开：从一键导出的诊断信息（Diagnostic Info）、浏览器 HAR 文件、服务器日志到 JVM 性能剖析，再到数据库连接、超时与性能问题的专项排查。本文以 docs/troubleshooting-guide/index.md 为主线骨架，逐层展开每类问题的检测方法与修复步骤，并结合仓库源码（默认日志配置、连接池设置等）补充底层依据，帮助你建立一套可复用的排障 SOP。

故障排查的整体框架：按问题域组织，先取证后修复

Metabase 的排障文档按“问题域”分类组织，每一类都遵循“症状 → 原因 → 检测 → 修复”的闭环。整体分类如下：

排障的第一原则是先定位问题发生层：是浏览器端（前端 JS、网络请求）、Metabase 应用层（JVM、服务器日志）还是数据源层（数据库服务器）？以下各节按这条链路依次展开。

第一步：收集诊断信息（Diagnostic Info）

当你需要向他人求助或自行深挖问题时，最有效的做法是导出 Metabase 的诊断信息——一个结构化的 JSON 文件。

打开诊断信息弹窗

• 在页面任意位置按下Cmd + F1（Mac）或Ctrl + F1（PC）；
• 或者按Cmd/Ctrl + K唤起命令面板（Command Palette），搜索 "Diagnostic"，选择Open diagnostic error modal。

可包含的信息类型

在弹窗中勾选希望写入诊断 JSON 的内容，包括：

• Item definition：当前条目定义（例如某个仪表盘的元数据定义）；
• Browser error messages：浏览器端错误信息；
• All server error messages：全部服务器错误信息；
• All server logs：全部服务器日志；
• Server logs from the current user only：仅当前用户的服务器日志；
• Metabase instance version information：实例版本信息。

需要注意：Metabase 实际采集哪些数据，取决于你发起诊断时所在的页面（例如在某个仪表盘页发起，才会包含该仪表盘的定义）。

⚠️ 分享诊断文件前务必先检查内容，因为诊断信息可能包含敏感数据（会话、凭据、用户信息等）。

服务器日志与控制台日志的获取

Metabase 会在服务器与浏览器控制台两侧分别记录错误，取决于错误发生在哪一层：

• 服务器日志：管理员可在界面右上角点击网格图标 > Admin > Tools > Logs（新版界面位于Monitor > Application logs）查看；自托管部署时也可直接在运行 Metabase 的终端中查看。读取方法见 server-logs.md。
• 浏览器控制台：Metabase 会将调试信息与错误输出到浏览器开发者工具控制台，任何用户都可以按浏览器对应方式打开开发者工具查看（Chrome/Edge 的 DevTools、Firefox 的 Web Console、Safari 的 Web Inspector）。
• HAR 文件：浏览器记录的完整网络请求日志，详见下文。

第二步：读懂 Metabase 服务器日志

日志是排障的核心证据。下面是一条真实风格的查询请求日志（出自 server-logs.md）：

2021-07-07 15:53:18,560 DEBUG middleware.log :: POST /api/dataset 202 [ASYNC: completed] 46.9 ms (17 DB calls) App DB connections: 1/10 Jetty threads: 3/50 (4 idle, 0 queued) (72 total active threads) Queries in flight: 0 (0 queued); h2 DB 4 connections: 0/1 (0 threads blocked)

逐字段拆解如下：

从源码看默认日志配置

Metabase 使用 Log4j 2 作为日志框架，仓库根目录的 resources/log4j2.xml 是默认配置，其中关键的 Logger 设置如下（与文档中的自定义示例一致）：

<Loggers> <Logger name="com.mchange" level="ERROR"/> <Logger name="liquibase" level="INFO"/> <Logger name="metabase" level="INFO"/> <Logger name="metabase-enterprise" level="INFO"/> <Logger name="metabase.metabot" level="DEBUG"/> <Logger name="metabase.plugins" level="DEBUG"/> <Logger name="metabase.query-processor.async" level="DEBUG"/> <Logger name="metabase.server.middleware" level="DEBUG"/> <Logger name="org.quartz" level="INFO"/> <Root level="WARN"> <AppenderRef ref="STDOUT"/> </Root> </Loggers>

从源码可见：metabase与metabase-enterprise默认 INFO，metabase.plugins、metabase.query-processor.async、metabase.server.middleware默认 DEBUG，com.mchange（c3p0 连接池）默认 ERROR。测试环境另有 test_config/log4j2-test.xml 可供参考。

临时调整日志级别（无需重启）

在Monitor > Application logs页面点击Customize log levels，可选用常用排障预设，或直接以 JSON 提交自定义配置。例如排查联动过滤器（linked filters）问题时可以临时提高以下命名空间的日志级别：

{ "metabase.parameters.chain-filter": "debug", "metabase.parameters.chain-filter.dedupe-joins": "debug" }

该覆盖是临时的：可以指定生效时长（如 60 分钟），超时后自动回退到默认配置（或你自定义的 log4j2 文件）。

使用自定义 log4j 配置文件

1. 复制一份默认的 resources/log4j2.xml；
2. 按需调整各 Logger 的级别。例如打开同步/指纹/扫描相关的 TRACE 日志：

   <Logger name="metabase.sync" level="TRACE"/>

3. 重启 Metabase 并指向自定义文件：
   • Docker 方式（通过JAVA_OPTS注入）：

     docker run -p 3000:3000 -v $PWD/my_log4j2.xml:/tmp/my_log4j2.xml -e JAVA_OPTS=-Dlog4j.configurationFile=file:/tmp/my_log4j2.xml metabase/metabase

   • JAR 方式（通过-Dlog4j.configurationFile参数）：

     java -Dlog4j.configurationFile=file:/path/to/custom/log4j2.xml -jar metabase.jar

开启 Jetty 调试日志与日志显示控制

• 若需查看 Web 服务器（Jetty）的详细日志，在<Loggers>节点中增加<Logger name="org.eclipse.jetty" level="DEBUG"/>。注意 Jetty 的 DEBUG 日志非常冗长，可能反而干扰定位。
• 默认日志会包含 emoji 与颜色输出，可通过环境变量关闭：

  export MB_EMOJI_IN_LOGS="false" export MB_COLORIZE_LOGS="false" java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

  相关环境变量的完整说明见 environment-variables.md。

第三步：创建 HAR 文件定位性能与网络问题

HAR（HTTP Archive）文件记录了浏览器产生的全部网络请求，适合排查 Metabase 的性能问题与请求链路异常。

⚠️ 录制 HAR 会包含敏感信息（会话 Cookie、认证信息等）。仅在明确要求且确需诊断会话/认证类问题时录制；分享前务必用文本编辑器检查文件内容。

Chrome 与 Edge 中的录制步骤

1. 打开开发者工具（页面任意位置右键 →Inspect）；

2. 切换到Network标签，网络日志自动开始录制；

3. 点击开发者工具顶栏的齿轮图标进入设置，在Network区域勾选Allow to generate HAR files with sensitive data：

4. 保持 Network 标签页打开并处于录制状态，复现问题；

5. 复现完成后，点击标签栏下方工具栏最右侧的下载图标，选择Export HAR (with sensitive data)…保存文件。

Firefox 中的录制步骤

1. 打开开发者工具（右键 →Inspect）；
2. 切换到Network标签；
3. 在录制状态下复现问题；
4. 在网络请求列表任意位置右键，选择Save All As HAR。

Safari 中的录制步骤

1. 若未开启开发者菜单：Safari > 设置 > 高级，勾选Show features for web developers；
2. 通过开发 > 显示 Web 检查器或右键 →检查元素打开开发者工具；
3. 切换到Network标签（自动开始录制）；
4. 复现问题；
5. 点击 Network 标签右上角的Export。

HAR 文件与服务器日志、诊断 JSON 组合使用，可以覆盖“浏览器发起请求 → Metabase 处理 → 数据库响应”的完整链路。

第四步：内存与 JVM 问题排查

Metabase 以 JAR 形式运行在 JVM 上，因此 JVM 与文件系统的异常都会阻止其正常运行（详见 running.md）。

Java 版本要求

当前仓库要求的运行版本为Java 25（更旧版本不受支持），且应选择所选主版本号下的最新次版本。官方建议单台服务器只运行一个 Java 版本；若多个应用需要不同 Java 版本，优先使用容器隔离。

区分 Metabase 内存与 JVM 内存

• JVM 会恒定占用约机器内存的1/4（可通过参数调整）；
• Metabase 只使用 JVM 分配到的这部分内存，并会释放不再使用的部分；
• 但 JVM 不会把空闲内存归还给操作系统，因此从机器视角看 JVM 始终占用那份固定内存。

例如一台 8 GB 内存的机器，JVM 默认占用约 2 GB，Metabase 只在这 2 GB 内活动，但机器侧看到的内存占用始终是 2 GB。

两个典型内存红旗

1. java.lang.OutOfMemoryError: Java heap space：常见于共享主机等无法正确探测可用内存的环境，解决办法是增大 JVM 堆内存（见下）。
2. 内存使用随时间呈锯齿状（sawtooth）：Metabase 快速消耗内存 → 触发垃圾回收（GC）→ 释放 → 再快速消耗，循环往复。频繁 GC 会占用大量 CPU 拖慢应用。可通过 Prometheus 指标jvm_memory_bytes_used{area="heap"}观察，监控接入方式见 observability-with-prometheus.md。

增大 JVM 堆内存

使用-X系列参数（以 2 GB 为例）：

java -Xmx2g -jar metabase.jar

经验法则：为机器上其他进程至少预留 1～2 GB 内存，例如 2 GB 内存机器设-Xmx1g，4 GB 机器设-Xmx2g。Docker 场景下通过JAVA_OPTS注入：

docker run -d -p 3000:3000 -e "JAVA_OPTS=-Xmx2g" metabase/metabase

在 OOM 时自动导出堆转储（Heap Dump）

如果实例运行一段时间后才 OOM，可能是某个具体事件（如大查询）触发。可在启动参数中启用 OOM 时的堆转储：

java -Xmx2g -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/path/to/a/directory -jar metabase-jar

• -XX:HeapDumpPath指定 hprof 文件输出目录（默认当前目录）；
• hprof 文件可能和-Xmx一样大，请确保磁盘空间充足；
• 可用 JDK 自带的jhat或 Eclipse Memory Analyzer Tool（MAT）分析。

两个可忽略的告警

• WARNING: sun.reflect.Reflection.getCallerClass is not supported. This will impact performance.：此警告可以安全忽略，Metabase 运行正常；
• 若遇到文件读写权限类 IOError（如无法读取 SQLite 数据库或自定义 GeoJSON 地图文件），参考 docker.md 中“Metabase can't read to/from a file or directory”一节。

第五步：使用 JMX 与 VisualVM 剖析运行中的 Metabase

对于“内存吃紧”“实例卡死”“响应缓慢”这类性能问题，JVM 自带的 JMX 监控 + VisualVM 是最直接的剖析手段（详见 profiling-metabase.md）。

前置条件

• 本地安装 VisualVM：它随 OpenJDK 与 Oracle JDK 附带，位于 JDK 安装目录的bin下；部分 Linux 发行版将其独立为visualvm包。

连接本地 Metabase

如果 VisualVM 与 Metabase 在同一台机器上，这是最省事的方式——无需任何远程通信配置：正常启动 Metabase，再单独启动 VisualVM 即可看到本地进程：

连接远程 Metabase（含 Docker 容器）

远程监控（包括本地 Docker 容器内的实例）需要给 JVM 指定 JMX 系统属性。以 JAR 方式运行为例，将原命令：

java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

改为：

java --add-to-start=jmx,jmx-remote \ -Dcom.sun.management.jmxremote \ -Dcom.sun.management.jmxremote.port=1099 \ -Dcom.sun.management.jmxremote.rmi.port=1099 \ -Dcom.sun.management.jmxremote.authenticate=false \ -Dcom.sun.management.jmxremote.ssl=false \ -Dcom.sun.management.jmxremote.local.only=false \ -Djava.rmi.server.hostname=<Metabase Hostname> \ -jar metabase.jar

端口1099是常见的 RMI/JMX 端口，可换成任意可访问端口。注意：上述命令将实例开放给任何可访问者监控，仅应在受信网络环境中短时使用；如需加固连接，参见 Oracle 官方 JMX 管理文档。

Docker 容器场景：将 JMX 属性写入环境变量文件metabase-vars.env：

JAVA_OPTS=-Dcom.sun.management.jmxremote.port=1099 -Dcom.sun.management.jmxremote.rmi.port=1099 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.local.only=false -Djava.rmi.server.hostname=<Metabase Hostname>

文件要求每行一个环境变量、无多余换行，然后通过--env-file注入并暴露 JMX 端口：

docker run --env-file=metabase-vars.env -d -p 3000:3000 -p 1099:1099 -h <Metabase Hostname> --name metabase metabase/metabase

之后在 VisualVM 中：右键Add Remote Host添加远程主机 → 填入上述 hostname → 右键该主机Add JMX connection填入端口1099→ 双击打开远程 JMX 进程（Docker 场景下端口需与系统属性及映射端口一致）。

Heap Dump 与 Thread Dump

连接成功后，VisualVM 会暴露大量运行时信息，其中两个最有价值：

• Heap Dump（堆转储）：在 "Monitor" 标签页生成，快照当前时刻堆中所有对象，可用 Eclipse MAT 等工具事后分析“内存被什么占用了”；
• Thread Dump（线程转储）：在 "Threads" 标签页采集，展示每个线程在特定时刻正在执行什么、被什么阻塞。当 Metabase 看起来卡死或缓慢时，线程转储能直接指出阻塞点：

第六步：数据库连接问题的排查与修复

连接数据库失败时，核心任务是判断问题出在Metabase 侧还是数据库服务器侧（详见 db-connection.md）。

先检查 Metabase 侧

1. 进入Admin > Databases，选中目标数据库，确认连接配置没有被改动或删除；
   • 若未开始同步，点击Sync database schema；
   • 若同步耗时过长，参考 sync-fingerprint-scan.md。
2. 进入Admin > Tools > Logs，检查是否因报错导致同步失败（日志读取见上文）；若你没有 Admin 权限，需要联系 Metabase 的搭建者。

再检查数据库服务器侧

1. 确认数据仓库服务正在运行（托管服务看控制台状态；有 CLI 则登录执行查询验证）；
2. 用运行 Metabase 的机器通过其他客户端测试连通性：
   • 若通过堡垒机可访问但 Metabase 不行，检查 Metabase 的 IP 是否有权访问数据库；
   • Metabase Cloud 用户需确认已将 Metabase 的 IP 加入白名单；
3. 确认 Metabase 使用的数据库角色具备所需权限，参考 users-roles-privileges.md 授权。

常见数据库连接错误

• “Your question took too long”：界面出现该提示时，按 timeout.md 排查超时问题。
• “Connections cannot be acquired from the underlying database”：在日志中发现该错误时：
  1. 进入Admin > Databases选中目标数据库；
  2. 在Advanced options > Additional JDBC connection string options中添加trustServerCertificate=true；
  3. 点击Save。 另外注意：Metabase 版本必须支持对应数据库版本，例如早于 46 的版本不支持 Microsoft SQL Server 2022。

逐层验证连通性

• 检查端口连通（以默认 PostgreSQL 5432 端口为例）：

  nc -v your-db-host 5432

• 验证凭据（数据库名或用户/密码错误会报错）：

  psql -h HOSTNAME -p PORT -d DATABASENAME -U DATABASEUSER

• 在 Metabase 内测试连接：打开 SQL 编辑器执行：

  SELECT 1

Snowflake 走 JAR 运行时的特殊处理

若连接 Snowflake 报JDBC driver internal error: exception creating result且以 JAR 方式运行，需要在java命令中加入：

java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

完整的 JAR 运行说明见 running-the-metabase-jar-file.md。

第七步：数据库性能、超时与连接池调优

数据库本身的性能问题同样有系统化的排查路径（详见 db-performance.md）。

识别瓶颈

1. （可选）用 Usage Analytics 查看使用统计（Pro/Enterprise 计划可用）；
2. 查看数据库服务器日志，确认是否存在：表规模增长、Metabase 使用人数/频率上升、其他脚本或应用频繁访问数据库；
3. 对高频查询的表优化表结构；
4. 关键对照实验：在 Metabase 中跑一个问题，再对数据库直接执行同一查询：
   • 两者耗时接近 → 数据量或使用模式超过了数据库能力，需要给数据库扩容；
   • Metabase 中明显更慢 → 问题在 Metabase 应用层部署，需要考虑横向扩展。
5. 若脚本或第三方应用高频打库：停止脚本并清理排队查询，给脚本加超时、安排在非高峰时段运行，或对数据库做副本并将工具指向副本。

重置数据库连接（“重启大法”）

1. 进入Admin > Databases> 目标数据库；
2. 不做任何修改直接点击Save changes，即可重置 Metabase 与该数据库的连接；
3. 备选：直接从数据库侧杀掉连接。

一般 Metabase 会在挂起连接超时 10 分钟后、再 20 分钟后尝试关闭；若数据库不响应，可能需要从数据库侧主动关闭到 Metabase 的连接。

清除排队查询

当有人/某程序一次性发起大量查询（如一个卡片过多的仪表盘），查询“雪崩”会占满 Metabase 与数据库之间的所有连接，导致新查询无法执行，且排队速度超过数据库消化速度。处理方式：

1. 停止引发查询的进程；
2. 到数据库服务器上停止所有进行中的（来自 Metabase 的）查询；
3. 可选：调大MB_JDBC_DATA_WAREHOUSE_MAX_CONNECTION_POOL_SIZE连接池上限。

从源码看，该设置定义在 src/metabase/driver/settings.clj，底层对应 c3p0 连接池，默认值为 15；文档提示：当连接全部被占用时，Metabase 处理查询会变慢（需要等待可用连接）。同文件还定义了jdbc-data-warehouse-connection-pool-checkout-timeout-ms（默认0，即无限等待）与jdbc-data-warehouse-connection-pool-max-pending-checkouts（默认0，即无界排队），两者可配合使用：设置正数后，池满时的额外查询会以 HTTP 503 快速失败而不是无限排队——这对防止查询雪崩拖垮实例非常有价值。

其他性能优化项

• 重新安排或禁用同步/扫描：Metabase 默认定期对数据库执行 sync/scan 以刷新表、筛选下拉值与建议。大数据库场景可改为手动触发，见 sync-scan.md。
• 修正列的数据类型：数字、日期、时间戳被存成字符串时，Metabase 生成的查询会要求数据库实时转换，性能差。在数据库层修正 schema 类型并同步进 Metabase 即可提速。

连接与查询超时（Timeout）排查

超时问题的来源可能是：数据库连接、负载均衡器、反向代理（如 Nginx）、Jetty、云服务。定位思路是按链路逐层检查（详见 timeout.md）：

• Jetty 连接器配置（Jetty 官方协议/连接器文档）；
• 云平台的相关超时治理：如 AWS EC2 连接排障、ELB 空闲超时控制、Google App Engine 的 DeadlineExceededError 处理。

第八步：认证、权限、模型、邮件等其他问题域的快速入口

• 登录问题：无法登录时优先重置密码（managing.md 中的“重置某人的密码”与“重置管理员密码”小节）；确认站点 URL 设置（settings.md）与账号是否被停用；注意 Metabase Cloud 的商店账号密码与实例登录密码是两回事。SAML/LDAP 场景分别见 saml.md 与 ldap.md。
• 权限问题：权限不生效参考 permissions.md，行列级安全失效参考 row-and-column-security.md。
• 表缺失：连接成功但数据浏览器看不到表，参考 cant-see-tables.md；数据与数据库不一致则看 sync-fingerprint-scan.md。
• 问题/仪表盘问题：保存失败看 proxies.md，无法查看/编辑看 cant-view-or-edit.md，可视化错误看 visualization.md，仪表盘缓慢看 my-dashboard-is-slow.md，SQL 问题看 sql.md，日期时间错乱看 timezones.md，过滤器失效看 filters.md 与 linked-filters.md。
• 模型问题：参考 models.md。
• 邮件与告警：邮件发不出看 cant-send-email.md，通知类问题看 notifications.md。
• 界面报错：参考 error-message.md。

第九步：已知 Bug、产品限制与升级

如果上述指南都解决不了，很可能遇到了团队已知的 Bug 或产品限制（详见 known-issues.md）：

• 查找已知 Bug：进入 Metabase 的 GitHub issues 页面，在Label下拉中选择Type: Bug（升级后出现的问题可叠加.Regression标签），并结合功能关键词搜索；按 👍 排序可看到最常被遇到的 Bug；若命中已有 issue，点 👍 帮助团队排定优先级。
• 查找产品限制：在 Label 中选择Type: New Feature搜索——如果功能“从来就不存在”，那多半是产品限制而非回归缺陷。
• 上报新 Bug / 请求新功能：确认既非已知 Bug 也非产品限制后，按 bugs.md 提交 Bug 报告，或按 requesting-new-features.md 提交功能请求。

最后也是最值得一试的“万能药”是升级：Metabase 每个版本都会新增功能并修复 Bug。升级指南见 upgrading-metabase.md；Metabase Cloud 用户则由官方自动完成升级。自托管用户可以先查看当前版本的发布说明，确认是否已有针对所遇问题的修复，再决定是否升级。

小结：一套可复用的排障流程

结合以上内容，完整的 Metabase 排障流程可以归纳为五步：

1. 取证：按Cmd/Ctrl + F1导出诊断 JSON，按需录制 HAR 文件，同时收集服务器日志与浏览器控制台错误；
2. 读懂日志：对照“时间/级别/命名空间/路径/状态码/ASYNC/响应时间/DB calls/连接池/线程/Queries in flight”逐字段分析（必要时用 Monitor > Application logs 临时调整日志级别）；
3. 分层定位：判断问题在浏览器端、Metabase 应用层（JVM 内存、Jetty 线程、连接池）还是数据源层（数据库服务器、网络、权限）；
4. 定向修复：连接问题用nc/psql/SELECT 1逐层验证；性能问题用 VisualVM 做 Heap/Thread Dump、按 db-performance.md 排查瓶颈并调优连接池；内存问题调整-Xmx与堆转储参数；
5. 求助闭环：仍无法解决时，检索已知 Bug/产品限制，必要时提交 Bug 报告，或直接升级到最新版本。

每个分类的详细步骤均可从 index.md 一键直达，配合仓库内的 默认日志配置 与 连接池源码定义 深入理解底层行为，即可建立起对 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