TeslaMate数据库迁移指南：PostgreSQL升级与数据备份最佳实践

1. 引言：为什么需要数据库迁移？

PostgreSQL数据库（关系型数据库管理系统，Relational Database Management System）的主版本升级通常包含重大功能改进和安全更新。对于TeslaMate用户而言，定期升级PostgreSQL不仅能提升系统性能，还能确保数据存储的安全性和兼容性。本指南将系统讲解PostgreSQL升级全流程，包括数据备份策略、风险规避措施和故障恢复方案，帮助用户平稳完成数据库迁移。

1.1 迁移前准备清单

在开始迁移前，请确认已完成以下准备工作：

• 已安装Docker Compose v2（参考Docker Compose官方迁移指南）
• 系统磁盘空间充足（建议至少为当前数据库大小的3倍）
• 已停止所有可能写入数据库的应用（如TeslaMate主服务）
• 已阅读本文档中"风险提示"章节

2. 数据备份：迁移的安全网

2.1 自动备份脚本

创建backup_teslamate.sh脚本实现一键备份：

#!/bin/bash
# 备份文件名包含时间戳（如 teslamate_20250922_030304.bck）
BACKUP_FILE="teslamate_$(date +%Y%m%d_%H%M%S).bck"

# 创建备份（-T 参数避免TTY分配错误，适用于crontab自动化）
docker compose exec -T database pg_dump -U teslamate teslamate > "$BACKUP_FILE"

# 验证备份文件完整性
if [ $? -eq 0 ] && [ -s "$BACKUP_FILE" ]; then
  echo "备份成功: $BACKUP_FILE"
  # 可选：复制到外部存储
  # cp "$BACKUP_FILE" /path/to/external/drive/
else
  echo "备份失败！请检查日志" >&2
  exit 1
fi

2.2 备份验证方法

备份完成后，执行以下命令验证文件有效性：

# 检查文件头是否包含PostgreSQL备份标识
head -n 1 teslamate_*.bck | grep -q "PGDMP" && echo "备份文件有效" || echo "备份文件损坏"

# 统计备份中的表数量（应与生产环境一致）
grep -c "CREATE TABLE" teslamate_*.bck

:::warning 安全警示 备份文件包含敏感车辆数据，请立即转移至加密存储设备。切勿将备份文件保留在Docker工作目录，部分GUI管理工具在升级时可能删除该目录。 :::

3. PostgreSQL升级全流程

3.1 升级流程图

flowchart TD
    A[创建备份] --> B[停止容器集群]
    B --> C{备份验证通过?}
    C -->|否| A
    C -->|是| D[删除旧数据库卷]
    D --> E[修改docker-compose.yml]
    E --> F[启动新数据库容器]
    F --> G[恢复数据]
    G --> H[验证数据完整性]
    H --> I[启动所有服务]

3.2 详细操作步骤

步骤1：停止TeslaMate服务

# 停止所有相关容器并保留网络配置
docker compose down --remove-orphans

步骤2：删除旧数据库卷

⚠️ 危险操作：此步骤将永久删除现有数据库。确保备份已验证无误！

# 获取数据库卷名称（通常为当前目录名_teslamate-db）
VOLUME_NAME="$(basename "$PWD")_teslamate-db"
echo "即将删除卷: $VOLUME_NAME"
docker volume rm "$VOLUME_NAME"

步骤3：修改配置文件

编辑docker-compose.yml更新PostgreSQL版本：

services:
  database:
    image: postgres:16  # 将16替换为目标版本号
    volumes:
      - teslamate-db:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=teslamate
      - POSTGRES_PASSWORD=secret
      - POSTGRES_DB=teslamate
    restart: always

volumes:
  teslamate-db:

步骤4：启动新数据库容器

# 仅启动数据库服务
docker compose up -d database

# 等待数据库初始化完成（约30秒）
until docker compose exec -T database pg_isready; do
  echo "等待数据库就绪..."
  sleep 5
done

步骤5：恢复数据备份

# 替换为实际备份文件名
BACKUP_FILE="teslamate_20250922_030304.bck"

# 清理目标数据库并创建必要扩展
docker compose exec -T database psql -U teslamate teslamate << SQL
DROP SCHEMA public CASCADE;
CREATE SCHEMA public;
CREATE EXTENSION cube;
CREATE EXTENSION earthdistance;
CREATE OR REPLACE FUNCTION public.ll_to_earth(float8, float8)
  RETURNS public.earth
  LANGUAGE SQL
  IMMUTABLE STRICT
  PARALLEL SAFE
  AS 'SELECT public.cube(public.cube(public.cube(public.earth()*cos(radians(\$1))*cos(radians(\$2))),public.earth()*cos(radians(\$1))*sin(radians(\$2))),public.earth()*sin(radians(\$1)))::public.earth';
SQL

# 执行恢复操作
docker compose exec -T database psql -U teslamate -d teslamate < "$BACKUP_FILE"

# 重启所有服务
docker compose up -d

4. 数据恢复与验证

4.1 恢复后检查项

检查内容	命令	预期结果
数据库连接	docker compose exec database psql -U teslamate -c "\l"	显示teslamate数据库
表结构完整性	docker compose exec database psql -U teslamate -c "\dt" teslamate	显示至少20张表
车辆数据	docker compose exec database psql -U teslamate -c "SELECT COUNT(*) FROM cars" teslamate	与备份前数量一致
最近充电记录	docker compose exec database psql -U teslamate -c "SELECT MAX(start_date) FROM charges" teslamate	显示最近日期

4.2 常见恢复问题解决

问题1：扩展创建失败

ERROR: extension "earthdistance" already exists

解决方法：跳过已存在的扩展创建

CREATE EXTENSION IF NOT EXISTS cube;
CREATE EXTENSION IF NOT EXISTS earthdistance;

问题2：备份文件权限错误

Permission denied when trying to read backup file

解决方法：修改文件权限并重新执行恢复

chmod 644 teslamate_*.bck
docker compose exec -T database psql -U teslamate -d teslamate < teslamate_*.bck

5. 高级迁移策略

5.1 不停机迁移方案

对于需要持续监控车辆状态的用户，可采用双数据库并行方案：

sequenceDiagram
    participant 主数据库(旧版本)
    participant 从数据库(新版本)
    participant TeslaMate服务
    
    TeslaMate服务->>主数据库(旧版本): 写入数据
   主数据库(旧版本)->>从数据库(新版本): 实时同步
    Note over 主数据库(旧版本),从数据库(新版本): 使用pg_replication
    TeslaMate服务-->>从数据库(新版本): 只读查询
    Note over TeslaMate服务: 切换VIP完成割接

5.2 自动化迁移脚本

创建upgrade_postgres.sh实现一键升级：

#!/bin/bash
set -euo pipefail

# 定义目标PostgreSQL版本
TARGET_VERSION=16

# 1. 创建备份
./backup_teslamate.sh

# 2. 停止服务
docker compose down

# 3. 删除旧卷
VOLUME_NAME="$(basename "$PWD")_teslamate-db"
docker volume rm "$VOLUME_NAME"

# 4. 更新配置文件
sed -i "s/postgres:[0-9]\+/postgres:$TARGET_VERSION/" docker-compose.yml

# 5. 启动新数据库
docker compose up -d database

# 6. 等待数据库就绪
until docker compose exec -T database pg_isready; do
  echo "等待数据库就绪..."
  sleep 5
done

# 7. 恢复数据
BACKUP_FILE=$(ls -t teslamate_*.bck | head -1)
./restore_teslamate.sh "$BACKUP_FILE"

# 8. 启动所有服务
docker compose up -d

echo "PostgreSQL升级完成！当前版本:"
docker compose exec database psql -U teslamate -c "SELECT version();"

6. 风险提示与故障恢复

6.1 高风险操作清单

操作	风险等级	预防措施
删除数据库卷	⚠️⚠️⚠️	执行前验证备份有效性
修改docker-compose.yml	⚠️	使用版本控制工具追踪变更
恢复过程中断	⚠️⚠️	确保恢复期间网络稳定

6.2 灾难恢复流程

当升级失败导致系统无法启动时，执行以下步骤回滚：

1. 停止当前数据库容器
2. 恢复旧版本PostgreSQL配置
3. 创建空数据库卷
4. 启动旧版本数据库容器
5. 恢复最近一次成功备份

# 回滚示例
docker compose down
sed -i "s/postgres:16/postgres:14/" docker-compose.yml
docker volume create "$(basename "$PWD")_teslamate-db"
docker compose up -d database
./restore_teslamate.sh teslamate_20250922_030304.bck

7. 总结与最佳实践

7.1 迁移周期建议

• 主版本升级：每12-18个月（如从14→16）
• 次版本升级：通过Docker自动更新（无需数据迁移）
• 数据备份：每日自动备份，保留至少7个历史版本

7.2 关键经验总结

1. 备份优先：任何数据库操作前必须创建可验证的备份
2. 环境隔离：建议先在测试环境验证升级流程
3. 版本选择：使用PostgreSQL官方镜像，避免第三方修改版本
4. 监控跟进：升级后24小时内监控系统日志和数据同步状态

通过遵循本文档中的步骤，您可以安全地完成TeslaMate的PostgreSQL数据库升级，确保车辆数据的长期可管理性和系统稳定性。如需进一步支持，请参考TeslaMate官方文档或社区论坛。