飞牛NAS相册备份还原脚本使用文档
一、脚本简介
本脚本适用于飞牛NAS，实现相册分类数据的备份与还原功能。脚本仅负责恢复相册分类结构与照片关联关系，不包含缩略图、AI识别数据的备份与还原。
相较于传统「直接复制数据库+原图+手动生成缩略图」的迁移方案，本脚本具备多项核心优势：
- 备份体积小、操作极简：仅备份相册分类关联数据库，无需打包海量图片资源，备份、还原步骤大幅简化。
- 无需文件配套适配：不要求备份的数据库与照片文件严格配套，脚本可自动适配处理关联逻辑。
- 支持跨设备迁移：内置用户UID转换功能，完美适配不同NAS设备、不同用户UID场景的相册迁移。
- 规避异常问题：通过专属数据处理逻辑，从源头杜绝路径不匹配、相册图片不显示、分类丢失等常见迁移故障。
二、前置条件
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. 相册标准备份流程
- 飞牛NAS网页端停用相册应用（避免数据库占用报错）；
- SSH执行备份命令：
sudo ./albumBackup.py /vol2/photo-backup.db；
- 手动备份NAS内所有原始照片文件（备份方式不限）；
- 网页端重新启用相册应用，备份完成。
2. 同设备标准还原流程
- 将备份的原始照片文件复制到当前NAS对应存储目录；
- 启动相册应用，等待NAS自动完成照片索引、缩略图、AI识别构建；
- 构建完成后，停用相册应用；
- SSH执行还原命令：
sudo ./albumRestore.py /vol2/photo-backup.db；
- 重新启用相册，相册分类及照片关联关系恢复完成。
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）精准匹配照片，重建所有照片与相册的绑定关系，写入数据库。
七、重要注意事项
- 启停规则：所有备份、还原操作必须在停用相册应用状态下执行，防止数据库被进程占用，导致写入失败、数据库损坏。
- 文件区分：脚本仅处理相册分类数据，不备份、不迁移原图照片，照片文件需用户手动备份还原。
- UID参数规则：同设备还原无需配置
--user 参数，仅跨设备、UID不一致场景需要配置映射。
