feat(ops): W4-B single-container packaging, DATA_DIR, backup/restore
- DATA_DIR (/data: agent-sessions, backups, exports, tmp); entrypoint chowns it to PUID/PGID then drops privileges via gosu; /app binary stays root read-only - compile with --allow-read --allow-write so mounted library roots are writable - preflight: DATA_DIR/session dir must be writable (fatal); enabled library roots and downloader path mappings checked read/write (warn + audit) - --role export-mappings (mapping manifest JSON, --compare row counts) and --role read-only-on (automation.readOnlyReconcile=true + audit) - scripts/backup.sh (pg_dump custom + mappings + agent sessions, SHA256SUMS, BACKUP_KEEP rotation) and scripts/restore.sh (checksum, refuses with live connections, psql single-transaction replay compatible with PG16, read-only reconcile on, row-count verification) - compose: app + postgres only, data volume, env example with key generation - docs: runbook deploy.md, backup-restore.md with verification record Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
rootandClaude Opus 5.5 committed
1 parent
8c6a922cfb
commit
34e8751b45
18 files changed
+918
-43
No files matched your search
@@ -0,0 +1,81 @@
|
||||
# 备份与恢复运行手册(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` 里的 `SECRET_MASTER_KEY` 必须与备份时一致。
|
||||
|
||||
## 日常备份
|
||||
|
||||
```sh
|
||||
docker compose exec app umt backup # 在线备份(pg_dump 一致性快照,不停服)
|
||||
docker compose exec app ls /data/backups
|
||||
# 拷到机器外(示例):
|
||||
docker compose cp app:/data/backups/20260927T120000Z ./offsite/
|
||||
```
|
||||
|
||||
定时:宿主 cron `0 4 * * * cd /opt/umt && docker compose exec -T app umt backup >> /var/log/umt-backup.log 2>&1`。
|
||||
单独导出映射清单:`docker compose exec app umt export-mappings`(写到 `/data/exports/`)。
|
||||
|
||||
## 恢复
|
||||
|
||||
恢复会删除并重建备份里的全部对象。**先停 app**,脚本检测到库里还有其它连接会拒绝(`--force` 可跳过,不建议)。
|
||||
|
||||
```sh
|
||||
docker compose stop app
|
||||
docker compose run --rm --no-deps app restore 20260927T120000Z --yes # 或绝对路径 /data/backups/...
|
||||
docker compose up -d app
|
||||
```
|
||||
|
||||
`restore.sh` 依次:
|
||||
|
||||
1. 校验 `SHA256SUMS`;
|
||||
2. `pg_restore --clean --if-exists --no-owner` 生成 SQL,经 `psql --single-transaction -v ON_ERROR_STOP=1` 回放(失败整体回滚,库保持恢复前状态)。镜像里是 17 版客户端,回放前去掉 16 版服务端不认识的 `SET transaction_timeout`;
|
||||
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 cp ./20260927T120000Z app:/data/backups/`),
|
||||
`.env` 用原来的 `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`:
|
||||
|
||||
```sh
|
||||
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#验证记录](deploy.md#验证记录)(同一次演练)。
|
||||
Reference in new issue
Block a user