如何无损平滑升级homelab-hub:Docker镜像更新与SQLite数据库自动迁移实战

原创2026-10-24 10:52:041,993 阅读

如何无损平滑升级homelab-hub:Docker镜像更新与SQLite数据库自动迁移实战

homelab-hub 是一个自托管的家庭实验室资产管理系统,用于统一管理硬件、虚拟机、应用、存储、网络等资产。很多新手在升级 homelab-hub 时最怕两件事:Docker 镜像更新后配置丢失、SQLite 数据库结构变更导致数据损坏。本文带你掌握 homelab-hub 的平滑升级方法,通过备份 data/ 目录 + 镜像自动迁移机制,实现一次完成、数据零丢失的版本升级。

homelab-hub 家庭实验室资产管理系统升级后的网络地图界面

一、先搞懂原理:为什么升级可以"无损"

很多同门服务升级后数据就"没了",而 homelab-hub 天生具备两个让升级变简单的特性:

1. 代码与数据完全分离

容器内的代码每次升级都会被整体替换,但所有资产数据都存放在独立的 SQLite 数据库中,并通过 Docker 卷挂载到宿主机的 ./data/ 目录(数据库文件为 data/homelab-hub.db)。也就是说:升级只是换了新代码,你的数据始终在宿主机上。

这一机制在 docker-compose.yml 中定义:

services:
  homelab-hub:
    image: raidowl/homelab-hub:latest
    container_name: homelab-hub
    ports:
      - "8000:8000"
    volumes:
      - ./data:/data   # 关键:数据卷挂载,升级不丢数据
    restart: unless-stopped

2. 数据库迁移自动执行

homelab-hub 使用 Alembic 管理 SQLite 数据库的表结构版本。容器的启动脚本 backend/docker-entrypoint.sh 会先执行迁移、再启动应用:

#!/bin/sh
set -e

echo "Running database migrations..."
alembic upgrade head   # 先升级数据库到最新版本

echo "Starting application..."
exec gunicorn --bind 0.0.0.0:8000 --workers 1 --timeout 120 wsgi:app

所以你只需拉取新镜像并重启容器,数据库结构会自动迁移到位,全程无需手动操作。

二、升级前准备:备份 data 目录(最关键一步)

虽然机制上已经足够安全,但"先备份再升级"永远是铁律。只需一行命令:

cp -r ./data ./data-backup-$(date +%Y%m%d)

💡 进阶做法:还可以额外导出一份 JSON 备份作为双保险(见 backend/app/routes/inventory.py 实现的导出接口):

curl -X GET http://localhost:8000/api/inventory/export -o homelab-export.json

这样即使数据库文件损坏,也能通过"导入数据"功能恢复全部资产。

三、标准升级步骤:两条命令完成镜像更新

方式 A:使用 Docker Compose(推荐)

# 1. 拉取最新版镜像
docker pull raidowl/homelab-hub:latest

# 2. 停止旧容器并用新镜像启动
docker compose down
docker compose up -d

容器启动时会自动执行 alembic upgrade head,把 SQLite 数据库迁移到新版本结构,然后正常服务,整个过程通常只需几十秒。

方式 B:使用 docker run 部署

docker stop homelab-hub
docker rm homelab-hub
docker run -d \
  --name homelab-hub \
  -p 8000:8000 \
  -v ./data:/data \
  --restart unless-stopped \
  raidowl/homelab-hub:latest

⚠️ 注意:-v ./data:/data 的挂载参数不能漏,否则新容器会使用容器内的空数据库,历史数据将"消失"在旧目录里。

四、SQLite 数据库自动迁移是如何工作的

升级过程中后台究竟做了什么?homelab-hub 的迁移脚本全部位于 backend/migrations/versions/,每个版本脚本按 down_revision 链接成一条升级链:

版本 内容
001 初始表结构(hardware、vms、apps、storage 等)
003 移除 hypervisor、misc 增加 IP
005 存储空间从 GB 换算为 TB
007 应用增加 https 字段
008 硬件和虚拟机增加 MAC 地址字段
add89462ccd0 新增 shares(共享目录)表

alembic upgrade head 会读取数据库当前版本,只执行尚未运行的脚本,已执行的自动跳过。以 backend/migrations/versions/005_storage_gb_to_tb.py 为例,它展示了"无损迁移"的完整套路:

  1. 新增 raw_space_tb / usable_space_tb 列;
  2. 用 UPDATE ... SET raw_space_tb = raw_space_gb / 1024.0 把旧数据换算后拷贝过去;
  3. 删除旧的 GB 列。

此外,backend/utils/migration_helpers.py 提供了 add_column_if_not_exists() 辅助函数——列已存在时静默跳过,让迁移脚本具备幂等性,即使部分执行过也不会报错,这正是"平滑"的关键。

五、非 Docker 环境如何升级

如果你直接部署在服务器上(见 README.md 的 Non-Docker Deployment 章节),升级流程为:

git pull                       # 拉取最新代码
cd backend
pip install -r requirements.txt # 更新依赖
alembic upgrade head           # 手动执行数据库迁移
# 重新构建前端并重启 gunicorn

其中 backend/migrations/env.py 会读取 Flask 应用配置中的 DATABASE_URL,确保迁移作用于正确的数据库文件。

六、升级验证与问题回滚

验证升级成功

# 1. 查看健康检查
curl http://localhost:8000/api/health
# 返回 {"status": "ok"} 即正常

# 2. 查看启动日志,确认迁移正常完成
docker logs homelab-hub | head -20
# 应看到 "Running database migrations..." 与 "Starting application..."

然后打开浏览器访问 http://localhost:8000,确认资产列表、网络地图等数据完好无损。

万一出问题:一键回滚

因为升级前备份了 data/ 目录,回滚非常简单:

# 1. 停止服务
docker compose down

# 2. 用备份恢复数据
rm -rf ./data
cp -r ./data-backup-20260220 ./data

# 3. 启动旧版本镜像(把镜像 tag 换回旧版本即可)
docker compose up -d

配合 JSON 导出备份,数据双保险基本不可能丢失。

七、升级最佳实践清单 ✅

实践 说明
先备份再升级 cp -r ./data ./data-backup-日期,30 秒的事
固定使用 latest 或明确版本 tag 便于需要时切回旧版本
保留 JSON 导出 数据库级备份之外的逻辑备份
升级后跑一次健康检查 GET /api/health + 页面抽查

总结

homelab-hub 的升级之所以能做到无损平滑,核心在于两点设计:数据卷与代码分离 + Alembic 启动时自动迁移。你只需要记住三步:备份 data/ 目录 → 拉取新镜像 → 重启容器,剩下的交给 alembic upgrade head。按照本文的步骤操作,哪怕版本跨度再大,你的资产数据也会安然无恙地跟随系统一起升级。

登录后查看全文
homelab-hub