相册分类备份与还原脚本

BaiHuaiyu

飞牛NAS相册备份还原脚本使用文档

一、脚本简介

本脚本适用于飞牛NAS，实现相册分类数据的备份与还原功能。脚本仅负责恢复相册分类结构与照片关联关系，不包含缩略图、AI识别数据的备份与还原。

相较于传统「直接复制数据库+原图+手动生成缩略图」的迁移方案，本脚本具备多项核心优势：

1. 备份体积小、操作极简：仅备份相册分类关联数据库，无需打包海量图片资源，备份、还原步骤大幅简化。
2. 无需文件配套适配：不要求备份的数据库与照片文件严格配套，脚本可自动适配处理关联逻辑。
3. 支持跨设备迁移：内置用户UID转换功能，完美适配不同NAS设备、不同用户UID场景的相册迁移。
4. 规避异常问题：通过专属数据处理逻辑，从源头杜绝路径不匹配、相册图片不显示、分类丢失等常见迁移故障。

二、前置条件

1. 技能要求

使用者需掌握基础 Linux 操作，包含：NAS SSH 连接、脚本运行、文件权限配置等基础操作。

2. 环境依赖

飞牛NAS自带 Python3 环境，无需额外安装依赖。

3. 脚本安装部署

下载脚本： 附件：albumTools.zip

将两个脚本文件上传至NAS任意目录（示例路径：/vol2/），并赋予执行权限：

chmod +x albumBackup.py
chmod +x albumRestore.py

三、脚本功能说明

脚本文件名	核心作用
albumBackup.py	相册数据库备份，导出完整相册分类关联数据
albumRestore.py	相册备份数据还原，支持UID映射、跨设备迁移

⚠️ 重要回滚预案

执行任何还原操作前，必须手动备份原相册数据库！

原数据库路径：/usr/local/apps/@appdata/trim.photos/db/photo.db

若还原出现异常，直接用该备份文件覆盖原文件即可完成手动回滚。

四、详细参数说明

1. 备份脚本 albumBackup.py

命令格式：sudo ./albumBackup.py [path] [--src 源数据库路径]

• 位置参数 path（必填）：数据库备份文件保存路径，示例：/vol2/photo-backup.db
• 可选参数 --src：需要备份的相册数据库原始路径，默认值：/usr/local/apps/@appdata/trim.photos/db/photo.db

2. 还原脚本 albumRestore.py

命令格式：sudo ./albumRestore.py [src] [--dst 目标路径] [--user UID映射]

• 位置参数 src（必填）：已备份的数据库文件路径，示例：/vol1/1000/相册备份/photo.db
• 可选参数 --dst：待还原的目标数据库路径，默认值：/usr/local/apps/@appdata/trim.photos/db/photo.db
• 可选参数 --user：用户UID归属映射，格式为 源UID:目标UID，支持多组映射，示例：1000:1002 1001:1003

五、完整使用教程

1. 相册标准备份流程

1. 飞牛NAS网页端停用相册应用（避免数据库占用报错）；
2. SSH执行备份命令：sudo ./albumBackup.py /vol2/photo-backup.db；
3. 手动备份NAS内所有原始照片文件（备份方式不限）；
4. 网页端重新启用相册应用，备份完成。

2. 同设备标准还原流程

1. 将备份的原始照片文件复制到当前NAS对应存储目录；
2. 启动相册应用，等待NAS自动完成照片索引、缩略图、AI识别构建；
3. 构建完成后，停用相册应用；
4. SSH执行还原命令：sudo ./albumRestore.py /vol2/photo-backup.db；
5. 重新启用相册，相册分类及照片关联关系恢复完成。

3. 跨设备高级还原（UID映射迁移）

基础概念

• 用户名：NAS登录的可视化账号（如 user1、user2）；
• 用户UID：系统内部用户唯一编码，可通过文件路径查看（路径中数字即为UID，如 /vol2/1000/xxx 中 1000 为用户UID）。

场景示例

旧设备备份数据：user1(UID:1000)、user2(UID:1001)

新设备用户UID：user1(UID:1002)、user2(UID:1003)

新旧设备UID不匹配，需手动配置UID映射，执行命令：

sudo ./albumRestore.py /vol2/photo-backup.db --user 1000:1002 1001:1003

六、核心工作流程

1. 备份核心逻辑

直接读取飞牛NAS默认相册数据库 photo.db，完整拷贝至用户指定的备份路径，仅保留相册分类、照片关联核心数据。

2. 还原核心逻辑

步骤1：恢复相册分类信息

• 清空目标数据库 user_album 旧数据表；
• 读取备份数据库的 user_album 数据，根据UID映射规则转换用户归属，写入目标数据库。

步骤2：重建照片-相册关联关系

• 清空目标数据库 album_user_photo 旧关联表；
• 通过文件哈希值（file_hash）精准匹配照片，重建所有照片与相册的绑定关系，写入数据库。

七、重要注意事项

1. 启停规则：所有备份、还原操作必须在停用相册应用状态下执行，防止数据库被进程占用，导致写入失败、数据库损坏。
2. 文件区分：脚本仅处理相册分类数据，不备份、不迁移原图照片，照片文件需用户手动备份还原。
3. UID参数规则：同设备还原无需配置 --user 参数，仅跨设备、UID不一致场景需要配置映射。