TeslaMate项目开发环境搭建与贡献指南

TeslaMate项目开发环境搭建与贡献指南

teslamate teslamate-org/teslamate: TeslaMate 是一个开源项目，用于收集特斯拉电动汽车的实时数据，并存储在数据库中以便进一步分析和可视化。该项目支持监控车辆状态、行驶里程、充电详情等信息。 项目地址: https://gitcode.com/gh_mirrors/te/teslamate

前言

TeslaMate是一款优秀的特斯拉车辆数据监控与分析工具，本文将为开发者详细介绍如何搭建TeslaMate的开发环境，以及参与项目开发的最佳实践。无论你是想为项目贡献代码，还是希望基于TeslaMate进行二次开发，本文都将为你提供全面的指导。

开发环境要求

在开始开发前，请确保你的系统满足以下基础要求：

• Elixir：版本不低于1.17.3-otp-26
• PostgreSQL：版本不低于17.3
• NodeJS：版本不低于20.15.0
• MQTT代理（可选）：如mosquitto等

对于使用Nix包管理器的开发者，可以直接使用项目提供的nix devenv配置，这将大大简化环境配置过程。

开发环境初始化

数据库设置

TeslaMate需要两个数据库环境：开发环境和测试环境。执行以下命令完成初始化：

# 下载依赖、创建开发数据库并运行迁移
mix setup

# 创建测试数据库
MIX_ENV=test mix ecto.setup

本地运行项目

启动一个iex会话并运行Phoenix服务器：

iex -S mix phx.server

启动后，你可以通过特斯拉账户登录系统进行测试。

开发效率提升技巧

热重载功能

TeslaMate支持热重载，修改代码后只需刷新浏览器页面即可看到变化。你也可以在iex会话中重新加载特定模块：

iex> r TeslaMate.Vehicles.Vehicle

如果只需要编译修改而不重启服务：

mix compile

代码格式化

TeslaMate项目使用Treefmt进行代码格式化，推荐开发者安装Treefmt工具或使用nix devenv配置。

格式化所有文件：

treefmt

仅格式化Elixir文件：

mix format

VS Code用户可安装treefmt扩展，实现保存时自动格式化。

国际化支持

更新翻译文件：

mix gettext.extract --merge

测试流程

在提交代码前，建议运行完整的CI测试：

mix ci

该命令会执行：

1. 代码格式检查
2. 所有单元测试

Grafana仪表板开发

TeslaMate集成了Grafana进行数据可视化，开发仪表板时需要本地运行Grafana服务。

本地Grafana配置

使用以下docker-compose配置启动Grafana：

services:
  grafana:
    image: teslamate/grafana:latest
    environment:
      - DATABASE_USER=postgres
      - DATABASE_PASS=postgres
      - DATABASE_NAME=teslamate_dev
      - DATABASE_HOST=host.docker.internal
    ports:
      - 3000:3000
    volumes:
      - grafana-data:/var/lib/grafana

volumes:
  grafana-data:

Linux用户需将host.docker.internal替换为主机实际IP地址。

访问http://localhost:3000，使用默认凭证（admin/admin）登录后进行仪表板开发。

仪表板修改流程

1. 在Grafana界面编辑仪表板
2. 点击保存并选择"Save JSON to file"
3. 将JSON文件保存到./grafana/dashboards/目录
4. 重新构建Grafana镜像并启动容器

对于重大修改，请提供更新后的截图（1920x1080 @ x2分辨率，Kiosk模式），并保存到./website/static/screenshots目录，注意模糊处理敏感信息。

VS Code扩展推荐

Grafana官方VS Code扩展可让你：

• 直接编辑Grafana仪表板JSON文件
• 实时预览仪表板效果
• 通过Grafana界面编辑仪表板
• 将修改保存回原始JSON文件

开发最佳实践

时间戳列查询

项目中时间戳使用timestamp类型存储，这不是最佳实践。在Grafana中使用PostgreSQL函数时需特别注意：

DATE_TRUNC('day', TIMEZONE('UTC', date), '$__timezone')

确保比较时时间戳类型一致（都带时区或不带时区）。

流API数据优化

启用流API后，每辆车每3万公里约产生1GB数据，其中95%存储在positions表。优化建议：

• 仅在必要时查询positions表
• 如15秒间隔数据足够，添加ideal_battery_range_km IS NOT NULL and car_id = $car_id条件排除流数据

提交PR前，请使用EXPLAIN ANALYZE分析索引使用和查询性能。

查询性能分析

启用pg_stat_statements扩展收集查询统计：

1. 在docker-compose中配置：

   command: postgres -c shared_preload_libraries=pg_stat_statements
   

2. 创建扩展：

   CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
   

3. 分析慢查询：

   SELECT query, calls, mean_exec_time, total_exec_time 
   FROM pg_stat_statements 
   ORDER BY mean_exec_time DESC LIMIT 10;
   

4. 分析高频查询：

   SELECT query, calls, mean_exec_time, total_exec_time 
   FROM pg_stat_statements 
   ORDER BY calls DESC LIMIT 10;
   

实体关系模型

TeslaMate的数据模型设计精良，理解其ERM对开发至关重要。项目文档中提供了完整的实体关系图，展示了各表间的关联关系，建议开发者在进行数据库相关开发前仔细研究。

通过本文的介绍，相信你已经掌握了TeslaMate项目开发的基本流程和最佳实践。无论是修复bug、添加新功能还是优化性能，你的贡献都将使这个优秀的项目更加完善。

teslamate teslamate-org/teslamate: TeslaMate 是一个开源项目，用于收集特斯拉电动汽车的实时数据，并存储在数据库中以便进一步分析和可视化。该项目支持监控车辆状态、行驶里程、充电详情等信息。 项目地址: https://gitcode.com/gh_mirrors/te/teslamate