TeslaMate v4.4.0 常用 CLI 命令与工具详解

TeslaMate v4.4.0 命令面速查：bin/teslamate 十一命令帮助全文与 version/pid/eval/rpc 实测回显、Release.migrate 迁移触发（幂等）、psql 数据库巡检 15 表、Grafana API 表单登录与 24 张仪表盘核对、compose 日常子集与 401/迁移失败等排障。

TeslaMateTeslaMate数据采集2026/11/01

TeslaMate v4.4.0 常用 CLI 命令与工具详解

目标：把 TeslaMate v4.4.0 日常运维会碰到的全部命令面收敛成一篇可独立执行的速查手册——Elixir release 自带的 bin/teslamate 启动控制命令（帮助全文、版本、eval 求值、rpc 远程调用、数据库迁移触发）、数据库侧 psql 查询、Grafana HTTP API 验证、容器编排日常操作，每条命令配真实回显。已在 TeslaMate 4.4.0 运行实例上逐条实测（部署过程见 《TeslaMate v4.4.0 Docker Compose 部署指南》）。

一、环境信息

  • 操作系统：Ubuntu 26.04.1 LTS（x86_64，内核 7.0.0-38-generic）
  • TeslaMate：v4.4.0（官方镜像 teslamate/teslamate:4.4.0；官方最新稳定版 2026-11-01 实查仍为 v4.4.0）
  • 部署形态：Docker Compose 四服务栈（项目名 teslamate-4.4.0-stack，compose 目录 /opt/teslamate/）
  • TeslaMate 安装目录（容器内 release 根目录）：/opt/app，命令入口 /opt/app/bin/teslamate
  • 运行时：Erlang/OTP 29 (jit)（启动日志实测回显 System Info: Erlang/OTP 29 (jit)）
  • 数据库：PostgreSQL 18.6（库名 teslamate，用户 teslamate）；Grafana 13.2.4（宿主机 8135 → 3000）
  • TeslaMate Web：宿主机 8128 → 容器 4000

二、工具概览

TeslaMate 是常驻 Web 服务，官方没有提供独立的系统管理 CLI 二进制（无 teslamate-cli 之类工具）。日常运维的命令面由四类工具构成，各管一段：

工具所在位置职责本篇章节
bin/teslamaterelease 安装目录（本机 /opt/app/bin/teslamate）应用启停控制、版本查询、Elixir 表达式求值（eval/rpc）、远程 shell、数据库迁移触发五、6
psql数据库服务器数据库巡检、表结构查看、数据量统计、迁移版本核对七
Grafana HTTP APIcurl 调 3000 端口服务健康、仪表盘清单、数据源配置验证八
docker compose部署机四服务栈的启停、日志、重建（部署细节见部署篇，本篇只收日常子集）九

💡 技术拓展：bin/teslamate 不是 TeslaMate 专属程序，而是 Elixir/Phoenix 应用的标准 release 控制脚本（Elixir 官方 releases 机制随应用构建生成）。| 命令形态 | 原理 | 适用场景 | |---|---|---| | bin/<app> eval "EXPR" | 新起一个非引导 BEAM 实例执行表达式后退出 | 迁移触发、离线脚本任务 | | bin/<app> rpc "EXPR" | 连上运行中系统的分布式节点远程执行 | 在线查运行时状态 | | bin/<app> remote | 连上运行系统进入交互式 IEx shell | 深度排障调试 |

TeslaMate 完全沿用这套标准机制，因此本篇命令对任何 Elixir release 应用（Phoenix 系服务）通用。

三、前置条件

  • TeslaMate 四服务栈已在运行（docker compose ps 四容器 Up，部署见部署篇）；
  • 容器内执行命令统一用 docker exec teslamate-4.4.0-app <命令> 形态；裸机（官方 Debian 手动安装形态，不受官方支持）则直接在安装目录执行 bin/teslamate；
  • Grafana 管理账号：admin / q1w2e3r4（部署篇预设 GF_SECURITY_ADMIN_PASSWORD 的形态）。

四、bin/teslamate 帮助全文（命令清单）

不带参数调用即输出全部可用命令与一句话说明，这是命令面的权威清单：

docker exec teslamate-4.4.0-app bin/teslamate

实测回显（逐行照抄）：

Usage: teslamate COMMAND [ARGS]

The known commands are:

    start          Starts the system
    start_iex      Starts the system with IEx attached
    daemon         Starts the system as a daemon
    daemon_iex     Starts the system as a daemon with IEx attached
    eval "EXPR"    Executes the given expression on a new, non-booted system
    rpc "EXPR"     Executes the given expression remotely on the running system
    remote         Connects to the running system via a remote shell
    restart        Restarts the running system via a remote command
    stop           Stops the running system via a remote command
    pid            Prints the operating system PID of the running system via a remote command
    version        Prints the release name and version to be booted

十一个命令分三组：前台/后台启动（start/start_iex/daemon/daemon_iex——容器形态下由镜像入口脚本执行，运维无需手工调用）、表达式执行（eval/rpc/remote）、运行时控制（restart/stop/pid/version）。

五、常用命令详解（实测）

5.1 version：查询版本

docker exec teslamate-4.4.0-app bin/teslamate version

实测回显：

teslamate 4.4.0

升级后第一时间核对版本用它（与启动日志 [info] Version: 4.4.0 互证）。

5.2 pid：查询主进程 PID

docker exec teslamate-4.4.0-app bin/teslamate pid

实测回显：

7

与进程表核对（BEAM 虚拟机进程即 pid 7）：

docker exec teslamate-4.4.0-app sh -c 'for p in /proc/[0-9]*; do if grep -q beam $p/comm 2>/dev/null; then echo "pid=$(basename $p) comm=$(cat $p/comm)"; fi; done'

实测回显：

pid=7 comm=beam.smp

5.3 eval：在新实例上执行 Elixir 表达式

eval 在「非引导的新系统」上执行表达式（帮助原文：on a new, non-booted system），执行完即退出，不影响运行中的服务。日常两大用途：

用途一：触发数据库迁移（升级后手工补跑的官方姿势）：

docker exec teslamate-4.4.0-app bin/teslamate eval "TeslaMate.Release.migrate"

实测回显（迁移已全部应用时的幂等输出）：

2026-11-01 11:34:33.517 [info] Migrations already up

💡 说明：TeslaMate 主服务每次启动会自动执行迁移（部署篇 4.5 节实测），正常升级无需手工跑这条命令；它的价值在于自动迁移失败后的手工重试与确认迁移状态（幂等，重复执行安全）。

用途二：读取运行时环境（验证环境变量注入）：

docker exec teslamate-4.4.0-app bin/teslamate eval "IO.puts(System.get_env(\"TZ\"))"

实测回显：

Asia/Shanghai

任意 Elixir 表达式均可求值，如算术：

docker exec teslamate-4.4.0-app bin/teslamate eval "IO.puts(1 + 1)"

实测回显：

2

5.4 rpc：在运行中的系统上远程执行表达式

rpc 连接正在运行的 BEAM 节点执行表达式，能拿到真实运行时状态（eval 拿不到）：

docker exec teslamate-4.4.0-app bin/teslamate rpc "node() |> IO.inspect()"

实测回显：

:teslamate@f23a7a974459

节点名格式为 :teslamate@<主机名>（@后即当前机器主机名）。rpc 可用即证明分布式节点通道健康。

5.5 remote：交互式远程 shell（调试用）

bin/teslamate remote

进入运行系统的交互式 IEx shell，可逐行求值、查进程、看 ETS——深度排障的最后手段。⚠️ 该命令是交互式会话，无法在本篇的逐命令实测形态下回显；且在 IEx 里执行有副作用的代码（如重启应用）会直接影响线上服务，仅排障时短会话使用，退出用 Ctrl+C 两次。

5.6 stop / restart：远程停止与重启运行时

bin/teslamate stop       # 向运行中系统发送优雅停止命令
bin/teslamate restart    # 远程重启运行时

两者均通过远程命令作用于运行中系统。⚠️ 容器形态下不推荐用它们管服务——stop 会把容器主进程带停、触发 restart: always 策略重启整容器，效果等价于 docker restart teslamate-4.4.0-app 但多绕一层；服务级重启统一走 compose（见第九章）。本篇未对运行实例执行 stop/restart（避免无谓的服务中断）。

六、数据库迁移机制与命令

迁移（migration）是 TeslaMate 数据库结构变更的载体，两条命令面：

# 1. 自动迁移：主服务每次启动时执行（部署篇 4.5 节实测日志形态）
#    == Running 20190330150000 TeslaMate.Repo.Migrations.CreateCar.change/0 forward
#    == Migrated 20190330150000 in 0.0s

# 2. 手工触发：eval 调 Release.migrate（幂等）
docker exec teslamate-4.4.0-app bin/teslamate eval "TeslaMate.Release.migrate"

2026-11-01 11:34:33.517 [info] Migrations already up

核对已应用迁移数（当前库共 107 个迁移版本，2026-11-01 实测）：

docker exec teslamate-4.4.0-db psql -U teslamate -d teslamate -t -c "SELECT count(*) FROM schema_migrations;"

实测回显：

   107

升级版本后此数增长即代表新迁移已应用。若启动日志出现迁移报错（== Error 行），按「先备份 → 手工 eval 迁移 → 观察日志」顺序处理，仍失败则回滚到上一版本镜像并带日志求助社区。

七、数据库巡检命令（psql）

Grafana 仪表盘的本质是 SQL，数据库侧命令是深度排障与数据校验的底层工具。统一入口：

docker exec teslamate-4.4.0-db psql -U teslamate -d teslamate -c "<SQL>"

表清单（15 张业务表，实测回显）：

docker exec teslamate-4.4.0-db psql -U teslamate -d teslamate -c "\dt"

                    List of tables
 Schema |          Name           | Type  |   Owner   
--------+-------------------------+-------+-----------
 public | addresses               | table | teslamate
 public | car_settings            | table | teslamate
 public | cars                    | table | teslamate
 public | charges                 | table | teslamate
 public | charging_processes      | table | teslamate
 public | drives                  | table | teslamate
 public | geofences               | table | teslamate
 public | import_file_checkpoints | table | teslamate
 public | import_rejections       | table | teslamate
 public | import_runs             | table | teslamate
 public | positions               | table | teslamate
 public | schema_migrations       | table | teslamate
 public | settings                | table | teslamate
 public | states                  | table | teslamate
 public | updates                 | table | teslamate
(15 rows)

核心表速记：cars 车辆、positions 逐秒轨迹、drives 行程、charging_processes/charges 充电会话与明细、states 状态变迁（在线/离线/休眠枚举）、addresses 地址反解缓存、geofences 地理围栏、updates 软件更新、import_runs/import_rejections/import_file_checkpoints TeslaFi 导入三件套。

扩展核对（cube/earthdistance 必须在位，实测回显）：

docker exec teslamate-4.4.0-db psql -U teslamate -d teslamate -c "\dx"

                                 List of installed extensions
     Name      | Version | Default version |   Schema   |                         Description                          
---------------+---------+-----------------+------------+--------------------------------------------------------------
 cube          | 1.5     | 1.5             | public     | data type for multidimensional cubes
 earthdistance | 1.2     | 1.2             | public     | calculate great-circle distances on the surface of the Earth
 plpgsql       | 1.0     | 1.0             | pg_catalog | PL/pgSQL procedural language
(3 rows)

连接池巡检（DATABASE_POOL_SIZE 未设默认 10 时的实测形态）：

docker exec teslamate-4.4.0-db psql -U teslamate -d teslamate -c "SELECT application_name, state, count(*) FROM pg_stat_activity WHERE datname='teslamate' GROUP BY 1,2;"

 application_name | state  | count 
------------------+--------+-------
                  | idle   |    10
 psql             | active |     1
(2 rows)

车辆注册核对（绑定车辆后应有行）：

docker exec teslamate-4.4.0-db psql -U teslamate -d teslamate -t -c "SELECT id, name, vid FROM cars;"

本机未绑定真实特斯拉账号（该步骤依赖真实账号凭据，见部署篇 4.8 节），实测返回 0 行（空）。

逻辑备份一行流（官方维护文档姿势）：

docker exec teslamate-4.4.0-db pg_dump -U teslamate teslamate > /opt/teslamate/teslamate-$(date +%F).bck

恢复方向（重建库后回灌）用 psql -U teslamate teslamate < 备份文件，完整备份/恢复流程见官方 Maintenance 文档。

八、Grafana 验证命令（curl）

Grafana 无 CLI，验证走 HTTP API。该定制镜像关闭了 HTTP Basic 认证（直接 -u admin:q1w2e3r4 会 401，排障见 10.1 节），统一先表单登录取会话 Cookie：

curl -s -c /tmp/gf-cookie.txt -H 'Content-Type: application/json' \
  -d '{"user":"admin","password":"q1w2e3r4"}' http://127.0.0.1:8135/login

实测回显：

{"message":"Logged in","redirectUrl":"/"}

健康检查（无需登录）：

curl -s http://127.0.0.1:8135/api/health

{
  "database": "ok",
  "version": "13.2.4",
  "commit": "0e79aef9d91abf3bdadae9af15763029072fb45b"
}

仪表盘清单（预置面板自动导入确认；27 项 = 3 个导航文件夹 + 24 张仪表盘，实测逐行照抄）：

curl -s -b /tmp/gf-cookie.txt 'http://127.0.0.1:8135/api/search' \
  | python3 -c 'import json,sys; d=json.load(sys.stdin); print("count:",len(d)); [print(x["title"]) for x in d]'

count: 27
Internal
Reports
TeslaMate
Battery Health
Charge Details
Charge Level
Charges
Charging Stats
Database Information
Drive Details
Drive Stats
Drives
Drives - Dutch tax
Efficiency
Home
Locations
Mileage
Overview
Projected Range
States
Statistics
Temperatures
Timeline
Trip
Updates
Vampire Drain
Visited

数据源核对（PostgreSQL 数据源自动配置确认）：

curl -s -b /tmp/gf-cookie.txt 'http://127.0.0.1:8135/api/datasources'

实测回显（节选）：

[{"id":1,"uid":"PC98BA2F4D77E1A42","orgId":1,"name":"TeslaMate","type":"grafana-postgresql-datasource","typeName":"PostgreSQL",...,"url":"database:5432","user":"teslamate",...,"jsonData":{"database":"teslamate","postgresVersion":1500,"sslmode":"disable"},...}]

💡 说明：仪表盘「导入」在 TeslaMate 形态下是自动的——teslamate/grafana 定制镜像启动时经 provisioning 机制导入全部预置面板与数据源，升级镜像后新面板同样自动到位；手工导入官方 JSON 的做法只在用原版 grafana/grafana 镜像时才需要（部署篇第二章对比）。清单里 Drives - Dutch tax 为地区专用面板、Home 为导航主页，官方 Screenshots 页的 22 张统计口径不含这两者。

九、容器编排日常命令（compose 子集）

部署篇第十章有完整清单，日常最高频的五条：

cd /opt/teslamate
docker compose ps                    # 四服务状态一览
docker logs -f teslamate-4.4.0-app   # 跟踪主服务日志（采集活动、错误）
docker compose up -d                 # 变更 compose 后增量拉起（幂等）
docker compose up -d --force-recreate teslamate   # 改环境变量后重建主服务
docker compose pull && docker compose up -d       # 升级：拉新镜像并滚动更新（启动自动迁移）

up -d 增量拉起的实测回显形态（仅状态变化的服务有输出）：

 Container teslamate-4.4.0-db Running 
 Container teslamate-4.4.0-app Starting 
 Container teslamate-4.4.0-app Started

十、注意事项与常见问题

10.1 Grafana API 返回 401 Unauthorized

{"extra":null,"message":"Unauthorized","messageId":"auth.unauthorized","statusCode":401,"traceID":""}

原因：Grafana 13 定制镜像关闭 HTTP Basic 认证，curl -u 形态一律 401（实测确认）。解决：走 POST /login 表单登录取 Cookie 再带 Cookie 调 API（第八章统一入口的两条命令），浏览器访问不受影响。

10.2 eval 与 rpc 的选择

  • eval：新起非引导实例执行，看不到运行中系统的内存状态，适合迁移、环境变量核对等离线任务；
  • rpc：连运行中节点执行，能拿运行时状态（node()、进程列表），但执行有副作用的表达式会直接影响服务；
  • 判据：改数据/查静态配置用 eval，查运行时用 rpc，交互调试用 remote。

10.3 容器里 bin/teslamate 报 No such file or directory

exec 默认工作目录不一定是 release 根目录。统一用绝对路径或先切目录：

docker exec teslamate-4.4.0-app sh -c 'cd /opt/app && bin/teslamate version'

teslamate 4.4.0

10.4 rpc 报连不上节点

运行中系统尚未就绪（启动几秒内）或系统已崩溃时 rpc 无法建立连接。先 docker logs teslamate-4.4.0-app --tail 20 确认 Running TeslaMateWeb.Endpoint 行已出现，再试 rpc。

10.5 迁移失败（升级后启动报错）

症状：启动日志出现 == Error 或应用反复重启。处理顺序：pg_dump 全量备份 → bin/teslamate eval "TeslaMate.Release.migrate" 手工重试看完整报错 → 按报错修（多为旧数据兼容问题）→ 无法解决时把镜像标签改回上一版本回滚（数据卷不动），带完整日志向官方仓库提 issue。

十一、参考链接

TeslaMate v4.4.0 常用 CLI 命令与工具详解 - Quzuo