From a1be19bb0f4d84c014977e20b5d271d9ea5c5f95 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?= Date: Fri, 9 Oct 2026 12:22:55 +0800 Subject: [PATCH] =?UTF-8?q?docs(backup):=20=E8=A1=A5=E5=AE=9E=E6=B5=8B?= =?UTF-8?q?=E8=80=97=E6=97=B6=EF=BC=882m52s=20=E5=BF=AB=E8=B7=AF=E5=BE=84?= =?UTF-8?q?=20/=2019m40s=20=E5=90=AB=20ES=20=E5=9B=9E=E4=BC=A0=EF=BC=89?= =?UTF-8?q?=E4=B8=8E=20ES=20=E5=AF=BC=E5=87=BA=E5=93=88=E5=B8=8C=E9=9D=9E?= =?UTF-8?q?=E7=A1=AE=E5=AE=9A=E6=80=A7=E5=88=A4=E6=8D=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/P6_RELEASE_WORKER_ACCEPTANCE.md | 6 ++++-- docs/PRODUCTION_BACKUP_RECOVERY.md | 13 ++++++++----- scripts/target_kb_snapshot.sh | 3 +++ 3 files changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/P6_RELEASE_WORKER_ACCEPTANCE.md b/docs/P6_RELEASE_WORKER_ACCEPTANCE.md index d35509c..fdd1dd8 100644 --- a/docs/P6_RELEASE_WORKER_ACCEPTANCE.md +++ b/docs/P6_RELEASE_WORKER_ACCEPTANCE.md @@ -336,8 +336,10 @@ INCLUDE_CHUNKS=0 bash scripts/target_kb_snapshot.sh # 不导 chunks(快照 且不触碰目标库一行。页面把该码显示为"缺少目标知识库的发布前快照留档,已拒绝发布"。 - 云内执行:`bash scripts/target_kb_snapshot.sh` 默认在与 DB 同 VPC 的云主机上跑 (凭据取自已部署的 WeKnora 容器,不经家用带宽),PG 8 张表 **44 秒**;ES 导出走云主机直连 - ES 容器(只读 scroll),两个库共 13 万条文档 gzip 后约 450 MiB;隧道模式保留为 - `EXECUTION=tunnel` 兜底。`PULL_ES=0` 可把 ES 大文件留在云主机,只回传清单。 + ES 容器(只读 scroll),两个库共 **131,122 条**文档、gzip 后 **692 MB**;全流程实测 + **2 分 52 秒**(ES 字节留云主机),拉回本机则 19 分 40 秒(家用上行 ~0.6 MB/s)—— + 故 `PULL_ES` 默认 0,清单以 `location=cloud:<主机>:<路径>` 记字节位置。 + 隧道模式保留为 `EXECUTION=tunnel` 兜底。 ## Elasticsearch 通道 diff --git a/docs/PRODUCTION_BACKUP_RECOVERY.md b/docs/PRODUCTION_BACKUP_RECOVERY.md index 15b1dc7..ff09c2a 100644 --- a/docs/PRODUCTION_BACKUP_RECOVERY.md +++ b/docs/PRODUCTION_BACKUP_RECOVERY.md @@ -7,8 +7,8 @@ | 层 | 状态 | 证据 | |---|---|---| -| 导入前留档(PG 行 + ES 文档) | ✅ 已建:`scripts/target_kb_snapshot.sh` 云内执行,8 张表 + 该库在 ES 的全部文档(只读 scroll,gzip JSONL,按 `_id` 可重建)+ `MANIFEST.json`(行数/字节/sha256/每库 ES 文档数)+ `export.sql` + `README.md` | `$KB_BACKUP_ROOT/target-kb-snapshots/-/`(云主机产出一份,本地镜像一份) | -| 发布前硬门禁 | ✅ 已上线(`internal/releasesnapshot`):写目标库之前必须存在覆盖该库、24h 内、**PG 行与 ES 文档两层都齐备且哈希可校验**的留档,否则 `release_target_snapshot_missing`(不可重试),目标库一行不碰 | 单测 9(门禁)+ 6(发布器);`cmd/guardcheck` 可用真实产物复核 | +| 导入前留档(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/-/`(云主机全量;本地镜像 PG 行 + 清单) | +| 发布前硬门禁 | ✅ 已上线(`internal/releasesnapshot`):写目标库之前必须存在覆盖该库、24h 内、**PG 行与 ES 文档两层都齐备且哈希可校验**的留档,否则 `release_target_snapshot_missing`(不可重试),目标库一行不碰 | 单测 10(门禁)+ 6(发布器);`go run ./cmd/guardcheck $KB_BACKUP_ROOT/target-kb-snapshots ` 实测:两个绑定库 PASS、未绑定库 BLOCK | | 自管整库逻辑备份 | ✅ 已建:`scripts/logical-backup.sh`(`pg_dump -Fd -j4 -Z6` 目录格式,可并行/按表恢复;按天轮转保留 7 份 + 每月一份) | `$KB_BACKUP_ROOT/rds-logical//<库>.dir` + `MANIFEST.json` | | 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` | @@ -68,8 +68,9 @@ docker run --rm --network host postgres:17-alpine psql "$TARGET_DB_URL" \ ## 每次导入/发布前的标准动作 -1. `bash scripts/target_kb_snapshot.sh`(默认云内执行;PG 8 张表 44 秒,ES 导出按库只读 scroll - 另需数分钟;`INCLUDE_CHUNKS=1` 才带 chunks,`PULL_ES=0` 把 ES 大文件留在云主机只回传清单); +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 `。 @@ -82,4 +83,6 @@ docker run --rm --network host postgres:17-alpine psql "$TARGET_DB_URL" \ `es-snapshots/` 与 `target-kb-snapshots/` 同步到 OSS(需一把可写备份桶的 AK,属授权项)。 - 自管逻辑备份**不能替代 PITR**:它只能回到"备份那一刻",且恢复要靠 `pg_restore` 手工执行。 - 留档默认不含 `chunks` 行:向量在 ES 里、分块行可由源端重发;要"整库行级可离线重建"才需 - `INCLUDE_CHUNKS=1`(实测本机隧道约 24 分钟、云内 44 秒内)。 \ No newline at end of file + `INCLUDE_CHUNKS=1`(实测本机隧道约 24 分钟、云内 44 秒内)。 +- `es_documents.jsonl.gz` 的 sha256 **每次导出都不同**(scroll 顺序非确定),判据是清单里的 + 每库文档数与逐条内容;要跨次比对请比 `es_document_counts` 与 `_id` 集合,不要比文件哈希。 \ No newline at end of file diff --git a/scripts/target_kb_snapshot.sh b/scripts/target_kb_snapshot.sh index f0ac80a..f5de8f3 100755 --- a/scripts/target_kb_snapshot.sh +++ b/scripts/target_kb_snapshot.sh @@ -307,6 +307,9 @@ cat >"$OUT/README.md" <<'MD' > 若 `MANIFEST.json` 里某文件的 `location` 是 `cloud:<主机>:<路径>`,说明字节留在目标主机上 > (家用带宽拉不动),本地只有清单与哈希;同机执行时按该路径直接读。 +> +> `es_documents.jsonl.gz` 的 sha256 每次导出都不同(scroll 顺序非确定);判断"两份留档是不是 +> 同一份现场"请看 `es_document_counts` 与逐条的 `_id` 集合,而不是文件哈希。 ## 它不是什么 - 不含 Elasticsearch 文档与向量(见 ES 仓库 `kb_backup` 与 SLM 策略 `kb-hourly`/`kb-daily`)、