Initial TeslaMate dashboard

Author: zijian-z

.env.example

@@ -0,0 +1,22 @@
+# Aliyun image location used by compose.yaml
+IMAGE_REGISTRY=registry.cn-shenzhen.aliyuncs.com
+IMAGE_NAMESPACE=your-namespace
+IMAGE_TAG=latest
+
+# Only Nginx is published to the host.
+WEB_PORT=8080
+BASIC_AUTH_USER=admin
+BASIC_AUTH_PASSWORD=change-this-password
+
+# The Docker network where TeslaMate's PostgreSQL container is reachable.
+# Common TeslaMate compose network names are teslamate_default or teslamate_teslamate.
+TESLAMATE_DOCKER_NETWORK=teslamate_default
+
+# Use a read-only PostgreSQL role. See deploy/create-readonly-user.sql.
+# The host should be the database service/container name inside TESLAMATE_DOCKER_NETWORK.
+DATABASE_URL=postgresql://dashboard_readonly:replace-with-a-strong-password@database:5432/teslamate
+
+# Optional API tuning
+STATEMENT_TIMEOUT_MS=15000
+DB_POOL_MIN_SIZE=1
+DB_POOL_MAX_SIZE=5

.github/workflows/publish.yml

@@ -0,0 +1,73 @@
+name: Build and Push Images
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - image: tesla-dashboard-api
+            context: ./backend
+          - image: tesla-dashboard-web
+            context: ./frontend
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Aliyun Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ secrets.ALIYUN_REGISTRY }}
+          username: ${{ secrets.ALIYUN_USERNAME }}
+          password: ${{ secrets.ALIYUN_PASSWORD }}
+
+      - name: Prepare tags
+        id: tags
+        shell: bash
+        env:
+          REGISTRY: ${{ secrets.ALIYUN_REGISTRY }}
+          NAMESPACE: ${{ secrets.ALIYUN_NAMESPACE }}
+          IMAGE: ${{ matrix.image }}
+        run: |
+          set -euo pipefail
+          if [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+            VERSION="${GITHUB_REF_NAME}"
+          else
+            VERSION="${GITHUB_SHA::12}"
+          fi
+
+          {
+            echo "tags<<EOF"
+            echo "${REGISTRY}/${NAMESPACE}/${IMAGE}:${VERSION}"
+            if [[ "${GITHUB_REF_NAME}" == "main" ]]; then
+              echo "${REGISTRY}/${NAMESPACE}/${IMAGE}:latest"
+            fi
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: ${{ matrix.context }}
+          push: true
+          platforms: linux/amd64
+          tags: ${{ steps.tags.outputs.tags }}
+          cache-from: type=gha,scope=${{ matrix.image }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.image }}

.gitignore

@@ -0,0 +1,41 @@
+.env
+.env.*
+!.env.example
+.htpasswd
+*.htpasswd
+secrets/
+private/
+
+*.pem
+*.key
+*.crt
+*.p12
+*.pfx
+id_rsa*
+id_ed25519*
+known_hosts
+
+node_modules/
+dist/
+build/
+.vite/
+*.tsbuildinfo
+
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+venv/
+
+*.log
+*.bck
+*.dump
+*.backup
+*.bak
+*.sql.bz2
+*.sql.gz
+*.dump.gz
+*.backup.gz
+teslamate*.sql
+
+.DS_Store

README.md

@@ -0,0 +1,181 @@
+# TeslaMate Dashboard
+
+一个只读 TeslaMate 报表界面。它不依赖 TeslaMate 的 Web UI 或 Grafana，只读取 TeslaMate PostgreSQL 中 `public` schema 的行程、充电、位置、状态、升级等数据；Nginx 负责对外入口和 Basic Auth，后端与数据库都不暴露到宿主机端口。
+
+## 架构
+
+```text
+浏览器
+  |
+  | Basic Auth
+  v
+Nginx / Frontend  -- 内网 HTTP -->  FastAPI Backend  -- Docker 内网 -->  TeslaMate PostgreSQL
+```
+
+默认生产部署只发布 `web` 的 `WEB_PORT`。`api` 只在 Docker 内网暴露 `8000`，TeslaMate、Grafana、PostgreSQL 不需要对外开放端口。
+
+## 功能
+
+- 当前车辆状态、电量、额定续航、里程表、温度、胎压、软件版本
+- 周期行程统计：里程、时长、最高速度、估算能耗
+- 周期充电统计：充电次数、电量、费用、SOC 增量、进行中的充电
+- 日趋势、月汇总、电量/续航趋势、在线/睡眠/离线状态占比
+- 最近行程、最近充电、常到地点、充电地点
+- 移动端优先的单页界面
+
+## 本地用当前备份验证
+
+当前目录里的 `teslamate.bck` 是 PostgreSQL 18 plain SQL dump，可以直接用本地 compose 恢复测试库：
+
+```bash
+docker compose version
+```
+
+如果提示 `unknown command: docker compose` 或 `unknown shorthand flag: 'f' in -f`，说明没有安装 Docker Compose v2 插件。在 Ubuntu 24.04 上安装：
+
+```bash
+sudo apt-get update
+sudo apt-get install -y docker-compose-v2
+```
+
+```bash
+sudo docker compose -f compose.local.yaml up --build
+```
+
+访问：
+
+```text
+http://localhost:8080
+用户名：admin
+密码：change-me-local
+```
+
+首次启动会导入 `teslamate.bck`，需要等待 PostgreSQL 初始化完成。重新导入时先删除本地 volume：
+
+```bash
+sudo docker compose -f compose.local.yaml down -v
+sudo docker compose -f compose.local.yaml up --build
+```
+
+## 生产部署
+
+### 1. 创建只读数据库用户
+
+在 TeslaMate 的 PostgreSQL 数据库里执行 [deploy/create-readonly-user.sql](deploy/create-readonly-user.sql)，先替换密码：
+
+```sql
+create user dashboard_readonly with password 'replace-with-a-strong-password';
+grant connect on database teslamate to dashboard_readonly;
+grant usage on schema public to dashboard_readonly;
+grant select on all tables in schema public to dashboard_readonly;
+grant select on all sequences in schema public to dashboard_readonly;
+alter default privileges for role teslamate in schema public
+  grant select on tables to dashboard_readonly;
+alter role dashboard_readonly set default_transaction_read_only = on;
+alter role dashboard_readonly set statement_timeout = '15s';
+```
+
+不要给 `private` schema 授权。这样后端无法读取 Tesla API token。
+
+### 2. 找到 TeslaMate Docker 网络
+
+在部署机上查看 TeslaMate 所在网络：
+
+```bash
+sudo docker network ls | grep -i tesla
+```
+
+常见值是 `teslamate_default`。`DATABASE_URL` 里的数据库 host 要使用该网络内 PostgreSQL 服务名，常见是 `database`。
+
+### 3. 配置环境变量
+
+```bash
+cp .env.example .env
+```
+
+编辑 `.env`：
+
+```dotenv
+IMAGE_REGISTRY=registry.cn-shenzhen.aliyuncs.com
+IMAGE_NAMESPACE=your-namespace
+IMAGE_TAG=latest
+
+WEB_PORT=8080
+BASIC_AUTH_USER=admin
+BASIC_AUTH_PASSWORD=change-this-password
+
+TESLAMATE_DOCKER_NETWORK=teslamate_default
+DATABASE_URL=postgresql://dashboard_readonly:replace-with-a-strong-password@database:5432/teslamate
+```
+
+### 4. 启动
+
+先确认部署机有 Docker Compose v2：
+
+```bash
+docker compose version
+```
+
+Ubuntu 24.04 如果缺失 Compose v2：
+
+```bash
+sudo apt-get update
+sudo apt-get install -y docker-compose-v2
+```
+
+```bash
+sudo docker compose pull
+sudo docker compose up -d
+```
+
+之后访问：
+
+```text
+http://部署机IP:8080
+```
+
+只要外层还有反向代理或公网入口，把它转发到 `WEB_PORT` 即可；不需要暴露 TeslaMate、Grafana 或 PostgreSQL。
+
+## GitHub Actions 推送到阿里云镜像仓库
+
+工作流在 [.github/workflows/publish.yml](.github/workflows/publish.yml)。在 GitHub 仓库的 `Settings -> Secrets and variables -> Actions` 添加：
+
+| Secret | 示例 |
+| --- | --- |
+| `ALIYUN_REGISTRY` | `registry.cn-shenzhen.aliyuncs.com` |
+| `ALIYUN_NAMESPACE` | `your-namespace` |
+| `ALIYUN_USERNAME` | 阿里云镜像仓库用户名 |
+| `ALIYUN_PASSWORD` | 阿里云镜像仓库密码或访问凭证 |
+
+推送到 `main` 时会构建并推送：
+
+```text
+registry.cn-shenzhen.aliyuncs.com/your-namespace/tesla-dashboard-api:<commit-sha>
+registry.cn-shenzhen.aliyuncs.com/your-namespace/tesla-dashboard-api:latest
+registry.cn-shenzhen.aliyuncs.com/your-namespace/tesla-dashboard-web:<commit-sha>
+registry.cn-shenzhen.aliyuncs.com/your-namespace/tesla-dashboard-web:latest
+```
+
+推送 `v*` tag 时会额外使用 tag 名作为镜像 tag。
+
+## 直接开发
+
+后端：
+
+```bash
+cd backend
+python -m venv .venv
+. .venv/bin/activate
+pip install -r requirements.txt
+DATABASE_URL=postgresql://teslamate:teslamate@localhost:5432/teslamate uvicorn app.main:app --reload
+```
+
+前端：
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+前端开发服务器会把 `/api` 代理到 `http://localhost:8000`。

backend/.dockerignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+venv/
+.env
+Dockerfile

backend/Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY app ./app
+
+EXPOSE 8000
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--proxy-headers"]

backend/app/__init__.py

@@ -0,0 +1 @@
+"""TeslaMate read-only dashboard API."""

backend/app/config.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from functools import lru_cache
+
+
+@dataclass(frozen=True)
+class Settings:
+    app_name: str
+    database_url: str
+    statement_timeout_ms: int
+    db_pool_min_size: int
+    db_pool_max_size: int
+    cors_origins: tuple[str, ...]
+
+
+def _int_env(name: str, default: int) -> int:
+    raw = os.getenv(name)
+    if raw is None or raw == "":
+        return default
+    return int(raw)
+
+
+def _csv_env(name: str) -> tuple[str, ...]:
+    raw = os.getenv(name, "")
+    return tuple(item.strip() for item in raw.split(",") if item.strip())
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings(
+        app_name=os.getenv("APP_NAME", "TeslaMate Dashboard API"),
+        database_url=os.getenv(
+            "DATABASE_URL",
+            "postgresql://teslamate:teslamate@database:5432/teslamate",
+        ),
+        statement_timeout_ms=_int_env("STATEMENT_TIMEOUT_MS", 15000),
+        db_pool_min_size=_int_env("DB_POOL_MIN_SIZE", 1),
+        db_pool_max_size=_int_env("DB_POOL_MAX_SIZE", 5),
+        cors_origins=_csv_env("CORS_ORIGINS"),
+    )