tobiasehlert/teslamateapi

TeslaMateApi

TeslaMateApi 是一个 RESTful API，用于以 JSON 格式获取自托管数据记录器 https://github.com/teslamate-org/teslamate 收集的数据。

• 使用 Golang 编写
• 从 TeslaMate 的 Postgres 数据库和本地 MQTT 代理收集数据
• 端点以 JSON 格式返回数据
• 通过 TeslaMateApi 向特斯拉车辆发送命令

目录

• 使用方法
  • Docker-compose配置
  • 环境变量
• API文档
  • 可用端点
  • 认证
  • 命令
• 安全信息
• Credits

使用方法

您可以将其部署在 Docker 容器中，或下载代码并自行部署到任何服务器。

Docker-compose配置

如果您运行的是 TeslaMate 的简单 Docker 部署，添加以下配置即可。TeslaMateApi 将在本地 8080 端口暴露。

yaml
services:
  teslamateapi:
    image: tobiasehlert/teslamateapi:latest
    restart: always
    depends_on:
      - database
    environment:
      - ENCRYPTION_KEY=MySuperSecretEncryptionKey
      - DATABASE_USER=teslamate
      - DATABASE_PASS=secret
      - DATABASE_NAME=teslamate
      - DATABASE_HOST=database
      - MQTT_HOST=mosquitto
      - TZ=Europe/Berlin
    ports:
      - 8080:8080

如果您在 Docker 中使用带有环境变量文件（.env）的 TeslaMate Traefik 配置，可以将以下部分添加到 docker-compose.yml 文件的 services: 部分：

yaml
services:
  teslamateapi:
    image: tobiasehlert/teslamateapi:latest
    restart: always
    depends_on:
      - database
    environment:
      - ENCRYPTION_KEY=${TM_ENCRYPTION_KEY}
      - DATABASE_USER=${TM_DB_USER}
      - DATABASE_PASS=${TM_DB_PASS}
      - DATABASE_NAME=${TM_DB_NAME}
      - DATABASE_HOST=database
      - MQTT_HOST=mosquitto
      - TZ=${TM_TZ}
    labels:
      - "traefik.enable=true"
      - "traefik.port=8080"
      - "traefik.http.middlewares.redirect.redirectscheme.scheme=https"
      - "traefik.http.middlewares.teslamateapi-auth.basicauth.realm=teslamateapi"
      - "traefik.http.middlewares.teslamateapi-auth.basicauth.usersfile=/auth/.htpasswd"
      - "traefik.http.routers.teslamateapi-insecure.rule=Host(`${FQDN_TM}`)"
      - "traefik.http.routers.teslamateapi-insecure.middlewares=redirect"
      - "traefik.http.routers.teslamateapi.rule=Host(`${FQDN_TM}`) && (Path(`/api`) || PathPrefix(`/api/`))"
      - "traefik.http.routers.teslamateapi.entrypoints=websecure"
      - "traefik.http.routers.teslamateapi.middlewares=teslamateapi-auth"
      - "traefik.http.routers.teslamateapi.tls.certresolver=tmhttpchallenge"

在这种情况下，TeslaMateApi 可通过 teslamate.example.com/api/ 访问。

环境变量

基本上，TeslaMateApi 需要与 TeslaMate 相同的数据库、MQTT 和时区环境变量。

必填环境变量（即使某些有默认值）

可选环境变量

命令环境变量

API文档

更详细的每个端点文档即将推出...

可用端点

• GET /api
• GET /api/v1
• GET /api/v1/cars
• GET /api/v1/cars/:CarID
• GET /api/v1/cars/:CarID/charges
  • 支持的参数：
    • startDate（可选，使用RFC3339规范的UTC格式）
    • endDate（可选，使用RFC3339规范的UTC格式）
• GET /api/v1/cars/:CarID/charges/:ChargeID
• GET /api/v1/cars/:CarID/command
• POST /api/v1/cars/:CarID/command/:Command
• GET /api/v1/cars/:CarID/drives
  • 支持的参数：
    • startDate（可选，使用RFC3339规范的UTC格式）
    • endDate（可选，使用RFC3339规范的UTC格式）
• GET /api/v1/cars/:CarID/drives/:DriveID
• PUT /api/v1/cars/:CarID/logging/:Command
• GET /api/v1/cars/:CarID/logging
• GET /api/v1/cars/:CarID/status
• GET /api/v1/cars/:CarID/updates
• POST /api/v1/cars/:CarID/wake_up
• GET /api/v1/globalsettings
• GET /api/healthz
• GET /api/ping
• GET /api/readyz

[!TIP] RFC3339规范的UTC格式示例：2006-01-02T15:04:05Z 或 2006-01-02T15:04:05+07:00

认证

如果您想使用命令或日志端点，例如 /api/v1/cars/:CarID/command/:Command、/api/v1/cars/:CarID/wake_up 或 /api/v1/cars/:CarID/logging/:Command，需要在请求中添加认证。

您需要在环境变量文件中自行指定一个令牌（称为 API_TOKEN）。该令牌要求至少32个字符长。

有两种可用的认证方式：

1. 将额外的请求头 Authorization: Bearer <token> 添加到请求中。（推荐选项）

2. 在要访问的端点添加 URI 参数 ?token=<token>。（不推荐选项）

• 注意：如果使用第二种选项，且日志被泄露，您的令牌将面临泄露风险。

命令

命令默认未启用。

您需要在环境变量中启用它们（设置 ENABLE_COMMANDS=true），并指定要使用的命令。

有3种使用命令的方式：

1. 可以启用特定命令组，例如 COMMANDS_ALERT=true 将启用 警报 命令组。

2. 如果需要启用精细的命令集，可以使用 COMMANDS_ALLOWLIST=/path/to/allow_list.json 指定一个 JSON格式的命令列表 来启用。

3. 最粗略的选项 COMMANDS_ALL=true 将启用所有命令（特定组和允许列表将被忽略）。

• 注意：如果启用了 COMMANDS_ALL 或任何特定命令组，COMMANDS_ALLOWLIST 将被忽略。

可能的命令列表可在 环境变量 下找到。

关于命令中需要提供的字段，请参考 timdorr/tesla-api 文档。

安全信息

此 API 无法 访问您的 Tesla 账户令牌，我们将保持这一原则！

可访问的数据包括车辆、充电记录、行驶记录、当前状态、更新和全局设置等。

此外，请在容器前的 Web 服务器上应用一些认证措施，以确保您的数据不会未受保护而过度暴露。在上面的示例中，我们使用与 TeslaMate 相同的 .htpasswd 文件。

如果您在容器前应用了一定级别的认证，API_TOKEN_DISABLE=true 将允许无需请求头或 URI 令牌值即可执行命令。但即使如此，始终建议使用 API 密钥。

Credits

• 作者：Tobias Lindberg – https://github.com/tobiasehlert/teslamateapi/graphs/contributors
• 根据 MIT 许可证分发