UHD_Media_Tool/docs/runbook/backup-restore.md

备份与恢复运行手册(W4-B)

需求 §8.5:路径不携带完整身份,数据库里的映射(作品 ↔ 外部身份 ↔ 路径绑定 ↔ 资产位置 ↔ Slot ↔ 整理记录)就是关键资产。 只靠重新扫描目录恢复不了 Slot、审批、人工纠错和历史关系,所以备份以整库为准,映射清单做人工可读的副本与恢复校验。

备份内容

scripts/backup.sh(镜像内 /app/scripts/backup.sh,入口命令 umt backup)在 DATA_DIR/backups/<UTC 时间戳>/ 下生成:

文件	内容
db.dump	pg_dump --format=custom 整库:业务表、secret 表(密文)、任务引擎 schema、审计
mappings.json	--role export-mappings 导出的映射清单:library_root、path_mapping、media_entity、external_identity、path_binding、asset_location、acquisition_slot、organization_record 的关键列 + 每表行数(counts)
agent-sessions.tar.gz	Agent Pi JSONL 会话(有才打包)
manifest.txt	时间、pg_dump 版本、服务端版本、"主密钥未包含"标记
SHA256SUMS	以上文件校验和,恢复前校验

先写到 .<时间戳>.partial/,全部成功才改名,不会留下半截备份。BACKUP_KEEP=N(compose 缺省 14)时只保留最近 N 份。

SECRET_MASTER_KEY 不在备份里。 它和备份必须分开保管:备份泄露时密文仍然安全;主密钥丢失时备份里的站点/下载器/模型凭证无法解密(需要重新录入)。 恢复到新机器时,.env.deploy 里的 SECRET_MASTER_KEY 必须与备份时一致。

日常备份

docker compose --env-file .env.deploy exec app umt backup                              # 在线备份(pg_dump 一致性快照,不停服)
docker compose --env-file .env.deploy exec app ls /data/backups
# 拷到机器外(示例):
docker compose --env-file .env.deploy cp app:/data/backups/20260927T120000Z ./offsite/

定时:宿主 cron 0 4 * * * cd /opt/umt && docker compose --env-file .env.deploy exec -T app umt backup >> /var/log/umt-backup.log 2>&1。 单独导出映射清单:docker compose --env-file .env.deploy exec app umt export-mappings(写到 /data/exports/)。

恢复

恢复会删除并重建备份里的全部对象。先停 app,脚本检测到库里还有其它连接会拒绝(--force 可跳过,不建议)。

docker compose --env-file .env.deploy stop app
docker compose --env-file .env.deploy run --rm --no-deps app restore 20260927T120000Z --yes   # 或绝对路径 /data/backups/...
docker compose --env-file .env.deploy up -d app

restore.sh 依次:

1. 校验 SHA256SUMS;
2. pg_restore --clean --if-exists --no-owner 生成 SQL,经 psql --single-transaction -v ON_ERROR_STOP=1 回放(失败整体回滚,库保持恢复前状态)。当前镜像使用 18.6 客户端,支持 PG18 备份;回放前仍过滤 SET transaction_timeout,以兼容回滚到 PG16;
3. 还原 agent-sessions.tar.gz;
4. --role read-only-on:把 automation.readOnlyReconcile 置为 true(保留 automation 其它字段),写审计 ops.read_only_reconcile_on;
5. 重新导出映射清单到 DATA_DIR/tmp/restore-check-*.json,逐表与备份里的 counts 比对,不一致以退出码 3 结束;
6. 打印"恢复后先对账再关闭只读"提示。

从别的机器恢复:把备份目录拷进目标机器的 umt-data 卷(docker compose --env-file .env.deploy cp ./20260927T120000Z app:/data/backups/), .env.deploy 用原来的 SECRET_MASTER_KEY,空库上照上面的命令执行。备份早于当前镜像版本时,up -d app 会自动跑后续迁移。

恢复后:先对账,再关闭只读

只读对账模式下,自动下载提交、自动整理、订阅调度与 Agent/API Key 的自动执行一律拒绝(控制台首页有提示),查询和人工操作不受影响。

1. 库根:设置 → 媒体库根 → 逐个"测试"(哨兵文件在、目录可写)。
2. 下载器:下载页核对 qB 里的任务与库里的下载任务(托管标签)一致;路径映射"验证"。
3. 整理记录 / 资产位置:抽查最近的整理记录,目标文件确实存在。
4. 凭证:打开一个站点/下载器"测试",能通过说明主密钥一致。
5. 确认无误后关闭:设置 → 系统 → 关闭「只读对账」,或 PATCH /api/v1/settings {"automation":{"readOnlyReconcile":false}}。

开发机上用

脚本不依赖容器,只要有 pg_dump/pg_restore/psql:

cd apps/server && deno task compile && cd ../..
set -a; . ./.env; set +a
DATA_DIR=./data UMT_BIN=dist/umt-server scripts/backup.sh
DATA_DIR=./data UMT_BIN=dist/umt-server scripts/restore.sh <时间戳> --yes

验证记录

见 deploy.md#验证记录(同一次演练)。