TeslaMate v4.4.0 介绍与选型指南

TeslaMate v4.4.0 自托管特斯拉车辆数据记录器介绍与选型指南：组件架构、流式采集机制、22 张 Grafana 仪表盘、MQTT 集成与 TeslaFi 导入，含 TeslaLogger/TeslaFi/evcc 量化对比。

TeslaMateTeslaMate数据采集2026/10/31

TeslaMate v4.4.0 介绍与选型指南

目标：面向正在为特斯拉车辆挑选「数据记录 + 统计分析」自托管方案的读者，梳理 TeslaMate v4.4.0 的项目定位、组件架构、功能边界与同类产品量化对比，帮助读者判断「要不要用、和谁比、怎么选」。本文为认知篇，全部数据来自官方仓库与官方文档站联网溯源（查询日期 2026-10-31），本地未做车辆数据实测。

一、环境信息

本文为认知与选型篇，结论均基于官方公开信息溯源，不依赖本地部署。溯源对象与环境说明如下：

  • 溯源对象：teslamate-org/teslamate 官方仓库与官方文档站 docs.teslamate.org
  • 溯源日期：2026-10-31（文中所有版本号、星数、发布节奏数据均为当日实查值）
  • 最新稳定版本：v4.4.0（GitHub Releases 实查，发布于 2026-10-23，非预发布版本）
  • 社区热度：GitHub Stars 约 9.2k（shields.io 徽章数据实查，2026-10-31）
  • 适用读者：特斯拉车主（Model 3/Y/S/X，Cybertruck 同理）、家庭服务器/NAS 玩家、新能源数据分析爱好者
  • 部署载体要求（官方口径）：一台常年在线、至少 1 GB 内存（官方推荐 2 GB 以上）、能访问特斯拉服务器的机器；官方镜像提供 amd64 与 arm64（aarch64）两种架构，不再支持 armv7（即树莓派 3 以前 32 位系统不可用）

💡 说明：TeslaMate 记录的是「车」的数据，不是「充电桩」的数据。若核心诉求是充电桩调度与光伏联动，请直接看第七章对 evcc 的对比。

二、软件概述

2.1 基本信息

项目内容（均为 2026-10-31 实查）
软件名称TeslaMate
官方仓库github.com/teslamate-org/teslamate
开源许可MIT（仓库 LICENSE 文件）
开发语言Elixir（Phoenix 框架 Web 端 + 原生 Ecto 数据层），伴随少量 Rust 组件
最新稳定版v4.4.0（2026-10-23 发布）
GitHub Stars约 9.2k（shields.io 徽章）
官方文档站docs.teslamate.org
部署形态官方唯一一等公民形态为 Docker Compose 一键编排栈；另有 NixOS flake 官方支持，Debian/FreeBSD/Unraid 手动安装列为「不受支持方法」

TeslaMate 一句话定位：一个自托管的特斯拉车辆数据记录器（data logger），把车辆每次行驶、充电、休眠、软件更新的细节数据落到自己的数据库里，并用一套预置的 Grafana 仪表盘做可视化统计。

2.2 项目由来与解决的核心痛点

特斯拉官方 App 只保留近期行程的摘要数据，充电历史、电耗曲线、休眠功耗（Vampire Drain，俗称「幽灵耗电」）等长期数据既不可导出、也不可细看。TeslaMate 的核心价值在于：

  1. 数据主权：所有历史数据（逐秒级的位置、电量、温度、速度）落在本机 PostgreSQL 数据库，不经过任何第三方；
  2. 高频采集：默认优先使用特斯拉流式接口（streaming），车辆行驶中数据近乎实时入库，这是官方 App 与多数第三方 SaaS 达不到的分辨率；
  3. 长期统计：充电成本、百公里电耗、电池健康度（续航衰减）、年度里程等统计由 22 张预置 Grafana 仪表盘直接呈现；
  4. 自动化联动：通过 MQTT 把车辆状态实时推送给 Home Assistant 等智能家居平台，实现「车到家自动开灯、离家自动关车库门」类联动。

2.3 技术栈构成

  • 应用主体：Elixir/Erlang VM（BEAM），Phoenix LiveView 提供 Web 管理界面（车辆总览、设置、地理围栏管理），优势是长连接流式处理与低内存占用；
  • 存储：PostgreSQL（v4.4.0 官方编排模板指定 postgres:18-trixie），并要求启用 cube/earthdistance 扩展以支持地理位置计算；
  • 可视化：Grafana（官方维护定制镜像 teslamate/grafana，v4.4.0 跟进 Grafana 13.2.4），预置 22 张仪表盘并在启动时自动导入；
  • 消息集成：可选 Mosquitto（MQTT Broker），官方编排模板默认携带，用于向外部系统发布车辆状态主题；
  • 地理编码：调用 OpenStreetMap 的 Nominatim 公共服务做地址反解，海拔数据来自欧空局 DEM 服务（step.esa.int）。

三、核心架构

3.1 组件与数据流

TeslaMate 的标准运行形态由四个服务协作（MQTT 可关闭）：

特斯拉车辆
   │  ① 流式接口（wss://streaming.vn.teslamotors.com，行驶中逐秒推送）
   │  ② Owner API 轮询（https://owner-api.teslamotors.com，休眠/充电/在线低频拉取）
   ▼
teslamate 主服务（Elixir/Phoenix）
   │  解析、落库、地址反解（nominatim.openstreetmap.org）
   ▼
PostgreSQL 数据库（cube/earthdistance 扩展）
   │  ③ Grafana 直连库查询渲染            │  ④ MQTT 主题发布（teslamate/cars/...）
   ▼                                      ▼
Grafana（22 张预置仪表盘）               Mosquitto / Home Assistant 等外部系统
  • Web 管理界面默认监听 4000 端口（PORT 环境变量可改），Grafana 默认监听 3000 端口；
  • TeslaMate 与 Grafana 共用同一个 PostgreSQL 库：TeslaMate 负责写入，Grafana 负责只读展示；
  • 官方明确声明：TeslaMate 没有公开 REST API，数据库结构也不是对外接口，MQTT 是唯一受支持的集成面（官方 FAQ 原文口径，2026-10-31 查询）。第三方工具若直接读库或调内部路由，官方不保证兼容。

💡 技术拓展：车辆数据采集有「流式（streaming）」与「轮询（polling）」两种路线。流式通过 WebSocket 长连接由车辆主动逐秒推送，分辨率高但要求连接保活；轮询按固定间隔调用 REST 接口拉取，实现简单但每次调用会重置车辆休眠计时器。TeslaMate 两者并用：行驶中走流式，车辆静默后主动暂停轮询 15 分钟给车「入睡窗口」，避免把车喊醒——这也是它相比简单轮询方案省电的关键设计。Tesla 官方新推出的 Fleet Telemetry 属第三条路线（消息队列投递，最低约每分钟一条），官方文档明确指出其默认分辨率低于传统流式。

3.2 数据模型要点

  • 以 cars（车辆）、positions（位置轨迹）、drives（行程）、charging_processes/charges（充电会话与逐条充电数据）、battery_health、updates（软件更新）、geofences（地理围栏）等表为核心；
  • 充电成本可按地理围栏（如「家」）配置电价自动计算；
  • 消耗值（kWh/100km）不是特斯拉 API 返回的，而是 TeslaMate 基于充电记录估算：官方 FAQ 说明需要至少两次有效充电会话（单次超过 10 分钟且结束电量低于 95%）后才会出现首个估算值，之后每次充电都会回溯修正历史估算。

3.3 账号与令牌机制

  • TeslaMate 使用特斯拉账号的 access token / refresh token 登录，不内置令牌生成功能（官方解释：生成逻辑需频繁跟进特斯拉改动）；官方推荐用独立工具 Tesla Auth（0.13.0+，macOS/Linux/Windows）或 iOS 端 Auth app for Tesla 自行生成；
  • 令牌用 ENCRYPTION_KEY 环境变量加密后存库；
  • 默认走「非官方 Owner API」；企业车队（Business Fleet）账号因 Owner API 停用必须迁移到 Fleet API，可通过 TOKEN/TESLA_API_HOST 等环境变量切换到第三方代理（如 MyTeslaMate 免费端点、Teslemetry 付费端点）或自建 Fleet API。

四、功能特性

4.1 Web 管理界面

  • 车辆总览：实时电量、里程、状态（在线/充电/行驶/休眠）、当前地址；
  • 设置页：全局设置（单位、语言、时区）、车辆启停记录开关、车辆排序；
  • 地理围栏管理：自定义「家」「公司」等围栏（圆形或多边形），支撑充电成本与通勤统计；
  • 支持浅色/深色/跟随系统三种主题；
  • 导入入口：检测到导入目录有 TeslaFi CSV 时，Web 界面自动切换为导入表单。

4.2 预置 Grafana 仪表盘（22 张，官方 Screenshots 页清单）

总览（Overview）、行程（Trip/Drives/Drive Details）、驾驶统计（Drive Stats）、充电相关（Charges、Charge Details、Charging Stats、Charge Level）、效率（Efficiency）、里程（Mileage）、位置（Location、Visited 终身驾驶地图）、状态（States、Timeline）、统计（Statistics）、温度（Temperatures）、软件更新（Updates）、幽灵耗电（Vampire Drain）、续航预测（Projected Range）、电池健康（Battery Health）、数据库信息（Database Information）等。

4.3 MQTT 与智能家居

  • 主题结构形如 teslamate/cars/<车ID>/battery_level、.../state，车辆每次状态变化即发布；
  • v4.4.0 起原生支持 Home Assistant MQTT Discovery（MQTT_HOME_ASSISTANT_DISCOVERY=true），自动发布发现配置，免去手工维护 sensors 配置文件；
  • 生态项目（官方 Projects 页收录）包括：TeslaMateApi（Golang REST 封装，v1.25.0）、TeslaMate-Telegram-Bot（车辆软件更新推送）、teslamate-abrp（把车况推给 ABRP 导航）、TeslaMate Achievements（驾驶成就徽章）、TeslaMate Dash（免 Grafana 的只读历史浏览面板）、Home Assistant Addon（HA 插件形态封装）等 16 个。

4.4 数据导入与迁移

  • 支持从 TeslaFi（BETA）与 tesla-apiscraper 导入历史 CSV：把按月导出的 CSV 放入 import 目录（IMPORT_DIR 可改），重启后 Web 界面出现导入表单，选时区后开始导入；导入完成后按官方建议对 positions 表执行 REINDEX TABLE positions;；
  • 导入机制具备断点续传与坏行跳过报告（v4.4.0 官方文档：按文件级检查点恢复，坏行记录文件名/行号/字段但不展示内容）；
  • 备份恢复走 PostgreSQL 原生通道：pg_dump 导出 .bck、重建 schema 后 psql 回灌，官方还随 NixOS 形态提供 teslamate-backup/teslamate-restore 惯用脚本。

五、快速开始（最小可用示例）

本章内容为官方文档安装页步骤的转述（来源：docs.teslamate.org/docs/installation/docker，查询日期 2026-10-31），供选型评估体量与门槛；完整的逐命令实测部署流程见本专栏 《TeslaMate v4.4.0 Docker Compose 部署指南》。

  1. 准备一台常年在线、≥1 GB 内存、可联网的机器，安装 Docker 与 Docker Compose v2；
  2. 新建 docker-compose.yml：官方模板包含 teslamate（主服务，4000 端口）、database（postgres:18-trixie）、grafana（teslamate/grafana，3000 端口）、mosquitto（eclipse-mosquitto:2，可选）四个服务与四个数据卷；
  3. 替换模板中三处占位：ENCRYPTION_KEY（用于加密特斯拉令牌的密钥）、DATABASE_PASS/POSTGRES_PASSWORD（数据库密码，两处必须一致）；
  4. docker compose up -d 启动；
  5. 用 Tesla Auth 等工具生成 access token 与 refresh token，打开 http://<主机IP>:4000 在登录页填入完成车辆绑定；
  6. 打开 http://<主机IP>:3000 进入 Grafana（默认账号 admin，首次登录强制改密），在 TeslaMate 设置页把 Web App 与 Dashboards 两个 URL 填好，让界面与仪表盘互链。

门槛小结：不碰任何一行代码，但需要自行完成「生成特斯拉令牌」这一步——这是整个安装流程中唯一有门槛的环节，也是所有自托管特斯拉数据方案的共同前置。

六、适用场景与限制

6.1 适用场景

场景说明
个人车主长期数据档案保修期电池健康度追踪、年度里程/电耗报告、幽灵耗电排查
家庭节能分析结合地理围栏电价自动算充电成本，配合分时电价优化充电时段
智能家居联动MQTT 推送车辆状态到 Home Assistant，实现到达/离开自动化
数据极客二次开发数据在自己库里，社区有成就系统、Telegram 通知、ABRP 上报等增值项目
多车家庭官方支持一台实例记录账号下多辆车，Grafana 仪表盘按车筛选

6.2 已知限制（官方口径）

  1. 需要特斯拉账号令牌：无车无号无法使用；令牌泄露等于车辆控制权泄露，官方安装页警告「若要从公网访问，建议 VPN/Cloudflare Tunnel/Tailscale 等安全通道，勿裸暴露 4000 端口」；
  2. 无公开 API、无稳定库结构：官方 FAQ 强调 MQTT 是唯一受支持集成面，直接读库的自定义面板/第三方工具可能在任意版本升级后失效；
  3. 依赖特斯拉接口现状：Owner API 属非官方接口，企业车队账号已强制迁移 Fleet API（分辨率下降、需公网宿主机或第三方代理）；接口变更可能随时影响采集；
  4. 数据不可回补：特斯拉 API 不提供历史行程/充电数据，记录停摆期间的数据无法找回（只能靠 TeslaFi 等第三方历史数据导入补齐）；
  5. 持续在线要求：机器必须常年开机联网，停机即丢数据；
  6. 国内网络环境：auth.tesla.com、owner-api.teslamotors.com、streaming.vn.teslamotors.com、nominatim.openstreetmap.org（443/TCP）与 step.esa.int（80/TCP）为官方列明的必通出口；中国大陆特斯拉账号需注意 TeslaMate 对中国区 API 域名（owner-api.vn.cloud.tesla.cn 等）有专门配置项。

七、同类选型对比

7.1 候选同类方案

特斯拉车辆数据记录方案可分三类：自托管日志器（TeslaMate、TeslaLogger）、商业 SaaS（TeslaFi、Teslascope）、以及定位不同但部分重叠的开源充放电管理平台（evcc）。本章选取最有代表性的四款做量化对比。

7.2 量化对比表

维度TeslaMate v4.4.0TeslaLogger V1.63.0TeslaFi（SaaS）evcc v0.318.1
定位自托管全量数据记录+统计自托管数据记录+统计（德系老牌）商业托管日志服务光伏充电桩调度管理（自带车辆数据读取）
GitHub Stars9.2k（2026-10-31 实查）643（2026-10-31 实查）非开源，无7.5k（2026-10-31 实查）
技术栈Elixir/Phoenix + PostgreSQL + GrafanaPHP + MariaDB + 自研 Web闭源托管Go + 内置 Web UI
可视化Grafana 22 张预置仪表盘自研 Web 界面商业 Web 界面自研充电管理界面
数据存储自己的 PostgreSQL自己的 MariaDB存在厂商云端自己的 SQLite/MySQL/Postgres
流式采集✅（传统 streaming，逐秒）✅✅—（非记录器定位）
MQTT 集成✅（含 HA Discovery）⚠️ 支持 MQTT❌✅（HA 原生集成）
API无公开 API（MQTT 唯一集成面）有 Web API有（付费）有 REST API 与 MQTT
历史数据导入✅ TeslaFi/apiscraper CSV⚠️ 有限—（即数据源本身）—
生态衍生项目官方收录 16 个少量商业生态大量（充电桩/电表适配）
许可MITGPL-3.0商业订阅（约 $5/月档）Apache-2.0
部署门槛Compose 一键栈（4 服务）Compose/树莓派镜像免部署单二进制/Compose
资源要求≥1 GB（推荐 2 GB）低（树莓派可用）零（云端）低

7.3 选型建议

  • 要「数据完全自主 + 长期统计深度」选 TeslaMate：社区规模（9.2k vs 643）意味着迭代更快、仪表盘生态更厚；Grafana 面板可自由改 SQL，适合愿意折腾的玩家。代价是必须自己管理令牌与升级，且要接受「无公开 API」的集成约束。
  • 要「开箱即用 + 零维护」且不介意数据出户选 TeslaFi：商业服务免部署、有官方 App，但按月付费、数据在厂商云端，且 TeslaMate 反向支持从 TeslaFi 导入历史数据，迁移路径友好。
  • 主诉求是「光伏充电调度」顺带看车况选 evcc：evcc 的核心是充电桩与电价调度，车辆数据只是其输入之一；若你要的是「记录并分析每一次出行」，evcc 不是答案，两者甚至可以并存（TeslaMate 记录、evcc 调度，经 MQTT 互通）。
  • 树莓派级硬件且想要极简栈可考虑 TeslaLogger：资源占用更低，但社区活跃度与仪表盘生态明显弱于 TeslaMate，2026 年仍以维护为主。
  • 综合推荐：对绝大多数有家庭服务器/NAS 的特斯拉车主，TeslaMate 是当前社区规模最大、数据分辨率最高、长期成本最低的自托管方案；企业车队账号用户需先确认 Fleet API 迁移路径（可借 MyTeslaMate/Teslemetry 第三方端点）再落地。

八、参考链接