TeslaMate 时区设置问题排查指南

问题背景

在使用 TeslaMate 开源项目时，部分用户遇到了充电完成时间预估显示时区不正确的问题。尽管用户已经按照文档要求设置了 TZ 环境变量，但系统仍然无法正确显示本地时区时间。

技术原理分析

TeslaMate 使用 Elixir 语言的 Timex 库来处理时区转换。具体实现逻辑如下：

1. 获取当前时间：Timex.now()
2. 计算充电完成时间：在当前时间基础上加上预估充电时间
3. 获取本地时区：Timex.Timezone.local()
4. 转换时区：将计算出的充电完成时间转换为本地时区时间
5. 格式化显示：按照指定格式输出时间字符串

Timex 库默认会使用操作系统设置的 TZ 环境变量来确定本地时区。在 Docker 环境中，这个变量需要在容器启动时正确配置。

常见问题排查步骤

1. 确认 TZ 变量设置正确

确保 docker-compose.yml 文件中正确设置了 TZ 环境变量，例如：

environment:
  - TZ=America/New_York

时区值必须符合 IANA 时区数据库标准格式，如"Asia/Shanghai"、"Europe/Berlin"等。

2. 检查 Docker 容器配置

修改 docker-compose.yml 后，必须执行以下命令使更改生效：

docker compose up -d

仅重启 Docker 服务不会重新加载配置变更。

3. 验证系统时间

确保宿主机系统时间和时区设置正确。虽然 TeslaMate 主要依赖 TZ 环境变量，但系统时间不正确也可能导致问题。

4. 区分浏览器时区和系统时区

需要注意的是，TeslaMate 的 Grafana 仪表板显示的时间是基于浏览器时区，而充电预估时间是使用容器内设置的时区。两者可能不同，这并非错误。

解决方案

对于大多数用户，按照以下步骤操作可以解决问题：

1. 编辑 docker-compose.yml 文件，确保 TZ 环境变量设置正确
2. 保存文件后运行 docker compose up -d 命令
3. 等待容器重新启动
4. 检查充电预估时间是否已更正

技术细节补充

Timex 库处理时区的底层逻辑是：首先检查 TZ 环境变量，如果未设置则尝试从操作系统获取时区信息。在 Docker 环境中，由于容器通常使用精简版操作系统镜像，依赖环境变量是最可靠的方式。

对于 macOS 用户，特别需要注意的是 Docker Desktop 的时区处理可能与原生系统有所不同。如果问题持续存在，可以尝试在容器内执行命令验证时区设置：

docker exec -it teslamate_app_1 date

这将显示容器内部的当前时间和时区设置，帮助确认配置是否生效。

通过以上步骤，大多数时区显示问题都可以得到解决。如果问题仍然存在，建议检查 TeslaMate 和 Timex 库的版本是否最新，因为时区处理逻辑可能会随版本更新而改进。