Files
knowledge-governance/internal/libraryretention/retention.go
T
姚章浩 281699a431
build / build (push) Successful in 1m21s
feat(library): 生产整库真实读写/校验/恢复与本机真实服务验收
为什么:生产目标此前是"无条件失败"的占位,编排再完整也不能落地;本轮把它做成真实实现,
并在本机 WeKnora 测试栈的真实 PG/ES 上跑通导入、撤销、预备份与故障恢复。

- ProductionLibraryTarget:Current 读行数+身份摘要;Apply 按阶段真实写入(database/wiki
  同事务先删本库再插、resources 传对象、index 搬运原始文档与向量);Verify 比对身份摘要;
  Restore 按预备份快照回放。
- 撤销真正生效:索引阶段写入后 PruneScope 删除快照里没有的文档。
- ProductionBackupStore:导出前独立完整预备份,导出前后行数不一致即失败。
- worker 用注入配置装配目标与预备份;缺项把变量名写进阶段并失败,不再有占位对象。
- capacity 安全加法防溢出;保留策略组合语义明确(各维度都超限才候选)。
- 新增本机真实服务集成测试(一次性 kg_library_test_* 库 + 随机 ES 索引),
  覆盖导入/校验/撤销/预备份/故障注入/恢复。
2026-10-28 15:54:01 +08:00

142 lines
5.7 KiB
Go

// Package libraryretention 计算整库归档的保留、依赖保护与清理预览。
//
// 只做计算,不做删除:所有结论都是"如果按这个策略清理,哪些版本会被保留、
// 哪些成为候选、大约能释放多少独占字节"。共享 blob 不计入回收量,因为仍有
// 其它版本引用它;没有任何策略配置时不给候选,也不拿默认值替用户拍板。
package libraryretention
import (
"fmt"
"sort"
"time"
)
// Version 是参与保留判断的一个整库版本。
type Version struct {
ID string `json:"id"`
Kind string `json:"kind"`
CreatedAt time.Time `json:"created_at"`
// Protected 由调用方依据真实引用计算(生产生效、最近封存、在飞作业),
// 这里不猜;ProtectedBy 写明是哪条依据,审计时能逐条核对。
Protected bool `json:"protected"`
ProtectedBy []string `json:"protected_by,omitempty"`
// ExclusiveBytes 是只有这个版本引用的内容字节(来自归档用量)。
ExclusiveBytes int64 `json:"exclusive_bytes"`
SharedBytes int64 `json:"shared_bytes"`
}
// Policy 是保留策略。零值表示"未设置"——这时不给任何候选。
//
// 组合语义(当两个维度都设置时)是**交集**,即"既超出最近 N 个、又早于 D 天"
// 才成为候选;只要还满足其中一个维度就保留。这比"任一维度超限就删"保守:
// 宁可少删,也不能因为天数短于版本节奏而误判一批刚封存的版本。
type Policy struct {
KeepVersions int `json:"keep_versions"`
KeepDays int `json:"keep_days"`
}
// Describe 用一句话写清当前组合语义,接口和页面直接展示,避免读者自行猜测。
func (p Policy) Describe() string {
switch {
case p.KeepVersions > 0 && p.KeepDays > 0:
return fmt.Sprintf("同时保留最近 %d 个版本与最近 %d 天,两者都不满足才成为候选", p.KeepVersions, p.KeepDays)
case p.KeepVersions > 0:
return fmt.Sprintf("保留最近 %d 个版本", p.KeepVersions)
case p.KeepDays > 0:
return fmt.Sprintf("保留最近 %d 天", p.KeepDays)
default:
return "未设置(全部保留,不生成候选)"
}
}
func (p Policy) Configured() bool { return p.KeepVersions > 0 || p.KeepDays > 0 }
type Candidate struct {
ID string `json:"id"`
Kind string `json:"kind"`
Reason []string `json:"reason"`
// ExclusiveBytes 是上限口径:就算删掉,共享 blob 也不会释放。
ExclusiveBytes int64 `json:"exclusive_bytes"`
}
type Plan struct {
Policy Policy `json:"policy"`
PolicyNote string `json:"policy_note"`
PolicyConfigured bool `json:"policy_configured"`
AutomaticCleanup bool `json:"automatic_cleanup"`
VersionCount int `json:"version_count"`
TotalBytes int64 `json:"total_bytes"`
Protected []string `json:"protected"`
Keep []string `json:"keep"`
Candidates []Candidate `json:"candidates"`
// ReclaimPreviewBytes 只是候选版本独占字节之和,不是承诺。
ReclaimPreviewBytes int64 `json:"reclaim_preview_bytes"`
// Blocked 说明为什么给不出安全预览(策略未配置、时间基准异常等)。
Blocked []string `json:"blocked"`
Now time.Time `json:"now"`
}
// Build 生成清理预览。now 由调用方给,便于测试;不给真实时钟依赖。
func Build(versions []Version, totalBytes int64, policy Policy, now time.Time) Plan {
plan := Plan{Policy: policy, PolicyConfigured: policy.Configured(), AutomaticCleanup: false,
PolicyNote: policy.Describe(),
VersionCount: len(versions), TotalBytes: totalBytes, Protected: []string{}, Keep: []string{},
Candidates: []Candidate{}, Blocked: []string{}, Now: now.UTC()}
sorted := append([]Version(nil), versions...)
sort.Slice(sorted, func(i, j int) bool {
if sorted[i].CreatedAt.Equal(sorted[j].CreatedAt) {
return sorted[i].ID > sorted[j].ID
}
return sorted[i].CreatedAt.After(sorted[j].CreatedAt)
})
if !policy.Configured() {
plan.Blocked = append(plan.Blocked, "保留策略未设置(保留版本数与保留天数都没有),不生成清理候选")
}
if policy.KeepVersions < 0 || policy.KeepDays < 0 {
plan.Blocked = append(plan.Blocked, "保留策略取值非法,拒绝生成预览")
return plan
}
for rank, version := range sorted {
if version.Protected {
plan.Protected = append(plan.Protected, version.ID)
plan.Keep = append(plan.Keep, version.ID)
continue
}
if !policy.Configured() {
// 没策略时按"全部保留"处理,绝不默认清理。
plan.Keep = append(plan.Keep, version.ID)
continue
}
// 组合语义:对**每个已设置**的维度都超限才成为候选(未设置的维度不约束)。
// 只设版本数 ⇒ 看数量;只设天数 ⇒ 看天数;两者都设 ⇒ 必须同时超限。
beyondCount := policy.KeepVersions > 0 && rank >= policy.KeepVersions
beyondDays := policy.KeepDays > 0 && !version.CreatedAt.IsZero() &&
version.CreatedAt.Before(now.AddDate(0, 0, -policy.KeepDays))
exceeds := true
if policy.KeepVersions > 0 {
exceeds = exceeds && beyondCount
}
if policy.KeepDays > 0 {
exceeds = exceeds && beyondDays
}
if !exceeds {
plan.Keep = append(plan.Keep, version.ID)
continue
}
reasons := make([]string, 0, 2)
if beyondCount {
reasons = append(reasons, fmt.Sprintf("超出保留 %d 个版本", policy.KeepVersions))
}
if beyondDays {
reasons = append(reasons, fmt.Sprintf("超出保留 %d 天", policy.KeepDays))
}
plan.Candidates = append(plan.Candidates, Candidate{ID: version.ID, Kind: version.Kind,
Reason: reasons, ExclusiveBytes: version.ExclusiveBytes})
plan.ReclaimPreviewBytes += version.ExclusiveBytes
}
return plan
}