部署指南

推荐将 Xiaomi EV Mate 部署在私有环境，例如 NAS、家庭服务器或个人云主机。
项目会保存车辆和账号相关配置，不建议直接暴露在公网。

按设备选择部署方式

普通 Linux 服务器：Linux 一键安装教程
绿联 NAS：绿联 NAS 安装教程
极空间 NAS：极空间安装教程

方式一：脚本一键部署

curl -fSsL 'https://www.xiaomievmate.com/scripts/install.sh' | sudo bash

首次部署时，脚本会提示输入数据库密码。完整步骤请查看 Linux 一键安装教程。

默认会拉取：

ponyix/xiaomiev-mate:backend-latest
ponyix/xiaomiev-mate:web-latest

方式二：手动使用 Docker Compose

如果你希望自己控制 Compose 配置，可以直接创建 docker-compose.yml 部署，不需要额外创建 .env。

创建 docker-compose.yml：

services:
  postgres:
    image: postgres:15-alpine
    container_name: xiaomiev-postgres
    restart: always
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: your_strong_password
      POSTGRES_DB: xiaomi_ev
      TZ: Asia/Shanghai
    ports:
      - "15432:5432"
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    healthcheck:
      test: [ "CMD-SHELL", "pg_isready -U postgres" ]
      interval: 5s
      timeout: 5s
      retries: 5

  xiaomiev-mate:
    container_name: xiaomiev-mate
    image: ponyix/xiaomiev-mate:backend-latest
    pull_policy: always
    volumes:
      - ./logs:/var/log/xiaomiev
      - ./config:/config
    environment:
      - TZ=Asia/Shanghai
      - SPRING_DATASOURCE_URL=jdbc:postgresql://postgres:5432/xiaomi_ev?stringtype=unspecified
      - SPRING_DATASOURCE_USERNAME=postgres
      - SPRING_DATASOURCE_PASSWORD=your_strong_password
      - XIAOMIEV_CONFIG_DIRECTORY=/config
    restart: always
    depends_on:
      postgres:
        condition: service_healthy

  xiaomiev-mate-web:
    container_name: xiaomiev-mate-web
    image: ponyix/xiaomiev-mate:web-latest
    pull_policy: always
    ports:
      - "18080:80"
    restart: always
    depends_on:
      - xiaomiev-mate

`config` 持久化目录的用途

config 是后端保存本地配置文件的目录，Compose 中保留 ./config:/config 和 XIAOMIEV_CONFIG_DIRECTORY=/config 即可。首次启动后，目录里会有：

config/.secrets/field-keyring.json：数据加密密钥环。
config/backup：自动备份生成的 .xmbak 文件。

更新镜像或重建容器时，保留原来的 config 即可。如果密钥文件丢失，数据将无法恢复和读取。数据迁移和备份可以采用系统中个人中心->数据备份功能，仅v1.1.3后的功能支持。

镜像拉取失败时

默认镜像地址直接从 Docker Hub 拉取。如果部署时提示镜像拉取超时、失败或 429，可将 Compose 中的三个 image 地址替换为 Xiaomi EV Mate 镜像代理地址：

    image: docker.xiaomievmate.com/postgres:15-alpine
    image: docker.xiaomievmate.com/ponyix/xiaomiev-mate:backend-latest
    image: docker.xiaomievmate.com/ponyix/xiaomiev-mate:web-latest

固定版本时保留原有 tag 即可，例如 docker.xiaomievmate.com/ponyix/xiaomiev-mate:backend-v1.0.x。

按需修改：

your_strong_password：数据库密码，必须替换成自己的强密码，两处要保持一致。
backend-latest：后端镜像版本。如果要固定版本，可以改成 backend-v1.0.x。
web-latest：前端镜像版本。如果要固定版本，可以改成 web-v1.0.x。
获取项目最新版本号更新日志。
15432:5432：数据库端口映射。如果宿主机 15432 被占用，可以改成其他端口，例如 25432:5432。
18080:80：前端访问端口。如果宿主机 18080 被占用，可以改成其他端口，例如 8080:80。

启动服务：

docker compose -f docker-compose.yml up -d

前端默认访问地址：

http://localhost:18080

固定版本部署

如果不想使用 latest，可以固定前后端镜像版本：

BACKEND_IMAGE_TAG=v1.0.x WEB_IMAGE_TAG=v1.0.x ./deploy.sh

也可以在 .env 中配置：

BACKEND_IMAGE_TAG=v1.0.5
WEB_IMAGE_TAG=v1.0.5

如果只想分别升级后端或前端，也可以指定不同版本。获取项目最新版本号更新日志。

部署建议

推荐部署在私有网络中。
首次登录后立即修改默认管理员密码。
不要把 .env、数据库数据和账号参数公开提交。
临时体验后可删除容器和数据，避免敏感信息残留。