TeslaMate API

一、项目基础信息

项目名称：TeslaMateApi

开源作者：tobiasehlert

GitHub 地址：https://github.com/tobiasehlert/teslamateapi

开发语言：Golang

开源协议：MIT 开源免费商用

核心定位：专为自托管 TeslaMate 配套的 RESTful 标准化 HTTP 接口服务，将 TeslaMate 存储的车辆历史数据、实时状态封装为 JSON 接口，打通第三方程序、智能家居、自定义面板的数据通道。

核心定位说明

TeslaMate 本身仅内置 Grafana、MQTT，无对外标准化 HTTP 接口，无法被外部脚本、HomeAssistant、安卓客户端、自研网页直接调用。

TeslaMateApi 作为独立中间层，不直接对接特斯拉官方 API，仅读取 TeslaMate 的 PostgreSQL 数据库与本地 MQTT 服务，实现数据查询与车辆远程指令下发，全程数据本地闭环，隐私可控。

二、核心技术架构

• 数据源 1：PostgreSQL 持久化数据库
  读取 TeslaMate 完整归档数据：车辆基础信息、全部行程记录、充电历史、电池容量、地理围栏、定位轨迹、能耗统计、长期衰减曲线。
  

• 数据源 2：本地 Mosquitto MQTT
  获取车辆实时动态数据：当前电量、胎压、车内温度、行驶速度、充电功率、门锁 哨兵 空调状态。
  

• 输出层：RESTful HTTP JSON 接口
  统一规范接口返回结构化 JSON 数据，内置接口文档页面，支持浏览器直接调试；
  

• 指令通道：MQTT 下发控制指令
  开启指令权限后，通过 API 接口向 MQTT 推送控车命令，由 TeslaMate 转发至特斯拉车辆。
  

三、两大核心功能模块

模块 1：只读数据查询接口（默认全部开放）

覆盖 TeslaMate 全量存储数据，支持单条 / 批量 / 时间段筛选，常用接口分类：

1. 车辆基础信息
   获取绑定车辆列表、VIN、车型、出厂配置、注册时间、总里程；
   

2. 实时车辆状态
   当前电量、预估续航、内外温度、胎压、充电状态、驻车 行驶 休眠识别、门锁、哨兵模式；
   

3. 充电全量记录
   单次充电起止时间、充电量、峰值功率、电费、电池温度曲线、快充 / 家充区分、谷峰电价统计；
   

4. 行程驾驶数据
   单次行程里程、平均时速、能耗、动能回收、海拔变化、轨迹 GPX 导出、月度年度里程汇总；
   

5. 电池健康数据
   满电可用容量、充放电循环次数、长期衰减趋势、高低温充电记录；
   

6. 地理围栏
   家、公司、超充站自定义点位进出记录；
   

7. 系统日志
   TeslaMate 登录、Token 刷新、API 请求日志。
   

模块 2：车辆远程控制指令（需手动开启）

默认关闭，配置ENABLE_COMMANDS=true并设置允许指令白名单后启用，通过鉴权 Token 调用，支持操作：

• 唤醒车辆 wake_up
  

• 闪灯、鸣笛寻车
  

• 解锁 / 锁闭车门
  

• 开启 / 关闭充电口盖板
  

• 启动 / 停止充电、设置充电上限、调节充电电流
  

• 开启 / 关闭空调预调节
  

• 开启 / 关闭哨兵模式

四、安全鉴权机制

1. 全局 API 访问 Token
   环境变量配置API_TOKEN，长度至少 32 位，所有接口请求必须携带鉴权凭证；
   两种传参方式：
   

• 推荐：请求头 Authorization: Bearer 你的Token（日志不会泄露密钥）
  

• 不推荐：URL 拼接?token=xxx（访问日志会明文记录 Token）
  

1. 指令单独权限隔离
   读数据接口与控车指令接口权限分离，可仅开放查询、禁用所有控车命令；
   

2. 跨域、IP 访问限制
   支持配置允许访问的客户端域名、内网 IP 白名单，杜绝外网未授权访问；
   

3. 无外部数据上传
   服务仅读取本地数据库与 MQTT，不会将车辆数据上传第三方服务器。