b32755b35f
- 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 同步留档语义
221 lines
8.0 KiB
Go
221 lines
8.0 KiB
Go
// 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
|
||
}
|