Files
knowledge-governance/internal/releasesnapshot/guard.go
T
姚章浩 b32755b35f feat(backup): 备份目录契约 + 导入前留档覆盖 ES 层
- scripts/backup_layout.sh:定义 $KB_BACKUP_ROOT/{target-kb-snapshots,rds-logical,es-snapshots,logs}
  与 /etc/knowledge-governance/backup.env,任意主机跑同一份(测试云主机 → 未来生产云主机)
- scripts/es_kb_export.py:只读 scroll 导出目标库 ES 文档(gzip JSONL,_id/_source,可按 _id 重建)
- scripts/target_kb_snapshot.sh:留档改为 PG 行 + ES 文档两层;PULL_ES 默认 0(692 MB / 家用上行 19m40s,
  留在目标主机,清单记 location=cloud:<host>:<path>);挂载源与落点统一走 KB_BACKUP_ROOT
- scripts/logical-backup.sh:自管整库逻辑备份(pg_dump -Fd -j4 -Z6,按天轮转)
- internal/releasesnapshot:门禁要求 PG 与 ES 两层齐备(ES 计数 >0);云侧留档核声明与哈希、
  声明本地却缺失则 fail-closed;新增 3 条用例(共 10)
- cmd/guardcheck:用真实产物复核门禁判断
- docs:PRODUCTION_BACKUP_RECOVERY.md 重写(契约/RDS 控制台/恢复路径/边界);P6 同步留档语义
2026-10-09 12:19:15 +08:00

221 lines
8.0 KiB
Go
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.
// Package releasesnapshot 实现"发布前必须有目标知识库快照"的硬门禁。
//
// 背景:发布链本身不做发布前备份(DocumentTarget.Prepare 只归档本包、解析
// previousRevision),而 wiki 通道在共享真实知识库上会覆盖整库页面。留档由
// scripts/target_kb_snapshot.sh 产生(KB 维度只读 PG 行级 JSONL + ES 文档 + MANIFEST.json),
// 本包只负责在写目标库之前证明"这份现场确实存在、且 PG 与 ES 两层都覆盖了目标库"。
// 只留 PG 行的留档在恢复后检索不到东西,因此同样拒绝。
package releasesnapshot
import (
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"io"
"os"
"path/filepath"
"sort"
"strings"
"time"
)
const manifestKind = "weknora-target-kb-snapshot"
// ErrNoFreshSnapshot 表示找不到覆盖目标库、且在有效期内的快照。
var ErrNoFreshSnapshot = errors.New("no fresh target knowledge base snapshot")
type manifestFile struct {
File string `json:"file"`
Rows int `json:"rows"`
// Bytes/SHA256 由快照脚本写入;本地文件会再校验一次。
Bytes int64 `json:"bytes"`
SHA256 string `json:"sha256"`
Location string `json:"location"`
}
type manifest struct {
Kind string `json:"kind"`
CreatedAt string `json:"created_at"`
KnowledgeBaseIDs []string `json:"knowledge_base_ids"`
Files []manifestFile `json:"files"`
// ESDocumentsFile/ESDocumentCounts:ES 那一层的留档。导入前留档必须同时覆盖
// PG 行与 ES 文档,否则"恢复"只能恢复一半。
ESDocumentsFile string `json:"es_documents_file"`
ESDocumentCounts map[string]int `json:"es_document_counts"`
}
// Guard 在快照根目录下寻找覆盖目标库的有效快照。
type Guard struct {
// Root 是快照根目录(每份快照一个子目录,内含 MANIFEST.json)。
Root string
// MaxAge 是允许的快照最大年龄(0 表示不限制年龄,仅要求存在)。
MaxAge time.Duration
// Now 便于测试注入时间。
Now func() time.Time
// VerifyLocalFiles 为真时校验本地 JSONL 的 sha256("可恢复"的最低证明)。
VerifyLocalFiles bool
}
// Check 要求 Root 下存在一份覆盖 knowledgeBaseID 的**完整**导入前留档:
// 类型正确、在有效期内、含 wiki_pages.jsonl、且含该库的 ES 文档留档(计数 > 0);
// 本地文件再按 sha256 校验一次。找到即返回 nil,否则返回包装 ErrNoFreshSnapshot 的原因。
func (guard Guard) Check(knowledgeBaseID string) error {
if strings.TrimSpace(knowledgeBaseID) == "" {
return fmt.Errorf("%w: 目标知识库为空", ErrNoFreshSnapshot)
}
root := strings.TrimSpace(guard.Root)
if root == "" {
return fmt.Errorf("%w: 未配置快照根目录(RELEASE_SNAPSHOT_ROOT)", ErrNoFreshSnapshot)
}
entries, err := os.ReadDir(root)
if err != nil {
return fmt.Errorf("%w: 读取快照目录失败: %v", ErrNoFreshSnapshot, err)
}
now := guard.now()
names := make([]string, 0, len(entries))
for _, entry := range entries {
if entry.IsDir() {
names = append(names, entry.Name())
}
}
// 目录名以 UTC 时间戳开头(<ts>-<kb前缀>),倒序即从最新开始找。
sort.Sort(sort.Reverse(sort.StringSlice(names)))
var newestProblem error
for _, name := range names {
ok, problem := guard.inspect(filepath.Join(root, name), knowledgeBaseID, now)
if ok {
return nil
}
if problem != nil && newestProblem == nil {
newestProblem = problem
}
}
if newestProblem != nil {
return newestProblem
}
return fmt.Errorf("%w: 未找到覆盖目标库 %s 的快照", ErrNoFreshSnapshot, knowledgeBaseID)
}
func (guard Guard) now() time.Time {
if guard.Now != nil {
return guard.Now().UTC()
}
return time.Now().UTC()
}
// inspect 判断一份快照是否可用;ok=true 表示通过。
func (guard Guard) inspect(directory, knowledgeBaseID string, now time.Time) (bool, error) {
path := filepath.Join(directory, "MANIFEST.json")
payload, err := os.ReadFile(path)
if err != nil {
return false, nil // 目录里没有清单(半成品),跳过
}
var parsed manifest
if err := json.Unmarshal(payload, &parsed); err != nil {
return false, fmt.Errorf("%w: 快照清单无法解析(%s)", ErrNoFreshSnapshot, filepath.Base(directory))
}
if parsed.Kind != manifestKind {
return false, nil
}
covered := false
for _, id := range parsed.KnowledgeBaseIDs {
if id == knowledgeBaseID {
covered = true
break
}
}
if !covered {
return false, nil
}
created, err := parseStamp(parsed.CreatedAt)
if err != nil {
return false, fmt.Errorf("%w: 快照时间戳无法识别(%s)", ErrNoFreshSnapshot, filepath.Base(directory))
}
if guard.MaxAge > 0 && now.Sub(created) > guard.MaxAge {
return false, fmt.Errorf("%w: 最新快照已过期(%s,超过 %s)",
ErrNoFreshSnapshot, created.Format(time.RFC3339), guard.MaxAge)
}
wiki, present := findFile(parsed.Files, "wiki_pages.jsonl")
if !present || wiki.SHA256 == "" {
return false, fmt.Errorf("%w: 快照缺少 wiki_pages.jsonl 或哈希(%s)",
ErrNoFreshSnapshot, filepath.Base(directory))
}
// ES 必须一起留档:只有 PG 行的快照,恢复后检索不到东西。
if parsed.ESDocumentsFile == "" {
return false, fmt.Errorf("%w: 快照未包含 ES 文档留档(%s)",
ErrNoFreshSnapshot, filepath.Base(directory))
}
if parsed.ESDocumentCounts[knowledgeBaseID] <= 0 {
return false, fmt.Errorf("%w: 快照里目标库 %s 的 ES 文档数为 %d(%s)",
ErrNoFreshSnapshot, knowledgeBaseID, parsed.ESDocumentCounts[knowledgeBaseID], filepath.Base(directory))
}
esFile, esPresent := findFile(parsed.Files, parsed.ESDocumentsFile)
if !esPresent || esFile.SHA256 == "" {
return false, fmt.Errorf("%w: 快照缺少 ES 文档文件或其哈希(%s)",
ErrNoFreshSnapshot, filepath.Base(directory))
}
if guard.VerifyLocalFiles {
if err := verifyLocal(directory, wiki); err != nil {
return false, err
}
// ES 留档可能是"云侧留档"(location 以 cloud: 开头):家用带宽拉几 GB 不现实,
// 此时字节在目标主机上,本地只核清单声明与哈希字符串;声明为本地却读不到 → 拒绝。
if !isCloudLocated(esFile.Location) {
if err := verifyLocal(directory, esFile); err != nil {
return false, err
}
}
}
return true, nil
}
// isCloudLocated 判断某份留档是否声明为"字节在目标主机上"(而非本地)。
func isCloudLocated(location string) bool {
return strings.HasPrefix(strings.ToLower(strings.TrimSpace(location)), "cloud:")
}
// parseStamp 接受脚本写出的 20261009T025017Z,也接受 RFC3339。
func parseStamp(value string) (time.Time, error) {
value = strings.TrimSpace(value)
if created, err := time.Parse("20060102T150405Z", value); err == nil {
return created.UTC(), nil
}
if created, err := time.Parse(time.RFC3339, value); err == nil {
return created.UTC(), nil
}
return time.Time{}, errors.New("unrecognized snapshot timestamp")
}
func findFile(files []manifestFile, name string) (manifestFile, bool) {
for _, file := range files {
if file.File == name {
return file, true
}
}
return manifestFile{}, false
}
// verifyLocal 校验本地 JSONL 的 sha256,作为"这份快照还能用"的最小证明。
// 放在云主机上(location=cloud:...)的文件无法在这里校验,跳过。
func verifyLocal(directory string, file manifestFile) error {
if strings.HasPrefix(file.Location, "cloud:") {
return nil
}
handle, err := os.Open(filepath.Join(directory, file.File))
if err != nil {
return fmt.Errorf("%w: 快照文件不可读(%s)", ErrNoFreshSnapshot, file.File)
}
defer handle.Close()
digest := sha256.New()
if _, err := io.Copy(digest, handle); err != nil {
return fmt.Errorf("%w: 快照文件校验失败(%s)", ErrNoFreshSnapshot, file.File)
}
actual := hex.EncodeToString(digest.Sum(nil))
if actual != file.SHA256 {
return fmt.Errorf("%w: 快照文件哈希不匹配(%s)", ErrNoFreshSnapshot, file.File)
}
return nil
}