Metabase 图表中日期时间和实际时区不一致怎么排查？

你在 Metabase 里对日期时间做计算，或在图表中展示它们，但出现两类现象：数值看起来不对，或汇总值（比如按天/按周的小计）不对。本文按 Metabase 官方时区排查指南 的路径，给出定位和修正这一问题的连续操作步骤：先判断问题是否由时区引起，再逐一核对四处时区设置（数据库、OS/JVM、Metabase 报表时区、部署环境），最后用下钻方法确认偏移量到底来自哪一侧。

先判断：问题是否由时区引起

文档给出的根因描述是：日期时间数据本身存储在不同的时区，而计算时部分或全部时区没有被考虑进去（即数据不一致）。要往下排查，你需要先弄清四个问题的答案：

1. 你认为显示错误的数据，它的正确时区是什么（即"正确答案"应该是什么）？
2. 数据里每个时间戳是否都带显式时区，还是有些/全部时间戳存储时不带时区？文档给的例子：Dec 1, 2019 00:00:00Z00 带时区（Z 后），而 Dec 1, 2019 不带。
3. 数据库服务器使用时区是什么？
4. Metabase 使用时区是什么？

拿到这四个答案后，对照文档列出的两种典型情形：

• 问题或图表在比较/排序时区不一致或缺失时区的值。例如航班起降时间按当地时间记录，图表里可能显得"到达早于起飞"。
• 问题在聚合来自不同时区的时间戳。例如网站流量的"每日"小计实际混入了东亚、欧洲和美洲的本地日期，一天里包含超过 24 小时的数据。

Metabase 文档（Timezones）建议的整体基线是：数据库列尽量带时区信息、数据库报表时区用 UTC 并统一存 UTC、JVM 与 Metabase Report Timezone 都设置为你想查看报表的时区，且这几处保持一致。

核对 Metabase 的 Report Timezone 设置

这是文档指出的常见根因：Metabase 使用的时区与数据仓库使用的时区不一致，导致问题或图表里的数字出错。

操作步骤：

1. 进入 Admin > Settings > Localization，检查 report timezone 设置（配置细节见 Localization）。
2. 注意 report timezone 只对以下数据库生效：BigQuery、Druid、MySQL、Oracle、PostgreSQL、Presto、Redshift、Vertica。如果你的数据库不在列表中，report timezone 不作用于它，此时要改为让 Metabase 自身的时区（即 JVM 时区）与数据库一致。

Metabase 的时区是 Java 虚拟机的时区，通常通过 -Duser.timezone<..> 参数或 JAVA_TIMEZONE 环境变量设置，具体方式取决于你如何启动 Metabase。如果你用 Docker 部署，Docker 部署文档 给出的写法是（示例值 US/Pacific，替换为你需要的时区）：

docker run -d -p 3000:3000 \
  -e "JAVA_TIMEZONE=US/Pacific" \
  --name metabase metabase/metabase

这是容器启动命令，JAVA_TIMEZONE 由 Metabase 启动脚本读取；修改它意味着按此配置重新拉起容器，请按你自己部署环境的实际参数调整。文档同时说明：Metabase（JVM）的时区不影响使用 Report Time Zone 的那些数据库。

JVM 时区与 Metabase Report Timezone 不一致被 Timezones 文档 列为常见坑之一，可用启动 Java 时设置 -Duser.timezone=<timezone> 使其与报表时区匹配来修正。

SQL 查询不尊重报表时区时怎么处理

文档给出的根因是：Metabase 会设置 session time zone，但部分数据库会忽略它。对应的两条处理路径：

• 联系数据库管理员，允许设置 session time zone；
• 或者直接在 SQL 查询里显式设置报表时区。文档以 PostgreSQL 为例：

SELECT column::TIMESTAMP AT TIME ZONE 'EST' AS column_est

这条语句先把 column 转换为 timestamp 类型，再把它转换为时区为 'EST' 的 timestamptz 类型。其中的 column、column_est 和 'EST' 按文档原样给出，替换成你自己的字段名和你需要的时区（时区名以你的数据库接受的值为准）。

日期不带时区被转换到另一天

文档给出的根因：你在按一个不带时区的日期（date 而不是 time）分组。步骤：

1. 打开 Data Model Reference，检查问题用到的每个时间字段，看是否有字段只是 "Date" 类型（不带时区）。
2. 如果存在，确保服务器时区与报表时区一致。因为查询在 Metabase 上运行时，服务器会把配置好的时区应用到该日期上。

混用显式与隐式时区

根因：你在比较或对两个日期做算术，其中一个带显式时区、另一个不带。文档建议：

1. 这种情况通常出现在使用多个字段的问题里，例如按一个时间戳过滤、按另一个分组。逐个检查问题中用到的每个日期/时间字段的时区。
2. 对不带显式时区的值显式设定时区。这需要在 SQL 查询里做，或在数据库里转换数据，保证两边时间戳都带时区。

如果在 Metabase 侧做转换，可以用 convertTimezone 表达式：对 timestamp with time zone / timestamp with offset 只需给 target，对 timestamp without time zone 必须额外提供 source。详见 convertTimezone 文档。注意该表达式目前不适用于 Amazon Athena、Databricks、Druid、MongoDB、Presto、SparkSQL、SQLite 和 Metabase Sample Database——如果你的数据库在列表中，SQL 侧显式转换是文档给出的替代路径。

用下钻方法确认偏移来自哪一侧

当你已经定位到可疑问题（比如按天展示的时间序列、周小计不对）时，文档给出的定位流程是：

1. 选一个你确定数值错误的日期。
2. 在图表上点击数据点（或结果表中的单元格），选择 "See these X"。
3. 在浏览器再开两个标签页打开这个问题：一个把日期过滤器改到前一天的底层数据行，另一个改到后一天的。
4. 检查底层展示中用于分组的日期字段是否正确。如果它与数据库里存储的值或你其他工具里的值不同，说明时间戳被整体错误地转换了——这通常发生在使用了不带显式时区的日期/时间上。
5. 如果底层时间戳本身是对的（带显式时区的数据应该是），那么各时间点大概率被按了另一个时区归组到天。
6. 在这个问题的日期过滤器上，把起始时间和起始日期每次往回拨 1 小时，直到数值变正确、或已经往回拨了 12 小时。如果你的时区涉及印度、纽芬兰或其他半小时时区，可能需要按半小时递增拨。
7. 如果往回拨无效，改为往前拨，直到数值正确或已前拨 12 小时。
8. 如果此时数值正确了，说明时区被转换了等于你手动拨动小时数的量。检查这个偏移量是否匹配数据仓库的时区或 Metabase 自身的时区。

验证与限制

完成设置后，用文档中的示例理解 report timezone 的显示边界（下表为 Localization 文档 中的示例结果，用于说明行为，不是所有环境必须复现的固定输出）：

Raw timestamp in your database	Data type	Report time zone	Displayed as
2022-12-28T12:00:00 AT TIME ZONE 'CST'	timestamp with time zone	'Canada/Eastern'	Dec 28, 2022, 7:00 AM
2022-12-28T12:00:00-06:00	timestamp with offset	'Canada/Eastern'	Dec 28, 2022, 7:00 AM
2022-12-28T12:00:00	timestamp without time zone	'Canada/Eastern'	Dec 28, 2022, 12:00 AM

两条必须记住的限制：

• Report timezone 只是显示设置，改动它不会影响数据库里数据的时区。
• Report timezone 不作用于 timestamp without time zone 数据类型，包括 convertTimezone 表达式的输出。如果你的数据恰好是第三行的类型，改 report timezone 不会改变它的显示——此时要走上面"日期不带时区"或 SQL 显式转换的路径。

文档同时给出了两个数据库侧的常见坑（Timezones）：数据库使用不带时区信息的列时，数据库会按它自身配置的时区（或默认 UTC，需向数据库厂商确认）来理解数据；JVM 时区与 Report Timezone 不一致时按前述 -Duser.timezone 方式对齐。按上面的顺序核对完四处设置并用下钻方法确认偏移后，如果数值仍与预期不符，回到四个判断问题重新核对"正确答案"的时区，而不是继续调整显示设置。