TeslaMate v4.4.0 配置参数详解

目标：把 TeslaMate v4.4.0 运行期可配置的全部环境变量按用途分成八类逐项讲清——官方默认值、取值规则、实测行为与踩坑点，并给出家用 NAS（2 GB 内存）场景的生产配置模板。全部默认值取自官方文档 Environment Variables 页（docs.teslamate.org，查询日期 2026-11-01），参数生效行为均在 Docker Compose 部署的 TeslaMate 4.4.0 实例上实测验证（部署过程见 《TeslaMate v4.4.0 Docker Compose 部署指南》）。

一、环境信息

• 操作系统：Ubuntu 26.04.1 LTS（x86_64）
• TeslaMate：v4.4.0（官方镜像 teslamate/teslamate:4.4.0，2026-11-01 实查官方最新稳定版仍为 v4.4.0）
• 部署形态：Docker Compose 四服务栈（teslamate + PostgreSQL 18.6 + Grafana 13.2.4 + eclipse-mosquitto 2），项目名 teslamate-4.4.0-stack，compose 目录 /opt/teslamate/
• TeslaMate Web：宿主机 8128 → 容器 4000；Grafana：8135 → 3000
• 参数来源：官方文档 https://docs.teslamate.org/docs/configuration/environment_variables（2026-11-01 查询）
• Grafana 侧另有少量 Grafana 原生变量（GF_SECURITY_ADMIN_PASSWORD 等），不属于 TeslaMate 参数，本篇仅在部署关联处提及

二、前置条件

• 已按部署篇完成四服务栈启动且四容器 Up（TeslaMate 未绑定真实车辆不影响本篇实验——参数注入与启动日志验证不依赖车辆数据）；
• compose 目录可编辑（本篇参数修改统一走「改 compose → force-recreate」流程）；
• 能查看 TeslaMate 启动日志：docker logs teslamate-4.4.0-app。

三、参数查看与修改方式

3.1 查看当前生效参数

TeslaMate 没有配置文件，全部参数经环境变量注入，三种查看途径：

# 途径一：看 compose 声明（期望值）
docker inspect teslamate-4.4.0-app --format '{{range .Config.Env}}{{println .}}{{end}}' | sort | grep -vE '^(PATH|HOME|LANG)='

实测回显：

DATABASE_HOST=database
DATABASE_NAME=teslamate
DATABASE_PASS=q1w2e3r4
DATABASE_USER=teslamate
ENCRYPTION_KEY=teslamate-demo-key-2026
MQTT_HOST=mosquitto
PORT=4000
TZ=Asia/Shanghai

# 途径二：容器进程视角（与途径一应一致；SRTM_CACHE 是镜像内置变量，compose 未声明）
docker exec teslamate-4.4.0-app env | sort | grep -vE '^(PATH|HOME|HOSTNAME|TERM|SHLVL|PWD|LANG|_)'

实测回显：

DATABASE_HOST=database
DATABASE_NAME=teslamate
DATABASE_PASS=q1w2e3r4
DATABASE_USER=teslamate
ENCRYPTION_KEY=teslamate-demo-key-2026
MQTT_HOST=mosquitto
PORT=4000
SRTM_CACHE=/opt/app/.srtm_cache
TZ=Asia/Shanghai

# 途径三：启动日志的参数读取行为（部分参数启动时回显读取结果）
docker logs teslamate-4.4.0-app 2>&1 | grep -E 'proxy|compatible'

实测回显：

2026-11-01 11:34:02.937 [info] PostgreSQL version 18.6 is compatible (18.x series).
2026-11-01 11:34:02.955 [info] [proxy] read NOMINATIM_PROXY=nil
2026-11-01 11:34:02.955 [info] [proxy] NOMINATIM_PROXY unset -> fallback: no proxy

未声明的变量即取官方默认值（如 DATABASE_POOL_SIZE 默认 10、PORT 默认 4000）。

3.2 修改参数的正确姿势

cd /opt/teslamate
# 1. 编辑 docker-compose.yml 中对应服务的 environment 段
# 2. 重建受影响服务（restart 不会刷新环境变量，必须 recreate）
docker compose up -d --force-recreate teslamate
# 3. 观察日志确认新参数生效
docker logs -f teslamate-4.4.0-app

实测回显（recreate 正常形态）：

 Container teslamate-4.4.0-app Recreate 
 Container teslamate-4.4.0-app Recreated 
 Container teslamate-4.4.0-app Starting 
 Container teslamate-4.4.0-app Started 

⚠️ 注意：docker compose restart teslamate 只重启进程、环境变量仍用容器创建时的旧值——改参数后必须 up -d --force-recreate（或至少 up -d 让 compose 检测到 env 变化自动 recreate）。

四、参数总览

官方文档列出的全部运行期变量，按类归组（默认值一栏为官方口径）：

💡 说明：以上共 40 余个变量。TeslaMate 无配置文件热加载机制——任何变量修改都要走 3.2 节的 recreate 流程；数据库连接类与 ENCRYPTION_KEY 属「启动即依赖」参数，配置错误会阻断启动（实测见 8.1、8.2 节）。

五、核心参数分类详解

5.1 数据库连接类（DATABASE_*）

TeslaMate 经 Ecto 连接 PostgreSQL，四要素 DATABASE_USER/PASS/NAME/HOST 是部署必填项（官方模板形态）。关键可选参数：

• DATABASE_PORT（默认 5432）：库端口非标准时设置。本机实测默认形态下数据库侧连接池行为——DATABASE_POOL_SIZE 未设（默认 10）时，库内可见 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)

• DATABASE_POOL_SIZE（默认 10）：连接池大小。官方文档标注「Size of the database connection pool」。本机实测注入 DATABASE_POOL_SIZE=3 后 compose 正常重建（Recreated → Started），TeslaMate 正常启动，验证该参数可安全下调；家用单车辆 3–5 足够，多车辆或高频 Grafana 查询保持 10；
• DATABASE_TIMEOUT（默认 60000）：单条查询超时毫秒数，Grafana 大跨度查询慢时可调大；
• DATABASE_SSL（默认 false）：库连接加密。库在容器网络内网直连场景保持 false；true 需配 DATABASE_SSL_CA_CERT_FILE（PEM CA 证书路径），nverify 跳过证书校验；
• DATABASE_SOCKET_DIR：改走 UNIX socket 连接（socket 文件所在目录），设置后 DATABASE_HOST/PORT 不再使用；目录内 socket 免密时连 DATABASE_USER/PASS 也可省略（peer 认证）。同机裸机部署（非容器）时最常用。

⚠️ 密码不一致故障：DATABASE_PASS 与 database 服务的 POSTGRES_PASSWORD 不同值时，TeslaMate 日志每秒刷 FATAL 28P01 (invalid_password) password authentication failed for user "teslamate"（实测回显与解决流程见部署篇 11.2 节）。

5.2 Web 与安全类（PORT / VIRTUAL_HOST / CHECK_ORIGIN / URL_PATH / HTTP_BINDING_ADDRESS）

• PORT（默认 4000）：Web 界面容器内监听端口。实测本机 PORT=4000，启动日志确认 Running TeslaMateWeb.Endpoint with cowboy 2.20.0 at :::4000 (http)；改端口需同步调整 compose 的 ports: 映射右侧；
• HTTP_BINDING_ADDRESS（默认空 = 全部地址）：绑定 IP。仅内网网卡监听时设具体 IP；
• VIRTUAL_HOST（默认 localhost）：生成站内跳转 URL 的主机部分。反代场景设为对外域名（如 teslamate.example.com）；
• URL_PATH（默认 /）：应用挂在反代子路径时设置（如 /teslamate）；
• CHECK_ORIGIN（默认 false）：Phoenix WebSocket 的 Origin 头校验。官方取值：true（按 VIRTUAL_HOST 校验，推荐）、false（不校验）、或逗号分隔白名单（如 https://example.com,//another.com:8080，支持通配符）。经反代/域名访问 LiveView 界面时必须开（否则页面报 WebSocket 连接失败）。

5.3 令牌与 API 类（ENCRYPTION_KEY / TOKEN / TESLA_*）

• ENCRYPTION_KEY：加密特斯拉 API 令牌的密钥（官方标注 required）。唯一不可逆的参数：绑定车辆产生数据后更换，旧令牌解密失败、车辆离线，只能重新生成令牌登录。建议 openssl rand -base64 48 生成；
• TOKEN：第三方 Tesla API 供应商（Fleet API 代理，如 MyTeslaMate/Teslemetry）的 Bearer 令牌，设置后所有 API 请求带 Authorization: Bearer <TOKEN>；个人账号用不到；
• TESLA_API_HOST（默认 https://owner-api.teslamotors.com）：Owner API 域名。中国大陆账号设为 https://owner-api.vn.cloud.tesla.cn；
• TESLA_WSS_HOST（默认 wss://streaming.vn.teslamotors.com）：流式接口域名，中国区同理换 .cn 域名；
• TESLA_AUTH_HOST/PATH/CLIENT_ID（默认 https://auth.tesla.com / /oauth2/v3 / ownerapi）：登录认证端点，特斯拉变更认证接口时官方会更新默认值，一般不动；
• TESLA_API_POOL_SIZE（默认 10）：对 Tesla API 域名的 HTTP 并发池；
• TESLA_WSS_USE_VIN：流式订阅改用 VIN 标识车辆（部分车队账号场景）。

5.4 MQTT 类（DISABLE_MQTT / MQTT_*）

TeslaMate 把车辆状态实时发布到 MQTT 主题（teslamate/cars/<车ID>/...），这是官方声明的唯一受支持集成面。关键实测：

• DISABLE_MQTT（默认 false）：设 true 彻底关闭 MQTT 客户端。本机做过 A/B 实测——false（默认形态）启动日志有：

2026-11-01 11:34:03.863 [info] MQTT connection has been established

注入 DISABLE_MQTT=true 重建后，启动日志同一阶段无任何 MQTT 行（连接逻辑未执行），两种形态日志对照即为该参数生效证据。不使用 Home Assistant/Node-RED 联动时可开启省一个 MQTT 依赖（此时 compose 可整段删掉 mosquitto 服务并去掉 MQTT_HOST）；

• MQTT_HOST（未禁用时必填）：Broker 主机名，本机实测 mosquitto（compose 服务名即 DNS 名）；
• MQTT_PORT（默认 1883；TLS 8883）/ MQTT_USERNAME / MQTT_PASSWORD / MQTT_TLS / MQTT_TLS_ACCEPT_INVALID_CERTS / MQTT_IPV6：Broker 接入细节。官方模板 mosquitto 用免认证配置，四项均可不设；Broker 加了认证后依次补齐；
• MQTT_NAMESPACE：主题插一级命名空间，如设 account_0 后主题变为 teslamate/account_0/cars/$car_id/state——单实例多账号汇聚到同一 Broker 时区分数据来源；
• MQTT_HOME_ASSISTANT_DISCOVERY（默认 false）：v4.4.0 原生支持 HA 自动发现，设 true 后 TeslaMate 向 <PREFIX>/.../config 发布发现配置，HA 自动生成实体，免去手工维护 mqtt_sensors.yaml；配套 MQTT_HOME_ASSISTANT_DISCOVERY_URL（发现面板里展示的 TeslaMate 地址）与 MQTT_HOME_ASSISTANT_DISCOVERY_PREFIX（默认 homeassistant）。官方注明：不开启时每次启动会清理发现主题。

💡 技术拓展：车辆状态外发的通道不止 MQTT 一种。| 通道 | 特点 | 适用场景 | |---|---|---| | MQTT（本组件主通道） | 实时主题推送，官方唯一受支持集成面 | Home Assistant / Node-RED 联动 | | 直接读 PostgreSQL | Grafana 天然走此路；官方声明库结构非对外接口，第三方直读不保证兼容 | 自建报表（自担升级风险） | | 社区 REST 封装（TeslaMateApi 等） | 官方 Projects 页收录的第三方项目，非官方组件 | 需要类 REST API 的轻量集成 |

本组件官方立场明确：MQTT 是唯一受支持集成面，本篇参数讲解也以 MQTT 类为主。

5.5 采集轮询类（POLLING_*）

车辆静默后 TeslaMate 按状态分档轮询 Owner API（行驶中改走流式接口）。六个间隔参数（秒）：

官方对全部六个参数标注同一警告：Do not alter this setting unless you are certain of the implications——调小会打断车辆休眠（每次 API 调用重置入睡计时器，长期结果是「幽灵耗电」增加），调大牺牲状态实时性。家用场景保持默认，本机未实测改动。

5.6 HTTP 与代理类（HTTP_POOL_SIZE / HTTP_POOL_TIMEOUT / NOMINATIM_PROXY）

• HTTP_POOL_SIZE（默认 5）：非 Tesla API 域名（Nominatim、api.github.com 等）的并发连接池上限；HTTP_POOL_TIMEOUT（默认 10000 微秒）：从池获取连接的等待超时。默认即可，地址反解量大（多车长途）时可升 HTTP_POOL_SIZE；
• NOMINATIM_PROXY：OpenStreetMap Nominatim 地址反解请求的 HTTP 代理（仅 HTTP 形式，如 http://127.0.0.1:7897）。本机实测启动日志固定回显该参数读取行为：

2026-11-01 11:34:02.955 [info] [proxy] read NOMINATIM_PROXY=nil
2026-11-01 11:34:02.955 [info] [proxy] NOMINATIM_PROXY unset -> fallback: no proxy

Nominatim 被墙或限流的环境，把代理地址落进该变量即可让反解流量走代理（其余 Tesla API 流量不在此列）。

5.7 数据导入类（IMPORT_DIR / TESLAFI_IMPORT_VEHICLE_ID）

• IMPORT_DIR（默认 ./import）：TeslaFi/apiscraper CSV 导入目录（容器内路径）。官方模板 bind mount ./import:/opt/app/import 与默认值配套，一般不动；
• TESLAFI_IMPORT_VEHICLE_ID：TeslaFi 数据无车辆标识时用的默认车辆 ID（不设取 1）。多车导入前规划好。

5.8 运行时杂项（TZ / DEFAULT_GEOFENCE / ULIMIT_MAX_NOFILE）

• TZ：本地时区（官方注明参见 tz database 时区列表）。本机实测 TZ=Asia/Shanghai，日志时间戳即为东八区（如 2026-11-01 11:34:08.113）；同时设到 database 与 grafana 服务保持三处一致；
• DEFAULT_GEOFENCE（默认 ""）：车辆不在任何地理围栏时上报的 GEOFENCE 缺省值，一般不设；
• ULIMIT_MAX_NOFILE（官方默认 65536）：限制 TeslaMate 进程的打开文件描述符上限，官方注明用于「默认 ulimit 值非常高的环境」防止内存膨胀，0 关闭该机制。本机实测：宿主 Docker 默认 hard limit 524288 的环境下，注入 ULIMIT_MAX_NOFILE=2048 重建后与默认形态对比，进程限制实测值均为 Max open files 1024 524288（soft 1024 / hard 524288），未见可见变化——该参数针对的「极高 ulimit」场景在本机不成立，家用环境无需关心；

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 grep "open files" $p/limits; fi; done'

实测回显：

Max open files            1024                 524288               files     

• SRTM_CACHE（镜像内置，非官方变量表成员）：海拔数据（ESA DEM）缓存目录，实测容器内为 /opt/app/.srtm_cache，无需配置。

六、Grafana 侧关联参数

teslamate/grafana 定制镜像用四个同名变量生成 PostgreSQL 数据源（部署篇实测 /api/datasources 回显 "name":"TeslaMate","url":"database:5432","user":"teslamate"），与 TeslaMate 服务的数据库类参数必须同值：

外加 Grafana 原生变量 GF_SECURITY_ADMIN_PASSWORD（管理员密码预设，本机 q1w2e3r4；不设则默认 admin/admin 首登强改）。数据源指向错误时症状是仪表盘能开、面板全部无数据（Grafana 数据源连通测试报错），按 5.1 节密码一致性排查。

七、生产配置模板（家用 NAS，2 GB 内存）

适用场景：单台家庭服务器/NAS（2 GB 内存、NVMe 或 SSD）、单账号 1–2 辆车、内网使用 + Home Assistant 联动。TeslaMate 服务 environment 段推荐：

    environment:
      - ENCRYPTION_KEY=<openssl rand -base64 48 生成的长随机串>   # 生成后妥善备份，产生数据后不可更换
      - DATABASE_USER=teslamate
      - DATABASE_PASS=<与 POSTGRES_PASSWORD 同值的强密码>
      - DATABASE_NAME=teslamate
      - DATABASE_HOST=database
      - DATABASE_POOL_SIZE=5          # 单车辆家用 5 足够（默认 10 亦无妨）
      - MQTT_HOST=mosquitto
      - MQTT_HOME_ASSISTANT_DISCOVERY=true   # HA 用户开启自动发现
      - MQTT_HOME_ASSISTANT_DISCOVERY_URL=https://teslamate.example.com
      - VIRTUAL_HOST=teslamate.example.com   # 经反代/域名访问时设置
      - CHECK_ORIGIN=true                    # 与 VIRTUAL_HOST 配套开启 WebSocket 来源校验
      - PORT=4000
      - TZ=Asia/Shanghai

磁盘：PostgreSQL 数据卷所在盘预留 ≥10 GB（逐秒轨迹数据五年量级约数 GB，随里程增长）；轮询参数保持官方默认；DATABASE_SSL 内网保持 false。

⚠️ 公网暴露警示（官方口径）：TeslaMate 4000 端口与 Grafana 3000 端口不要直接映射到公网——令牌泄露等于车辆控制权泄露。远程访问走 VPN/Cloudflare Tunnel/Tailscale 或带 TLS + Basic Auth 的反向代理（官方文档有 Traefik/Apache2 高级指南）。

八、常见问题

8.1 改了 compose 但参数没生效

docker compose restart 不刷新环境变量。实测正确流程：改 docker-compose.yml → docker compose up -d --force-recreate teslamate → docker exec teslamate-4.4.0-app env | grep <变量名> 核对（回显见 3.1 节途径二）。

8.2 数据库密码错误刷屏 28P01

DATABASE_PASS 与 POSTGRES_PASSWORD 不一致（或库内密码与变量不一致）时 TeslaMate 无法启动，日志每秒刷 FATAL 28P01 (invalid_password)（完整实测回显与三处一致性说明见部署篇 11.2 节）。库已初始化后改 POSTGRES_PASSWORD 不改库内密码，需 ALTER USER 同步。

8.3 ENCRYPTION_KEY 换了之后车辆全部离线

该密钥加密入库令牌，产生数据后不可更换。恢复方法：把 key 改回原值重启；或接受重新走一遍令牌生成与车辆登录（原令牌数据无法解密）。

8.4 中国大陆账号连不上特斯拉接口

Owner API 与流式接口默认用国际域名，中国区账号需把 TESLA_API_HOST 与 TESLA_WSS_HOST 换成 *.tesla.cn 域名（官方变量表明确列出中国区取值，见 5.3 节）；同时确认出站放行 auth.tesla.com 等必通域名。

九、参考链接

• 官方环境变量参考（默认值出处）：https://docs.teslamate.org/docs/configuration/environment_variables
• 官方 MQTT 集成文档（主题清单与 HA Discovery）：https://docs.teslamate.org/docs/integrations/mqtt
• 官方 Home Assistant 集成文档：https://docs.teslamate.org/docs/integrations/home_assistant
• 官方数据导入文档（TeslaFi）：https://docs.teslamate.org/docs/import/teslafi
• v4.4.0 发布说明：https://github.com/teslamate-org/teslamate/releases/tag/v4.4.0
• 本专栏配套篇目：《TeslaMate v4.4.0 介绍与选型指南》、《TeslaMate v4.4.0 Docker Compose 部署指南》（部署主线与排障实录）、《TeslaMate v4.4.0 常用 CLI 命令与工具详解》（命令行工具）