TeslaMate：Tesla 车辆数据黑匣子，让每一段行程都有数据可循

背景故事：为什么你的 Tesla 需要一个"数据保险箱"？

许多 Tesla 车主都有过这样的体验：跑了几个月后，想回顾某次长途旅行的能耗表现，或者想了解电池健康度的变化趋势，却发现车机自带的 App 只能看到最近几天的数据。更令人不安的是，Tesla 官方时不时调整 API 访问策略，第三方数据服务的稳定性无法保证。TeslaMate 正是为了解决这一痛点而生——它是一个完全自托管的 Tesla 车辆数据记录器，安装在你自己的一台小服务器上，7×24 小时默默记录车辆的一举一动，数据永远掌握在自己手里。

这个项目由社区驱动，目前由 @JakobLichterfeld 主导维护，在 GitHub 上已积累超过 8200 颗星，是 Tesla 第三方生态中最成熟的开源数据记录方案。

核心功能：从充电到驾驶，数据全覆盖

TeslaMate 的设计哲学是"零侵入"——它在后台安静运行，不打扰车辆正常休眠，不产生额外电量消耗（官方称之为 "No vampire drain"）。它通过 Tesla 官方 API 持续轮询车辆状态，将每一次行程、每一次充电、每一个地址都记录到本地 PostgreSQL 数据库中。

数据记录能力包括：

• 高精度行程数据：每一次出发和到达的时间、GPS 轨迹、总能耗、平均能耗等核心指标
• 充电记录：起始/终止电量、充电功率曲线、充电时长、充电成本（支持自定义电价）
• 电池健康监控：通过充电曲线推算电池实际容量，与出厂标称值对比，追踪电池衰减趋势
• 地址与地理围栏：自动将 GPS 坐标反向解析为地名，支持自定义地理围栏（家、公司、常去地点）
• 停车与休眠：记录停车时长、电池消耗速率，判断车辆是否进入深度休眠
• 多车辆支持：一个 Tesla 账户下的多辆 Tesla 车辆可以同时接入，数据分别统计

可视化：Grafana 仪表板让数据"看得见"

TeslaMate 捆绑了一套精心设计的 Grafana 仪表板，安装时一并部署。开箱即可查看以下核心看板：

• Battery Health（电池健康）：展示电池实际容量 vs 出厂容量百分比，以及随时间的衰减曲线
• Charge Level（充电水平）：显示每次充电的 SOC 变化、充电功率和能耗对比
• Drives（行程）：地图叠加轨迹、时速/能耗随时间变化、里程效率分析
• Charging（充电详情）：充电成本分摊、充电速率热力图、充电频次统计
• Updates（软件更新）：Tesla 每次 OTA 推送后记录版本号，便于追溯性能变化
• Statistics（综合统计）：月度/年度行驶里程、能耗总览、费用汇总
• Trips（旅途）：长距离旅途的详细分析，含高速/城区能耗分段对比
• Locations（地点）：地理围栏视图、各地点停留频次热力图

图1：Battery Health 仪表板 — 实时追踪电池容量衰减趋势

图2：每次充电的 SOC 变化与功率曲线

图3：自定义地理围栏 — 自动识别"家"和"公司"等常去地点

技术架构：Elixir/Phoenix 构建的高可靠数据管道

TeslaMate 后端采用 Elixir 语言编写，运行时基于 Erlang/OTP 虚拟机，这为系统的稳定性和容错能力提供了先天优势。以下是它的核心技术栈：

层次	技术选型	作用
Web 框架	Phoenix + Phoenix LiveView	提供实时交互式 Web UI，无须额外页面刷新
数据库	PostgreSQL + Ecto ORM	结构化存储所有车辆数据，支持复杂查询
MQTT	Tortoise (EMQTT 兼容客户端)	车辆数据发布到本地 MQTT 总线，可对接 Home Assistant / Node-RED
Tesla API	Tesla (Elixir HTTP 客户端库)	封装 Tesla 官方 OAuth 认证和 API 轮询逻辑
状态机	gen_state_machine	管理车辆生命周期状态（在线/休眠/充电/驾驶）
时间处理	Timex + Tzdata	精确时区转换，确保跨时区行程时间准确
静态地图	SRTM (Shuttle Radar Topography Mission)	海拔数据辅助能耗分析

核心模块解析

TeslaApi.TeslaAPI：负责与 Tesla 云端 API 通信。TeslaMate 使用 Token 认证（非用户名密码），需要从 Tesla App 中获取 refresh_token（项目文档有详细指引）。该模块通过 GenServer 实现定时轮询，间隔可配置，默认为 3 分钟（休眠时自动延长到 11 分钟以节省电量）。

TeslaMate.Vehicle：每个车辆对应一个 Vehicle GenServer，管理该车的生命周期状态。它监听 API 返回的车辆状态（sleeping/charging/driving/online），触发不同的数据记录逻辑。当车辆进入休眠后，轮询间隔自动拉长，极大降低对车辆电耗的影响。

TeslaMate.PubSub：基于 ETS 的发布订阅系统，所有模块通过 Topic 订阅感兴趣的事件。例如 Grafana 数据导入模块订阅 [:charge, :drive] 事件，MQTT 推送模块订阅所有传感器数据。

前端资产

Web UI 的前端代码位于 assets/ 目录，使用 Node.js 22 + npm 构建，产物通过 mix assets.deploy 集成到 Phoenix 发行版中。Dockerfile 采用多阶段构建，将 Elixir 编译产物和 npm 构建产物打包进同一个镜像，镜像大小控制在合理范围内。

质量保障体系

项目在代码质量上的投入令人印象深刻：

• Credo：Elixir 代码风格静态检查
• Dialyzer：基于 Dialyzer 的类型规格验证（通过 :dialyxir 集成）
• ExCoveralls：测试覆盖率追踪，持续集成报告到 coveralls.io
• ** spell_check**：文档拼写检查
• Dependabot + OSV Scanner：依赖安全漏洞扫描
• GitHub Actions：覆盖测试、构建、镜像发布全链路 CI/CD

这套质量保障体系使得 TeslaMate 在多年迭代中保持了极高的稳定性，用户报告的 issue 数量相对项目规模而言非常低。

图4：Statistics 仪表板 — 月度/年度能耗和费用一目了然

部署指南：三种方式，总有一种适合你

方式一：直接安装（适合 Linux 服务器）

需要准备：PostgreSQL 数据库、MQTT Broker（推荐 mosquitto）、Elixir/Erlang 环境。克隆仓库后：

# 1. 配置环境变量（参考 .envrc.example）
cp .envrc.example .envrc
# 编辑填入 Tesla API Token、数据库连接串等

# 2. 安装依赖
mix deps.get
cd assets && npm install && cd ..

# 3. 数据库初始化
mix ecto.create && mix ecto.migrate

# 4. 启动
mix phx.server

然后访问 http://your-server:4000 即可打开 Web UI，首次登录需输入 Tesla 账号的 refresh_token。

方式二：Docker（适合有 Docker 基础的用户）

项目提供了精心设计的多阶段 Dockerfile，可构建为 teslamate/teslamate:latest 镜像：

docker build -t teslamate .
docker run -d --name teslamate   -p 4000:4000   -e DATABASE_USER=xxx   -e DATABASE_PASS=xxx   -e MQTT_HOST=mosquitto   -e TESLA_REFRESH_TOKEN=xxx   teslamate

⚠️ 注意：PostgreSQL 和 MQTT Broker 需要另外启动，没有 docker-compose.yml 可用，因此需要自行管理容器间网络。

方式三：Nix（面向 NixOS 用户）

项目包含 flake.nix，可直接在 NixOS 上通过 nix develop 进入开发环境，或在 NixOS 配置中引用 flake 构建。

图5：Trips 仪表板 — 长途旅行的能耗与效率分析

Home Assistant 集成：打造个性化 Tesla 智能家居体验

TeslaMate 的 MQTT 集成是其最具想象空间的特性之一。车辆数据实时发布到本地 MQTT 总线后，Home Assistant 可以自动发现 Tesla 车辆，获取以下传感器数据：

• 当前电量（SOC）、预估续航里程
• 充电状态（是否插枪、充电速率）
• 车辆位置（经纬度）
• 车内/车外温度
• 软件版本号

这意味着你可以构建自动化场景：当车辆驶入小区半径 500 米时，自动打开车库门；当电量低于 20% 且处于谷时电价时段时，自动通知并询问是否预约充电。 这些在 Tesla App 中无法实现的个性化联动，通过 TeslaMate + Home Assistant 的组合可以轻松实现。

安全警示：认准官方渠道

项目 README 有专门的安全警示章节。近期有不法分子创建了恶意 fork 和仿冒 App，诱导用户输入 Tesla 账号密码，存在凭证泄露和车辆被远程控制的风险。TeslaMate 永远只需要你的 refresh_token，不需要用户名密码，且数据完全在本地存储，请务必从 github.com/teslamate-org/teslamate 官方仓库获取代码。

图6：Drives 仪表板 — 每次行程的轨迹、速度和能耗随时间变化

局限与挑战

尽管 TeslaMate 功能完善，但它也面临一些固有限制：

1. 依赖 Tesla 官方 API：Tesla 不定期调整 API 访问策略，可能导致轮询频率受限或功能降级。项目维护者需要持续跟进 API 变化并推送更新。
2. API 速率限制：Tesla 对第三方 API 调用有隐性速率限制，过高的轮询频率可能导致 Token 被临时封禁。TeslaMate 提供了休眠策略来规避，但用户在调整配置时需注意。
3. 无原生移动 App：Web UI 在手机浏览器上体验尚可，但没有独立的 iOS/Android 原生 App。
4. 数据迁移成本：TeslaFi 和 tesla-apiscraper 用户可以导入历史数据，但迁移过程需要手动操作，不够顺畅。

图7：Charging 仪表板 — 充电成本分摊和充电速率热力图

总结：开源社区的力量

TeslaMate 的成功诠释了"自托管"理念在 IoT 和车辆数据领域的价值——当数据的主权归还给用户，第三方服务的可靠性就不再是瓶颈。项目在 GitHub 上 8200+ 星的认可，证明了这一需求的真实存在。随着 Tesla 保有量持续增长，TeslaMate 很可能成为 Tesla 车主必备的"数据保险箱"，其 Grafana 仪表板设计和 MQTT 集成方案也为其他车辆的第三方数据采集提供了优秀的参考范本。