如何无损平滑升级homelab-hub:Docker镜像更新与SQLite数据库自动迁移实战
如何无损平滑升级homelab-hub:Docker镜像更新与SQLite数据库自动迁移实战
homelab-hub 是一个自托管的家庭实验室资产管理系统,用于统一管理硬件、虚拟机、应用、存储、网络等资产。很多新手在升级 homelab-hub 时最怕两件事:Docker 镜像更新后配置丢失、SQLite 数据库结构变更导致数据损坏。本文带你掌握 homelab-hub 的平滑升级方法,通过备份 data/ 目录 + 镜像自动迁移机制,实现一次完成、数据零丢失的版本升级。
一、先搞懂原理:为什么升级可以"无损"
很多同门服务升级后数据就"没了",而 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 为例,它展示了"无损迁移"的完整套路:
- 新增
raw_space_tb/usable_space_tb列; - 用
UPDATE ... SET raw_space_tb = raw_space_gb / 1024.0把旧数据换算后拷贝过去; - 删除旧的 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。按照本文的步骤操作,哪怕版本跨度再大,你的资产数据也会安然无恙地跟随系统一起升级。
