Files
knowledge-governance/docs/PRODUCTION_BACKUP_RECOVERY.md
T
姚章浩 19e0596e1d fix(backup): 整库逻辑备份按库容错,默认跳过 RDS 管理库 rdsadmin
单库 pg_dump 失败(权限/编码/管理库)不再中止整次备份:清掉半个目录、记进 MANIFEST.failed_databases、
轮转照常执行、最后按失败情况给退出码。云主机实跑:33 秒 / 742.6 MiB / 8 库 / 失败 0。
2026-10-09 12:25:12 +08:00

90 lines
8.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 生产级备份与恢复(目标环境)
面向目标环境(云上 WeKnora v0.7.1 + Aliyun RDS + ES + OSS)。核心原则只有一条:
**导入/发布之前,先把目标库现场留档,然后才允许写库** —— 这件事不是靠人记得做,而是靠发布前置硬门禁强制。
## 现状(2026-10-09 实测)
| 层 | 状态 | 证据 |
|---|---|---|
| 导入前留档(PG 行 + ES 文档) | ✅ 已建:`scripts/target_kb_snapshot.sh` 云内执行,8 张表 + 该库在 ES 的全部文档(只读 scroll,gzip JSONL,按 `_id` 可重建)+ `MANIFEST.json`(行数/字节/sha256/每库 ES 文档数)+ `export.sql` + `README.md`。实测 **2 分 52 秒**(两个库 13.1 万条 ES 文档 / 692 MB,字节留云主机);`PULL_ES=1` 拉回本机则 **19 分 40 秒** | `$KB_BACKUP_ROOT/target-kb-snapshots/<UTC>-<kb8>/`(云主机全量;本地镜像 PG 行 + 清单) |
| 发布前硬门禁 | ✅ 已上线(`internal/releasesnapshot`):写目标库之前必须存在覆盖该库、24h 内、**PG 行与 ES 文档两层都齐备且哈希可校验**的留档,否则 `release_target_snapshot_missing`(不可重试),目标库一行不碰 | 单测 10(门禁)+ 6(发布器);`go run ./cmd/guardcheck $KB_BACKUP_ROOT/target-kb-snapshots <kb_id>` 实测:两个绑定库 PASS、未绑定库 BLOCK |
| 自管整库逻辑备份 | ✅ 已建并在云主机实跑:`scripts/logical-backup.sh`(`pg_dump -Fd -j4 -Z6` 目录格式,可并行/按表恢复;按天轮转保留 7 份 + 每月一份)。实测 **33 秒 / 742.6 MiB / 214 文件 / 失败 0**,覆盖该实例全部 8 个库(`weknora_test`、`weknora_prod`、`weknora_drill74`、`dobotai_prod/test`、`knowledge_adapter_prod/test`、`postgres`);RDS 管理库 `rdsadmin` 默认跳过,单库失败只记账不中止 | `$KB_BACKUP_ROOT/rds-logical/<UTC>/<库>.dir` + `MANIFEST.json`(含 `failed_databases`) |
| ES 快照 | ✅ 已建:仓库 `kb_backup`(容器内 `path.repo=/usr/share/elasticsearch/backup`,宿主 `$KB_BACKUP_ROOT/es-snapshots`)→ 首个快照 `initial-20261009t024209z` **36 秒 / 4.7 GB / 0 分片失败**;SLM `kb-hourly`(留 3 天)+ `kb-daily`(留 7 天)已各成功执行 | `GET _snapshot/kb_backup/_all`、`_slm/policy/*` |
| OSS 对象 | ✅ 目标桶 `dobot-weknora-test` 已开启**版本控制**(覆盖/删除可按 VersionId 回滚);未配跨区域复制 | `GET /?versioning` = `Enabled` |
| RDS 托管备份 | ⏳ **待控制台确认**:库里 `archive_mode=on` 但 `archive_command` 为空、`pg_stat_archiver.archived_count=0`;当前连接 `is_superuser=off`(看不到备节点)→ 系列与日志备份开关只能看控制台 | 见下节 |
## 备份目录契约(换主机只改一处)
任何一台扮演"目标库所在主机"的机器(现在的**测试云主机**、未来的**生产云主机**、以及本地演练机)
都跑同一份 `scripts/backup_layout.sh`,得到同一套落点:
| 目录 | 内容 | 谁写 |
|---|---|---|
| `$KB_BACKUP_ROOT/target-kb-snapshots/<UTC>-<kb8>/` | 导入前留档(PG 8 表 + ES 文档 + 清单) | `scripts/target_kb_snapshot.sh` |
| `$KB_BACKUP_ROOT/rds-logical/<UTC>/` | 整库逻辑备份(`pg_dump -Fd`) | `scripts/logical-backup.sh` |
| `$KB_BACKUP_ROOT/es-snapshots/` | ES 共享仓库 `kb_backup` 的宿主目录 | ES 快照 / SLM |
| `$KB_BACKUP_ROOT/logs/` | 上述脚本运行日志 | 各脚本 |
- 默认 `$KB_BACKUP_ROOT=/srv/kb-backups`,由 `/etc/knowledge-governance/backup.env` 落盘(`backup_layout.sh` 生成);
脚本与 compose 都读它:`source /etc/knowledge-governance/backup.env`,compose 用 `${KB_BACKUP_ROOT:-…}` 插值。
- 已执行实例:测试云主机 `/srv/kb-backups/`(原 `/opt/weknora-test/{kb-snapshots,es-backup}` 已迁移,
容器内路径不变,ES 仓库无需重新注册、快照与 SLM 全部保留)。
- **切到生产云主机时**:① 在生产云主机跑同一份 `backup_layout.sh`;② 把生产 compose 的
ES 挂载源与发布前留档挂载源指向 `$KB_BACKUP_ROOT`;③ 门禁配置 `target_snapshot.root` 保持
**容器内路径** `/var/lib/knowledge-governance/target-kb-snapshots`(不用改);④ 在发布管理里授权前先跑一次留档。
## RDS 控制台(约 5 分钟;先看"系列")
实例:`pgm-wz9ohr9gk919pr1q`(PostgreSQL 17.9,阿里云 RDS)。
1. 实例列表 → 点实例 ID → 左侧「备份恢复」→「备份策略」。
2. 「数据备份设置」编辑:备份周期 ≥ 每周 2 次(建议周一/周四)、时间窗 03:00-04:00、
**保留天数 14 天**(可选 7~730;不可关闭;云盘实例可开秒级备份/提高频率)。
3. 「日志备份设置」:**打开日志备份**(决定能否按时间点恢复 PITR)、保留 7 天。
注意:日志保留必须 ≤ 数据保留;关掉会清空已有日志备份并失去 PITR。
4. 抄下四个值到 `RDS_BACKUP_POLICY.md`:数据保留天数、日志备份开关+保留天数、最近一次备份完成时间、**最近可恢复时间点**。
5. 分支:**高可用系列** → 支持"按时间点恢复到新实例"(云盘实例不复制白名单/安全组,需重配);
**基础系列** → 不支持日志备份/PITR,改用:数据保留期拉长 + 稀疏备份(月/年各留一份)+
开云盘加密后启用跨地域备份;控制台有「实例备份下载」按钮时才可导出到 OSS。
只读旁证(最终以控制台为准):
```bash
docker run --rm --network host postgres:17-alpine psql "$TARGET_DB_URL" \
-c "show archive_mode; show archive_command; select archived_count, last_archived_time from pg_stat_archiver"
```
## 恢复路径(按事故类型选,越快越靠前)
| 事故 | 首选 | 耗时 |
|---|---|---|
| 某个 KB 的 wiki / 元数据被覆盖 | **留档回填**(快照目录 `README.md` 的 SQL:先删按 `_id`/主键冲突行,再 `\copy` 回) | 秒~分钟 |
| 检索/向量异常、索引误删 | **ES 快照 restore**(`kb_backup`;或按 `es_documents.jsonl.gz` 用 `_id` 重建) | 分钟级 |
| OSS 对象被覆盖 / 删除 | **OSS 版本控制**回滚单对象或前缀 | 秒~分钟 |
| 整库被改坏(要带走/异地一份) | **自管逻辑备份** `pg_restore -j4` 到临时库或新实例 | 分钟~十分钟 |
| 整实例级错误、需要"回到某个时刻" | **RDS 快照 / PITR** → 新实例 → 按 KB 取行 | 10~30 分钟 |
| 主机/磁盘整体丢失 | ES 仓 + 留档在**同一块盘**上 → 必须靠 RDS 托管备份 + OSS(见"边界") | 30 分钟+ |
## 每次导入/发布前的标准动作
1. `bash scripts/target_kb_snapshot.sh`(默认云内执行 + ES 字节留云主机,实测 **2 分 52 秒**;
PG 8 张表 44 秒,其余是 ES 只读 scroll 导出;`INCLUDE_CHUNKS=1` 才带 chunks,
`PULL_ES=1` 才把 692 MB ES 导出拉回本机——家用上行 ~0.6 MB/s,要 19 分 40 秒);
2. **不需要人工登记**:worker 门禁自动核验"覆盖目标库 + 24h 内 + PG 与 ES 两层哈希可校验";
3. 门禁报 `release_target_snapshot_missing` → 先跑第 1 步,再在发布管理里授权发布;
4. 想复核门禁判断,可直接跑 `go run ./cmd/guardcheck $KB_BACKUP_ROOT/target-kb-snapshots <kb_id>`。
## 边界(别把这些当"已经备份了")
- 留档**不含**:OSS 对象本体(`resources.jsonl` 只记路径/大小/哈希)、ES 索引 settings/mappings、
表结构与索引、列出知识库之外的行。整库级要靠 RDS 托管备份 + 自管逻辑备份。
- **ES 快照仓与留档在同一台云主机、同一块盘**上:整机故障会一起丢。异地副本需把
`es-snapshots/` 与 `target-kb-snapshots/` 同步到 OSS(需一把可写备份桶的 AK,属授权项)。
- 自管逻辑备份**不能替代 PITR**:它只能回到"备份那一刻",且恢复要靠 `pg_restore` 手工执行。
它按库产出目录格式归档(`pg_restore -d <库> -j4 <库>.dir`,跨实例加 `--no-owner --no-acl`),
且 **同一实例上的生产库(`weknora_prod`)也在其中** —— 备份目录权限按 0700/0600 保管。
- 留档默认不含 `chunks` 行:向量在 ES 里、分块行可由源端重发;要"整库行级可离线重建"才需
`INCLUDE_CHUNKS=1`(实测本机隧道约 24 分钟、云内 44 秒内)。
- `es_documents.jsonl.gz` 的 sha256 **每次导出都不同**(scroll 顺序非确定),判据是清单里的
每库文档数与逐条内容;要跨次比对请比 `es_document_counts` 与 `_id` 集合,不要比文件哈希。