Speedtest-Tracker 时区问题分析与解决方案

问题背景

在 Speedtest-Tracker v0.20.3 版本中，用户报告了一个与时区相关的问题：尽管在配置中设置了本地时区（如欧洲/罗马），但测试结果显示的时间仍然是UTC时间，比实际时间晚了2小时。这个问题不仅影响历史测试结果的显示，也影响"下一次速度测试"的显示时间。

问题分析

经过深入分析，我们发现这个问题源于几个关键因素：

1. 数据库存储时间的方式：Speedtest-Tracker 默认将时间以UTC格式存储在数据库中，但在显示时没有正确转换为配置的本地时区。

2. 环境变量配置冲突：用户可能在容器中同时配置了多个时区相关的环境变量（如TZ、APP_TIMEZONE、DISPLAY_TIMEZONE），导致系统无法确定应该使用哪个时区设置。

3. 时间格式显示问题：即使时间转换正确，默认的时间格式可能不符合用户的预期显示格式。

解决方案

推荐配置方案

根据社区验证的有效解决方案，我们推荐以下配置方式：

1. 保持数据库和应用程序容器使用UTC时区：

   • 这是最佳实践，可以避免跨时区问题
   • 确保容器内执行date命令显示UTC时间

2. 仅设置DISPLAY_TIMEZONE环境变量：

   environment:
     - DISPLAY_TIMEZONE="Asia/Shanghai"  # 替换为您所在的时区
   

3. 移除其他时区相关配置：

   • 不要设置TZ或APP_TIMEZONE环境变量
   • 确保数据库容器也不设置时区变量

自定义时间格式

如果需要调整时间的显示格式，可以添加以下环境变量：

environment:
  - DATETIME_FORMAT="Y-m-d H:i"      # 表格中时间的显示格式
  - CHART_DATETIME_FORMAT="Y-m-d H"  # 图表中时间的显示格式

支持的格式参数参考PHP的date()函数格式，例如：

• Y：4位数的年份
• m：2位数的月份
• d：2位数的日期
• H：24小时制的小时
• i：分钟

注意事项

1. 对于已经存在的测试记录，时区转换可能不会自动应用到历史数据，新记录将正确显示。

2. 如果使用MySQL/MariaDB等外部数据库，确保数据库服务器本身也使用UTC时区。

3. 完整的时区名称列表可以参考PHP支持的时区标识符。

技术原理

Speedtest-Tracker在处理时间时采用以下逻辑：

1. 存储层：所有时间都以UTC格式存储在数据库中，这是国际化的最佳实践。

2. 应用层：应用程序根据DISPLAY_TIMEZONE配置，在从数据库读取时间数据后进行时区转换。

3. 显示层：转换后的本地时间再根据DATETIME_FORMAT和CHART_DATETIME_FORMAT配置进行格式化输出。

这种分层处理方式确保了系统在不同时区环境下都能正确工作，同时提供了灵活的显示配置选项。

总结

通过正确配置DISPLAY_TIMEZONE环境变量并移除其他时区相关配置，可以解决Speedtest-Tracker中的时区显示问题。这种方案不仅解决了当前问题，也为系统提供了更好的国际化支持。对于有特殊时间格式需求的用户，还可以通过DATETIME_FORMAT等参数自定义显示格式。

记住，保持数据库和应用程序使用UTC时区，仅在显示层进行时区转换，这是处理时区问题的黄金准则。