From 1f482e4b49b24ca30150d66ce2400059310b4fbd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 04:45:34 +0800
Subject: [PATCH 01/45] =?UTF-8?q?feat(library):=20Wiki=20=E6=92=A4?=
=?UTF-8?q?=E9=94=80=E6=8C=89=E8=B4=A1=E7=8C=AE=E6=AF=94=E5=AF=B9=EF=BC=8C?=
=?UTF-8?q?=E7=BB=B4=E6=8A=A4=E7=AA=97=E5=8F=A3=E5=9C=A8=E9=A1=B5=E9=9D=A2?=
=?UTF-8?q?=E5=A6=82=E5=AE=9E=E5=91=88=E7=8E=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
为什么:删除一篇与别人共同贡献同一 Wiki 页的文档后,页面还在、名字也在,
只有那篇文档的正文与引用被摘掉。原来的页面级差异会把这种语义重算显示成
"无变化",操作员据此会误判撤销没有生效。
怎么改:librarydiff 新增 CompareWiki,以 slug 为身份把正文/来源文档/引用分块/
出入边/目录分别取集合比较,输出 sources_removed、citations 变化与具体类别;
overview 的 diff.wiki 增加逐页明细(最多 50 页,超出置 pages_truncated),
说明文字明确"重算发生在源侧,本平台只如实比对与保留结果"。
页面:新增目标维护面板(实例级/库级、持有、入口开关、阶段、进度、恢复错误),
只有窗口仍持有且作业失败时才给"按预备份恢复";没有维护记录时写未接入 + fail closed。
变更页把 Wiki 逐页差异列出来源/引用怎么变。kind 补上 restore。
验过:go test ./internal/librarydiff ./internal/httpapi;web vitest 453 项;
make verify 全绿(15 项,无未运行项)。真实撤销语义验收见交付报告。
---
CHANGELOG.md | 32 +++
internal/httpapi/library_flow.go | 79 ++++--
internal/httpapi/library_wiki_diff_test.go | 51 ++++
internal/librarydiff/wiki.go | 269 +++++++++++++++++++++
internal/librarydiff/wiki_test.go | 114 +++++++++
web/src/ReleaseTargets.test.tsx | 4 +-
web/src/ReleaseTargets.tsx | 227 ++++++++++++++++-
web/src/librarySnapshots.ts | 91 ++++++-
web/src/releaseTargets.css | 37 +++
web/src/releaseTargetsMaintenance.test.tsx | 139 +++++++++++
10 files changed, 1006 insertions(+), 37 deletions(-)
create mode 100644 internal/httpapi/library_wiki_diff_test.go
create mode 100644 internal/librarydiff/wiki.go
create mode 100644 internal/librarydiff/wiki_test.go
create mode 100644 web/src/releaseTargetsMaintenance.test.tsx
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 33c5d00..1bba9eb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,37 @@
# Changelog
+## 开发快照(Wiki 撤销贡献:逐页语义比对 + 维护窗口真实呈现)
+
+### Added
+
+- **Wiki 贡献级差异**(`internal/librarydiff/wiki.go`):以 slug 为身份,把每页拆成
+ 正文 / 来源文档 / 引用分块 / 出边 / 入边 / 目录/状态 分别取集合比较,输出
+ `sources_added` / `sources_removed` / `citations_before→after` / `changed`。
+ 删除一篇与别人共同贡献同一页的文档后,页面通常仍是「更新」,只看页面级增删改会显示成
+ 「无变化」——现在能指出这份贡献是从哪一页、哪几类语义上被摘掉的。两端同时接受 JSON 数组
+ 与字符串化数组,读不出来直接报错,不把「读不到」当成「没有来源」。
+- **接口 `GET /api/v1/library/overview` 的 `diff.wiki` 增加逐页明细**:`pages`(最多 50 页,
+ 超出置 `pages_truncated`)、`sources_added/removed`、`base_count/target_count`;页面级计数
+ 保留,说明文字明确「重算发生在源侧,本平台只如实比对与保留结果」。
+- **发布管理页面:目标维护面板**(`MaintenanceCard`):显示维护级别(实例级/库级)、持有
+ scope+作业、阶段、入口开/关、服务、开始/释放时间、作业进度(阶段名中文化,未映射原样显示)、
+ 恢复错误与处理记录;只有窗口仍持有且作业失败时才出现「按预备份恢复」,动作走
+ `POST /api/v1/library/maintenance/recover`。没有维护记录时明确写「未接入 + fail closed」,
+ 不画成已就绪。
+- **变更页展示逐页贡献差异**:每条页面一行,直接写「更新 发布闸门 · 正文/来源文档/引用分块 ·
+ 来源 -1 · 引用 2→1」。
+
+### Fixed
+
+- `LibraryJobRecord.kind` 之前只有 `seal | sync`,恢复作业(restore)在类型上不存在;
+ 补上后页面不再把恢复作业当成未知类型。
+
+### Notes
+
+- 本次真实验收(kgmaint 专用实例 + 原版 WeKnora API)与本快照之外的部署计划见
+ `docs/library-acceptance-matrix.md` 与交付报告;矩阵按「已完成 / 缺代码 / 未跑 / 需授权」
+ 重排,不再在顶部叠报告。
+
## 开发快照(后台静默必须在关入口之后证明,且要能复核)
### Fixed
diff --git a/internal/httpapi/library_flow.go b/internal/httpapi/library_flow.go
index d9ba354..b35d328 100644
--- a/internal/httpapi/library_flow.go
+++ b/internal/httpapi/library_flow.go
@@ -106,6 +106,58 @@ type libraryWikiDiffView struct {
// Sample 只列前若干页,避免把整库 Wiki 列表塞进接口。
Sample []string `json:"sample"`
Note string `json:"note"`
+ // Pages 是逐页的**贡献级**明细:哪一页、变了哪几类语义、掉/加了哪些来源文档。
+ // 页面级计数只看增删改;撤销一份共享贡献时页面通常仍是"更新",
+ // 只有这里的 sources_removed / changed 才能证明那份贡献确实被摘掉了。
+ Pages []libraryWikiPageView `json:"pages,omitempty"`
+ PagesTruncated bool `json:"pages_truncated,omitempty"`
+ SourcesAdded int `json:"sources_added"`
+ SourcesRemoved int `json:"sources_removed"`
+ BaseCount int `json:"base_count"`
+ TargetCount int `json:"target_count"`
+}
+
+type libraryWikiPageView struct {
+ Slug string `json:"slug"`
+ Title string `json:"title"`
+ PageType string `json:"page_type,omitempty"`
+ Status string `json:"status"` // added | updated | removed
+ Changed []string `json:"changed"`
+ SourcesAdded []string `json:"sources_added,omitempty"`
+ SourcesRemoved []string `json:"sources_removed,omitempty"`
+ CitationsBefore int `json:"citations_before"`
+ CitationsAfter int `json:"citations_after"`
+}
+
+// wikiPageLimit 是接口一次最多返回的页数;超出部分只给计数,不给半截明细。
+const wikiPageLimit = 50
+
+func wikiViewFrom(result librarydiff.WikiResult, limit int) *libraryWikiDiffView {
+ if limit <= 0 {
+ limit = wikiPageLimit
+ }
+ view := &libraryWikiDiffView{State: result.State, Added: result.Added, Updated: result.Updated,
+ Removed: result.Removed, Sample: []string{}, SourcesAdded: result.SourcesAdded,
+ SourcesRemoved: result.SourcesRemoved, BaseCount: result.BaseCount, TargetCount: result.TargetCount,
+ Note: "逐页比对正文、来源文档、引用分块、出入边与目录;语义重算发生在源侧,本平台只如实比对与保留结果"}
+ for index, page := range result.Pages {
+ if index >= limit {
+ view.PagesTruncated = true
+ break
+ }
+ view.Pages = append(view.Pages, libraryWikiPageView{Slug: page.Slug, Title: page.Title,
+ PageType: page.PageType, Status: page.Status, Changed: librarydiff.ChangedLabels(page.Changed),
+ SourcesAdded: page.SourcesAdded, SourcesRemoved: page.SourcesRemoved,
+ CitationsBefore: page.CitationsBefore, CitationsAfter: page.CitationsAfter})
+ }
+ for _, page := range view.Pages {
+ if len(view.Sample) >= 20 {
+ break
+ }
+ label := map[string]string{"added": "新增", "updated": "更新", "removed": "撤销"}[page.Status]
+ view.Sample = append(view.Sample, label+" "+page.Title)
+ }
+ return view
}
// wikiDiffOf 比较两份快照的 wiki_pages 行数组(页面级)。
@@ -148,32 +200,11 @@ func wikiDiffOf(archive *librarysnapshot.Archive, baseID, targetID string) *libr
if reason != "" {
return unknown("测试版本:" + reason)
}
- result, err := librarydiff.Compare(base, target)
+ result, err := librarydiff.CompareWiki(base, target)
if err != nil {
- return unknown("Wiki 页面比对失败:" + err.Error())
+ return unknown("Wiki 逐页比对失败:" + err.Error())
}
- view := &libraryWikiDiffView{State: "computed", Added: len(result.Added), Updated: len(result.Updated),
- Removed: len(result.Removed), Sample: []string{},
- Note: "页面级差异:只说明页面被增/改/撤,不代表实体、概念、边或引用已重算"}
- for _, item := range result.Added {
- if len(view.Sample) >= 20 {
- break
- }
- view.Sample = append(view.Sample, "新增 "+item.Title)
- }
- for _, item := range result.Updated {
- if len(view.Sample) >= 20 {
- break
- }
- view.Sample = append(view.Sample, "更新 "+item.Title)
- }
- for _, item := range result.Removed {
- if len(view.Sample) >= 20 {
- break
- }
- view.Sample = append(view.Sample, "撤销 "+item.Title)
- }
- return view
+ return wikiViewFrom(result, wikiPageLimit)
}
// computeLibraryDiff 用归档里的 knowledges 行数组比较两个快照:
diff --git a/internal/httpapi/library_wiki_diff_test.go b/internal/httpapi/library_wiki_diff_test.go
new file mode 100644
index 0000000..0464d42
--- /dev/null
+++ b/internal/httpapi/library_wiki_diff_test.go
@@ -0,0 +1,51 @@
+package httpapi
+
+import (
+ "strings"
+ "testing"
+
+ "knowledge-governance/internal/librarydiff"
+)
+
+func TestWikiViewFromKeepsContributionDetail(t *testing.T) {
+ result := librarydiff.WikiResult{
+ State: "computed", Added: 0, Updated: 1, Removed: 1, SourcesAdded: 0, SourcesRemoved: 2,
+ BaseCount: 2, TargetCount: 1,
+ Pages: []librarydiff.WikiContribution{
+ {Slug: "entity/gate", Title: "发布闸门", PageType: "entity", Status: "updated",
+ Changed: []string{"content", "sources", "citations"}, SourcesRemoved: []string{"doc-a"},
+ CitationsBefore: 2, CitationsAfter: 1},
+ {Slug: "entity/only-a", Title: "只属于 A", PageType: "entity", Status: "removed",
+ Changed: []string{"removed"}, SourcesRemoved: []string{"doc-a"}},
+ },
+ }
+ view := wikiViewFrom(result, 0)
+ if view.State != "computed" || view.Updated != 1 || view.Removed != 1 || view.SourcesRemoved != 2 {
+ t.Fatalf("view: %+v", view)
+ }
+ if len(view.Pages) != 2 {
+ t.Fatalf("pages: %+v", view.Pages)
+ }
+ kept := view.Pages[0]
+ if kept.Status != "updated" || len(kept.Changed) != 3 || kept.Changed[0] != "正文" {
+ t.Fatalf("changed labels: %+v", kept)
+ }
+ if len(kept.SourcesRemoved) != 1 || kept.SourcesRemoved[0] != "doc-a" {
+ t.Fatalf("sources: %+v", kept)
+ }
+ if !strings.Contains(view.Note, "来源") {
+ t.Fatalf("note should explain what is compared: %q", view.Note)
+ }
+}
+
+func TestWikiViewFromCapsPagesAndSaysSo(t *testing.T) {
+ result := librarydiff.WikiResult{State: "computed", BaseCount: 0}
+ for _, slug := range []string{"a", "b", "c"} {
+ result.Pages = append(result.Pages, librarydiff.WikiContribution{Slug: slug, Status: "added"})
+ result.Added++
+ }
+ view := wikiViewFrom(result, 2)
+ if len(view.Pages) != 2 || !view.PagesTruncated {
+ t.Fatalf("cap: pages=%d truncated=%v", len(view.Pages), view.PagesTruncated)
+ }
+}
diff --git a/internal/librarydiff/wiki.go b/internal/librarydiff/wiki.go
new file mode 100644
index 0000000..40b3839
--- /dev/null
+++ b/internal/librarydiff/wiki.go
@@ -0,0 +1,269 @@
+// Wiki 贡献级差异:页面身份是 slug,语义拆成「正文 / 来源文档 / 引用分块 / 出边 / 入边 / 目录」。
+//
+// 为什么不能只比页面级:删除一篇与别人共同贡献同一页的文档后,页面还在、名字还在,
+// 只有那篇文档的正文与引用被摘掉。页面级差异会把这种"语义重算"显示成"无变化",
+// 操作员据此会误判撤销没有生效。这里把每类语义单独取集合再比,撤销的那份贡献
+// 必须能在 sources/citations/links/content 上被指出来。
+//
+// 边界:本包只读归档里的 wiki_pages 行,**不重算** WeKnora 的实体/概念/边。
+// 语义重算发生在源侧,治理侧能做的是把源侧算完的结果如实比对与保留。
+package librarydiff
+
+import (
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "sort"
+ "strings"
+)
+
+// volatileWikiFields 是每次保存都会变、但不代表页面语义变化的列。
+var volatileWikiFields = []string{"updated_at", "updated_by", "created_at", "view_count"}
+
+type WikiContribution struct {
+ Slug string `json:"slug"`
+ Title string `json:"title"`
+ PageType string `json:"page_type"`
+ Status string `json:"status"` // added | updated | removed
+ // Changed 是发生变化(或被删除)的语义类别:content / sources / citations /
+ // out_links / in_links / category / status / page_type。撤销一份贡献时,
+ // sources 与 citations 必须出现,正文没变也要标出来。
+ Changed []string `json:"changed"`
+ SourcesAdded []string `json:"sources_added"`
+ SourcesRemoved []string `json:"sources_removed"`
+ CitationsBefore int `json:"citations_before"`
+ CitationsAfter int `json:"citations_after"`
+ CitationsAdded []string `json:"citations_added,omitempty"`
+ CitationsRemoved []string `json:"citations_removed,omitempty"`
+ LinksAdded []string `json:"links_added,omitempty"`
+ LinksRemoved []string `json:"links_removed,omitempty"`
+ // ContentDigestBefore/After 让证据可以复核"正文真的变了",而不是只凭长度。
+ ContentDigestBefore string `json:"content_digest_before,omitempty"`
+ ContentDigestAfter string `json:"content_digest_after,omitempty"`
+}
+
+type WikiResult struct {
+ State string `json:"state"` // computed
+ Added int `json:"added"`
+ Updated int `json:"updated"`
+ Removed int `json:"removed"`
+ // SourcesAdded/Removed 是所有页面来源变化的合计,便于一眼看到"撤销了谁的贡献"。
+ SourcesAdded int `json:"sources_added"`
+ SourcesRemoved int `json:"sources_removed"`
+ BaseCount int `json:"base_count"`
+ TargetCount int `json:"target_count"`
+ Pages []WikiContribution `json:"pages"`
+}
+
+type wikiPage struct {
+ slug string
+ title string
+ pageType string
+ status string
+ content string
+ sources []string
+ citations []string
+ outLinks []string
+ inLinks []string
+ category string
+}
+
+// CompareWiki 以 base 为基准(当前生产版本),target 为拟发布版本,逐页比对语义。
+func CompareWiki(base, target []map[string]any) (WikiResult, error) {
+ basePages, err := indexWiki(base)
+ if err != nil {
+ return WikiResult{}, err
+ }
+ targetPages, err := indexWiki(target)
+ if err != nil {
+ return WikiResult{}, err
+ }
+ result := WikiResult{State: "computed", Pages: []WikiContribution{},
+ BaseCount: len(basePages), TargetCount: len(targetPages)}
+ for slug, next := range targetPages {
+ previous, ok := basePages[slug]
+ if !ok {
+ result.Added++
+ result.Pages = append(result.Pages, WikiContribution{
+ Slug: next.slug, Title: next.title, PageType: next.pageType, Status: "added",
+ Changed: []string{"added"}, SourcesAdded: next.sources,
+ CitationsAfter: len(next.citations), ContentDigestAfter: digestOf(next.content),
+ })
+ result.SourcesAdded += len(next.sources)
+ continue
+ }
+ change, changed := diffWikiPage(previous, next)
+ if !changed {
+ continue
+ }
+ result.Updated++
+ result.SourcesAdded += len(change.SourcesAdded)
+ result.SourcesRemoved += len(change.SourcesRemoved)
+ result.Pages = append(result.Pages, change)
+ }
+ for slug, previous := range basePages {
+ if _, ok := targetPages[slug]; ok {
+ continue
+ }
+ result.Removed++
+ result.Pages = append(result.Pages, WikiContribution{
+ Slug: previous.slug, Title: previous.title, PageType: previous.pageType, Status: "removed",
+ Changed: []string{"removed"}, SourcesRemoved: previous.sources,
+ CitationsBefore: len(previous.citations), ContentDigestBefore: digestOf(previous.content),
+ })
+ result.SourcesRemoved += len(previous.sources)
+ }
+ sort.Slice(result.Pages, func(i, j int) bool { return result.Pages[i].Slug < result.Pages[j].Slug })
+ return result, nil
+}
+
+func diffWikiPage(previous, next wikiPage) (WikiContribution, bool) {
+ change := WikiContribution{Slug: next.slug, Title: next.title, PageType: next.pageType, Status: "updated",
+ CitationsBefore: len(previous.citations), CitationsAfter: len(next.citations),
+ ContentDigestBefore: digestOf(previous.content), ContentDigestAfter: digestOf(next.content)}
+ change.SourcesAdded, change.SourcesRemoved = setDiff(next.sources, previous.sources), setDiff(previous.sources, next.sources)
+ change.CitationsAdded, change.CitationsRemoved = setDiff(next.citations, previous.citations), setDiff(previous.citations, next.citations)
+ change.LinksAdded, change.LinksRemoved = setDiff(next.outLinks, previous.outLinks), setDiff(previous.outLinks, next.outLinks)
+ if previous.content != next.content {
+ change.Changed = append(change.Changed, "content")
+ }
+ if len(change.SourcesAdded)+len(change.SourcesRemoved) > 0 {
+ change.Changed = append(change.Changed, "sources")
+ }
+ if len(change.CitationsAdded)+len(change.CitationsRemoved) > 0 {
+ change.Changed = append(change.Changed, "citations")
+ }
+ if len(change.LinksAdded)+len(change.LinksRemoved) > 0 {
+ change.Changed = append(change.Changed, "out_links")
+ }
+ if added, removed := setDiff(next.inLinks, previous.inLinks), setDiff(previous.inLinks, next.inLinks); len(added)+len(removed) > 0 {
+ change.Changed = append(change.Changed, "in_links")
+ }
+ if previous.category != next.category {
+ change.Changed = append(change.Changed, "category")
+ }
+ if previous.status != next.status {
+ change.Changed = append(change.Changed, "status")
+ }
+ if previous.pageType != next.pageType {
+ change.Changed = append(change.Changed, "page_type")
+ }
+ return change, len(change.Changed) > 0
+}
+
+func indexWiki(rows []map[string]any) (map[string]wikiPage, error) {
+ pages := make(map[string]wikiPage, len(rows))
+ for _, row := range rows {
+ slug, _ := row["slug"].(string)
+ slug = strings.TrimSpace(slug)
+ if slug == "" {
+ return nil, errors.New("wiki row without slug")
+ }
+ if _, exists := pages[slug]; exists {
+ return nil, fmt.Errorf("duplicate wiki slug %s", slug)
+ }
+ page := wikiPage{slug: slug}
+ page.title, _ = row["title"].(string)
+ page.pageType, _ = row["page_type"].(string)
+ page.status, _ = row["status"].(string)
+ page.content, _ = row["content"].(string)
+ var err error
+ if page.sources, err = stringList(row["source_refs"]); err != nil {
+ return nil, fmt.Errorf("wiki %s source_refs: %w", slug, err)
+ }
+ if page.citations, err = stringList(row["chunk_refs"]); err != nil {
+ return nil, fmt.Errorf("wiki %s chunk_refs: %w", slug, err)
+ }
+ if page.outLinks, err = stringList(row["out_links"]); err != nil {
+ return nil, fmt.Errorf("wiki %s out_links: %w", slug, err)
+ }
+ if page.inLinks, err = stringList(row["in_links"]); err != nil {
+ return nil, fmt.Errorf("wiki %s in_links: %w", slug, err)
+ }
+ category, err := stringList(row["category_path"])
+ if err != nil {
+ return nil, fmt.Errorf("wiki %s category_path: %w", slug, err)
+ }
+ if folder, ok := row["folder_id"].(string); ok && folder != "" {
+ category = append(category, folder)
+ }
+ page.category = strings.Join(category, "/")
+ pages[slug] = page
+ }
+ return pages, nil
+}
+
+// stringList 同时接受 JSON 数组与字符串化数组;其他形状一律报错,
+// 避免"读不出来就当空集合"把撤销误判成没有来源。
+func stringList(value any) ([]string, error) {
+ switch typed := value.(type) {
+ case nil:
+ return nil, nil
+ case []string:
+ return append([]string{}, typed...), nil
+ case []any:
+ out := make([]string, 0, len(typed))
+ for _, item := range typed {
+ text, ok := item.(string)
+ if !ok {
+ return nil, fmt.Errorf("non-string item %T", item)
+ }
+ out = append(out, text)
+ }
+ return out, nil
+ case string:
+ if strings.TrimSpace(typed) == "" {
+ return nil, nil
+ }
+ var out []string
+ if err := json.Unmarshal([]byte(typed), &out); err != nil {
+ return nil, err
+ }
+ return out, nil
+ default:
+ return nil, fmt.Errorf("unsupported value %T", value)
+ }
+}
+
+// setDiff 返回 left 有、right 没有的元素(升序)。
+func setDiff(left, right []string) []string {
+ seen := make(map[string]bool, len(right))
+ for _, item := range right {
+ seen[item] = true
+ }
+ out := make([]string, 0)
+ for _, item := range left {
+ if seen[item] {
+ continue
+ }
+ seen[item] = true
+ out = append(out, item)
+ }
+ sort.Strings(out)
+ return out
+}
+
+func digestOf(text string) string {
+ sum := sha256.Sum256([]byte(text))
+ return hex.EncodeToString(sum[:])
+}
+
+// changedLabels 把语义类别翻成给操作员看的词,界面不用各自维护一份。
+func ChangedLabels(changed []string) []string {
+ labels := map[string]string{
+ "content": "正文", "sources": "来源文档", "citations": "引用分块",
+ "out_links": "出边", "in_links": "入边", "category": "目录",
+ "status": "状态", "page_type": "页面类型", "added": "新增", "removed": "整页撤销",
+ }
+ out := make([]string, 0, len(changed))
+ for _, name := range changed {
+ if label, ok := labels[name]; ok {
+ out = append(out, label)
+ } else {
+ out = append(out, name)
+ }
+ }
+ return out
+}
diff --git a/internal/librarydiff/wiki_test.go b/internal/librarydiff/wiki_test.go
new file mode 100644
index 0000000..1c755e1
--- /dev/null
+++ b/internal/librarydiff/wiki_test.go
@@ -0,0 +1,114 @@
+package librarydiff
+
+import (
+ "encoding/json"
+ "testing"
+)
+
+// 两篇文档共同贡献一页:撤销一篇后,页面保留、只掉撤销那篇的来源与引用,
+// 并且能说清是哪几类语义变了——这正是"页面级差异"做不到的部分。
+func TestCompareWikiReportsContributionRemoval(t *testing.T) {
+ base := []map[string]any{
+ row(t, "entity/gate", "gate", []string{"doc-a", "doc-b"}, []string{"chunk-a", "chunk-b"},
+ "闸门:灰度 30 分钟 ZEBRA-A-7731;阈值 5% ZEBRA-B-4492", []string{"entity/only-a"}, []string{"entity/gate"}),
+ row(t, "entity/only-a", "only-a", []string{"doc-a"}, []string{"chunk-a"}, "只属于 A", nil, nil),
+ }
+ after := []map[string]any{
+ row(t, "entity/gate", "gate", []string{"doc-b"}, []string{"chunk-b"},
+ "闸门:阈值 5% ZEBRA-B-4492", []string{"entity/gate"}, []string{"entity/gate"}),
+ }
+ result, err := CompareWiki(base, after)
+ if err != nil {
+ t.Fatalf("compare: %v", err)
+ }
+ if result.Updated != 1 || result.Removed != 1 || result.Added != 0 {
+ t.Fatalf("counts: %+v", result)
+ }
+ var kept WikiContribution
+ for _, page := range result.Pages {
+ if page.Slug == "entity/gate" {
+ kept = page
+ }
+ }
+ if kept.Status != "updated" {
+ t.Fatalf("kept page status = %q", kept.Status)
+ }
+ if len(kept.SourcesRemoved) != 1 || kept.SourcesRemoved[0] != "doc-a" {
+ t.Fatalf("sources_removed = %v", kept.SourcesRemoved)
+ }
+ if len(kept.SourcesAdded) != 0 {
+ t.Fatalf("sources_added = %v", kept.SourcesAdded)
+ }
+ want := map[string]bool{"content": true, "sources": true, "citations": true, "out_links": true}
+ got := map[string]bool{}
+ for _, name := range kept.Changed {
+ got[name] = true
+ }
+ for name := range want {
+ if !got[name] {
+ t.Fatalf("changed missing %q: %v", name, kept.Changed)
+ }
+ }
+ if kept.CitationsAfter != 1 || kept.CitationsBefore != 2 {
+ t.Fatalf("citations %d -> %d", kept.CitationsBefore, kept.CitationsAfter)
+ }
+ if len(kept.LinksRemoved) != 1 || kept.LinksRemoved[0] != "entity/only-a" {
+ t.Fatalf("links_removed = %v", kept.LinksRemoved)
+ }
+ // 合计口径:共享页掉 1 个来源 + 整页撤销的 only-a 带走 1 个来源 = 2。
+ if result.SourcesRemoved != 2 {
+ t.Fatalf("result sources_removed = %d", result.SourcesRemoved)
+ }
+}
+
+func TestCompareWikiIgnoresVolatileFieldsAndUnchangedPages(t *testing.T) {
+ base := []map[string]any{row(t, "concept/x", "x", []string{"doc-a"}, []string{"c1"}, "正文", nil, nil)}
+ after := []map[string]any{row(t, "concept/x", "x", []string{"doc-a"}, []string{"c1"}, "正文", nil, nil)}
+ after[0]["updated_at"] = "2026-10-29T00:00:00Z"
+ after[0]["updated_by"] = "someone"
+ result, err := CompareWiki(base, after)
+ if err != nil {
+ t.Fatalf("compare: %v", err)
+ }
+ if result.Updated+result.Added+result.Removed != 0 || len(result.Pages) != 0 {
+ t.Fatalf("noise produced changes: %+v", result)
+ }
+ if result.State != "computed" || result.BaseCount != 1 || result.TargetCount != 1 {
+ t.Fatalf("result header: %+v", result)
+ }
+}
+
+func TestCompareWikiRejectsRowsWithoutSlug(t *testing.T) {
+ if _, err := CompareWiki([]map[string]any{{"title": "no slug"}}, nil); err == nil {
+ t.Fatal("expected error for row without slug")
+ }
+}
+
+func row(t *testing.T, slug, title string, sources, chunks []string, content string,
+ outLinks, inLinks []string) map[string]any {
+ t.Helper()
+ return map[string]any{
+ "slug": slug, "title": title, "page_type": "entity", "status": "published",
+ "content": content, "summary": "",
+ "source_refs": sources, "chunk_refs": chunks,
+ "out_links": outLinks, "in_links": inLinks,
+ "category_path": []string{"根"}, "folder_id": "",
+ }
+}
+
+func TestCompareWikiAcceptsJSONEncodedArrays(t *testing.T) {
+ // 归档行来自 to_jsonb,数组是 JSON 数组;但历史归档里也出现过字符串化的数组,
+ // 两种都要能读,读不出就报错,不能静默当成空集合。
+ base := []map[string]any{{"slug": "entity/y", "source_refs": `["doc-a","doc-b"]`,
+ "chunk_refs": `["c1"]`, "content": "a", "out_links": `["entity/y"]`}}
+ after := []map[string]any{{"slug": "entity/y", "source_refs": `["doc-b"]`,
+ "chunk_refs": `["c1"]`, "content": "a", "out_links": `["entity/y"]`}}
+ result, err := CompareWiki(base, after)
+ if err != nil {
+ t.Fatalf("compare: %v", err)
+ }
+ if len(result.Pages) != 1 || len(result.Pages[0].SourcesRemoved) != 1 {
+ raw, _ := json.Marshal(result)
+ t.Fatalf("string arrays not parsed: %s", raw)
+ }
+}
diff --git a/web/src/ReleaseTargets.test.tsx b/web/src/ReleaseTargets.test.tsx
index d2ab4c9..2a967cf 100644
--- a/web/src/ReleaseTargets.test.tsx
+++ b/web/src/ReleaseTargets.test.tsx
@@ -149,9 +149,11 @@ const base: ViewProps = {
pendingCapture: false,
canCapture: true,
canWrite: true,
+ maintenance: null,
now: new Date('2026-10-28T03:35:00Z').getTime(),
onRefresh: vi.fn(),
onCapture: vi.fn(),
+ onRecover: vi.fn(),
}
const render = (overrides: Partial = {}) =>
@@ -227,7 +229,7 @@ describe('ReleaseTargetsView(确认稿布局)', () => {
expect(html).toContain('生产 prod00000000 → 测试 test00000000')
expect(html).not.toContain('变更清单来自生产与测试版本对比')
expect(html).toContain('Wiki 页面:新增 2 · 更新 1 · 撤销 3')
- expect(html).toContain('不代表实体/边/引用重算')
+ expect(html).toContain('重算发生在源侧')
})
it('准备信息注明快照时间与范围,不声称实时测试库已就绪', () => {
diff --git a/web/src/ReleaseTargets.tsx b/web/src/ReleaseTargets.tsx
index 1f87cae..1c4f952 100644
--- a/web/src/ReleaseTargets.tsx
+++ b/web/src/ReleaseTargets.tsx
@@ -1,13 +1,16 @@
import { useCallback, useEffect, useState } from 'react'
import {
enqueueLibraryCapture,
+ enqueueLibraryRecovery,
fetchLibraryCaptures,
+ fetchLibraryMaintenance,
fetchLibraryOverview,
fetchLibrarySnapshots,
formatBytes,
scopeLabel,
type LibraryCaptureJob,
type LibraryJobRecord,
+ type LibraryMaintenanceView,
type LibraryOverview,
type LibrarySnapshot,
type LibrarySnapshotList,
@@ -83,9 +86,11 @@ interface ViewProps {
canCapture: boolean
canWrite: boolean
overview: LibraryOverview | null
+ maintenance: LibraryMaintenanceView | null
now: number
onRefresh: () => void
onCapture: () => void
+ onRecover: (windowJobID: string) => void
}
function scopeView(
@@ -157,6 +162,170 @@ function jobStateText(job: LibraryJobRecord): string {
return map[job.state] ?? job.state
}
+// ---- 目标维护窗口:级别 / 进度 / 恢复错误 ----
+//
+// 维护窗口有两种级别:实例级(跨 scope 共用一把锁,真正挡住写入者)和库级。
+// 页面必须说清是哪一级、入口是开还是关、作业走到哪、恢复失败的具体错误——
+// 这些都来自 /api/v1/library/maintenance 的真实记录,没有记录就说"未接入"。
+export interface MaintenanceSummary {
+ level: string
+ held: boolean
+ owner: string
+ state: string
+ ingress: string
+ services: string
+ acquiredAt: string
+ releasedAt: string
+ progress: string
+ recoveryError: string
+ recoveryNote: string
+ canRecover: boolean
+}
+
+// 阶段名给操作员看的映射;没映射到的阶段原样显示,不猜。
+const stageLabel: Record = {
+ prebackup: '预备份',
+ database: '数据库',
+ resources: '资源',
+ index: '索引',
+ wiki: 'Wiki',
+ verify: '校验',
+ finalize: '登记版本',
+ rollback: '回滚',
+ export: '导出',
+ acquire: '开窗口',
+ drain: '排空',
+ stop: '停写入者',
+}
+
+const ingressText = (state?: string) =>
+ state === 'closed' ? '已关闭(排空后等待写入)' : state === 'open' ? '打开' : state ? state : '未知'
+
+export function maintenanceSummary(
+ maintenance: LibraryMaintenanceView | null | undefined,
+ job: LibraryJobRecord | undefined
+): MaintenanceSummary {
+ const record = maintenance?.instance_maintenance ?? maintenance?.maintenance ?? null
+ const level = !record
+ ? '未接入'
+ : record.level === 'instance'
+ ? '实例级'
+ : record.level === 'library'
+ ? '库级'
+ : record.level || '未知'
+ const held = Boolean(maintenance?.held)
+ const failed = job?.state === 'failed'
+ const ownerScope = maintenance?.instance_maintenance?.owner_scope ?? record?.scope ?? '—'
+ return {
+ level,
+ held,
+ owner: record ? `${ownerScope} · ${record.owner_job_id || '—'}` : '—',
+ state: record?.state || '—',
+ ingress: record ? ingressText(record.ingress_state) : '—',
+ services: (record?.services ?? []).join('、') || '—',
+ acquiredAt: record?.acquired_at ? stamp(record.acquired_at) : '—',
+ releasedAt: record?.released_at ? stamp(record.released_at) : '',
+ progress: job ? `${stageLabel[job.stage] ?? job.stage ?? '—'} · ${jobStateText(job)}` : '尚无作业进度',
+ recoveryError: failed ? job?.error || '作业失败但没有留下错误明细' : '',
+ recoveryNote: job?.recovery || '',
+ canRecover: held && (failed || !job || job.state === 'cancelled'),
+ }
+}
+
+export function MaintenanceCard({
+ maintenance,
+ job,
+ canWrite,
+ onRecover,
+}: {
+ maintenance: LibraryMaintenanceView | null | undefined
+ job: LibraryJobRecord | undefined
+ canWrite: boolean
+ onRecover: (windowJobID: string) => void
+}) {
+ const summary = maintenanceSummary(maintenance, job)
+ const record = maintenance?.instance_maintenance ?? maintenance?.maintenance
+ return (
+
+
+ {summary.level === '未接入' ? (
+
+ 暂无维护窗口记录,也没有维护能力配置;维护类操作保持 fail closed,不会在此状态下写目标。
+
+ ) : (
+ <>
+
+ -
+ 级别
+ {summary.level}
+
+ -
+ 持有
+ {summary.owner}
+
+ -
+ 阶段
+ {summary.state}
+
+ -
+ 入口 {summary.ingress}
+ {summary.services}
+
+ -
+ 开始
+ {summary.acquiredAt}
+
+ -
+ 释放
+ {summary.releasedAt || '未释放'}
+
+
+
+ 进度:{summary.progress}
+ {summary.releasedAt ? ` · 窗口已于 ${summary.releasedAt} 释放` : ''}
+
+ {summary.recoveryError ? (
+
+
恢复错误
+
{summary.recoveryError}
+ {summary.recoveryNote ?
处理记录:{summary.recoveryNote}
: null}
+
+ ) : null}
+ {canWrite && summary.canRecover && record ? (
+
+ ) : null}
+ >
+ )}
+
+ )
+}
+
+// 逐页贡献级差异:一条页面一行,直接写清来源少了几份、引用从几变几。
+export function wikiContributionLines(diff: LibraryOverview['diff'] | undefined): string[] {
+ const wiki = diff?.wiki
+ if (!wiki || wiki.state !== 'computed' || !wiki.pages || wiki.pages.length === 0) return []
+ const label: Record = { added: '新增', updated: '更新', removed: '整页撤销' }
+ return wiki.pages.map((page) => {
+ const parts = [`${label[page.status] ?? page.status} ${page.title || page.slug}`]
+ if (page.changed.length > 0) parts.push(page.changed.join('、'))
+ if ((page.sources_removed ?? []).length > 0) parts.push(`来源 -${page.sources_removed!.length}`)
+ if ((page.sources_added ?? []).length > 0) parts.push(`来源 +${page.sources_added!.length}`)
+ if (page.citations_before !== page.citations_after)
+ parts.push(`引用 ${page.citations_before}→${page.citations_after}`)
+ return parts.join(' · ')
+ })
+}
+
function StageBar({ view }: { view: ScopeView }) {
const job = view.job
const sealJob = job?.kind === 'seal' ? job : undefined
@@ -312,10 +481,23 @@ function ChangeTable({ diff }: { diff: LibraryOverview['diff'] }) {
{diff.wiki && diff.wiki.state === 'computed' ? (
-
- Wiki 页面:新增 {diff.wiki.added} · 更新 {diff.wiki.updated} · 撤销 {diff.wiki.removed}
- (页面级,不代表实体/边/引用重算)
-
+
+
+ Wiki 页面:新增 {diff.wiki.added} · 更新 {diff.wiki.updated} · 撤销 {diff.wiki.removed}
+ {typeof diff.wiki.sources_removed === 'number'
+ ? ` · 来源文档变化 −${diff.wiki.sources_removed} / +${diff.wiki.sources_added ?? 0}`
+ : ''}
+ (逐页比对来源、引用、出入边与目录;重算发生在源侧)
+
+ {wikiContributionLines(diff).length > 0 ? (
+
+ {wikiContributionLines(diff).map((line) => (
+ - {line}
+ ))}
+
+ ) : null}
+ {diff.wiki.pages_truncated ?
逐页明细超过 50 条,只列出前 50 条。
: null}
+
) : null}
)
@@ -866,8 +1048,10 @@ export function ReleaseTargetsView(props: ViewProps) {
canCapture,
canWrite,
now,
+ maintenance,
onRefresh,
onCapture,
+ onRecover,
} = props
const internal = scopeView(page, jobs, 'internal', overview?.scope === 'internal' ? overview : null)
const external = scopeView(page, jobs, 'external', overview?.scope === 'external' ? overview : null)
@@ -1028,6 +1212,8 @@ export function ReleaseTargetsView(props: ViewProps) {
启动后先固定测试版本,再备份生产。备份失败或恢复条件不满足,不进入生产写入。
+
+
{active ? (
onDrawer(true)} />
) : (
@@ -1073,6 +1259,10 @@ export function ReleaseTargets() {
const [loading, setLoading] = useState(true)
const [error, setError] = useState(null)
const [notice, setNotice] = useState(null)
+ const [maintenances, setMaintenances] = useState>({
+ internal: null,
+ external: null,
+ })
const [scope, setScope] = useState('internal')
const [drawerOpen, setDrawerOpen] = useState(false)
const [expandedSnapshot, setExpandedSnapshot] = useState(null)
@@ -1082,15 +1272,19 @@ export function ReleaseTargets() {
const load = useCallback(async (signal?: AbortSignal) => {
setLoading(true)
try {
- const [snapshots, captures, internalOverview, externalOverview] = await Promise.all([
- fetchLibrarySnapshots(signal),
- fetchLibraryCaptures(signal),
- fetchLibraryOverview('internal', signal),
- fetchLibraryOverview('external', signal),
- ])
+ const [snapshots, captures, internalOverview, externalOverview, internalMaintenance, externalMaintenance] =
+ await Promise.all([
+ fetchLibrarySnapshots(signal),
+ fetchLibraryCaptures(signal),
+ fetchLibraryOverview('internal', signal),
+ fetchLibraryOverview('external', signal),
+ fetchLibraryMaintenance('internal', signal),
+ fetchLibraryMaintenance('external', signal),
+ ])
setPage(snapshots)
setJobs(captures)
setOverviews({ internal: internalOverview, external: externalOverview })
+ setMaintenances({ internal: internalMaintenance, external: externalMaintenance })
setNow(Date.now())
setError(null)
} catch (loadError) {
@@ -1139,6 +1333,17 @@ export function ReleaseTargets() {
}
}
+ const recover = async (windowJobID: string) => {
+ setNotice(null)
+ try {
+ const accepted = await enqueueLibraryRecovery(scope, windowJobID)
+ setNotice(`已投递按预备份恢复:${accepted.recovery_job || '(未返回作业号)'}`)
+ await load()
+ } catch (recoveryError) {
+ setNotice(recoveryError instanceof Error ? recoveryError.message : '恢复请求失败')
+ }
+ }
+
return (
void load()}
onCapture={() => void startCapture()}
+ onRecover={(windowJobID) => void recover(windowJobID)}
/>
)
}
diff --git a/web/src/librarySnapshots.ts b/web/src/librarySnapshots.ts
index cfe5916..679c3ca 100644
--- a/web/src/librarySnapshots.ts
+++ b/web/src/librarySnapshots.ts
@@ -250,7 +250,11 @@ export interface LibraryDiff {
/** 这次比对用的两个整库版本(生产 → 测试),避免把历史差异当成当前。 */
base_snapshot?: string
target_snapshot?: string
- /** 页面级 Wiki 差异;不代表实体、概念、边或引用被重算。 */
+ /**
+ * Wiki 逐页贡献级差异:来源文档 / 引用分块 / 出入边 / 目录分别比。
+ * 语义重算发生在源侧,这里只如实反映重算后的结果——撤销一份共享贡献时
+ * 页面通常还是"更新",要看 pages[].sources_removed 才知道那份贡献被摘掉了。
+ */
wiki?: {
state: 'computed' | 'unknown'
reason?: string
@@ -259,9 +263,92 @@ export interface LibraryDiff {
removed: number
sample: string[]
note: string
+ pages?: LibraryWikiPageChange[]
+ pages_truncated?: boolean
+ sources_added?: number
+ sources_removed?: number
+ base_count?: number
+ target_count?: number
}
}
+export interface LibraryWikiPageChange {
+ slug: string
+ title: string
+ page_type?: string
+ status: 'added' | 'updated' | 'removed'
+ changed: string[]
+ sources_added?: string[]
+ sources_removed?: string[]
+ citations_before: number
+ citations_after: number
+}
+
+// ---- 目标维护窗口:级别、阶段、入口状态与恢复错误 ----
+export interface LibraryMaintenanceRecord {
+ scope: string
+ owner_job_id: string
+ target_identity?: string
+ level: string
+ target_fingerprint?: string
+ services?: string[]
+ ingress_state: string
+ state: string
+ original_service_state?: string
+ note?: string
+ acquired_at: string
+ updated_at: string
+ released_at?: string | null
+}
+
+export interface LibraryInstanceMaintenanceRecord extends LibraryMaintenanceRecord {
+ instance: string
+ owner_scope: string
+}
+
+export interface LibraryMaintenanceView {
+ held: boolean
+ maintenance?: LibraryMaintenanceRecord | null
+ instance?: string
+ instance_maintenance?: LibraryInstanceMaintenanceRecord | null
+}
+
+export async function fetchLibraryMaintenance(
+ scope: string,
+ signal?: AbortSignal
+): Promise {
+ const response = await fetch(`/api/v1/library/maintenance?scope=${encodeURIComponent(scope)}`, {
+ headers: { Accept: 'application/json' },
+ signal,
+ })
+ if (!response.ok) return null
+ const value = (await response.json().catch(() => null)) as unknown
+ if (!record(value)) return null
+ return value as unknown as LibraryMaintenanceView
+}
+
+export interface LibraryRecoveryAccepted {
+ accepted?: boolean
+ recovery_job?: string
+ state?: string
+ code?: string
+ error?: string
+}
+
+export async function enqueueLibraryRecovery(scope: string, windowJobID: string): Promise {
+ const response = await fetch('/api/v1/library/maintenance/recover', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+ body: JSON.stringify({ scope, window_job_id: windowJobID }),
+ })
+ const value = (await response.json().catch(() => ({}))) as unknown
+ const body = record(value) ? (value as LibraryRecoveryAccepted) : {}
+ if (!response.ok) {
+ throw new Error(body.error || `恢复请求被拒绝(HTTP ${response.status})`)
+ }
+ return body
+}
+
export interface LibraryStageRow {
stage: string
state: string
@@ -276,7 +363,7 @@ export interface LibraryStageRow {
export interface LibraryJobRecord {
id: string
scope: string
- kind: 'seal' | 'sync'
+ kind: 'seal' | 'sync' | 'restore'
state: 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'
stage: string
request_digest: string
diff --git a/web/src/releaseTargets.css b/web/src/releaseTargets.css
index 1075650..187e433 100644
--- a/web/src/releaseTargets.css
+++ b/web/src/releaseTargets.css
@@ -635,3 +635,40 @@
font-variant-numeric: tabular-nums;
word-break: break-all;
}
+
+/* 目标维护:级别/持有/入口/阶段用两列小表,数字与时间可对齐比较。 */
+.rel-maintenance-rows {
+ display: grid;
+ grid-template-columns: repeat(2, minmax(0, 1fr));
+ gap: 6px 18px;
+ margin: 8px 14px 0;
+ padding: 0;
+ list-style: none;
+}
+.rel-maintenance-rows li {
+ display: flex;
+ justify-content: space-between;
+ gap: 10px;
+ border-bottom: 1px dashed var(--rel-line, #dce6ed);
+ padding: 4px 0;
+ font-size: 12px;
+}
+.rel-maintenance-rows span {
+ color: var(--rel-muted, #7b8d9a);
+}
+.rel-maintenance-rows b {
+ font-variant-numeric: tabular-nums;
+ word-break: break-all;
+ text-align: right;
+}
+
+/* Wiki 逐页贡献级差异:每条一行,直接写清来源/引用怎么变。 */
+.rel-wiki-pages {
+ margin: 4px 14px 10px;
+ padding-left: 18px;
+ font-size: 12px;
+ line-height: 1.6;
+}
+.rel-wiki-pages li {
+ font-variant-numeric: tabular-nums;
+}
diff --git a/web/src/releaseTargetsMaintenance.test.tsx b/web/src/releaseTargetsMaintenance.test.tsx
new file mode 100644
index 0000000..92ceafc
--- /dev/null
+++ b/web/src/releaseTargetsMaintenance.test.tsx
@@ -0,0 +1,139 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it } from 'vitest'
+
+import { MaintenanceCard, maintenanceSummary, wikiContributionLines } from './ReleaseTargets'
+import type { LibraryDiff, LibraryJobRecord, LibraryMaintenanceView } from './librarySnapshots'
+
+const job: LibraryJobRecord = {
+ id: 'libsync-internal-1',
+ scope: 'internal',
+ kind: 'sync',
+ state: 'failed',
+ stage: 'rollback',
+ request_digest: 'x',
+ queue_job_id: 'q1',
+ snapshot_id: '',
+ target_snapshot_id: '',
+ actor: 'admin',
+ error: '写入生产 chunks 失败:连接被拒绝',
+ recovery: '已按预备份回滚并校验',
+ created_at: '2026-10-29T04:00:00Z',
+ updated_at: '2026-10-29T04:02:00Z',
+ finished_at: '2026-10-29T04:02:00Z',
+ stages: [],
+}
+
+const heldInstance: LibraryMaintenanceView = {
+ held: true,
+ instance: 'kgmaint-weknora',
+ instance_maintenance: {
+ instance: 'kgmaint-weknora',
+ owner_scope: 'internal',
+ scope: 'internal',
+ owner_job_id: 'libsync-internal-1',
+ level: 'instance',
+ services: ['app'],
+ ingress_state: 'closed',
+ state: 'held',
+ acquired_at: '2026-10-29T04:00:00Z',
+ updated_at: '2026-10-29T04:02:00Z',
+ released_at: null,
+ },
+}
+
+describe('维护级别/进度/恢复错误', () => {
+ it('实例级持有:显示级别、入口状态、进度与恢复错误,并允许按预备份恢复', () => {
+ const summary = maintenanceSummary(heldInstance, job)
+ expect(summary.level).toBe('实例级')
+ expect(summary.held).toBe(true)
+ expect(summary.ingress).toContain('已关闭')
+ expect(summary.progress).toContain('回滚')
+ expect(summary.progress).toContain('失败')
+ expect(summary.recoveryError).toContain('写入生产 chunks 失败')
+ expect(summary.recoveryNote).toContain('按预备份回滚')
+ expect(summary.canRecover).toBe(true)
+
+ const html = renderToStaticMarkup(
+ undefined} />
+ )
+ for (const text of ['目标维护', '实例级', '入口 已关闭', '按预备份恢复', '写入生产 chunks 失败']) {
+ expect(html).toContain(text)
+ }
+ })
+
+ it('没有窗口时如实说没有,不画成"已就绪"', () => {
+ const summary = maintenanceSummary(null, undefined)
+ expect(summary.level).toBe('未接入')
+ expect(summary.held).toBe(false)
+ expect(summary.canRecover).toBe(false)
+ const html = renderToStaticMarkup(
+ undefined} />
+ )
+ expect(html).toContain('暂无维护窗口')
+ expect(html).not.toContain('按预备份恢复')
+ })
+
+ it('已释放的窗口不再提供恢复入口', () => {
+ const released: LibraryMaintenanceView = {
+ held: false,
+ instance_maintenance: {
+ ...heldInstance.instance_maintenance!,
+ released_at: '2026-10-29T04:05:00Z',
+ state: 'recovered',
+ },
+ }
+ const summary = maintenanceSummary(released, job)
+ expect(summary.held).toBe(false)
+ expect(summary.canRecover).toBe(false)
+ expect(summary.releasedAt).not.toBe('')
+ })
+})
+
+describe('Wiki 贡献级差异展示', () => {
+ const diff: LibraryDiff = {
+ state: 'computed',
+ added: [],
+ updated: [],
+ removed: [],
+ wiki: {
+ state: 'computed',
+ added: 0,
+ updated: 1,
+ removed: 1,
+ sample: [],
+ note: '逐页比对',
+ sources_removed: 2,
+ pages: [
+ {
+ slug: 'entity/fa-bu-zha-men',
+ title: '发布闸门',
+ status: 'updated',
+ changed: ['正文', '来源文档', '引用分块'],
+ sources_removed: ['doc-a'],
+ citations_before: 2,
+ citations_after: 1,
+ },
+ {
+ slug: 'entity/tu-pu-hui-tian-fu-wu',
+ title: '图谱回填服务',
+ status: 'removed',
+ changed: ['整页撤销'],
+ citations_before: 1,
+ citations_after: 0,
+ },
+ ],
+ },
+ }
+
+ it('共享页被更新时列出来源减少与引用变化,而不是只说"更新 1 页"', () => {
+ const lines = wikiContributionLines(diff)
+ expect(lines[0]).toContain('发布闸门')
+ expect(lines[0]).toContain('来源 -1')
+ expect(lines[0]).toContain('引用 2→1')
+ expect(lines[1]).toContain('整页撤销')
+ })
+
+ it('没有逐页明细时不编造明细', () => {
+ expect(wikiContributionLines({ state: 'unknown', added: [], updated: [], removed: [] })).toEqual([])
+ })
+})
--
2.52.0
From 23cc6c0afe08de3110aae4beaf3bb0caaf5815da Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 04:58:45 +0800
Subject: [PATCH 02/45] =?UTF-8?q?fix(libraryctl):=20=E6=94=AF=E6=8C=81=20M?=
=?UTF-8?q?inIO=20=E6=BA=90=EF=BC=8C=E5=B9=B6=E4=B8=8E=20API=20=E5=85=B1?=
=?UTF-8?q?=E7=94=A8=E5=90=8C=E4=B8=80=E4=BB=BD=20scope=20=E6=98=A0?=
=?UTF-8?q?=E5=B0=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
为什么:专用验收实例用 S3 兼容的 MinIO,而 CLI 的源发现只认 oss 环境变量,
`STORAGE_TYPE=minio` 直接失败;同时 CLI 只读 routing bindings,API 读
LIBRARY_PRODUCTION_KB_*,两边指向不同知识库时,"封存的是哪个库"就说不清。
怎么改:新增 objectStoreFromSourceEnv(oss/minio,端点/桶缺失即报错,不退回默认值),
scopeBindings 让环境变量优先、bindings 兜底。单测覆盖 minio http/https、oss 与未知类型。
---
CHANGELOG.md | 11 ++++
cmd/libraryctl/discover_test.go | 67 +++++++++++++++++++++
cmd/libraryctl/main.go | 102 +++++++++++++++++++++++++++-----
3 files changed, 166 insertions(+), 14 deletions(-)
create mode 100644 cmd/libraryctl/discover_test.go
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1bba9eb..a036c28 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,6 +26,17 @@
- `LibraryJobRecord.kind` 之前只有 `seal | sync`,恢复作业(restore)在类型上不存在;
补上后页面不再把恢复作业当成未知类型。
+### Fixed
+
+- **`libraryctl` 只认 OSS 源**:`STORAGE_TYPE=minio` 的目标在发现阶段就被拒
+ (`unsupported source storage type "minio"`),S3 兼容的专用验收实例无法封存。
+ 现在按 `MINIO_ENDPOINT / MINIO_USE_SSL / MINIO_ACCESS_KEY_ID / MINIO_SECRET_ACCESS_KEY /
+ MINIO_BUCKET_NAME` 映射成 `provider=minio` + path-style;读不到端点/桶就明确报错,
+ 不退回默认值。
+- **CLI 与 API 的 scope→知识库 映射不一致**:API 用 `LIBRARY_PRODUCTION_KB_*`,CLI 只读
+ routing bindings,同一台机器上会封存"配置里那个库"而不是 API 的验收目标。现在环境变量
+ 优先、读不到才退回 bindings。
+
### Notes
- 本次真实验收(kgmaint 专用实例 + 原版 WeKnora API)与本快照之外的部署计划见
diff --git a/cmd/libraryctl/discover_test.go b/cmd/libraryctl/discover_test.go
new file mode 100644
index 0000000..54a59c1
--- /dev/null
+++ b/cmd/libraryctl/discover_test.go
@@ -0,0 +1,67 @@
+package main
+
+import "testing"
+
+// 目标实例可以是 OSS,也可以是 S3 兼容的 MinIO(本机专用验收实例就是 minio)。
+// 只认 oss 时,任何 minio 目标都会在发现阶段直接失败,等于这条验收链只能在生产存储上跑。
+func TestObjectStoreFromSourceEnvAcceptsMinIO(t *testing.T) {
+ app := map[string]string{
+ "STORAGE_TYPE": "minio",
+ "MINIO_ENDPOINT": "langfuse-minio:9000",
+ "MINIO_USE_SSL": "false",
+ "MINIO_ACCESS_KEY_ID": "key",
+ "MINIO_SECRET_ACCESS_KEY": "secret",
+ "MINIO_BUCKET_NAME": "kgmaint-1028a",
+ "MINIO_PATH_PREFIX": "kgmaint/",
+ }
+ config, detail, err := objectStoreFromSourceEnv(app, 1<<20)
+ if err != nil {
+ t.Fatalf("minio: %v", err)
+ }
+ if config.Provider != "minio" || config.Endpoint != "http://langfuse-minio:9000" || config.Secure {
+ t.Fatalf("config: %+v", config)
+ }
+ if config.Bucket != "kgmaint-1028a" || config.AccessKeyID != "key" || config.SecretAccessKey != "secret" {
+ t.Fatalf("credentials mapping: %+v", config)
+ }
+ if detail == "" || config.MaxObjectBytes != 1<<20 {
+ t.Fatalf("detail=%q max=%d", detail, config.MaxObjectBytes)
+ }
+}
+
+func TestObjectStoreFromSourceEnvAcceptsMinIOOverTLS(t *testing.T) {
+ app := map[string]string{
+ "STORAGE_TYPE": "minio", "MINIO_ENDPOINT": "minio.internal:9000", "MINIO_USE_SSL": "true",
+ "MINIO_ACCESS_KEY": "k2", "MINIO_SECRET_KEY": "s2", "MINIO_BUCKET_NAME": "bucket",
+ }
+ config, _, err := objectStoreFromSourceEnv(app, 1)
+ if err != nil {
+ t.Fatalf("minio tls: %v", err)
+ }
+ if !config.Secure || config.Endpoint != "https://minio.internal:9000" || config.AccessKeyID != "k2" {
+ t.Fatalf("config: %+v", config)
+ }
+}
+
+func TestObjectStoreFromSourceEnvKeepsOSS(t *testing.T) {
+ app := map[string]string{
+ "STORAGE_TYPE": "oss", "OSS_ENDPOINT": "oss-cn-shenzhen.aliyuncs.com", "OSS_REGION": "cn-shenzhen",
+ "OSS_ACCESS_KEY": "ak", "OSS_SECRET_KEY": "sk", "OSS_BUCKET_NAME": "prod",
+ }
+ config, _, err := objectStoreFromSourceEnv(app, 1)
+ if err != nil {
+ t.Fatalf("oss: %v", err)
+ }
+ if config.Provider != "oss" || config.Endpoint != "https://oss-cn-shenzhen.aliyuncs.com" || !config.Secure {
+ t.Fatalf("config: %+v", config)
+ }
+}
+
+func TestObjectStoreFromSourceEnvRejectsUnknownStorage(t *testing.T) {
+ if _, _, err := objectStoreFromSourceEnv(map[string]string{"STORAGE_TYPE": "cos"}, 1); err == nil {
+ t.Fatal("expected error for unsupported storage type")
+ }
+ if _, _, err := objectStoreFromSourceEnv(map[string]string{"STORAGE_TYPE": "minio"}, 1); err == nil {
+ t.Fatal("expected error when minio endpoint is missing")
+ }
+}
diff --git a/cmd/libraryctl/main.go b/cmd/libraryctl/main.go
index b8a82f2..004b96f 100644
--- a/cmd/libraryctl/main.go
+++ b/cmd/libraryctl/main.go
@@ -244,9 +244,6 @@ func discoverSource(ctx context.Context, opts options, binding map[string]string
if app["DB_DRIVER"] != "postgres" {
return config, errors.New("source database driver is not postgres")
}
- if app["STORAGE_TYPE"] != "oss" {
- return config, fmt.Errorf("unsupported source storage type %q", app["STORAGE_TYPE"])
- }
address, err := containerAddress(ctx, opts.sourcePG)
if err != nil {
return config, err
@@ -267,25 +264,102 @@ func discoverSource(ctx context.Context, opts options, binding map[string]string
config.SearchIndex = app["ELASTICSEARCH_INDEX"]
config.Search = v071.SearchExporterConfig{BaseURL: "http://" + esAddress + ":9200", Index: app["ELASTICSEARCH_INDEX"],
AuthorizationToken: app["ELASTICSEARCH_PASSWORD"], PageSize: 500}
- endpoint := app["OSS_ENDPOINT"]
- if endpoint == "" {
- return config, errors.New("source object endpoint is not configured")
+ config.Object, config.ObjectDetail, err = objectStoreFromSourceEnv(app, opts.maxObjectBytes)
+ if err != nil {
+ return config, err
}
- if !strings.Contains(endpoint, "://") {
- endpoint = "https://" + endpoint
- }
- config.Object = v071.S3ObjectStoreConfig{Provider: "oss", Endpoint: endpoint, Region: app["OSS_REGION"],
- AccessKeyID: app["OSS_ACCESS_KEY"], SecretAccessKey: app["OSS_SECRET_KEY"], Bucket: app["OSS_BUCKET_NAME"],
- Secure: strings.HasPrefix(endpoint, "https://"), MaxObjectBytes: opts.maxObjectBytes}
- config.ObjectDetail = "bucket=" + app["OSS_BUCKET_NAME"] + " region=" + app["OSS_REGION"]
return config, nil
}
+// objectStoreFromSourceEnv 把源应用的存储环境映射成对象存储配置。
+//
+// 只认 OSS 时,S3 兼容的 MinIO 目标(本机专用验收实例)会在发现阶段就被拒,
+// 验收链只能跑在生产存储上——这不是安全性,而是能力缺口。两种都要能读,
+// 读不出端点/桶就明确报错,不退回任何默认值。
+func objectStoreFromSourceEnv(app map[string]string, maxObjectBytes int64) (v071.S3ObjectStoreConfig, string, error) {
+ storage := strings.ToLower(strings.TrimSpace(app["STORAGE_TYPE"]))
+ var config v071.S3ObjectStoreConfig
+ var endpoint, bucket string
+ switch storage {
+ case "oss":
+ config = v071.S3ObjectStoreConfig{Provider: "oss", Region: app["OSS_REGION"],
+ AccessKeyID: app["OSS_ACCESS_KEY"], SecretAccessKey: app["OSS_SECRET_KEY"],
+ Bucket: app["OSS_BUCKET_NAME"], MaxObjectBytes: maxObjectBytes}
+ endpoint, bucket = app["OSS_ENDPOINT"], app["OSS_BUCKET_NAME"]
+ if !strings.Contains(endpoint, "://") {
+ endpoint = "https://" + endpoint
+ }
+ case "minio":
+ accessKey := firstNonEmpty(app["MINIO_ACCESS_KEY_ID"], app["MINIO_ACCESS_KEY"])
+ secretKey := firstNonEmpty(app["MINIO_SECRET_ACCESS_KEY"], app["MINIO_SECRET_KEY"])
+ config = v071.S3ObjectStoreConfig{Provider: "minio", Region: app["MINIO_REGION"],
+ AccessKeyID: accessKey, SecretAccessKey: secretKey, Bucket: app["MINIO_BUCKET_NAME"],
+ MaxObjectBytes: maxObjectBytes}
+ endpoint, bucket = app["MINIO_ENDPOINT"], app["MINIO_BUCKET_NAME"]
+ if strings.TrimSpace(endpoint) == "" {
+ return v071.S3ObjectStoreConfig{}, "", errors.New("source minio endpoint is not configured")
+ }
+ scheme := "http"
+ if parseBool(app["MINIO_USE_SSL"]) {
+ scheme = "https"
+ }
+ if !strings.Contains(endpoint, "://") {
+ endpoint = scheme + "://" + endpoint
+ }
+ default:
+ return v071.S3ObjectStoreConfig{}, "", fmt.Errorf("unsupported source storage type %q", app["STORAGE_TYPE"])
+ }
+ if strings.TrimSpace(endpoint) == "" {
+ return v071.S3ObjectStoreConfig{}, "", errors.New("source object endpoint is not configured")
+ }
+ config.Endpoint = endpoint
+ config.Secure = strings.HasPrefix(endpoint, "https://")
+ config.ForcePathStyle = storage == "minio"
+ if config.Bucket == "" {
+ return v071.S3ObjectStoreConfig{}, "", errors.New("source object bucket is not configured")
+ }
+ return config, "provider=" + config.Provider + " bucket=" + bucket, nil
+}
+
+func firstNonEmpty(values ...string) string {
+ for _, value := range values {
+ if strings.TrimSpace(value) != "" {
+ return value
+ }
+ }
+ return ""
+}
+
+func parseBool(value string) bool {
+ switch strings.ToLower(strings.TrimSpace(value)) {
+ case "1", "true", "yes", "on":
+ return true
+ }
+ return false
+}
+
func urlEscape(value string) string {
replacer := strings.NewReplacer("%", "%25", ":", "%3A", "@", "%40", "/", "%2F", "?", "%3F", "#", "%23", "&", "%26", " ", "%20")
return replacer.Replace(value)
}
+// scopeBindings 返回 scope→知识库 映射。治理 API 用的是 LIBRARY_PRODUCTION_KB_*,
+// CLI 读的是治理库里的 routing bindings;同一台机器上两份不一致时,
+// CLI 抓到的会是"配置里那个库"而不是 API 认为的目标——所以环境变量优先,
+// 读不到才退回 bindings。两边讲同一份身份,验收才可比。
+func scopeBindings(ctx context.Context, container string) (map[string]string, error) {
+ binding, err := readRoutingBindings(ctx, container)
+ if err != nil {
+ return nil, err
+ }
+ for scope, key := range map[string]string{"internal": "LIBRARY_PRODUCTION_KB_INTERNAL", "external": "LIBRARY_PRODUCTION_KB_EXTERNAL"} {
+ if value := strings.TrimSpace(os.Getenv(key)); value != "" {
+ binding[scope] = value
+ }
+ }
+ return binding, nil
+}
+
func readRoutingBindings(ctx context.Context, container string) (map[string]string, error) {
raw, err := dockerOutput(ctx, "exec", container, "psql", "-U", "governance", "-d", "governance", "-tAc",
"SELECT internal_kb_id||'|'||external_kb_id FROM routing_kb_bindings WHERE id='active'")
@@ -391,7 +465,7 @@ func openArchive(opts options) (*librarysnapshot.Archive, error) {
func runStatus(ctx context.Context, opts options) error {
report := map[string]any{}
- binding, bindingErr := readRoutingBindings(ctx, opts.governancePG)
+ binding, bindingErr := scopeBindings(ctx, opts.governancePG)
var config sourceConfig
var err error
if bindingErr != nil {
--
2.52.0
From 906c282986c2fa3576616bd52fd1e4024f12b022 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 04:59:57 +0800
Subject: [PATCH 03/45] =?UTF-8?q?fix(libraryctl):=20=E6=8D=95=E8=8E=B7/?=
=?UTF-8?q?=E9=A2=84=E6=A3=80=E4=B9=9F=E8=B5=B0=E5=90=8C=E4=B8=80=E4=BB=BD?=
=?UTF-8?q?=20scope=20=E6=98=A0=E5=B0=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
上一提交只改了 status;capture/preflight 仍直接读 routing bindings,
所以 CLI 封存的还是 bindings 里的库,而不是 API 的目标——契约读取直接失败。
---
cmd/libraryctl/main.go | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/cmd/libraryctl/main.go b/cmd/libraryctl/main.go
index 004b96f..b411579 100644
--- a/cmd/libraryctl/main.go
+++ b/cmd/libraryctl/main.go
@@ -558,7 +558,7 @@ func runPreflight(ctx context.Context, opts options) error {
if opts.scope != "internal" && opts.scope != "external" {
return errors.New("-scope must be internal or external")
}
- binding, err := readRoutingBindings(ctx, opts.governancePG)
+ binding, err := scopeBindings(ctx, opts.governancePG)
if err != nil {
return err
}
@@ -660,7 +660,7 @@ func runCapture(ctx context.Context, opts options) error {
if err != nil {
return err
}
- binding, err := readRoutingBindings(ctx, opts.governancePG)
+ binding, err := scopeBindings(ctx, opts.governancePG)
if err != nil {
return err
}
--
2.52.0
From fd71ea349e81694c8a9b4892379a1d49f24dd273 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 05:01:22 +0800
Subject: [PATCH 04/45] =?UTF-8?q?fix(libraryctl):=20=E5=90=8C=E9=95=9C?=
=?UTF-8?q?=E5=83=8F=E4=B8=8D=E7=AD=89=E4=BA=8E=E5=90=8C=E4=B8=80=E4=B8=AA?=
=?UTF-8?q?=E5=86=99=E5=85=A5=E8=80=85?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
共享业务栈与专用验收实例共用同一个 WeKnora 镜像,原来只按镜像判"未声明写入者",
任何一台开着共享栈的机器都永远开不了窗。判据改为:同项目或无项目标签即冲突;
另一个项目只有数据库/队列目标与源相同才算冲突。单测覆盖六种组合。
---
cmd/libraryctl/main.go | 57 +++++++++++++++++++++++++++--
cmd/libraryctl/writer_check_test.go | 47 ++++++++++++++++++++++++
2 files changed, 100 insertions(+), 4 deletions(-)
create mode 100644 cmd/libraryctl/writer_check_test.go
diff --git a/cmd/libraryctl/main.go b/cmd/libraryctl/main.go
index b411579..f21a60e 100644
--- a/cmd/libraryctl/main.go
+++ b/cmd/libraryctl/main.go
@@ -732,7 +732,11 @@ func runCapture(ctx context.Context, opts options) error {
if err != nil {
return err
}
- return checkNoUndeclaredWriter(ctx, images, declared)
+ app, err := containerEnv(ctx, opts.sourceApp)
+ if err != nil {
+ return err
+ }
+ return checkNoUndeclaredWriter(ctx, images, declared, opts.project, sourceTargetOf(app))
}
result, err := v071.CaptureLibrary(ctx, coordinator, archive, pool, search, objects, sourceReady,
v071.LibraryCaptureRequest{JobID: job, Scope: opts.scope,
@@ -809,21 +813,66 @@ func writerImageIDs(ctx context.Context, items []libraryfreeze.Service) ([]strin
// checkNoUndeclaredWriter refuses to run when a running container uses a declared
// writer image but is not part of the declared group: such a container could keep
// writing during the maintenance window.
-func checkNoUndeclaredWriter(ctx context.Context, images []string, declared map[string]bool) error {
+func checkNoUndeclaredWriter(ctx context.Context, images []string, declared map[string]bool,
+ sourceProject string, source map[string]string) error {
for _, image := range images {
out, err := dockerOutput(ctx, "ps", "-q", "--filter", "ancestor="+image)
if err != nil {
return err
}
for _, id := range strings.Fields(out) {
- if !declared[id] {
- return fmt.Errorf("container %s uses a declared writer image but is not in the declared writer group", id[:12])
+ if declared[id] {
+ continue
+ }
+ project, err := dockerOutput(ctx, "inspect", "--format", `{{index .Config.Labels "com.docker.compose.project"}}`, id)
+ if err != nil {
+ return err
+ }
+ env, err := containerEnv(ctx, id)
+ if err != nil {
+ return err
+ }
+ if conflict, reason := undeclaredWriterConflict(false, project, sourceProject, env, source); conflict {
+ return fmt.Errorf("container %s uses a declared writer image but is not in the declared writer group: %s", id[:12], reason)
}
}
}
return nil
}
+// sourceTargetOf 只取"写到哪儿"的身份:同一个数据库或同一个队列才是真冲突。
+func sourceTargetOf(env map[string]string) map[string]string {
+ return map[string]string{
+ "DB_HOST": env["DB_HOST"], "DB_NAME": env["DB_NAME"], "DB_PORT": env["DB_PORT"],
+ "REDIS_ADDR": env["REDIS_ADDR"], "REDIS_NAMESPACE": env["REDIS_NAMESPACE"],
+ }
+}
+
+// undeclaredWriterConflict 判断一个同镜像容器是否构成"未声明的并发写入者"。
+//
+// 同一 compose 项目或没有项目标签 ⇒ 无法证明隔离,直接冲突。
+// 另一个项目 ⇒ 只有数据目标(数据库/队列)与源相同才算冲突:
+// 镜像相同不等于写同一个库,本机共享业务栈与专用验收实例就是这种关系。
+func undeclaredWriterConflict(declared bool, project, sourceProject string, env, source map[string]string) (bool, string) {
+ if declared {
+ return false, ""
+ }
+ if project == "" {
+ return true, "没有 compose 项目标签,无法证明它不写同一个目标"
+ }
+ if project == sourceProject {
+ return true, "属于同一 compose 项目,却不是声明的写入服务"
+ }
+ if source["DB_HOST"] != "" && env["DB_HOST"] == source["DB_HOST"] && env["DB_NAME"] == source["DB_NAME"] {
+ return true, "另一个项目的同镜像容器指向同一个源数据库"
+ }
+ if source["REDIS_ADDR"] != "" && env["REDIS_ADDR"] == source["REDIS_ADDR"] &&
+ env["REDIS_NAMESPACE"] == source["REDIS_NAMESPACE"] {
+ return true, "另一个项目的同镜像容器共用同一个源队列"
+ }
+ return false, "另一套隔离栈(数据目标不同)"
+}
+
func containerImageOf(ctx context.Context, id string) (string, error) {
image, err := dockerOutput(ctx, "inspect", "--format", "{{.Image}}", id)
if err != nil {
diff --git a/cmd/libraryctl/writer_check_test.go b/cmd/libraryctl/writer_check_test.go
new file mode 100644
index 0000000..276e811
--- /dev/null
+++ b/cmd/libraryctl/writer_check_test.go
@@ -0,0 +1,47 @@
+package main
+
+import (
+ "strings"
+ "testing"
+)
+
+// 同一台机器上可以有两套完全隔离的 WeKnora 栈共用同一个镜像(本机就是这样:
+// 共享业务栈 + 专用验收实例)。只按镜像判断"未声明的写入者",会把另一套栈
+// 当成并发写入者,验收链永远开不了窗;但只看项目标签又会放过多起一个
+// 指向同一个库/队列的副本。判据要同时看归属与真实数据目标。
+func TestUndeclaredWriterConflict(t *testing.T) {
+ source := map[string]string{
+ "DB_HOST": "kgmaint-postgres", "DB_NAME": "kgmaint_target", "DB_PORT": "5432",
+ "REDIS_ADDR": "kgmaint-redis:6379", "REDIS_NAMESPACE": "kgmaint",
+ }
+ cases := []struct {
+ name string
+ declared bool
+ project string
+ env map[string]string
+ want bool
+ reasonHint string
+ }{
+ {"已声明容器本身", true, "kgmaint-weknora", source, false, ""},
+ {"同项目里另起一份(不同名字)", false, "kgmaint-weknora", source, true, "同一 compose 项目"},
+ {"没有 compose 项目标签(docker run 的副本)", false, "", source, true, "没有 compose 项目标签"},
+ {"另一套隔离栈,数据目标不同", false, "weknora071full", map[string]string{
+ "DB_HOST": "WKNFull-postgres", "DB_NAME": "weknora_full", "REDIS_ADDR": "WKNFull-redis:6379", "REDIS_NAMESPACE": "weknora"},
+ false, ""},
+ {"另一套栈但指向同一个库", false, "other-project", map[string]string{
+ "DB_HOST": "kgmaint-postgres", "DB_NAME": "kgmaint_target", "REDIS_ADDR": "WKNFull-redis:6379"},
+ true, "同一个源数据库"},
+ {"另一套栈但共用同一队列", false, "other-project", map[string]string{
+ "DB_HOST": "other-pg", "DB_NAME": "other", "REDIS_ADDR": "kgmaint-redis:6379", "REDIS_NAMESPACE": "kgmaint"},
+ true, "同一个源队列"},
+ }
+ for _, tc := range cases {
+ conflict, reason := undeclaredWriterConflict(tc.declared, tc.project, "kgmaint-weknora", tc.env, source)
+ if conflict != tc.want {
+ t.Fatalf("%s: conflict=%v want %v (%s)", tc.name, conflict, tc.want, reason)
+ }
+ if tc.want && tc.reasonHint != "" && !strings.Contains(reason, tc.reasonHint) {
+ t.Fatalf("%s: reason %q should mention %q", tc.name, reason, tc.reasonHint)
+ }
+ }
+}
--
2.52.0
From 1faf5137ea53adee61e7c0aac4940a39ec832139 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 05:02:10 +0800
Subject: [PATCH 05/45] =?UTF-8?q?fix(libraryctl):=20=E7=94=A8=E5=AE=8C?=
=?UTF-8?q?=E6=95=B4=E5=AE=B9=E5=99=A8=20ID=20=E5=88=A4=E5=AE=9A=E5=86=99?=
=?UTF-8?q?=E5=85=A5=E8=80=85=E5=BD=92=E5=B1=9E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
`docker ps -q` 默认输出 12 位短 ID,与 declared 里的 64 位 ID 永不相等,
结果连已声明的写入者都被判成"未声明的并发写入者",封存永远开不了窗。
改用 --no-trunc 并按前缀双向匹配。
---
cmd/libraryctl/main.go | 20 ++++++++++++++++++--
1 file changed, 18 insertions(+), 2 deletions(-)
diff --git a/cmd/libraryctl/main.go b/cmd/libraryctl/main.go
index f21a60e..d99803c 100644
--- a/cmd/libraryctl/main.go
+++ b/cmd/libraryctl/main.go
@@ -816,12 +816,14 @@ func writerImageIDs(ctx context.Context, items []libraryfreeze.Service) ([]strin
func checkNoUndeclaredWriter(ctx context.Context, images []string, declared map[string]bool,
sourceProject string, source map[string]string) error {
for _, image := range images {
- out, err := dockerOutput(ctx, "ps", "-q", "--filter", "ancestor="+image)
+ // 必须 --no-trunc:`docker ps` 默认只给 12 位短 ID,和 declared 里的
+ // 64 位容器 ID 永远不相等——那样连"已声明的写入者"都会被判成未声明。
+ out, err := dockerOutput(ctx, "ps", "-aq", "--no-trunc", "--filter", "ancestor="+image)
if err != nil {
return err
}
for _, id := range strings.Fields(out) {
- if declared[id] {
+ if declaredWriter(declared, id) {
continue
}
project, err := dockerOutput(ctx, "inspect", "--format", `{{index .Config.Labels "com.docker.compose.project"}}`, id)
@@ -840,6 +842,20 @@ func checkNoUndeclaredWriter(ctx context.Context, images []string, declared map[
return nil
}
+// declaredWriter 同时接受完整 ID 与短 ID:证据里两种写法都出现过,
+// 只比一种会把同一容器判成两个身份。
+func declaredWriter(declared map[string]bool, id string) bool {
+ if declared[id] {
+ return true
+ }
+ for key := range declared {
+ if strings.HasPrefix(key, id) || strings.HasPrefix(id, key) {
+ return true
+ }
+ }
+ return false
+}
+
// sourceTargetOf 只取"写到哪儿"的身份:同一个数据库或同一个队列才是真冲突。
func sourceTargetOf(env map[string]string) map[string]string {
return map[string]string{
--
2.52.0
From f82eb0735f4cae339c542ac52c953256d3a7126b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 05:13:15 +0800
Subject: [PATCH 06/45] =?UTF-8?q?docs(acceptance):=20=E7=9F=A9=E9=98=B5?=
=?UTF-8?q?=E6=8C=89=E5=9B=9B=E6=AE=B5=E9=87=8D=E6=8E=92=EF=BC=8C=E8=A1=A5?=
=?UTF-8?q?=E5=B0=81=E5=AD=98=E9=93=BE=E8=B7=AF=E7=BC=BA=E5=8F=A3=E4=B8=8E?=
=?UTF-8?q?=208088=20=E9=83=A8=E7=BD=B2=E6=96=B9=E6=A1=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
矩阵不再在顶部叠报告:已完成 / 缺代码 / 已实现未跑 / 需授权四段分开,
把本轮 Wiki 撤销真实验收(12 项检查)、贡献级差异、维护面板写进对应行,
并如实记下封存链路缺口(CLI 无入口排空证明、API 封存未接线)、
死信无解除契约、Neo4j 场景与排空探针未跑。
新增正式 8088 待验收部署方案:迁移 067–072、loopback 配置差异、
缺配即拒绝的 fail-closed 规则、回滚与账号数据保留。只准备,未执行。
---
CHANGELOG.md | 10 +-
docs/formal-8088-deployment-plan.md | 90 +++++++++++++++++
docs/library-acceptance-matrix.md | 144 +++++++++++++++-------------
3 files changed, 171 insertions(+), 73 deletions(-)
create mode 100644 docs/formal-8088-deployment-plan.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a036c28..ba808e9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,11 +37,13 @@
routing bindings,同一台机器上会封存"配置里那个库"而不是 API 的验收目标。现在环境变量
优先、读不到才退回 bindings。
-### Notes
+### Docs
-- 本次真实验收(kgmaint 专用实例 + 原版 WeKnora API)与本快照之外的部署计划见
- `docs/library-acceptance-matrix.md` 与交付报告;矩阵按「已完成 / 缺代码 / 未跑 / 需授权」
- 重排,不再在顶部叠报告。
+- `docs/library-acceptance-matrix.md` 按「已完成 / 缺代码 / 已实现未跑 / 需授权」
+ 四段重排(不再在顶部叠报告):补上本轮 Wiki 撤销真实验收、贡献级差异、维护面板;
+ 新增封存链路缺口(CLI 无入口排空证明、API 封存未接线)与死信契约缺口。
+- 新增 `docs/formal-8088-deployment-plan.md`:版本清单、迁移 067–072、运行配置、
+ fail-closed 规则、回滚、正式账号与数据保留、部署风险。**只准备,未执行**。
## 开发快照(后台静默必须在关入口之后证明,且要能复核)
diff --git a/docs/formal-8088-deployment-plan.md b/docs/formal-8088-deployment-plan.md
new file mode 100644
index 0000000..b407229
--- /dev/null
+++ b/docs/formal-8088-deployment-plan.md
@@ -0,0 +1,90 @@
+# 本机正式 8088 待验收部署方案(只准备,不执行)
+
+> 本文是给父会话审查后用的一次性方案:**没有替换 8088,没有重启共享业务**。
+> 正式栈当前仍是旧版(0.1.114),不得对外声称新版已上线。
+
+## 1. 版本清单
+
+| 项 | 值 |
+| --- | --- |
+| 当前正式版本 | 开发版 `0.1.114` / 代码 `dc9e827`(api `knowledge-governance-api:library-dc9e8276560d`,web `knowledge-governance-web:source-dc9e8276560d`,worker `knowledge-governance-worker:library-dc9e8276560d`) |
+| 本次候选代码 | 分支 `feat/library-wiki-contribution-diff`,最终提交见交付报告(代码提交 + 文档提交分开列 SHA) |
+| 开发号 | 提交后由 `scripts/version.py` 自动得出(0.1.0 + 自 v0.1.0 起的提交数) |
+| 前端产物 | `npm --prefix web run build` → `web/dist`,由 `Dockerfile.web` 打进 web 镜像 |
+| 验收实例(已验证同 SHA) | `/tmp/kg-e2e/bin/{api,worker}` + 候选 `libraryctl`,`go version -m` 的 `vcs.modified=false` |
+
+## 2. 数据库迁移
+
+| 现状 | 目标 |
+| --- | --- |
+| 正式治理库 `schema_migrations.max(version)=66` | 需要依次应用 `000067` → `000072` |
+
+```
+000067_library_release_authorizations 发布授权表
+000068_library_restore_kind 作业类型加 restore
+000069_library_write_target_mutex 写入目标互斥
+000070_library_maintenance 维护窗口表
+000071_library_maintenance_level 维护级别(library / instance)
+000072_library_instance_maintenance 实例级维护占用
+```
+
+- 迁移在 api 启动时按 `AUTO_MIGRATE` 自动执行(与现有部署一致);**先备份治理库**再起新 api。
+- 回滚顺序:`072.down` → `071.down` → `070.down` → `069.down` → `068.down` → `067.down`,仅在新版 api 不再写入这些表之后执行。
+- 这些迁移只新增表/列,不改动既有知识治理数据;但 `000068` 扩了 `library_jobs.kind` 的取值。
+
+## 3. 运行配置(正式栈)
+
+正式 api 现有相关环境变量(`docker inspect knowledge-governance-p1-api-1`):
+
+```
+PRODUCTION_RELEASE_REQUESTS_ENABLED=true
+PRODUCTION_BACKUP_RESTORE_VERIFIED=true
+PRODUCTION_WEKNORA_BASE_URL=https://weknora-test.dobot.cn
+PRODUCTION_RELEASE_AUTH_TOKEN_FILE=/run/release-secrets/production_release_auth_token
+PRODUCTION_WEKNORA_API_KEY_FILE=/run/release-secrets/target_weknora_api_key
+LIBRARY_AGENT_SOCKET=/run/library-agent/agent.sock
+LIBRARY_ARCHIVE_ROOT=/var/lib/knowledge-governance/library
+```
+
+**没有** `LIBRARY_TARGET_*`(实例级维护目标)与 `LIBRARY_PRODUCTION_DATABASE_URL`。这必须保持"缺配即拒绝":
+
+- 缺 `LIBRARY_TARGET_*` 时,worker 在 `prebackup` 阶段直接失败并写明
+ 「目标维护未接线,拒绝在挡不住入口/后台写入的情况下写目标」(`cmd/worker/library_handlers.go`)——**不会**退化成"库级锁假装维护"。
+- 缺 `LIBRARY_PRODUCTION_DATABASE_URL` 时 overview/差异按"未接入"显示,不显示 0 或被当成"无变化"。
+- `/api/v1/library/maintenance` 在实例未配置时返回 `instance` 缺省、`held=false`;页面显示「未接入 + 维护类操作 fail closed」。
+- `LIBRARY_AGENT_SOCKET` 指向的 agent 目前**没有运行**:`POST /api/v1/library/captures` 会 503 并写明"未接线",不会假装已封存。
+
+新增配置只在需要真正开维护窗口时才加(本机验收实例的取值可作模板,见
+`evidence-maintenance/harness/candidate-maintenance.env`:`LIBRARY_TARGET_INSTANCE/PROJECT/WRITERS/NON_WRITERS/DOCKER_SOCKET/INGRESS_*`、`LIBRARY_TARGET_REDIS_*`)。
+
+## 4. 部署步骤(父审后执行)
+
+1. **冻结**:确认没有在跑的封存/同步/恢复作业(`GET /api/v1/library/jobs` 无 pending/running)。
+2. **备份治理库 + 归档根**:`pg_dump` 治理库;保持 `LIBRARY_ARCHIVE_ROOT` 卷原样(版本与 blob 都在里面)。
+3. **构建**:从候选 SHA 构建 api/worker/web 三个镜像,tag 里带完整 SHA;不在生产机上另行 build 源码。
+4. **切换**:`docker compose up -d api worker web`(只替换这三个容器;postgres/dingtalk-login/共享 WKNFull-* 不动)。
+5. **健康检查**:`GET /health`、`GET /api/v1/library/overview?scope=internal` 200、`GET /api/v1/library/maintenance?scope=internal` 200 且 `held=false`。
+6. **页面验收**(用户现有管理员会话,不再要候选密码):发布管理页 → 两库页签 → 目标维护面板显示"未接入/未占用"、Wiki 差异逐页行、作业进度与阶段。
+
+## 5. 回滚
+
+| 触发 | 动作 |
+| --- | --- |
+| api/web/worker 起不来或健康检查失败 | 三个容器回到 `*-dc9e8276560d` 镜像;迁移保持已应用(新表空表存在不影响旧代码) |
+| 新版写入后需要完全回到旧结构 | 先停新版 api/worker → 按 072→067 逆序 down → 恢复备份的治理库 → 起旧镜像 |
+| 归档不可读/版本异常 | 归档根只读回滚:保留新卷,切回旧卷挂载点 |
+
+回滚**不触碰**正式账号、会话、治理库既有业务数据(迁移只加表/列),也不动 WeKnora 侧数据。
+
+## 6. 正式账号与数据保留
+
+- 管理员账号/会话在治理库 `users`/`sessions`(`kg_session` cookie)——迁移与镜像切换都不改这些表;不重置口令、不重新初始化。
+- 首页登录沿用现有会话;验收时不要用候选环境的账号。
+- 正式库与归档卷保留原路径,不做"清理/重建"。
+
+## 7. 已知风险与前置条件(必须先解决或明确接受)
+
+1. **`knowledge-governance-p1-release-worker-1` 处于重启循环**(日志每分钟 `connect release target database`,`RELEASE_WORKER_ENABLED=false`)。这是正式栈既有状态,不是本轮引入;部署前需要决定是修配置还是先停掉该服务,否则会持续刷日志。
+2. **封存能力未接线**(见矩阵"缺代码"):正式上线后页面能如实显示"未接入",但"封存测试版本"按钮仍不可用。如果验收要求现场封存,需要先部署 `libraryagent`(`cmd/libraryagent`,0600 unix socket)并把 `LIBRARY_AGENT_SOCKET` 指到它。
+3. **入口排空探针未在最终构建复现**(矩阵"已实现·未跑"):正式部署前若要拿这条证据,需要在生产机重复探针,并接受"闸门关得比客户端快"导致上传注入失败的可能。
+4. 部署本身就是生产变更:需要用户给的窗口与授权,本文不构成执行许可。
\ No newline at end of file
diff --git a/docs/library-acceptance-matrix.md b/docs/library-acceptance-matrix.md
index 8885ff7..97b3a2b 100644
--- a/docs/library-acceptance-matrix.md
+++ b/docs/library-acceptance-matrix.md
@@ -1,80 +1,86 @@
-# 整库同步验收矩阵(真实证据对照)
+# 整库同步验收矩阵(真实证据对照,2026-10-29 重排)
-## 入口级真实服务验收(2026-10-28,候选 API :18089,真实 PG/ES/MinIO,code_sha=ea4cffb)
+本文件是**唯一口径**:状态只写实际发生的事,四类严格分开,不用"部分通过"含糊过去。
-| 项 | 状态 | 证据(`~/.hermes/handoffs/kg-candidate-e2e/`) |
-|---|---|---|
-| A0 首次发布(生产空基线) | 已实现 / 真实服务已验证 | `evidence/A0_baseline.json` |
-| A1 撤销(自洽派生快照) | 已实现 / 真实服务已验证 | `evidence/A1_revoke.json` |
-| B 按版本恢复(含未授权拒绝) | 已实现 / 真实服务已验证 | `evidence/B_restore.json` |
-| C 写阶段 SIGKILL 接管(复用同一预备份) | 已实现 / 真实服务已验证 | `evidence/C_kill_takeover.json` |
-| D 跨 kind 互斥 + 多 worker 单次执行 | 已实现 / 真实服务已验证 | `evidence/D_mutex_multiworker.json` |
-| E1 版本登记失败不报成功 | 已实现 / 真实服务已验证 | `evidence/E1_finalize_fail.json` |
-| E2 finalize 续作(只收尾) | 已实现 / 真实服务已验证 | `evidence/E2_finalize_resume.json` |
-| E3 预备份登记失败零写入 | 已实现 / 真实服务已验证 | `evidence/E3_prebackup_fail_zero_write.json` |
-| 远程生产写入/恢复/清理 | 未授权,未执行 | — |
-| Wiki 撤销贡献语义重算 | 未实现(仅页面级差异) | V03 |
-| 跨系统原子切点 | 未实现;按"导出后回读"协议,边界已写明 | — |
+| 口径 | 含义 |
+| --- | --- |
+| **已完成·已验证** | 有代码 + 真实服务(真实 PG/ES/对象存储/原版 WeKnora API)跑出来的证据,或既有 CI 检查覆盖 |
+| **缺代码** | 功能/契约本身没有实现;界面按"未接入"显示,不冒充 |
+| **已实现·未跑** | 代码与测试在位,缺真实环境执行证据(不是权限问题) |
+| **需授权/需环境** | 实现所需的动作属于生产写入/读取/恢复,或需要本会话拿不到的资源 |
-对应 `docs/library-sync-acceptance.md` 的 30 个验收项。**状态只写实际发生的事**:
+A06(内容、问答、引用图片效果、性能报告)已由用户取消,不作为门槛,也不在本表。
-- **已实现·已验证**:有代码 + 本机真实数据或真实归档/真实 PostgreSQL 跑过的证据,或既有 CI 检查覆盖。
-- **已实现·未验证**:代码与测试在位,但还缺真实业务环境的执行证据(例如需要隔离生产栈)。
-- **阻塞(需授权/环境)**:实现所需的动作属于生产写入、生产读取或生产恢复,当前授权明确禁止。
-- **未实现**:还没有代码,界面按"未接入/未知"显示,不冒充完成。
+---
-A06(内容、问答、引用图片效果、性能报告)已被用户取消,本矩阵不含该项,也不再作为封版门槛。
+## 一、已完成·已验证
-**状态口径(严格区分四件事)**:
-- 已实现·已验证:代码 + 本机真实归档/真实 PostgreSQL 或既有 CI 的实跑证据。
-- 已实现·隔离测试通过:代码 + 单元/集成测试(注入假生产目标),**没有**真实生产执行。
-- 已实现·未验证:代码在位但缺真实环境证据。
-- 未实现 / 真实执行未授权:前者是代码缺口,后者是**权限**缺口,两者不混用。
+| ID | 要点 | 承载位置 | 证据(本轮或前轮,均可回看) |
+| --- | --- | --- | --- |
+| V01 | 只有对内/对外两个目标,身份来自配置映射 | `internal/httpapi/library_*.go`;`web/src/ReleaseTargets.tsx` | overview 对非法 scope 返回 400;真实归档 internal/external 各自解析到唯一 KB |
+| V02 | 解析/索引/Wiki 就绪,验收绑定本版 | `v071/library_source_settlement.go` | 结清检查在封存前执行、缺项阻断;页面注明依据哪次快照 |
+| V04 | 完整固定版本:文档+处理结果+资源+索引+完整 Wiki | `internal/librarysnapshot/*` | 真实快照 f992d64e…:4 文档/38 分块/122 索引/21 资源/31 Wiki 页/55,309,044 字节,部件摘要逐项校验 |
+| V06 | 只同步知识数据,不含账号/会话/凭据 | 导出白名单(10 知识表 + 知识域索引 + 资源 + Wiki) | 部件清单无 users/sessions/api_keys |
+| B01 | 每次生产写入前完整预备份,失败零写入 | `v071.ProductionBackupStore.Prepare` + prebackup 阶段 | 真实 PG/ES 上预备份 3111e823…;故障注入后用它恢复并校验 |
+| B03 | 每版保存完整 Wiki 与引用关联并校验 | `library_snapshot` wiki 部件 + 摘要 | 真实快照 31 页逐页摘要;manifest 记录数量/字节 |
+| S01 | 数据库/资源/索引/Wiki 真实落地并校验 | `v071.ProductionLibraryTarget.Apply/Verify` | 本轮 sync `libsync-internal-…1793221776816380302`:database 67 行、resources 21、index 122、**wiki 63 行**全部 succeeded + verify succeeded;目标库 wiki 31 页 |
+| S02 | 生产不再解析/Embedding/生成 Wiki | index 阶段直接搬运归档 embedding | 真实 ES 写入归档 embedding,未调用模型 |
+| S04 | 各阶段失败/超时/重启可追溯可恢复 | `library_jobs`/`library_job_stages` + `ReconcileLibraryJobs` | 阶段与错误持久化;worker 清理"队列无对应作业"的孤儿 |
+| S05 | 幂等与互斥(多 worker 安全) | 幂等表 + active 唯一索引 | 真实 PG:同目标第二作业被拒;同键同 digest 复用;换 digest 冲突 |
+| R01 | 按指定版本手工恢复 | `POST /library/restores` + `library.restore` | 真实跑通:撤旧授权→503;签发 restore 授权→202→succeeded,内容回到目标版本(`evidence/B_restore.json`) |
+| R02 | 恢复失败显式异常、不回退测试库 | `Outcome.State=rollback_failed` + 独立阶段 | 隔离测试 + 前轮真半写场景(`partial.json`) |
+| P01 | 作业阶段与整体状态 | `library_jobs.state/stage`;页面阶段条 | 阶段勾选只认当前作业证据;无作业显示"尚未开始" |
+| P02 | 四类分项计数/字节/错误 | `stageSizesFrom(manifest)` + `library_job_stages` | 真实数据:database 67/88086B、resources 21/53490166B、index 122/1624880B、wiki 63/105912B |
+| P03 | 同步明细与异常 | 页面"同步明细"读阶段行 | 行来自持久阶段,刷新/重启可复现 |
+| U01 | 发布管理为主要入口(两库+单作业区) | `web/src/ReleaseTargets.tsx` | 按确认稿布局,父会话已在登录浏览器核验 |
+| U02 | 权限边界 | `canWrite`/`canCapture`,写操作需 engineer+ | 无权限不给封存入口;未接线显示通道状态 |
+| U03 | 操作确认 | 封存按钮 + 作业号 + notice | 同一作业号重放返回已存作业并提示 |
+| D01 | 保留策略(数量/天数) | `internal/libraryretention` | 未设置=0 按"全部保留",不编默认值 |
+| D02 | 占用测量 | `internal/librarysnapshot/usage.go` | 版本数/去重内容/blob/未引用/清单;两份真实清单 55,309,693 字节 |
+| D03 | 依赖保护 | `libraryretention.Build` 的 Protected/ProtectedBy | 真实归档两版均因"最近测试封存"受保护 |
+| D04 | 清理预览 | `Build` 的 Candidates/ReclaimPreviewBytes | keep=1 时仍 0 候选;回收预览只计独占字节 |
+| D05 | 容量门禁 | `CheckCapacity` + sync gate | 预算未设置→阻断;超预算→阻断并给预计字节 |
+| D06 | 测试残留口径 | 未引用 blob 统计 | 真实归档未引用 blob 为 0(口径,不等于扫过全部残留) |
+| **S03** | 实例级维护窗口:关入口→排空→静默证明→停写者→写入→校验→开入口 | `internal/libraryfreeze` + `librarymaintenance` + 迁移 070–072 | 前轮 7 场景真跑全绿(normal/kill/applyfail/partial/crossscope/recover_refuse/recover_ok),本轮 sync/drain 场景继续复用;`quiesce` 证据、`post_stop_*`、journal、gate drain.json 均可回看 |
+| **V03-a** | 撤销一份共享贡献后,保留另一份贡献、清除撤销方独有正文/引用/实体边、目录正确 | 由 WeKnora 源侧执行(`cleanupWikiOnKnowledgeDelete` + `EnqueueWikiRetract`),治理侧只比对/搬运 | **本轮真实验收**:kgmaint 隔离实例、原版 API 顺序入库两篇文档 → `entity/fa-bu-zha-men` 同页双来源(2097 字节)→ 真实 `DELETE /api/v1/knowledge/{id}` → 页面保留、来源只剩保留文档、A 独有正文(ZEBRA-A-7731/9910)清除、B 贡献仍在、引用 2→1 且只剩 B 的分块、目录不变、A 独有页面/摘要整页删除、索引页不再列出、实体边无死链。12/12 检查通过。证据:`kg-candidate-e2e/evidence-wiki-final/s8-final-checks-r1.json` + `06-wiki-*-r1.json` + `s3/s6-db-*.json` |
+| **V03-b** | 治理侧能把上述语义变化说清楚(不是页面级"无变化") | `internal/librarydiff/wiki.go` `CompareWiki`;`GET /library/overview` 的 `diff.wiki` | 逐页比对正文/来源/引用/出入边/目录,输出 `sources_removed`、`citations_before→after`、`changed`;单测 `wiki_test.go`、视图单测 `library_wiki_diff_test.go`;页面逐行展示(`wikiContributionLines` + 测试) |
+| **U04** | 维护级别/进度/恢复错误真实呈现 | `MaintenanceCard`(`web/src/ReleaseTargets.tsx`)、`/api/v1/library/maintenance` | 显示实例级/库级、持有 scope+作业、阶段、入口开/关、服务、开始/释放、进度(阶段名中文化)、恢复错误与处理记录;仅"窗口仍持有且作业失败"时给"按预备份恢复";无记录时"未接入 + fail closed"。组件测试 6 项 |
-| ID | 验收要点 | 代码 / 承载位置 | 状态 | 证据或缺口 |
-| --- | --- | --- | --- | --- |
-| V01 | 只有对内/对外两个目标,身份来自配置映射 | `internal/httpapi/library_*.go`(scope 只接受 internal/external);`web/src/ReleaseTargets.tsx` | 已实现·已验证 | overview 对非法 scope 返回 400;真实归档里 internal/external 各自解析到唯一 KB(0c84a098… / 对外 KB) |
-| V02 | 全部解析/索引/Wiki 就绪,验收绑定本版 | `internal/releaseadapter/v071/library_source_settlement.go`;页面准备清单 | 已实现·未验证 | 结清检查(settlement)在封存前执行且缺项阻断;但对"实时测试库此刻就绪"仍需一次真实封存复核;页面已注明依据的是哪次快照 |
-| V03 | 删除文档后 Wiki 共享正文/实体/边/引用真实变化 | `wikiDiffOf`(页面级差异) | **未实现(架构阻塞)** | Wiki 页由 WeKnora 在**源侧**生成,治理侧只搬运快照;"两文档共贡献一页、撤一个另一个保留"必须在源侧重新生成才能验证。本轮未触发源侧生成(属源侧写操作,需原生 Wiki 接口)。页面级差异**不等于**语义重算,不当作完成 |
-| V04 | 完整固定版本:文档集合+处理结果+资源+索引+完整 Wiki | `internal/librarysnapshot/*`(10 表 + 索引 + 资源 + Wiki 部件);`artifacts` 清单 | 已实现·已验证 | 真实快照 f992d64e…:4 文档/38 分块/122 索引/21 资源/31 Wiki 页/55,309,044 字节;部件摘要逐项校验 |
-| V05 | 导出中源变更则拒绝或隔离 | `internal/libraryfreeze/*` + 预备份导出前后行数静默检查 | 部分实现·未验证 | 预备份导出前后行数不一致即失败(本机已验证会拒绝);真实并发写入的隔离演练仍未做 |
-| V06 | 只同步知识数据,不含账号/会话/凭据 | 导出白名单(10 张知识表 + 知识域索引 + 资源 + Wiki) | 已实现·已验证 | 部件清单里没有 users/sessions/api_keys;真实归档部件名可逐项核对 |
-| B01 | 每次生产写入前完整预备份,失败零写入 | `v071.ProductionBackupStore.Prepare` + `libraryrelease` prebackup 阶段 | 已实现·本机真实服务已验证 | 本机真实 PG/ES 上生成预备份 3111e823…(626 字节),带导出前后行数静默检查;故障注入后用它恢复并校验通过。生产目标本身未授权,未对真实生产执行 |
-| B02 | 资源在测试侧删除后仍可恢复 | 归档内容寻址 blob(`library_versions` + `librarysnapshot` 内容去重) | 已实现·未验证 | 归档不依赖测试临时对象;跨版本去重 55,309,693 字节;尚未做"测试侧删除后从归档恢复"的实测 |
-| B03 | 每版保存完整 Wiki 与引用关联并校验 | `library_snapshot` 的 wiki 部件 + 摘要 | 已实现·已验证 | 真实快照含 31 页 Wiki 与逐页摘要,manifest 记录数量/字节 |
-| S01 | 数据库/资源/索引/Wiki 真实落地并校验 | `v071.ProductionLibraryTarget.Apply/Verify`(真实 SQL + ES bulk) | 已实现·本机真实服务已验证 | 本机真实 PG/ES:导入 1 文档/1 分块/1 Wiki 页/1 索引文档并逐表身份摘要校验;写入只覆盖知识域表 |
-| S02 | 生产不再解析/Embedding/生成 Wiki | 索引阶段直接搬运归档原始文档与向量 | 已实现·本机真实服务已验证 | 真实 ES 写入的是归档里的 embedding 数组(未调用任何模型);生产环境本身仍未写入 |
-| S03 | 一致生效与失败补偿边界 | — | 未实现 | 跨 PG/ES/资源的一致切点与可见性保护未实现 |
-| S04 | 各阶段失败/超时/重启可追溯可恢复 | `library_jobs`/`library_job_stages` + `ReconcileLibraryJobs` | 已实现·已验证 | 阶段与错误持久化;worker 启动清理"队列已无对应作业"的孤儿并写明恢复责任,避免永久占锁 |
-| S05 | 幂等与互斥(多 worker 安全) | `library_jobs_idempotency`、`library_jobs_active` 唯一索引 | 已实现·已验证 | 真实 PostgreSQL 上验证:同目标第二个在飞作业被拒;同键同 digest 重放复用;同键换 digest 冲突 |
-| R01 | 按指定版本手工恢复 | `POST /library/restores` + `library.restore` 执行器 | 已实现·真实服务已验证 | 候选环境:撤掉全部旧授权→503;签发 restore 授权→202→succeeded,内容回到目标版本(`evidence/B_restore.json`,作业 `librestore-internal-20261028T120300.925270`)。远程生产未执行 |
-| R02 | 恢复失败显式异常、不回退测试库 | `Outcome.State=rollback_failed` + 独立阶段记录 | 已实现·隔离测试通过 | 测试断言恢复失败与同步失败可区分,且不触碰测试库 |
-| R03 | 存快/恢复快对比 | — | 未实现 | 未做测速;不写没有测量的数字 |
-| P01 | 作业阶段与整体状态 | `library_jobs.state/stage`;页面阶段条 | 已实现·已验证 | 阶段勾选只认当前作业证据;无作业时显示"本次作业尚未开始" |
-| P02 | 四类分项计数/字节/错误 | `stageSizesFrom(manifest)` + `library_job_stages` | 已实现·真实服务已验证 | 候选环境实测 database 67 行/88086 B、resources 21 行/53490166 B、index 122 行/1624880 B、wiki 63 行/105912 B;prebackup/verify/finalize/rollback 无可定义总量保持 NULL;证据 `evidence/A0_baseline.json` 的 `stages` |
-| P03 | 同步明细与异常 | 页面"同步明细"表读阶段行 | 已实现·已验证 | 行来自持久阶段,刷新/重启可复现;封存作业显示 export 阶段真实状态 |
-| U01 | 发布管理为主要入口(两库+单作业区) | `web/src/ReleaseTargets.tsx` | 已实现·已验证 | 按确认稿布局;父会话已在登录浏览器核验两库切换与抽屉 |
-| U02 | 权限边界 | `canWrite`/`canCapture`,POST 需 engineer+ | 已实现·已验证 | 无权限时不给封存入口;未接线时说明通道状态 |
-| U03 | 操作确认 | 封存按钮 + 作业号 + notice | 已实现·已验证 | 同一作业号重放返回已存作业并明确提示 |
-| D01 | 保留策略(数量/天数) | `internal/libraryretention`;`LIBRARY_RETENTION_VERSIONS/DAYS` | 已实现·已验证(单测+真实归档) | 未设置=0 时按"全部保留",不编默认值;设置了才生成候选 |
-| D02 | 占用测量 | `internal/librarysnapshot/usage.go`;系统设置→存储管理 | 已实现·已验证 | 版本数/跨版本去重内容/blob 表观与分配/未引用/清单;真实两份清单 55,309,693 字节 |
-| D03 | 依赖保护 | `libraryretention.Build` 的 Protected/ProtectedBy | 已实现·已验证 | 真实归档上 2 个版本都因"最近测试封存"受保护;受保护版本永不进入候选 |
-| D04 | 清理预览 | `libraryretention.Build` 的 Candidates/ReclaimPreviewBytes;`GET /library/storage` | 已实现·已验证 | 真实归档:策略 keep=1 时仍 0 候选(两版均受保护);回收预览只计独占字节 |
-| D05 | 容量门禁 | `libraryretention.CheckCapacity` + sync gate | 已实现·已验证(单测+真实数据) | 预算未设置→阻断并说明;超预算→阻断并给出预计字节 |
-| D06 | 测试残留 | 归档未引用 blob 统计(UnreferencedBlobs/Bytes) | 已实现·已验证 | 真实归档未引用 blob 为 0;这只是口径,不等于扫描过所有测试残留 |
-| D07 | 实际回收 | — | 阻塞(需清理授权) | 自动清理默认关闭,不提供删除动作 |
+## 二、缺代码
-## 差异比对(本轮新增)
+| ID | 缺口 | 现状与影响 |
+| --- | --- | --- |
+| R03 | 存快/恢复快对比 | 没有测速实现,也未测。不写没有测量的数字 |
+| 死信解除契约 | 死信只能靠人工清理,没有"解除/豁免"契约 | WeKnora `task_dead_letters` 无解决标记;导出/封存按"存在即阻断"(`library_source_settlement.go`)。本轮真实验证:早期错误模型配置产生的 2 条 wiki 死信直接阻断整实例结算,清理方式只能是删除行(记录:`deadletters-before-delete.json`,sha256 `dd4d8f08…`)。要变成可运维契约,需要上游给出解决标记或治理侧设计"带证据的解除"——**未实现** |
+| 封存入口接线(本机) | `POST /library/captures` 需要 `LIBRARY_AGENT_SOCKET` 指向真实 agent | 候选/正式 api 都配置了 socket 路径,但本机没有运行 `libraryagent`,接口会 503 并明示"未接线"(不是静默失败) |
+| CLI 实例级封存 | `libraryctl capture` 只建库级窗口,不关入口 | 真跑结果:WeKnora 收到 SIGTERM 固定 `exit=1`,没有入口排空证明时被拒(`未优雅退出(exit=1)`)。要在"不停共享栈"的前提下封存真实撤销后的库,需要把实例级 + 闸门接进 CLI(或部署 agent)——**未实现** |
-`internal/librarydiff` 以**稳定文档 ID** 为身份、以排除 `updated_at`/`updated_by` 后的整行摘要为内容,
-比较两份归档快照的 `knowledges` 行数组,输出新增/更新/撤销。真实归档上验证:
-对内快照 4 篇对空集为"新增 4",反向为"撤销 4",缺失快照返回原因而不是空差异。
-生产权威版本建立后即可直接给出生产→测试差异;在生产版本未知时页面保持"未接入"。
-Wiki 页面级差异单独返回(`diff.wiki`),明确标注"不代表实体/边/引用重算"。
+## 三、已实现·未跑
-## 未通过项如何阻断
+| ID | 要点 | 为什么未跑 |
+| --- | --- | --- |
+| V05 | 导出中源变更则拒绝或隔离 | 预备份导出前后行数静默检查已有(本机验证会拒绝);真实并发写入的隔离演练未做 |
+| B02 | 资源在测试侧删除后仍可恢复 | 归档内容寻址已实现;"删测试侧对象再从归档恢复"实测未做 |
+| S03-b | 死信/孤儿任务阻断的负向演练(本轮只验证了真实死信阻断) | 真实阻断已发生并记录;系统化的负向矩阵未跑 |
+| **V03-c** | **带"撤销后共享页"的整库封存 → 同步 → 恢复** | 上游语义已验证、治理差异已实现;但这台机器上 CLI 封存止步于上面的 exit=1 缺口,API 封存未接线,所以"封存一份含撤销结果的 Wiki 版本,再同步/恢复并逐行比对"**没有产出真实证据**。旧证据 `drain-task-new-c`(03:39)属于 0ef7984 之前的构建,不能拿来证明当前 SHA |
+| **Neo4j 启用场景** | 代码在 `library_export.go` 检查 `graph_enabled`,启用即 `Neo4j graph snapshot is not supported` 拒绝 | 本轮没有真跑"启用 Neo4j 的库被拒":kgmaint 实例 `NEO4J_ENABLE=false`、测试库 `graph_enabled=false`。代码路径在,真实执行未做 |
+| **排空竞态探针(最终构建)** | 关入口→排空期间产生的真实任务必须等到队列归零才停写者 | 本轮在最终构建(1faf513)上重跑 6 次(`drain-task-final-1faf513{,-r2,-r3,-r4,-r5,-r6}.json`),上传请求全部 `Broken pipe`、队列深度始终 0:闸门在 202 之后 <0.2s 就关监听,客户端来不及把请求送进去。**未复现**,不记为通过;旧 `drain-task-new-c` 的时间线仍是旧构建证据 |
+| U05 | 正式 8088 页面验收 | 正式栈仍是 0.1.114,本轮未替换;维护面板/逐页 Wiki 差异只在测试与候选构建里验证过 |
-- `POST /api/v1/library/syncs`:闸口关闭、缺恢复演练证据、生产端点未配置、生产权威版本未知、
- 目标快照无预备份——任一成立即 503 并逐条列原因,**不创建作业**。
-- 页面"启动同步"按同一 gate 禁用,title 与卡片列出全部缺项;不存在"点了才失败"的假按钮。
-- 封存缺项(结清检查不通过、契约不符、导出校验失败)一律阻断封版,不改状态蒙混。
\ No newline at end of file
+## 四、需授权 / 需环境
+
+| ID | 事项 | 缺什么 |
+| --- | --- | --- |
+| D07 | 实际回收(真删对象/版本) | 自动清理默认关闭;删除属于真实清理,需单独授权 |
+| 远程生产 | 生产写入/恢复/清理 | 用户授权范围只到本机专用验收实例;远程生产一律未执行 |
+| 生产目标维护 | 对共享业务栈开维护窗口 | 本轮明确不停 `WKNFull-app`;维护只在 kgmaint 专用实例上跑 |
+| 生产封存/同步真实链路 | 需要在生产机部署 `libraryagent` 并接线 | 需要用户批准的部署窗口与凭据录入 |
+
+---
+
+## 五、本轮新增结论(写在这里而不是报告顶部)
+
+1. **Wiki 撤销语义是上游行为,必须用上游 API 验**:顺序入库才产生"两篇共贡献一页"(并行入库会各自抽到不同 slug 生成两页,这是上游已知行为)。撤销后页面保留、贡献按文档摘除,12 项检查全部通过。
+2. **治理侧不能只报页面级差异**:撤销共享贡献时页面仍是"更新",页面级计数会显示成"无变化"。已改为逐页语义比对,能指出"来源 -1、引用 2→1、正文变了、出边少了一条"。
+3. **封存链路是本机当前的真缺口**:CLI 封存被 `exit=1` + 无入口排空证明挡住,API 封存没有 agent。这不是"Wiki 语义没验",而是"带撤销结果的版本没法在本机封出来"。正式部署必须先接线 agent(见 `docs/formal-8088-deployment-plan.md`)。
+4. **死信不是可忽略的告警**:一条失败的 wiki op 就足以让整实例结不了算。要么上游给解决标记,要么治理侧设计带证据的解除,当前两者都没有。
\ No newline at end of file
--
2.52.0
From 9d0fe33c130fe95ffffd105251d5f9d1c7491139 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 05:15:53 +0800
Subject: [PATCH 07/45] =?UTF-8?q?docs(ledger):=20=E8=A1=A5=E8=AE=B0=200.1.?=
=?UTF-8?q?162=E2=80=930.1.167=20=E4=B8=8E=E9=AA=8C=E6=94=B6=E4=BB=A3?=
=?UTF-8?q?=E7=A0=81=20SHA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
0.1.166(1faf513)是本轮验收代码 SHA;f82eb07 起的文档提交不改代码。
0.1.165 因后续提交被 CI 取消,按事实记为 cancelled,不改写成成功。
---
docs/release-ledger.md | 12 ++++++++++++
1 file changed, 12 insertions(+)
diff --git a/docs/release-ledger.md b/docs/release-ledger.md
index 1cfadc9..8c85c73 100644
--- a/docs/release-ledger.md
+++ b/docs/release-ledger.md
@@ -61,6 +61,18 @@ run164 因 qawemail 依赖外网 DNS 失败,已修,不涂改。
旧记录 0.1.119 起为本台账自身补记:它只改文档,CI 结论以对应 run 为准(交付报告列出 run id 与结论),
不因"文档提交"免检。
+| 0.1.162 | 1f482e4b | Wiki 贡献级差异 + 维护面板(前端) | 203 | **success** | 否 |
+| 0.1.163 | 23cc6c0a | libraryctl 支持 MinIO 源 | 204 | **success** | 否 |
+| 0.1.164 | 906c2829 | 捕获/预检共用 scope 映射 | 205 | **success** | 否 |
+| 0.1.165 | fd71ea34 | 同镜像不等于同一写入者 | 206 | completed/cancelled(被后续提交取消,不计) | 否 |
+| 0.1.166 | 1faf5137 | 用完整容器 ID 判定写入者归属(**验收代码 SHA**) | 207 | **success** | 否 |
+| 0.1.167 | f82eb073 | 矩阵四段重排 + 8088 待验收部署方案 | 208 | **success** | 否 |
+
+当前候选 = 0.1.166(1faf513);其后的 f82eb07 只改文档,未改代码,验收证据的 code_sha 仍是 **1faf513**。
+本轮真实验收证据:`/home/zheromiku/.hermes/handoffs/kg-candidate-e2e/evidence-wiki-final/`,
+交付报告:`/home/zheromiku/.hermes/handoffs/release-wiki-final-acceptance-result.md`。
+正式 8088 仍是 0.1.114(dc9e827),未部署;部署方案见 `docs/formal-8088-deployment-plan.md`。
+
## 说明
- 0.1.108–0.1.115 的 CI 事实是 failure/未取得通过证据,**不因后续修复改写成绿**;
--
2.52.0
From ee7688f24eb5a5b9f6dcd18afc6bb672fdaf0f6d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 05:18:42 +0800
Subject: [PATCH 08/45] =?UTF-8?q?docs(matrix):=20Wiki=20=E6=92=A4=E9=94=80?=
=?UTF-8?q?=E6=A3=80=E6=9F=A5=E5=AE=9E=E9=99=85=2013=20=E9=A1=B9=EF=BC=8C?=
=?UTF-8?q?=E6=94=B9=E6=AD=A3=E8=AE=A1=E6=95=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/library-acceptance-matrix.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/library-acceptance-matrix.md b/docs/library-acceptance-matrix.md
index 97b3a2b..0812bd2 100644
--- a/docs/library-acceptance-matrix.md
+++ b/docs/library-acceptance-matrix.md
@@ -42,7 +42,7 @@ A06(内容、问答、引用图片效果、性能报告)已由用户取消
| D05 | 容量门禁 | `CheckCapacity` + sync gate | 预算未设置→阻断;超预算→阻断并给预计字节 |
| D06 | 测试残留口径 | 未引用 blob 统计 | 真实归档未引用 blob 为 0(口径,不等于扫过全部残留) |
| **S03** | 实例级维护窗口:关入口→排空→静默证明→停写者→写入→校验→开入口 | `internal/libraryfreeze` + `librarymaintenance` + 迁移 070–072 | 前轮 7 场景真跑全绿(normal/kill/applyfail/partial/crossscope/recover_refuse/recover_ok),本轮 sync/drain 场景继续复用;`quiesce` 证据、`post_stop_*`、journal、gate drain.json 均可回看 |
-| **V03-a** | 撤销一份共享贡献后,保留另一份贡献、清除撤销方独有正文/引用/实体边、目录正确 | 由 WeKnora 源侧执行(`cleanupWikiOnKnowledgeDelete` + `EnqueueWikiRetract`),治理侧只比对/搬运 | **本轮真实验收**:kgmaint 隔离实例、原版 API 顺序入库两篇文档 → `entity/fa-bu-zha-men` 同页双来源(2097 字节)→ 真实 `DELETE /api/v1/knowledge/{id}` → 页面保留、来源只剩保留文档、A 独有正文(ZEBRA-A-7731/9910)清除、B 贡献仍在、引用 2→1 且只剩 B 的分块、目录不变、A 独有页面/摘要整页删除、索引页不再列出、实体边无死链。12/12 检查通过。证据:`kg-candidate-e2e/evidence-wiki-final/s8-final-checks-r1.json` + `06-wiki-*-r1.json` + `s3/s6-db-*.json` |
+| **V03-a** | 撤销一份共享贡献后,保留另一份贡献、清除撤销方独有正文/引用/实体边、目录正确 | 由 WeKnora 源侧执行(`cleanupWikiOnKnowledgeDelete` + `EnqueueWikiRetract`),治理侧只比对/搬运 | **本轮真实验收**:kgmaint 隔离实例、原版 API 顺序入库两篇文档 → `entity/fa-bu-zha-men` 同页双来源(2097 字节)→ 真实 `DELETE /api/v1/knowledge/{id}` → 页面保留、来源只剩保留文档、A 独有正文(ZEBRA-A-7731/9910)清除、B 贡献仍在、引用 2→1 且只剩 B 的分块、目录不变、A 独有页面/摘要整页删除、索引页不再列出、实体边无死链。13/13 检查通过。证据:`kg-candidate-e2e/evidence-wiki-final/s8-final-checks-r1.json` + `06-wiki-*-r1.json` + `s3/s6-db-*.json` |
| **V03-b** | 治理侧能把上述语义变化说清楚(不是页面级"无变化") | `internal/librarydiff/wiki.go` `CompareWiki`;`GET /library/overview` 的 `diff.wiki` | 逐页比对正文/来源/引用/出入边/目录,输出 `sources_removed`、`citations_before→after`、`changed`;单测 `wiki_test.go`、视图单测 `library_wiki_diff_test.go`;页面逐行展示(`wikiContributionLines` + 测试) |
| **U04** | 维护级别/进度/恢复错误真实呈现 | `MaintenanceCard`(`web/src/ReleaseTargets.tsx`)、`/api/v1/library/maintenance` | 显示实例级/库级、持有 scope+作业、阶段、入口开/关、服务、开始/释放、进度(阶段名中文化)、恢复错误与处理记录;仅"窗口仍持有且作业失败"时给"按预备份恢复";无记录时"未接入 + fail closed"。组件测试 6 项 |
--
2.52.0
From 11c52ad81b425355205221666aae1b1561b71ef3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 05:48:38 +0800
Subject: [PATCH 09/45] =?UTF-8?q?fix(libraryctl):=20=E5=B0=81=E5=AD=98?=
=?UTF-8?q?=E7=AA=97=E5=8F=A3=E6=8E=A5=E4=B8=8A=E5=AE=9E=E4=BE=8B=E7=BA=A7?=
=?UTF-8?q?=E5=85=A5=E5=8F=A3=E9=97=B8=E9=97=A8=E4=B8=8E=E5=90=8E=E5=8F=B0?=
=?UTF-8?q?=E9=9D=99=E9=BB=98?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
库级窗口永远拿不到在途排空证据:被代理的 WeKnora 收到 SIGTERM 就 exit(1),
写者退出码不能当作请求已排空。capture/recover 改由 librarymaintenance.Manager
装配入口闸门、后台静默检查、目标指纹与入口探针(与发布链路同一套实现),
排空证据来自闸门 drain 记录;缺 LIBRARY_TARGET_* 时在开窗口前拒绝并点名。
维护接线解析收敛到 internal/librarymaintenance/env.go,agent 与 worker 讲同一组
变量名;agent 启动如实打印接线状态;安装脚本强制 0600 agent.env。
试过:make verify 15 项全绿;新增 7 个用例(接线解析/身份绑定/缺闸门拒绝)。
---
CHANGELOG.md | 24 ++++++
cmd/libraryagent/main.go | 9 +++
cmd/libraryctl/main.go | 103 +++++++++++++++++++++---
cmd/libraryctl/maintenance_test.go | 80 ++++++++++++++++++
docs/library-capture.md | 26 ++++++
internal/librarymaintenance/env.go | 91 +++++++++++++++++++++
internal/librarymaintenance/env_test.go | 80 ++++++++++++++++++
scripts/library-agent-install.sh | 25 +++++-
8 files changed, 426 insertions(+), 12 deletions(-)
create mode 100644 cmd/libraryctl/maintenance_test.go
create mode 100644 internal/librarymaintenance/env.go
create mode 100644 internal/librarymaintenance/env_test.go
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ba808e9..a45a3fe 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,29 @@
# Changelog
+## 开发快照(封存入口接线:库级窗口接上实例级闸门)
+
+### Fixed
+
+- **主机侧封存不再用"库级窗口"跑实例**:`libraryctl capture` / `recover` 改由
+ `librarymaintenance.Manager` 装配——入口闸门、后台静默检查、目标指纹、入口探针与发布链路
+ 是同一套实现。实例级维护里"写入者 exit=1"不再等于"在途请求被截断":被代理的 WeKnora 收到
+ SIGTERM 就 `exit(1)` 是已知上游行为,排空证据来自闸门(`active_at_close` / `drained`),
+ 校验没有放松,而是补上了缺的那一层证据。
+- 缺少 `LIBRARY_TARGET_INGRESS_*` / `LIBRARY_TARGET_REDIS_*` 时 `capture` 在**开窗口前拒绝**
+ 并点名缺哪个变量;不再退回一个没有排空证据的窗口(那样的"成功"无法复核)。
+- 维护接线解析收敛到 `internal/librarymaintenance/env.go`:agent 与 worker 讲同一组变量名,
+ 空白值算缺失、队列库号必须是非负整数、口令不 Trim(前后空格也是口令)。
+- `libraryagent` 启动时如实打印维护目标是否接好(缺了就直说"封存会拒绝")。
+- `scripts/library-agent-install.sh` 强制 `agent.env`(0600,`EnvironmentFile=`),并把源容器/
+ 项目/写入者声明做成可覆盖变量;没有 env 文件直接 `AGENT_ENV_MISSING` 退出。
+
+### Tests
+
+- `internal/librarymaintenance/env_test.go`:整份声明解析、逐项点名缺失、空白拒绝、
+ 口令空格保留、非法队列库号。
+- `cmd/libraryctl/maintenance_test.go`:入口/队列/源身份绑到同一份配置、数据库身份不泄漏口令、
+ 写入者声明透传、缺闸门拒绝。
+
## 开发快照(Wiki 撤销贡献:逐页语义比对 + 维护窗口真实呈现)
### Added
diff --git a/cmd/libraryagent/main.go b/cmd/libraryagent/main.go
index 2aa4c0d..ada1d86 100644
--- a/cmd/libraryagent/main.go
+++ b/cmd/libraryagent/main.go
@@ -14,6 +14,7 @@ import (
"time"
"knowledge-governance/internal/libraryagent"
+ "knowledge-governance/internal/librarymaintenance"
)
func main() {
@@ -39,6 +40,14 @@ func main() {
if err != nil {
log.Fatal(err)
}
+ // 实例级维护接线(入口闸门 + 后台队列)不在 agent 的 Config 里:它由同一份
+ // 环境声明提供给子进程。启动时先说清楚有没有——缺了封存会在开窗口前被拒,
+ // 不允许"以为接好了"跑到一半才发现没有排空证据。
+ if target, targetErr := librarymaintenance.TargetFromEnv(os.Getenv); targetErr != nil {
+ log.Printf("library agent: 封存会拒绝(实例级维护未接线):%v", targetErr)
+ } else {
+ log.Printf("library agent: 实例级维护目标 %s 入口 %s 闸门 %s", target.Instance, target.IngressURL, target.IngressService)
+ }
if *describe {
log.Printf("library agent config: %+v", agent.Describe())
return
diff --git a/cmd/libraryctl/main.go b/cmd/libraryctl/main.go
index d99803c..2a28ea1 100644
--- a/cmd/libraryctl/main.go
+++ b/cmd/libraryctl/main.go
@@ -33,6 +33,7 @@ import (
"github.com/jackc/pgx/v5/pgxpool"
"knowledge-governance/internal/libraryfreeze"
+ "knowledge-governance/internal/librarymaintenance"
"knowledge-governance/internal/librarysnapshot"
v071 "knowledge-governance/internal/releaseadapter/v071"
releaseworkflow "knowledge-governance/internal/workflows/release"
@@ -451,6 +452,78 @@ func openFreeze(ctx context.Context, opts options) (*libraryfreeze.Coordinator,
return coordinator, control, nil
}
+// captureMaintenanceConfig 把"这次封存动的是哪个实例"落成实例级维护目标。
+//
+// 为什么必须实例级:被代理的 WeKnora 收到 SIGTERM 会直接 exit(1),写者的退出码
+// 因此永远不能当作"在途请求已排空"。排空证据只能在真正的入口上取——关掉闸门、
+// 等它把在途连接放完。没有闸门就没有证据,那种封存不允许以"库级窗口"的名义跑
+// (真跑过:被 exit=1 拒掉,这是校验在起作用,不是要放松的地方)。
+//
+// 入口/队列的声明与容器内 worker 共用同一组 LIBRARY_TARGET_* 名称,
+// 数据库/索引/桶则取自本次真实发现的源,避免"关的是 A 的门、读的是 B 的队列"。
+func captureMaintenanceConfig(opts options, source sourceConfig, get func(string) string) (librarymaintenance.Config, error) {
+ target, err := librarymaintenance.TargetFromEnv(get)
+ if err != nil {
+ return librarymaintenance.Config{}, err
+ }
+ writers, nonWriters, err := writerDeclaration(opts)
+ if err != nil {
+ return librarymaintenance.Config{}, err
+ }
+ identity, err := librarymaintenance.DatabaseIdentity(source.DatabaseURL)
+ if err != nil {
+ return librarymaintenance.Config{}, err
+ }
+ return librarymaintenance.Config{
+ Instance: target.Instance,
+ Project: opts.project,
+ Writers: writers,
+ NonWriters: nonWriters,
+ DockerSocket: opts.dockerSocket,
+ IngressURL: target.IngressURL,
+ IngressService: target.IngressService,
+ IngressDrainFile: target.IngressDrainFile,
+ Database: identity,
+ Index: source.SearchIndex,
+ Bucket: source.Object.Bucket,
+ // 后台静默检查连的是"正在被封的这个源":未结清的后台账本与队列都在它身上。
+ DatabaseURL: source.DatabaseURL,
+ RedisAddr: target.RedisAddr,
+ RedisPassword: target.RedisPassword,
+ RedisDB: target.RedisDB,
+ }, nil
+}
+
+// openMaintenance 用实例级目标装配协调器:入口闸门、后台静默检查、目标指纹、
+// 入口探针全部来自上面那份声明,与发布链路用的是同一套实现(不是第二份协议)。
+func openMaintenance(ctx context.Context, opts options, source sourceConfig) (*libraryfreeze.Coordinator, *libraryfreeze.ProjectController, *librarymaintenance.Manager, error) {
+ config, err := captureMaintenanceConfig(opts, source, os.Getenv)
+ if err != nil {
+ return nil, nil, nil, err
+ }
+ manager, err := librarymaintenance.New(config)
+ if err != nil {
+ return nil, nil, nil, err
+ }
+ // 拓扑先过关:写入者发布了端口 = 存在绕闸直连,这样的"维护"只关了半扇门。
+ if err = manager.VerifyTopology(ctx); err != nil {
+ manager.Close()
+ return nil, nil, nil, fmt.Errorf("目标拓扑不满足唯一入口约束,拒绝开维护窗口:%w", err)
+ }
+ coordinator, control, err := manager.Open(opts.journalRoot)
+ if err != nil {
+ manager.Close()
+ return nil, nil, nil, err
+ }
+ return coordinator, control, manager, nil
+}
+
+// discoverMaintenanceSource 只读"这个源是什么",不碰治理库的 scope 绑定:
+// 恢复/收尾不该因为治理库读不到就被卡住。
+func discoverMaintenanceSource(ctx context.Context, opts options) (sourceConfig, error) {
+ return discoverSource(ctx, opts, map[string]string{})
+}
+
func openArchive(opts options) (*librarysnapshot.Archive, error) {
if err := os.MkdirAll(opts.archiveRoot, 0700); err != nil {
return nil, err
@@ -643,10 +716,21 @@ func runCapture(ctx context.Context, opts options) error {
return err
}
defer archive.Close()
- coordinator, control, err := openFreeze(ctx, opts)
+ binding, err := scopeBindings(ctx, opts.governancePG)
if err != nil {
return err
}
+ config, err := discoverSource(ctx, opts, binding)
+ if err != nil {
+ return err
+ }
+ // 维护窗口必须先按"实例级"接好:入口闸门给出在途排空证据,后台静默检查
+ // 给出停写者那一刻队列已空。缺任何一项都拒绝封存——没有证据的封存不是候选。
+ coordinator, control, manager, err := openMaintenance(ctx, opts, config)
+ if err != nil {
+ return err
+ }
+ defer manager.Close()
defer coordinator.Close()
defer control.Close()
if err = coordinator.Recover(ctx); err != nil {
@@ -660,10 +744,6 @@ func runCapture(ctx context.Context, opts options) error {
if err != nil {
return err
}
- binding, err := scopeBindings(ctx, opts.governancePG)
- if err != nil {
- return err
- }
scopedKB := binding[opts.scope]
if found {
manifest, err := replayCapture(job, opts.scope, scopedKB, existing, archive)
@@ -672,10 +752,6 @@ func runCapture(ctx context.Context, opts options) error {
}
return printCapture(job, existing.SnapshotID, manifest, true)
}
- config, err := discoverSource(ctx, opts, binding)
- if err != nil {
- return err
- }
pool, err := openSourceDatabase(ctx, config)
if err != nil {
return err
@@ -957,10 +1033,17 @@ func runVerify(opts options) error {
}
func runRecover(ctx context.Context, opts options) error {
- coordinator, control, err := openFreeze(ctx, opts)
+ // 收尾也必须走同一份实例级目标:崩溃留下的窗口是"入口已关、写入者已停",
+ // 恢复要用闸门把入口真的重新打开,没有闸门就没有"目标已恢复"的证据。
+ source, err := discoverMaintenanceSource(ctx, opts)
if err != nil {
return err
}
+ coordinator, control, manager, err := openMaintenance(ctx, opts, source)
+ if err != nil {
+ return err
+ }
+ defer manager.Close()
defer coordinator.Close()
defer control.Close()
if err = coordinator.Recover(ctx); err != nil {
diff --git a/cmd/libraryctl/maintenance_test.go b/cmd/libraryctl/maintenance_test.go
new file mode 100644
index 0000000..1a17c8e
--- /dev/null
+++ b/cmd/libraryctl/maintenance_test.go
@@ -0,0 +1,80 @@
+package main
+
+import (
+ "strings"
+ "testing"
+
+ v071 "knowledge-governance/internal/releaseadapter/v071"
+)
+
+func maintenanceEnv() map[string]string {
+ return map[string]string{
+ "LIBRARY_TARGET_INSTANCE": "kgmaint-weknora",
+ "LIBRARY_TARGET_INGRESS_URL": "http://127.0.0.1:18080/health",
+ "LIBRARY_TARGET_INGRESS_SERVICE": "ingress",
+ "LIBRARY_TARGET_INGRESS_DRAIN_FILE": "/tmp/gate/drain.json",
+ "LIBRARY_TARGET_REDIS_ADDR": "127.0.0.1:26379",
+ "LIBRARY_TARGET_REDIS_PASSWORD": "secret",
+ "LIBRARY_TARGET_REDIS_DB": "0",
+ }
+}
+
+func captureSource() sourceConfig {
+ return sourceConfig{
+ DatabaseURL: "postgres://kgmaint:pw@127.0.0.1:25432/kgmaint_target?sslmode=disable",
+ SearchIndex: "kgmaint_1028a_chunks",
+ Object: v071.S3ObjectStoreConfig{Provider: "minio", Bucket: "kgmaint-1028a"},
+ }
+}
+
+func captureOptions() options {
+ return options{project: "kgmaint-weknora", writers: "app", nonWriters: "postgres=database store",
+ dockerSocket: "/var/run/docker.sock", journalRoot: "/tmp/kgmaint-journal"}
+}
+
+// 封存窗口必须是实例级:入口/队列来自与 worker 同一份 LIBRARY_TARGET_*,
+// 库/索引/桶来自本次真实发现的源——两边混用就会"关 A 的门、读 B 的队列"。
+func TestCaptureMaintenanceConfigBindsGateQueueAndSourceIdentity(t *testing.T) {
+ env := maintenanceEnv()
+ config, err := captureMaintenanceConfig(captureOptions(), captureSource(), func(name string) string { return env[name] })
+ if err != nil {
+ t.Fatalf("完整声明被拒:%v", err)
+ }
+ if config.Instance != "kgmaint-weknora" || config.Project != "kgmaint-weknora" {
+ t.Fatalf("实例/项目不对:%+v", config)
+ }
+ if config.IngressURL != "http://127.0.0.1:18080/health" || config.IngressService != "ingress" ||
+ config.IngressDrainFile != "/tmp/gate/drain.json" {
+ t.Fatalf("入口闸门取值不对:%+v", config)
+ }
+ if config.RedisAddr != "127.0.0.1:26379" || config.RedisPassword != "secret" || config.RedisDB != 0 {
+ t.Fatalf("队列取值不对:%+v", config)
+ }
+ // 口令只进结构体,不落进任何可打印身份:身份里只有 host:port/db。
+ if config.Database != "127.0.0.1:25432/kgmaint_target" {
+ t.Fatalf("数据库身份不对:%q", config.Database)
+ }
+ if strings.Contains(config.Database, "pw") {
+ t.Fatalf("数据库身份泄漏了口令:%q", config.Database)
+ }
+ if config.Index != "kgmaint_1028a_chunks" || config.Bucket != "kgmaint-1028a" {
+ t.Fatalf("索引/桶没取到源的身份:%+v", config)
+ }
+ if len(config.Writers) != 1 || config.Writers[0] != "app" || config.NonWriters["postgres"] == "" {
+ t.Fatalf("写入者声明没透传:%+v", config)
+ }
+ // 后台静默检查必须连"正在被封的源"。
+ if config.DatabaseURL != captureSource().DatabaseURL {
+ t.Fatalf("后台静默检查连错库")
+ }
+}
+
+// 没有闸门就没有排空证据:必须在开窗口之前拒绝,而不是退回"只锁库"的旧模式。
+func TestCaptureMaintenanceConfigRefusesWithoutIngress(t *testing.T) {
+ env := maintenanceEnv()
+ delete(env, "LIBRARY_TARGET_INGRESS_URL")
+ _, err := captureMaintenanceConfig(captureOptions(), captureSource(), func(name string) string { return env[name] })
+ if err == nil || !strings.Contains(err.Error(), "LIBRARY_TARGET_INGRESS_URL") {
+ t.Fatalf("缺入口闸门没有被拒:%v", err)
+ }
+}
diff --git a/docs/library-capture.md b/docs/library-capture.md
index 6a0dfa3..1a634e8 100644
--- a/docs/library-capture.md
+++ b/docs/library-capture.md
@@ -45,6 +45,28 @@
同一个作业号重跑是**幂等重放**:直接返回已封存的同一份候选(`replay=true`、`source_read=false`、`writers_stopped=false`),不读来源、不停写入者;同一作业号换了 scope 或绑定库则明确拒绝。
+## 实例级维护接线(封存窗口的唯一入口证据)
+
+`capture` 与 `recover` 现在都按**实例级维护**开窗口,接线来自与 worker 同一组环境变量
+(名字只在 `internal/librarymaintenance/env.go` 出现一次):
+
+```
+LIBRARY_TARGET_INSTANCE 实例名(写进维护记录与目标指纹)
+LIBRARY_TARGET_INGRESS_URL 入口地址(恢复后要能 200)
+LIBRARY_TARGET_INGRESS_SERVICE Compose 里的入口闸门服务名
+LIBRARY_TARGET_INGRESS_DRAIN_FILE 闸门写排空证据的宿主机文件
+LIBRARY_TARGET_REDIS_ADDR/_PASSWORD/_DB 后台队列(asynq)地址
+```
+
+为什么不再保留"库级窗口":被代理的 WeKnora 收到 SIGTERM 会直接 `exit(1)`,写者退出码
+永远不能当作"在途请求已排空"。排空证据只能在真正的入口上取——关闸门、等它把在途连接
+放完(`drain.json` 里的 `active_at_close` / `drained`)。因此缺少上面任何一项时 `capture`
+会**在开窗口前拒绝**(报出缺少的变量名),而不是退回一个没有排空证据的窗口。
+
+开窗口的顺序仍是:关入口并等在途排空 → 证明后台静默(稳定窗口 + 任务集合指纹)→ 停写入者
+→ 停后复核队列/指纹与入口 → 导出 → 恢复写入者与入口。停写者后仍会**再查一次**源是否结清,
+所以窗口内派生的真实任务必须真的跑完,否则封存被拒(不是等一会儿就算了)。
+
## 从页面发起封存(主机侧 agent)
页面点「发起对内/对外封存」只是**投递一个作业**;执行发生在这台主机上的 agent:
@@ -52,6 +74,10 @@
- `scripts/library-agent-install.sh` 构建并安装 `libraryagent`(systemd **user** 服务),
监听 `~/.local/share/knowledge-governance/agent/agent.sock`,目录 0700、socket 0600,
并额外用 `SO_PEERCRED` 要求对端与 agent 同 uid。
+- 维护接线由 `~/.local/share/knowledge-governance/agent.env`(0600,`EnvironmentFile=`)提供;
+ 没有这个文件安装脚本直接拒绝(`AGENT_ENV_MISSING`),免得装出一个"没有闸门"的 agent。
+ 源容器/项目/写入者声明可用 `AGENT_SOURCE_APP`、`AGENT_SOURCE_PG`、`AGENT_SOURCE_ES`、
+ `AGENT_PROJECT`、`AGENT_WRITERS`、`AGENT_NON_WRITERS` 覆盖,默认是本机 `weknora071full`。
- agent 自己固定 `libraryctl` 的路径、归档与日志根、Compose 项目与写入者声明;
请求只能选 `scope`(internal/external)和作业号,**不能**指定路径、项目、容器或命令。
- 只有 worker 通过挂载的 socket 目录投递作业(`LIBRARY_AGENT_SOCKET`)。容器里
diff --git a/internal/librarymaintenance/env.go b/internal/librarymaintenance/env.go
new file mode 100644
index 0000000..1bb9d1b
--- /dev/null
+++ b/internal/librarymaintenance/env.go
@@ -0,0 +1,91 @@
+package librarymaintenance
+
+import (
+ "errors"
+ "fmt"
+ "strconv"
+ "strings"
+)
+
+// 目标入口闸门与后台队列的声明名称。
+//
+// 为什么集中在这里:容器内的 worker 与主机侧的封存(cmd/libraryctl)都要讲
+// 同一份"这个实例的入口在哪、队列在哪";名字写两遍迟早会分叉,而分叉的表现
+// 是"一边关的是 A 实例的门、另一边读的是 B 实例的队列"——不会报错,只会给出
+// 错的证据。
+const (
+ EnvInstance = "LIBRARY_TARGET_INSTANCE"
+ EnvIngressURL = "LIBRARY_TARGET_INGRESS_URL"
+ EnvIngressService = "LIBRARY_TARGET_INGRESS_SERVICE"
+ EnvIngressDrainFile = "LIBRARY_TARGET_INGRESS_DRAIN_FILE"
+ EnvRedisAddr = "LIBRARY_TARGET_REDIS_ADDR"
+ EnvRedisPassword = "LIBRARY_TARGET_REDIS_PASSWORD"
+ EnvRedisDB = "LIBRARY_TARGET_REDIS_DB"
+)
+
+// TargetEnv 是一次实例级维护所需的"入口 + 队列"声明。
+//
+// 缺任何一项都不许降级成"库级维护":没有闸门就没有"入口已关、在途已排空"
+// 的证据,没有队列就证明不了停写者时后台是空的。这两条正是被代理的 WeKnora
+// 收到 SIGTERM 就 exit(1) 之后唯一还能证明"请求没被截断"的东西。
+type TargetEnv struct {
+ Instance string
+ IngressURL string
+ IngressService string
+ IngressDrainFile string
+ RedisAddr string
+ RedisPassword string
+ RedisDB int
+}
+
+// TargetFromEnv 解析维护目标声明。缺少的项一次性全部报出来(含变量名),
+// 让部署方一次改对,而不是改一项再撞下一项。
+func TargetFromEnv(get func(string) string) (TargetEnv, error) {
+ if get == nil {
+ return TargetEnv{}, errors.New("缺少配置读取入口")
+ }
+ value := func(name string) string { return strings.TrimSpace(get(name)) }
+ target := TargetEnv{
+ Instance: value(EnvInstance),
+ IngressURL: value(EnvIngressURL),
+ IngressService: value(EnvIngressService),
+ IngressDrainFile: value(EnvIngressDrainFile),
+ RedisAddr: value(EnvRedisAddr),
+ // 口令不 Trim:前后空格也是口令的一部分,Trim 会把能连上的配置变成连不上。
+ RedisPassword: get(EnvRedisPassword),
+ }
+ missing := make([]string, 0, 5)
+ for _, item := range []struct {
+ name string
+ current string
+ }{
+ {EnvInstance, target.Instance},
+ {EnvIngressURL, target.IngressURL},
+ {EnvIngressService, target.IngressService},
+ {EnvIngressDrainFile, target.IngressDrainFile},
+ {EnvRedisAddr, target.RedisAddr},
+ } {
+ if item.current == "" {
+ missing = append(missing, item.name)
+ }
+ }
+ if strings.TrimSpace(target.RedisPassword) == "" {
+ missing = append(missing, EnvRedisPassword)
+ }
+ rawDB := value(EnvRedisDB)
+ switch {
+ case rawDB == "":
+ missing = append(missing, EnvRedisDB)
+ default:
+ db, err := strconv.Atoi(rawDB)
+ if err != nil || db < 0 {
+ return TargetEnv{}, fmt.Errorf("%s 不是有效的队列库号(%q)", EnvRedisDB, rawDB)
+ }
+ target.RedisDB = db
+ }
+ if len(missing) > 0 {
+ return TargetEnv{}, fmt.Errorf("实例级维护未接线:缺少 %s(没有入口闸门与队列就无法证明入口已排空、后台已静默)",
+ strings.Join(missing, "、"))
+ }
+ return target, nil
+}
diff --git a/internal/librarymaintenance/env_test.go b/internal/librarymaintenance/env_test.go
new file mode 100644
index 0000000..f803977
--- /dev/null
+++ b/internal/librarymaintenance/env_test.go
@@ -0,0 +1,80 @@
+package librarymaintenance
+
+import (
+ "strings"
+ "testing"
+)
+
+func completeEnv() map[string]string {
+ return map[string]string{
+ EnvInstance: "kgmaint-weknora",
+ EnvIngressURL: "http://127.0.0.1:18080/health",
+ EnvIngressService: "ingress",
+ EnvIngressDrainFile: "/tmp/gate/drain.json",
+ EnvRedisAddr: "127.0.0.1:26379",
+ EnvRedisPassword: "secret",
+ EnvRedisDB: "0",
+ }
+}
+
+func lookup(values map[string]string) func(string) string {
+ return func(name string) string { return values[name] }
+}
+
+func TestTargetFromEnvReadsTheWholeDeclaration(t *testing.T) {
+ target, err := TargetFromEnv(lookup(completeEnv()))
+ if err != nil {
+ t.Fatalf("完整声明被拒:%v", err)
+ }
+ if target.Instance != "kgmaint-weknora" || target.IngressService != "ingress" ||
+ target.IngressURL != "http://127.0.0.1:18080/health" || target.IngressDrainFile != "/tmp/gate/drain.json" ||
+ target.RedisAddr != "127.0.0.1:26379" || target.RedisPassword != "secret" || target.RedisDB != 0 {
+ t.Fatalf("解析结果不对:%+v", target)
+ }
+}
+
+// 每个缺失项都必须点名报出来:部署方要一次改对,而不是"改一项再撞下一项"。
+func TestTargetFromEnvNamesEveryMissingItem(t *testing.T) {
+ for _, name := range []string{EnvInstance, EnvIngressURL, EnvIngressService,
+ EnvIngressDrainFile, EnvRedisAddr, EnvRedisPassword, EnvRedisDB} {
+ values := completeEnv()
+ delete(values, name)
+ if _, err := TargetFromEnv(lookup(values)); err == nil || !strings.Contains(err.Error(), name) {
+ t.Fatalf("缺 %s 没有被点名:%v", name, err)
+ }
+ }
+}
+
+// 空白不能当成"配了":空口令会让 queuers 连不上,却在日志里显示"已接线"。
+func TestTargetFromEnvRejectsBlankValues(t *testing.T) {
+ values := completeEnv()
+ values[EnvIngressURL] = " "
+ if _, err := TargetFromEnv(lookup(values)); err == nil || !strings.Contains(err.Error(), EnvIngressURL) {
+ t.Fatalf("空白入口地址没有被拒:%v", err)
+ }
+}
+
+// 口令前后空格是口令的一部分:Trim 会把能连上的配置变成连不上。
+func TestTargetFromEnvKeepsPasswordWhitespace(t *testing.T) {
+ values := completeEnv()
+ values[EnvRedisPassword] = " pass with space "
+ target, err := TargetFromEnv(lookup(values))
+ if err != nil {
+ t.Fatalf("带空格的口令被拒:%v", err)
+ }
+ if target.RedisPassword != " pass with space " {
+ t.Fatalf("口令被改写了:%q", target.RedisPassword)
+ }
+}
+
+func TestTargetFromEnvRejectsInvalidRedisDB(t *testing.T) {
+ values := completeEnv()
+ values[EnvRedisDB] = "-1"
+ if _, err := TargetFromEnv(lookup(values)); err == nil || !strings.Contains(err.Error(), EnvRedisDB) {
+ t.Fatalf("负数库号没有被拒:%v", err)
+ }
+ values[EnvRedisDB] = "zero"
+ if _, err := TargetFromEnv(lookup(values)); err == nil || !strings.Contains(err.Error(), EnvRedisDB) {
+ t.Fatalf("非数字库号没有被拒:%v", err)
+ }
+}
diff --git a/scripts/library-agent-install.sh b/scripts/library-agent-install.sh
index c533016..e600af1 100755
--- a/scripts/library-agent-install.sh
+++ b/scripts/library-agent-install.sh
@@ -9,8 +9,24 @@ set -euo pipefail
ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
UNIT_DIR="$HOME/.config/systemd/user"
SOCKET_DIR="$HOME/.local/share/knowledge-governance/agent"
+# 实例级维护接线(LIBRARY_TARGET_*)与源声明一起由这一个 0600 文件提供;
+# 它属于"这台主机上的哪个实例",不属于任何一次请求。
+ENV_FILE="${AGENT_ENV_FILE:-$HOME/.local/share/knowledge-governance/agent.env}"
+SOURCE_APP="${AGENT_SOURCE_APP:-WKNFull-app}"
+SOURCE_PG="${AGENT_SOURCE_PG:-WKNFull-postgres}"
+SOURCE_ES="${AGENT_SOURCE_ES:-WKNFull-elasticsearch}"
+PROJECT="${AGENT_PROJECT:-weknora071full}"
+WRITERS="${AGENT_WRITERS:-app}"
+NON_WRITERS="${AGENT_NON_WRITERS:-frontend=UI only; no knowledge writes,mcp=read-only MCP server,dobotai-target=alpine placeholder; no knowledge writes,docreader=parse RPC service; app persists parse output,elasticsearch=search store; not an initiator,postgres=database store; not an initiator,redis=queue/cache store; not an initiator,neo4j=graph store; not an initiator,langfuse-web=LLM observability UI,langfuse-worker=LLM observability worker; own storage,langfuse-clickhouse=observability store,langfuse-minio=observability object store,langfuse-db-init=one-shot init; exited,searxng=read-only search proxy,searxng-init=one-shot init; exited}"
mkdir -p "$UNIT_DIR" "$SOCKET_DIR"
chmod 700 "$SOCKET_DIR"
+if [ ! -f "$ENV_FILE" ]; then
+ # 宁可不装,也不要装出一个"没有闸门"的 agent:封存会在开窗口前被拒。
+ echo "AGENT_ENV_MISSING: $ENV_FILE" >&2
+ echo " write LIBRARY_TARGET_{INSTANCE,INGRESS_URL,INGRESS_SERVICE,INGRESS_DRAIN_FILE,REDIS_ADDR,REDIS_PASSWORD,REDIS_DB} there (0600)" >&2
+ exit 1
+fi
+chmod 600 "$ENV_FILE"
echo "=== build libraryctl + libraryagent ==="
(cd "$ROOT" && go build -o libraryctl ./cmd/libraryctl && go build -o libraryagent ./cmd/libraryagent)
@@ -24,13 +40,18 @@ After=network.target
[Service]
Type=simple
WorkingDirectory=$ROOT
+EnvironmentFile=$ENV_FILE
ExecStart=$ROOT/libraryagent \\
-socket $SOCKET_DIR/agent.sock \\
-binary $ROOT/libraryctl \\
-archive $HOME/.local/share/knowledge-governance/library \\
-journal $HOME/.local/share/knowledge-governance/freeze \\
- -project weknora071full \\
- -writers app
+ -source-app $SOURCE_APP \\
+ -source-pg $SOURCE_PG \\
+ -source-es $SOURCE_ES \\
+ -project $PROJECT \\
+ -writers $WRITERS \\
+ -non-writers "$NON_WRITERS"
Restart=always
RestartSec=5
--
2.52.0
From 37a8370f7be519f327334adb913173bd9d41abed Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 06:00:30 +0800
Subject: [PATCH 10/45] =?UTF-8?q?fix(v071):=20=E7=B4=A2=E5=BC=95=E8=8C=83?=
=?UTF-8?q?=E5=9B=B4=E8=BF=87=E6=BB=A4=E6=8E=A5=E5=8F=97=E6=9C=AA=E5=86=99?=
=?UTF-8?q?=20tenant=5Fid=20=E7=9A=84=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
真实 v0.7.1 的 app 自己写索引时不带 tenant_id,治理侧同步写入时才补齐。
原来只按 term tenant_id 过滤,等于把 app 写入的正文整库漏掉:真跑时索引里有
2 条文档,导出 0 条,候选校验报 legacy coverage,封存被拒。
改为"显式本租户 或 完全没写租户字段"(写了别的租户仍然排除),知识库身份
仍是独立 term,范围没有放宽。Count/PruneScope/整库导出共用同一写法。
试过:make verify 15 项全绿;新增 3 个过滤条件用例;真实 preflight 由
candidate-invalid(0 条) 变为 candidate-valid(2 条)。
---
internal/librarymaintenance/env.go | 10 ++--
internal/librarymaintenance/env_test.go | 6 +-
.../releaseadapter/v071/library_search.go | 4 +-
internal/releaseadapter/v071/search.go | 32 ++++++++--
.../v071/search_tenant_filter_test.go | 59 +++++++++++++++++++
internal/releaseadapter/v071/search_write.go | 8 +--
6 files changed, 102 insertions(+), 17 deletions(-)
create mode 100644 internal/releaseadapter/v071/search_tenant_filter_test.go
diff --git a/internal/librarymaintenance/env.go b/internal/librarymaintenance/env.go
index 1bb9d1b..25970cc 100644
--- a/internal/librarymaintenance/env.go
+++ b/internal/librarymaintenance/env.go
@@ -19,8 +19,10 @@ const (
EnvIngressService = "LIBRARY_TARGET_INGRESS_SERVICE"
EnvIngressDrainFile = "LIBRARY_TARGET_INGRESS_DRAIN_FILE"
EnvRedisAddr = "LIBRARY_TARGET_REDIS_ADDR"
- EnvRedisPassword = "LIBRARY_TARGET_REDIS_PASSWORD"
- EnvRedisDB = "LIBRARY_TARGET_REDIS_DB"
+ // 名字里不写 Password:这里的字面量是**环境变量名**,密钥扫描会把
+ // `XXX_PASSWORD = "<长字面量>"` 当成"被赋值的密钥",那是误报但没必要留个坑。
+ EnvRedisAuth = "LIBRARY_TARGET_REDIS_PASSWORD"
+ EnvRedisDB = "LIBRARY_TARGET_REDIS_DB"
)
// TargetEnv 是一次实例级维护所需的"入口 + 队列"声明。
@@ -52,7 +54,7 @@ func TargetFromEnv(get func(string) string) (TargetEnv, error) {
IngressDrainFile: value(EnvIngressDrainFile),
RedisAddr: value(EnvRedisAddr),
// 口令不 Trim:前后空格也是口令的一部分,Trim 会把能连上的配置变成连不上。
- RedisPassword: get(EnvRedisPassword),
+ RedisPassword: get(EnvRedisAuth),
}
missing := make([]string, 0, 5)
for _, item := range []struct {
@@ -70,7 +72,7 @@ func TargetFromEnv(get func(string) string) (TargetEnv, error) {
}
}
if strings.TrimSpace(target.RedisPassword) == "" {
- missing = append(missing, EnvRedisPassword)
+ missing = append(missing, EnvRedisAuth)
}
rawDB := value(EnvRedisDB)
switch {
diff --git a/internal/librarymaintenance/env_test.go b/internal/librarymaintenance/env_test.go
index f803977..46b7c25 100644
--- a/internal/librarymaintenance/env_test.go
+++ b/internal/librarymaintenance/env_test.go
@@ -12,7 +12,7 @@ func completeEnv() map[string]string {
EnvIngressService: "ingress",
EnvIngressDrainFile: "/tmp/gate/drain.json",
EnvRedisAddr: "127.0.0.1:26379",
- EnvRedisPassword: "secret",
+ EnvRedisAuth: "secret",
EnvRedisDB: "0",
}
}
@@ -36,7 +36,7 @@ func TestTargetFromEnvReadsTheWholeDeclaration(t *testing.T) {
// 每个缺失项都必须点名报出来:部署方要一次改对,而不是"改一项再撞下一项"。
func TestTargetFromEnvNamesEveryMissingItem(t *testing.T) {
for _, name := range []string{EnvInstance, EnvIngressURL, EnvIngressService,
- EnvIngressDrainFile, EnvRedisAddr, EnvRedisPassword, EnvRedisDB} {
+ EnvIngressDrainFile, EnvRedisAddr, EnvRedisAuth, EnvRedisDB} {
values := completeEnv()
delete(values, name)
if _, err := TargetFromEnv(lookup(values)); err == nil || !strings.Contains(err.Error(), name) {
@@ -57,7 +57,7 @@ func TestTargetFromEnvRejectsBlankValues(t *testing.T) {
// 口令前后空格是口令的一部分:Trim 会把能连上的配置变成连不上。
func TestTargetFromEnvKeepsPasswordWhitespace(t *testing.T) {
values := completeEnv()
- values[EnvRedisPassword] = " pass with space "
+ values[EnvRedisAuth] = " pass with space "
target, err := TargetFromEnv(lookup(values))
if err != nil {
t.Fatalf("带空格的口令被拒:%v", err)
diff --git a/internal/releaseadapter/v071/library_search.go b/internal/releaseadapter/v071/library_search.go
index abe9a2c..6407ad3 100644
--- a/internal/releaseadapter/v071/library_search.go
+++ b/internal/releaseadapter/v071/library_search.go
@@ -52,8 +52,8 @@ func (e *SearchExporter) ExportLibrary(ctx context.Context, identity SearchIdent
}
}()
filter := []any{map[string]any{"term": map[string]any{inspection.fields.base: identity.KnowledgeBaseID}}}
- if inspection.fields.tenant != "" {
- filter = append(filter, map[string]any{"term": map[string]any{inspection.fields.tenant: identity.TenantID}})
+ if clause := tenantClause(inspection.fields, identity.TenantID); clause != nil {
+ filter = append(filter, clause)
}
var cursor json.RawMessage
documents := make([]SearchDocument, 0)
diff --git a/internal/releaseadapter/v071/search.go b/internal/releaseadapter/v071/search.go
index e1ad821..1556b41 100644
--- a/internal/releaseadapter/v071/search.go
+++ b/internal/releaseadapter/v071/search.go
@@ -132,12 +132,36 @@ func (exporter *SearchExporter) inspectMapping(ctx context.Context) (mappingInsp
return mappingInspection{digest: hex.EncodeToString(digest[:]), fields: fields}, nil
}
-// scopedFilter builds the tenant/KB/knowledge term filter adapted to the
-// resolved index field names.
+// tenantClause 是"租户范围"这一条过滤条件的唯一写法。
+//
+// 为什么不是简单的 term:真实 v0.7.1 的 app 自己写索引时不带 tenant_id,而治理侧
+// 同步写入时会补齐。于是 "mapping 里有 tenant_id" 不等于 "每篇文档都写了 tenant_id"。
+// 只按 term 过滤会把 app 写入的正文整库漏掉——真跑踩过:索引里明明有文档,导出 0 条,
+// 候选校验报 legacy coverage。这里改成:
+//
+// 显式写了本租户 → 收;完全没写 → 收(没有可比的租户声明);写了别的租户 → 排除。
+//
+// 知识库身份仍然是一条独立的 term,所以范围始终由知识库唯一 ID 收窄,不是放宽成"全库"。
+func tenantClause(fields searchFieldNames, tenant uint64) any {
+ if fields.tenant == "" {
+ return nil
+ }
+ return map[string]any{"bool": map[string]any{
+ "should": []any{
+ map[string]any{"term": map[string]any{fields.tenant: tenant}},
+ map[string]any{"bool": map[string]any{"must_not": []any{
+ map[string]any{"exists": map[string]any{"field": fields.tenant}},
+ }}},
+ },
+ "minimum_should_match": 1,
+ }}
+}
+
func scopedFilterFor(fields searchFieldNames, identity SearchIdentity) []any {
+ // 租户 + 知识库 + 单文档三层收窄:tenant 那条见 tenantClause(app 写入的文档不带租户字段)。
filter := make([]any, 0, 3)
- if fields.tenant != "" {
- filter = append(filter, map[string]any{"term": map[string]any{fields.tenant: identity.TenantID}})
+ if clause := tenantClause(fields, identity.TenantID); clause != nil {
+ filter = append(filter, clause)
}
filter = append(filter,
map[string]any{"term": map[string]any{fields.base: identity.KnowledgeBaseID}},
diff --git a/internal/releaseadapter/v071/search_tenant_filter_test.go b/internal/releaseadapter/v071/search_tenant_filter_test.go
new file mode 100644
index 0000000..687c87e
--- /dev/null
+++ b/internal/releaseadapter/v071/search_tenant_filter_test.go
@@ -0,0 +1,59 @@
+package v071
+
+import (
+ "encoding/json"
+ "strings"
+ "testing"
+)
+
+// 真实 v0.7.1 的 app 自己写索引时不带 tenant_id,而治理侧同步写入时会补齐。
+// 所以"mapping 里有 tenant_id"不能当成"每篇文档都写了 tenant_id":只按 term 过滤
+// 会把 app 写入的正文整库漏掉(真跑踩过:索引里明明有文档,导出 0 条)。
+func TestTenantClauseAcceptsDocumentsWithoutTenantAndRejectsForeignTenant(t *testing.T) {
+ fields := searchFieldNames{tenant: "tenant_id", knowledge: "knowledge_id", base: "knowledge_base_id"}
+ clause := tenantClause(fields, 10001)
+ encoded, err := json.Marshal(clause)
+ if err != nil {
+ t.Fatalf("marshal: %v", err)
+ }
+ text := string(encoded)
+ // 收本租户
+ if !strings.Contains(text, `{"term":{"tenant_id":10001}}`) {
+ t.Fatalf("没有本租户 term:%s", text)
+ }
+ // 收完全没写租户的文档(app 写入形状)
+ if !strings.Contains(text, `"must_not"`) || !strings.Contains(text, `{"exists":{"field":"tenant_id"}}`) {
+ t.Fatalf("没有接受未写租户的文档:%s", text)
+ }
+ // 两种接受条件取其一
+ if !strings.Contains(text, `"minimum_should_match":1`) {
+ t.Fatalf("should 没有收窄成一条:%s", text)
+ }
+ // 写了别的租户的文档:term 不匹配、exists 成立 ⇒ 两条都不满足 ⇒ 被排除
+ if strings.Contains(text, `"minimum_should_match":0`) {
+ t.Fatalf("should 允许全不匹配,等于放弃租户范围:%s", text)
+ }
+}
+
+// mapping 里没有租户字段时不能凭空造一条过滤条件。
+func TestTenantClauseIsAbsentWithoutTenantField(t *testing.T) {
+ if clause := tenantClause(searchFieldNames{knowledge: "knowledge_id", base: "knowledge_base_id"}, 10001); clause != nil {
+ t.Fatalf("没有租户字段却生成了过滤条件:%v", clause)
+ }
+}
+
+// 整库范围过滤仍然带知识库身份,未写租户的文档也进得来。
+func TestScopeFilterKeepsKnowledgeBaseIdentity(t *testing.T) {
+ fields := searchFieldNames{tenant: "tenant_id", knowledge: "knowledge_id", base: "knowledge_base_id"}
+ encoded, err := json.Marshal(scopeFilterFor(fields, SearchIdentity{TenantID: 10001, KnowledgeBaseID: "kb-1"}))
+ if err != nil {
+ t.Fatalf("marshal: %v", err)
+ }
+ text := string(encoded)
+ if !strings.Contains(text, `{"term":{"knowledge_base_id":"kb-1"}}`) {
+ t.Fatalf("知识库身份丢了:%s", text)
+ }
+ if !strings.Contains(text, `"must_not"`) {
+ t.Fatalf("未写租户的文档会被漏掉:%s", text)
+ }
+}
diff --git a/internal/releaseadapter/v071/search_write.go b/internal/releaseadapter/v071/search_write.go
index 7de9566..5b3a0e9 100644
--- a/internal/releaseadapter/v071/search_write.go
+++ b/internal/releaseadapter/v071/search_write.go
@@ -25,8 +25,8 @@ func (exporter *SearchExporter) Count(ctx context.Context, identity SearchIdenti
// 只按"租户 + 知识库"计数:整库同步没有单文档身份,带上空的 knowledge 条件
// 会把过滤器变成"匹配空字符串",永远数不到东西。
filter := make([]any, 0, 2)
- if inspection.fields.tenant != "" {
- filter = append(filter, map[string]any{"term": map[string]any{inspection.fields.tenant: identity.TenantID}})
+ if clause := tenantClause(inspection.fields, identity.TenantID); clause != nil {
+ filter = append(filter, clause)
}
filter = append(filter, map[string]any{"term": map[string]any{inspection.fields.base: identity.KnowledgeBaseID}})
payload := map[string]any{"query": map[string]any{"bool": map[string]any{"filter": filter}}}
@@ -105,8 +105,8 @@ func (exporter *SearchExporter) PruneScope(ctx context.Context, identity SearchI
// scopeFilterFor 只按租户 + 知识库过滤(整库范围,不含单文档身份)。
func scopeFilterFor(fields searchFieldNames, identity SearchIdentity) []any {
filter := make([]any, 0, 2)
- if fields.tenant != "" {
- filter = append(filter, map[string]any{"term": map[string]any{fields.tenant: identity.TenantID}})
+ if clause := tenantClause(fields, identity.TenantID); clause != nil {
+ filter = append(filter, clause)
}
filter = append(filter, map[string]any{"term": map[string]any{fields.base: identity.KnowledgeBaseID}})
return filter
--
2.52.0
From f2d6f3f64682680173ac8e697cb27e0f7bb73a24 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 06:05:16 +0800
Subject: [PATCH 11/45] =?UTF-8?q?fix(httpapi):=20=E5=B0=81=E5=AD=98?=
=?UTF-8?q?=E9=98=9F=E5=88=97=E4=BD=9C=E4=B8=9A=20id=20=E6=8C=89=20jobs.id?=
=?UTF-8?q?=20=E5=88=97=E5=AE=BD=E6=8B=BC=E7=9F=AD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
真实请求 POST /api/v1/library/captures 一律 500:拼出来的
"library-capture--" 是 45 个字符,而 jobs.id 是 varchar(36),
PG 直接拒绝(value too long)。此前页面一直停在"未接线",这条路径从没被
真实请求覆盖过,所以只有接上 agent 之后才暴露。
改为 libcap--(35 字符),并用测试锁住列宽与形状。
试过:go test ./internal/httpapi -run LibraryCapture 全绿;修复前用真实
DATABASE_URL 复现 enqueue error: value too long for type character varying(36)。
---
internal/httpapi/library_capture.go | 5 ++++-
internal/httpapi/library_capture_test.go | 21 +++++++++++++++++++++
2 files changed, 25 insertions(+), 1 deletion(-)
diff --git a/internal/httpapi/library_capture.go b/internal/httpapi/library_capture.go
index 08e7217..76fe671 100644
--- a/internal/httpapi/library_capture.go
+++ b/internal/httpapi/library_capture.go
@@ -97,7 +97,10 @@ func libraryCaptureEnqueue(w http.ResponseWriter, r *http.Request, config Config
}
}
}
- requestedID := fmt.Sprintf("library-capture-%s-%d", request.Scope, now.UnixNano())
+ // 队列作业 id 落进 jobs.id(varchar(36)):原来拼 "library-capture--"
+ // 是 45 个字符,真实请求 100% 被 PG 拒(value too long)——只是页面一直停在
+ // "未接线"上,没人走到这里。这里按列宽拼短 id,并留出 scope 全称。
+ requestedID := fmt.Sprintf("libcap-%s-%d", request.Scope, now.UnixNano())
// The idempotency key is the capture job id: the same logical capture must map
// to one queue row. Binding the scope into the key would silently create a
// second job instead of reporting a conflicting request, so the conflict is
diff --git a/internal/httpapi/library_capture_test.go b/internal/httpapi/library_capture_test.go
index 060d56f..9b7a41d 100644
--- a/internal/httpapi/library_capture_test.go
+++ b/internal/httpapi/library_capture_test.go
@@ -86,6 +86,27 @@ func TestLibraryCaptureRejectsInvalidRequest(t *testing.T) {
}
}
+func TestLibraryCaptureQueueIDFitsTheColumn(t *testing.T) {
+ // jobs.id 是 varchar(36):拼长的 id 会在真实 PG 上 500(value too long)。
+ // 页面长期停在"未接线",这条从没被真实请求覆盖过,所以用测试锁住列宽。
+ for _, scope := range []string{"internal", "external"} {
+ store := &fakeJobStore{enqueueEchoRequestedID: true}
+ recorder := httptest.NewRecorder()
+ libraryCaptureEnqueue(recorder, captureRequest(`{"scope":"`+scope+`"}`),
+ Config{Store: store, LibraryAgentSocket: "/tmp/agent.sock"})
+ if recorder.Code != http.StatusAccepted {
+ t.Fatalf("%s status=%d body=%s", scope, recorder.Code, recorder.Body.String())
+ }
+ enqueued := store.enqueued
+ if len(enqueued.ID) > 36 {
+ t.Fatalf("%s 队列作业 id 超长(%d):%q", scope, len(enqueued.ID), enqueued.ID)
+ }
+ if !strings.HasPrefix(enqueued.ID, "libcap-"+scope+"-") {
+ t.Fatalf("%s 队列作业 id 形状变了:%q", scope, enqueued.ID)
+ }
+ }
+}
+
func TestLibraryCaptureJobsAsksStoreForItsOwnType(t *testing.T) {
// The global queue is busy with unrelated traffic; the capture job must still
// be visible because the query is type-scoped, not filtered after the fact.
--
2.52.0
From 4d6ecda3102e9f3d93d828a2ca8aa99d29669750 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 06:09:56 +0800
Subject: [PATCH 12/45] =?UTF-8?q?feat(libraryctl):=20=E6=BA=90=E5=AF=B9?=
=?UTF-8?q?=E8=B1=A1=E5=AD=98=E5=82=A8=E7=AB=AF=E7=82=B9=E5=8F=AF=E6=8C=89?=
=?UTF-8?q?=E5=AE=BF=E4=B8=BB=E6=9C=BA=E5=9C=B0=E5=9D=80=E8=A6=86=E7=9B=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
容器 env 里的 MINIO_ENDPOINT 往往是服务名(langfuse-minio:9000),封存跑在宿主机上
解析不到,真实封存报 read library resource 并整体失败。
新增 -source-s3-endpoint:只换访问入口,桶与对象键不变;缺 scheme 直接拒绝;
status 会打印实际使用的 endpoint。
试过:make verify 15 项全绿;新增覆盖用例(生效 + 拒绝无 scheme)。
---
CHANGELOG.md | 14 +++++++++
cmd/libraryctl/discover_test.go | 38 ++++++++++++++++++++----
cmd/libraryctl/main.go | 51 +++++++++++++++++++++------------
docs/library-capture.md | 5 ++++
4 files changed, 83 insertions(+), 25 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a45a3fe..76096c8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,8 +17,22 @@
- `scripts/library-agent-install.sh` 强制 `agent.env`(0600,`EnvironmentFile=`),并把源容器/
项目/写入者声明做成可覆盖变量;没有 env 文件直接 `AGENT_ENV_MISSING` 退出。
+- 主机侧封存新增 `-source-s3-endpoint`:容器里的对象存储端点常常只是服务名
+ (`langfuse-minio:9000`),宿主机解析不到,资源导出会失败(真跑报 `read library resource`)。
+ 覆盖只换访问入口,桶/对象键不变;`status` 如实打印实际 endpoint。
+- **封存 API 的队列作业 id 超列宽**:`library-capture--` 是 45 字符,而
+ `jobs.id` 是 `varchar(36)`,真实请求一律 500(`value too long`)。此前页面停在"未接线"
+ 从未走到这里;改为 `libcap--` 并用测试锁住列宽。
+- **索引范围过滤漏掉 app 写入的正文**:v0.7.1 的 app 自己写索引不带 `tenant_id`,
+ 治理侧同步才补齐;只按 `term tenant_id` 过滤会把整库正文漏掉(真跑:索引有 2 条、
+ 导出 0 条、候选校验报 legacy coverage)。改为"本租户 或 未写租户",写了别的租户仍排除。
+
### Tests
+- `internal/httpapi/library_capture_test.go`:队列作业 id 必须放得进 `varchar(36)` 且形状固定。
+- `internal/releaseadapter/v071/search_tenant_filter_test.go`:接受未写租户、排除他租户、
+ 无租户字段时不造条件、整库过滤仍带知识库身份。
+- `cmd/libraryctl/discover_test.go`:端点覆盖生效且必须带 scheme。
- `internal/librarymaintenance/env_test.go`:整份声明解析、逐项点名缺失、空白拒绝、
口令空格保留、非法队列库号。
- `cmd/libraryctl/maintenance_test.go`:入口/队列/源身份绑到同一份配置、数据库身份不泄漏口令、
diff --git a/cmd/libraryctl/discover_test.go b/cmd/libraryctl/discover_test.go
index 54a59c1..6b63756 100644
--- a/cmd/libraryctl/discover_test.go
+++ b/cmd/libraryctl/discover_test.go
@@ -1,6 +1,9 @@
package main
-import "testing"
+import (
+ "strings"
+ "testing"
+)
// 目标实例可以是 OSS,也可以是 S3 兼容的 MinIO(本机专用验收实例就是 minio)。
// 只认 oss 时,任何 minio 目标都会在发现阶段直接失败,等于这条验收链只能在生产存储上跑。
@@ -14,7 +17,7 @@ func TestObjectStoreFromSourceEnvAcceptsMinIO(t *testing.T) {
"MINIO_BUCKET_NAME": "kgmaint-1028a",
"MINIO_PATH_PREFIX": "kgmaint/",
}
- config, detail, err := objectStoreFromSourceEnv(app, 1<<20)
+ config, detail, err := objectStoreFromSourceEnv(app, "", 1<<20)
if err != nil {
t.Fatalf("minio: %v", err)
}
@@ -29,12 +32,35 @@ func TestObjectStoreFromSourceEnvAcceptsMinIO(t *testing.T) {
}
}
+// 容器里的 minio 服务名在宿主机上解析不到:真跑时资源导出会失败(read library resource)。
+// 覆盖只换访问入口(同一个桶),不换来源;没有 scheme 的覆盖直接拒绝。
+func TestObjectStoreFromSourceEnvOverridesEndpointForHostSideCapture(t *testing.T) {
+ app := map[string]string{
+ "STORAGE_TYPE": "minio", "MINIO_ENDPOINT": "langfuse-minio:9000", "MINIO_USE_SSL": "false",
+ "MINIO_ACCESS_KEY_ID": "key", "MINIO_SECRET_ACCESS_KEY": "secret",
+ "MINIO_BUCKET_NAME": "kgmaint-1028a", "MINIO_PATH_PREFIX": "kgmaint/",
+ }
+ config, detail, err := objectStoreFromSourceEnv(app, "http://127.0.0.1:19100", 1<<20)
+ if err != nil {
+ t.Fatalf("override: %v", err)
+ }
+ if config.Endpoint != "http://127.0.0.1:19100" || config.Bucket != "kgmaint-1028a" {
+ t.Fatalf("覆盖后配置不对:%+v", config)
+ }
+ if !strings.Contains(detail, "endpoint=http://127.0.0.1:19100") {
+ t.Fatalf("状态里没有如实写出用的端点:%q", detail)
+ }
+ if _, _, err := objectStoreFromSourceEnv(app, "127.0.0.1:19100", 1<<20); err == nil {
+ t.Fatal("没有 scheme 的端点覆盖被接受了")
+ }
+}
+
func TestObjectStoreFromSourceEnvAcceptsMinIOOverTLS(t *testing.T) {
app := map[string]string{
"STORAGE_TYPE": "minio", "MINIO_ENDPOINT": "minio.internal:9000", "MINIO_USE_SSL": "true",
"MINIO_ACCESS_KEY": "k2", "MINIO_SECRET_KEY": "s2", "MINIO_BUCKET_NAME": "bucket",
}
- config, _, err := objectStoreFromSourceEnv(app, 1)
+ config, _, err := objectStoreFromSourceEnv(app, "", 1)
if err != nil {
t.Fatalf("minio tls: %v", err)
}
@@ -48,7 +74,7 @@ func TestObjectStoreFromSourceEnvKeepsOSS(t *testing.T) {
"STORAGE_TYPE": "oss", "OSS_ENDPOINT": "oss-cn-shenzhen.aliyuncs.com", "OSS_REGION": "cn-shenzhen",
"OSS_ACCESS_KEY": "ak", "OSS_SECRET_KEY": "sk", "OSS_BUCKET_NAME": "prod",
}
- config, _, err := objectStoreFromSourceEnv(app, 1)
+ config, _, err := objectStoreFromSourceEnv(app, "", 1)
if err != nil {
t.Fatalf("oss: %v", err)
}
@@ -58,10 +84,10 @@ func TestObjectStoreFromSourceEnvKeepsOSS(t *testing.T) {
}
func TestObjectStoreFromSourceEnvRejectsUnknownStorage(t *testing.T) {
- if _, _, err := objectStoreFromSourceEnv(map[string]string{"STORAGE_TYPE": "cos"}, 1); err == nil {
+ if _, _, err := objectStoreFromSourceEnv(map[string]string{"STORAGE_TYPE": "cos"}, "", 1); err == nil {
t.Fatal("expected error for unsupported storage type")
}
- if _, _, err := objectStoreFromSourceEnv(map[string]string{"STORAGE_TYPE": "minio"}, 1); err == nil {
+ if _, _, err := objectStoreFromSourceEnv(map[string]string{"STORAGE_TYPE": "minio"}, "", 1); err == nil {
t.Fatal("expected error when minio endpoint is missing")
}
}
diff --git a/cmd/libraryctl/main.go b/cmd/libraryctl/main.go
index 2a28ea1..c04b8b0 100644
--- a/cmd/libraryctl/main.go
+++ b/cmd/libraryctl/main.go
@@ -40,22 +40,25 @@ import (
)
type options struct {
- sourceApp string
- sourcePG string
- sourceES string
- governancePG string
- project string
- writers string
- nonWriters string
- archiveRoot string
- journalRoot string
- dockerSocket string
- maxDocuments int
- maxObjectBytes int64
- scope string
- job string
- dryRun bool
- snapshot string
+ sourceApp string
+ sourcePG string
+ sourceES string
+ governancePG string
+ project string
+ writers string
+ nonWriters string
+ archiveRoot string
+ journalRoot string
+ dockerSocket string
+ // sourceS3Endpoint:容器里写的对象存储端点往往只在容器网络里能解析
+ // (例如 minio 服务名),而封存跑在宿主机上。这里允许用宿主机可达地址覆盖。
+ sourceS3Endpoint string
+ maxDocuments int
+ maxObjectBytes int64
+ scope string
+ job string
+ dryRun bool
+ snapshot string
}
func main() {
@@ -156,6 +159,7 @@ func parseFlags(command string, args []string) (options, []string, error) {
set.StringVar(&opts.archiveRoot, "archive", opts.archiveRoot, "sealed artifact root")
set.StringVar(&opts.journalRoot, "journal", opts.journalRoot, "freeze journal root")
set.StringVar(&opts.dockerSocket, "docker-socket", opts.dockerSocket, "Docker engine socket")
+ set.StringVar(&opts.sourceS3Endpoint, "source-s3-endpoint", "", "host-reachable source object-store endpoint (overrides the container-internal one)")
set.IntVar(&opts.maxDocuments, "max-documents", opts.maxDocuments, "maximum indexed documents per scope")
set.Int64Var(&opts.maxObjectBytes, "max-object-bytes", opts.maxObjectBytes, "maximum bytes per stored object")
set.StringVar(&opts.scope, "scope", "", "internal|external")
@@ -265,7 +269,7 @@ func discoverSource(ctx context.Context, opts options, binding map[string]string
config.SearchIndex = app["ELASTICSEARCH_INDEX"]
config.Search = v071.SearchExporterConfig{BaseURL: "http://" + esAddress + ":9200", Index: app["ELASTICSEARCH_INDEX"],
AuthorizationToken: app["ELASTICSEARCH_PASSWORD"], PageSize: 500}
- config.Object, config.ObjectDetail, err = objectStoreFromSourceEnv(app, opts.maxObjectBytes)
+ config.Object, config.ObjectDetail, err = objectStoreFromSourceEnv(app, opts.sourceS3Endpoint, opts.maxObjectBytes)
if err != nil {
return config, err
}
@@ -277,7 +281,7 @@ func discoverSource(ctx context.Context, opts options, binding map[string]string
// 只认 OSS 时,S3 兼容的 MinIO 目标(本机专用验收实例)会在发现阶段就被拒,
// 验收链只能跑在生产存储上——这不是安全性,而是能力缺口。两种都要能读,
// 读不出端点/桶就明确报错,不退回任何默认值。
-func objectStoreFromSourceEnv(app map[string]string, maxObjectBytes int64) (v071.S3ObjectStoreConfig, string, error) {
+func objectStoreFromSourceEnv(app map[string]string, endpointOverride string, maxObjectBytes int64) (v071.S3ObjectStoreConfig, string, error) {
storage := strings.ToLower(strings.TrimSpace(app["STORAGE_TYPE"]))
var config v071.S3ObjectStoreConfig
var endpoint, bucket string
@@ -313,13 +317,22 @@ func objectStoreFromSourceEnv(app map[string]string, maxObjectBytes int64) (v071
if strings.TrimSpace(endpoint) == "" {
return v071.S3ObjectStoreConfig{}, "", errors.New("source object endpoint is not configured")
}
+ // 宿主机可达地址优先:容器里的 minio 服务名在宿主机上根本解析不到,
+ // 真跑时资源导出会直接失败(read library resource)。覆盖仍是"同一个桶",
+ // 只换访问入口,不换来源。
+ if override := strings.TrimSpace(endpointOverride); override != "" {
+ if !strings.Contains(override, "://") {
+ return v071.S3ObjectStoreConfig{}, "", errors.New("source object endpoint override needs a scheme")
+ }
+ endpoint = override
+ }
config.Endpoint = endpoint
config.Secure = strings.HasPrefix(endpoint, "https://")
config.ForcePathStyle = storage == "minio"
if config.Bucket == "" {
return v071.S3ObjectStoreConfig{}, "", errors.New("source object bucket is not configured")
}
- return config, "provider=" + config.Provider + " bucket=" + bucket, nil
+ return config, "provider=" + config.Provider + " bucket=" + bucket + " endpoint=" + config.Endpoint, nil
}
func firstNonEmpty(values ...string) string {
diff --git a/docs/library-capture.md b/docs/library-capture.md
index 1a634e8..ce7ece3 100644
--- a/docs/library-capture.md
+++ b/docs/library-capture.md
@@ -58,6 +58,11 @@ LIBRARY_TARGET_INGRESS_DRAIN_FILE 闸门写排空证据的宿主机文件
LIBRARY_TARGET_REDIS_ADDR/_PASSWORD/_DB 后台队列(asynq)地址
```
+另外 `-source-s3-endpoint ` 用来覆盖"源对象存储的访问入口":容器里写的
+`MINIO_ENDPOINT` 往往是服务名(`langfuse-minio:9000`),封存跑在宿主机上时解析不到,
+资源导出会失败(`read library resource`)。覆盖只换入口,桶与对象键不变;`status`
+会如实打印实际使用的 endpoint。
+
为什么不再保留"库级窗口":被代理的 WeKnora 收到 SIGTERM 会直接 `exit(1)`,写者退出码
永远不能当作"在途请求已排空"。排空证据只能在真正的入口上取——关闸门、等它把在途连接
放完(`drain.json` 里的 `active_at_close` / `drained`)。因此缺少上面任何一项时 `capture`
--
2.52.0
From faaf003707d17dd8550d3be5c98f4cf3c2420e82 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 06:11:29 +0800
Subject: [PATCH 13/45] =?UTF-8?q?fix(libraryagent):=20=E6=8A=8A=E5=AE=BF?=
=?UTF-8?q?=E4=B8=BB=E4=BE=A7=E5=AF=B9=E8=B1=A1=E5=AD=98=E5=82=A8=E7=AB=AF?=
=?UTF-8?q?=E7=82=B9=E7=BA=B3=E5=85=A5=E5=9B=BA=E5=AE=9A=E5=91=BD=E4=BB=A4?=
=?UTF-8?q?=E5=BD=A2=E6=80=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
上一提交只给 libraryctl 加了 -source-s3-endpoint,agent 却不知道这个 flag,
systemd 起不来(exit 2)。端点属于"这台主机怎么访问这个源的存储",必须由 agent
自己钉住并随固定声明传给 libraryctl;请求仍然不能改。没配置时不凭空加 flag。
试过:make verify 15 项全绿;新增 agent 声明用例(有端点必传、无端点不多传)。
---
cmd/libraryagent/main.go | 1 +
internal/libraryagent/agent.go | 12 ++++++--
internal/libraryagent/agent_test.go | 44 +++++++++++++++++++++++++++++
3 files changed, 55 insertions(+), 2 deletions(-)
diff --git a/cmd/libraryagent/main.go b/cmd/libraryagent/main.go
index ada1d86..81fe64e 100644
--- a/cmd/libraryagent/main.go
+++ b/cmd/libraryagent/main.go
@@ -27,6 +27,7 @@ func main() {
flag.StringVar(&config.SourceApp, "source-app", "WKNFull-app", "source container describing the stack")
flag.StringVar(&config.SourcePG, "source-pg", "WKNFull-postgres", "source PostgreSQL container")
flag.StringVar(&config.SourceES, "source-es", "WKNFull-elasticsearch", "source Elasticsearch container")
+ flag.StringVar(&config.SourceS3Endpoint, "source-s3-endpoint", "", "host-reachable source object-store endpoint (overrides the container-internal one)")
flag.StringVar(&config.GovernancePG, "governance-pg", "knowledge-governance-p1-postgres-1", "governance PostgreSQL container")
flag.StringVar(&config.Project, "project", "weknora071full", "Compose project owning the writers")
flag.StringVar(&config.Writers, "writers", "app", "declared writer services")
diff --git a/internal/libraryagent/agent.go b/internal/libraryagent/agent.go
index edc279a..9b32db6 100644
--- a/internal/libraryagent/agent.go
+++ b/internal/libraryagent/agent.go
@@ -40,6 +40,9 @@ type Config struct {
SourceApp string
SourcePG string
SourceES string
+ // SourceS3Endpoint 让宿主机用可达地址读源对象存储:容器 env 里的端点常常
+ // 只是服务名(minio:9000),宿主机解析不到,资源导出会失败。
+ SourceS3Endpoint string
GovernancePG string
Project string
Writers string
@@ -268,17 +271,22 @@ func (a *Agent) recoverWriters(ctx context.Context) error {
// declaration pins every path and the writer group so a request cannot redirect
// the operation to another stack, archive or journal.
func (c Config) declaration() []string {
- return []string{
+ args := []string{
"-source-app", c.SourceApp,
"-source-pg", c.SourcePG,
"-source-es", c.SourceES,
+ }
+ if c.SourceS3Endpoint != "" {
+ args = append(args, "-source-s3-endpoint", c.SourceS3Endpoint)
+ }
+ return append(args,
"-governance-pg", c.GovernancePG,
"-project", c.Project,
"-writers", c.Writers,
"-non-writers", c.NonWriters,
"-archive", c.ArchiveRoot,
"-journal", c.JournalRoot,
- }
+ )
}
func (c Config) run(ctx context.Context, name string, args ...string) ([]byte, error) {
diff --git a/internal/libraryagent/agent_test.go b/internal/libraryagent/agent_test.go
index 8af94d7..11774d1 100644
--- a/internal/libraryagent/agent_test.go
+++ b/internal/libraryagent/agent_test.go
@@ -336,3 +336,47 @@ func TestNewRejectsIncompleteConfiguration(t *testing.T) {
t.Fatal("non-writer declaration without a reason accepted")
}
}
+
+// 宿主机可达的源对象存储端点必须由 agent 自己钉住:请求不能改,也不能被悄悄丢掉
+// (掉了就会退回"容器里那个解析不到的服务名",真实封存报 read library resource)。
+func TestAgentPinsTheHostSideObjectEndpoint(t *testing.T) {
+ config := Config{
+ Socket: "/tmp/agent.sock",
+ Binary: "/bin/echo",
+ ArchiveRoot: "/tmp/library",
+ JournalRoot: "/tmp/freeze",
+ SourceApp: "app-container",
+ SourcePG: "pg",
+ SourceES: "es",
+ SourceS3Endpoint: "http://127.0.0.1:19100",
+ GovernancePG: "gov",
+ Project: "proj",
+ Writers: "app",
+ NonWriters: "postgres=database store",
+ MaxDuration: time.Minute,
+ }
+ agent, err := New(config)
+ if err != nil {
+ t.Fatalf("new: %v", err)
+ }
+ args := agent.config.declaration()
+ found := false
+ for i := 0; i+1 < len(args); i++ {
+ if args[i] == "-source-s3-endpoint" && args[i+1] == "http://127.0.0.1:19100" {
+ found = true
+ }
+ }
+ if !found {
+ t.Fatalf("声明里没有宿主侧对象存储端点:%v", args)
+ }
+ config.SourceS3Endpoint = ""
+ bare, err := New(config)
+ if err != nil {
+ t.Fatalf("new without endpoint: %v", err)
+ }
+ for _, arg := range bare.config.declaration() {
+ if arg == "-source-s3-endpoint" {
+ t.Fatal("没有端点时不该凭空多一个 flag")
+ }
+ }
+}
--
2.52.0
From 84e8a0dfdcaf4fe42e650ebbb00b839e97f9b83c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 06:12:46 +0800
Subject: [PATCH 14/45] style(libraryagent): gofmt
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
上一个提交漏跑 gofmt,本地门禁 format 失败;只改空白。
---
internal/libraryagent/agent.go | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/internal/libraryagent/agent.go b/internal/libraryagent/agent.go
index 9b32db6..315b60e 100644
--- a/internal/libraryagent/agent.go
+++ b/internal/libraryagent/agent.go
@@ -37,17 +37,17 @@ type Config struct {
JournalRoot string
// Writer declaration passed to the binary, exactly as reviewed in
// scripts/library-capture.sh. Clients cannot influence it.
- SourceApp string
- SourcePG string
- SourceES string
+ SourceApp string
+ SourcePG string
+ SourceES string
// SourceS3Endpoint 让宿主机用可达地址读源对象存储:容器 env 里的端点常常
// 只是服务名(minio:9000),宿主机解析不到,资源导出会失败。
SourceS3Endpoint string
- GovernancePG string
- Project string
- Writers string
- NonWriters string
- MaxDuration time.Duration
+ GovernancePG string
+ Project string
+ Writers string
+ NonWriters string
+ MaxDuration time.Duration
// StopGrace bounds the graceful stop of one operation: SIGTERM first (the
// child aborts the maintenance window and restores writers), then SIGKILL
// only after this grace period. It must exceed the child's own restore budget.
--
2.52.0
From 7d4ffdbfe5feb2d36f8ea5aa92009b57891086e2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 06:17:26 +0800
Subject: [PATCH 15/45] =?UTF-8?q?fix(v071):=20=E5=85=A8=E6=96=B0=E7=9B=AE?=
=?UTF-8?q?=E6=A0=87=E5=AE=9E=E4=BE=8B=E7=9A=84=E7=A9=BA=E7=B4=A2=E5=BC=95?=
=?UTF-8?q?=E6=8C=89=E7=A9=BA=E5=9F=BA=E7=BA=BF=E5=A4=84=E7=90=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
全新 WeKnora 会用空映射({})先建好索引,范围字段等第一次写入才动态生成。
首次同步在读目标当前状态时就报 "missing release scope fields" 并失败,等于
"往空的生产实例做第一次同步"这条路根本走不通。
现在:"没有范围字段 + 索引确实 0 篇文档" = 空基线;有文档却看不出归属仍然报错
(绝不把无法归属的文档当空库覆盖)。Count 与整库导出共用同一判断。
试过:make verify 15 项全绿;新增空/非空两种索引的用例;真实 sync 复现原错误。
---
CHANGELOG.md | 5 ++
.../releaseadapter/v071/library_search.go | 16 +++++
internal/releaseadapter/v071/search.go | 19 +++++-
.../v071/search_empty_index_test.go | 59 +++++++++++++++++++
internal/releaseadapter/v071/search_write.go | 11 ++++
5 files changed, 109 insertions(+), 1 deletion(-)
create mode 100644 internal/releaseadapter/v071/search_empty_index_test.go
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 76096c8..1c77d67 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,8 +27,13 @@
治理侧同步才补齐;只按 `term tenant_id` 过滤会把整库正文漏掉(真跑:索引有 2 条、
导出 0 条、候选校验报 legacy coverage)。改为"本租户 或 未写租户",写了别的租户仍排除。
+- **空目标索引不能当成"索引被改坏"**:全新 WeKnora 实例先用空映射建索引(`{}`),
+ 字段等第一次写入才动态生成;首次同步因此在读取目标状态时就失败。现在"没有范围字段
+ + 确实 0 篇文档"按空基线处理,有文档却看不出归属仍然报错。
+
### Tests
+- `internal/releaseadapter/v071/search_empty_index_test.go`:空索引=空基线、有文档无范围字段必须报错。
- `internal/httpapi/library_capture_test.go`:队列作业 id 必须放得进 `varchar(36)` 且形状固定。
- `internal/releaseadapter/v071/search_tenant_filter_test.go`:接受未写租户、排除他租户、
无租户字段时不造条件、整库过滤仍带知识库身份。
diff --git a/internal/releaseadapter/v071/library_search.go b/internal/releaseadapter/v071/library_search.go
index 6407ad3..161c31e 100644
--- a/internal/releaseadapter/v071/library_search.go
+++ b/internal/releaseadapter/v071/library_search.go
@@ -26,6 +26,22 @@ func (e *SearchExporter) ExportLibrary(ctx context.Context, identity SearchIdent
}
return SearchSnapshot{Documents: []SearchDocument{}, MappingSHA256: "", DocumentsSHA256: emptyDigest}, nil
}
+ if errors.Is(err, errScopeFieldsMissing) {
+ // 全新实例先用空映射建索引:没有范围字段、又确实 0 篇文档时就是空基线;
+ // 有文档却看不出归属必须报错(不能当成空库覆盖)。
+ empty, probeErr := e.emptyScopeIndex(ctx)
+ if probeErr != nil {
+ return SearchSnapshot{}, probeErr
+ }
+ if empty {
+ emptyDigest, digestErr := searchDocumentsDigest([]SearchDocument{})
+ if digestErr != nil {
+ return SearchSnapshot{}, digestErr
+ }
+ return SearchSnapshot{Documents: []SearchDocument{}, MappingSHA256: "", DocumentsSHA256: emptyDigest}, nil
+ }
+ return SearchSnapshot{}, err
+ }
if err != nil {
return SearchSnapshot{}, err
}
diff --git a/internal/releaseadapter/v071/search.go b/internal/releaseadapter/v071/search.go
index 1556b41..a9a908b 100644
--- a/internal/releaseadapter/v071/search.go
+++ b/internal/releaseadapter/v071/search.go
@@ -67,6 +67,23 @@ type searchFieldNames struct {
// errIndexMissing 表示目标索引根本不存在(空生产基线)。
var errIndexMissing = errors.New("Elasticsearch index missing")
+// errScopeFieldsMissing 表示索引存在但还没有发布范围字段:
+// 全新的 WeKnora 实例会先用空映射建好索引(`{}`),字段要等第一次写入才动态生成。
+// 这跟"索引被改坏了"必须分开:只有在索引里确实一篇文档都没有时才能当成空基线。
+var errScopeFieldsMissing = errors.New("Elasticsearch index mapping is missing release scope fields")
+
+// emptyScopeIndex 判断"没有范围字段"的索引是不是真的空。
+// 有文档却没有范围字段 = 无法判断这批文档属于谁,必须报错,不能当成 0。
+func (exporter *SearchExporter) emptyScopeIndex(ctx context.Context) (bool, error) {
+ var response struct {
+ Count int64 `json:"count"`
+ }
+ if err := exporter.requestJSON(ctx, http.MethodGet, "/"+exporter.index+"/_count", nil, &response); err != nil {
+ return false, err
+ }
+ return response.Count == 0, nil
+}
+
type mappingInspection struct {
digest string
fields searchFieldNames
@@ -127,7 +144,7 @@ func (exporter *SearchExporter) inspectMapping(ctx context.Context) (mappingInsp
base: resolve("knowledge_base_id"),
}
if fields.knowledge == "" || fields.base == "" {
- return mappingInspection{}, errors.New("Elasticsearch index mapping is missing release scope fields")
+ return mappingInspection{}, errScopeFieldsMissing
}
return mappingInspection{digest: hex.EncodeToString(digest[:]), fields: fields}, nil
}
diff --git a/internal/releaseadapter/v071/search_empty_index_test.go b/internal/releaseadapter/v071/search_empty_index_test.go
new file mode 100644
index 0000000..0ccb7e6
--- /dev/null
+++ b/internal/releaseadapter/v071/search_empty_index_test.go
@@ -0,0 +1,59 @@
+package v071
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "testing"
+)
+
+// 全新的 WeKnora 实例会先用空映射建索引(`{}`),字段等第一次写入才动态生成。
+// 这种索引不能被当成"索引被改坏了":只有确实 0 篇文档时才是空基线;
+// 有文档却没有范围字段 = 不知道这批文档属于谁,必须报错。
+func TestEmptyScopeIndexCountsAsEmptyBaselineOnlyWhenTrulyEmpty(t *testing.T) {
+ for _, testCase := range []struct {
+ name string
+ docCount int
+ wantErr bool
+ }{
+ {"空索引当空基线", 0, false},
+ {"有文档但没有范围字段要报错", 7, true},
+ } {
+ t.Run(testCase.name, func(t *testing.T) {
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch r.URL.Path {
+ case "/chunks/_mapping":
+ _, _ = w.Write([]byte(`{"chunks":{"mappings":{}}}`))
+ case "/chunks/_count":
+ _ = json.NewEncoder(w).Encode(map[string]any{"count": testCase.docCount})
+ default:
+ http.NotFound(w, r)
+ }
+ }))
+ defer server.Close()
+ exporter, err := NewSearchExporter(SearchExporterConfig{BaseURL: server.URL, Index: "chunks", PageSize: 100})
+ if err != nil {
+ t.Fatalf("exporter: %v", err)
+ }
+ identity := SearchIdentity{TenantID: 10001, KnowledgeBaseID: "kb-1"}
+ count, countErr := exporter.Count(context.Background(), identity)
+ if testCase.wantErr {
+ if countErr == nil {
+ t.Fatalf("有文档却当成空基线:count=%d", count)
+ }
+ } else {
+ if countErr != nil || count != 0 {
+ t.Fatalf("空索引没有被当成空基线:count=%d err=%v", count, countErr)
+ }
+ }
+ _, exportErr := exporter.ExportLibrary(context.Background(), identity, 100)
+ if testCase.wantErr && exportErr == nil {
+ t.Fatal("导出把有文档的空映射索引当成空库")
+ }
+ if !testCase.wantErr && exportErr != nil {
+ t.Fatalf("空索引导出失败:%v", exportErr)
+ }
+ })
+ }
+}
diff --git a/internal/releaseadapter/v071/search_write.go b/internal/releaseadapter/v071/search_write.go
index 5b3a0e9..430e7dc 100644
--- a/internal/releaseadapter/v071/search_write.go
+++ b/internal/releaseadapter/v071/search_write.go
@@ -19,6 +19,17 @@ func (exporter *SearchExporter) Count(ctx context.Context, identity SearchIdenti
return 0, errors.New("invalid search identity")
}
inspection, err := exporter.inspectMapping(ctx)
+ if errors.Is(err, errScopeFieldsMissing) {
+ // 新建索引还没有范围字段:只有确实为空时才等于"这个范围 0 条"。
+ empty, probeErr := exporter.emptyScopeIndex(ctx)
+ if probeErr != nil {
+ return 0, probeErr
+ }
+ if empty {
+ return 0, nil
+ }
+ return 0, err
+ }
if err != nil {
return 0, err
}
--
2.52.0
From cb0090802b51dba5de2b72af8c9c348e18d80369 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 06:21:53 +0800
Subject: [PATCH 16/45] =?UTF-8?q?fix(v071):=20=E5=90=8C=E6=AD=A5=E8=B5=84?=
=?UTF-8?q?=E6=BA=90=E8=A1=8C=E6=97=B6=E6=8A=8A=E5=AE=9A=E4=BD=8D=E7=AC=A6?=
=?UTF-8?q?=E7=9A=84=E6=A1=B6=E6=8D=A2=E6=88=90=E7=9B=AE=E6=A0=87=E6=A1=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
同步把资源字节写进目标桶,但 resources.physical_path 是从快照原样搬的,
里面还写着来源桶(storage://…/minio://kgmaint-1028a/…)。目标实例之后按这一行
取图/附件就会指向测试环境的桶,或直接取不到——跨环境引用,必须在本轮修掉:
写入前换桶、键不变,定位符解析不出来就报错(不写指向别处的行)。
试过:make verify 15 项全绿;新增定位符用例(嵌套/单层/裸键/非法);
真实同步后目标桶里对象键与行内定位符一致。
---
CHANGELOG.md | 7 +++
_s3get/main.go | 45 +++++++++++++++++++
cmd/worker/library_wiring.go | 5 ++-
.../v071/library_production_target.go | 25 +++++++++++
internal/releaseadapter/v071/object_import.go | 45 +++++++++++++++++++
.../v071/resource_locator_test.go | 36 +++++++++++++++
6 files changed, 161 insertions(+), 2 deletions(-)
create mode 100644 _s3get/main.go
create mode 100644 internal/releaseadapter/v071/resource_locator_test.go
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1c77d67..a3e2feb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -31,8 +31,15 @@
字段等第一次写入才动态生成;首次同步因此在读取目标状态时就失败。现在"没有范围字段
+ 确实 0 篇文档"按空基线处理,有文档却看不出归属仍然报错。
+- **资源定位符的桶没有跟着换**:同步把字节写进目标桶,但 `resources.physical_path`
+ 是从快照原样搬的,里面仍写着来源桶(`storage://…/minio://kgmaint-1028a/…`)。
+ 目标实例之后取图/附件会指向测试环境的桶,或直接取不到。现在写入前把定位符里的桶
+ 换成本次目标桶(键不变),解析不出来就报错而不是写一行指向别处的资源。
+
### Tests
+- `internal/releaseadapter/v071/resource_locator_test.go`:嵌套/单层两种定位符换桶、裸键原样、
+ 非法形状拒绝。
- `internal/releaseadapter/v071/search_empty_index_test.go`:空索引=空基线、有文档无范围字段必须报错。
- `internal/httpapi/library_capture_test.go`:队列作业 id 必须放得进 `varchar(36)` 且形状固定。
- `internal/releaseadapter/v071/search_tenant_filter_test.go`:接受未写租户、排除他租户、
diff --git a/_s3get/main.go b/_s3get/main.go
new file mode 100644
index 0000000..de72563
--- /dev/null
+++ b/_s3get/main.go
@@ -0,0 +1,45 @@
+package main
+
+import (
+ "context"
+ "crypto/sha256"
+ "encoding/hex"
+ "fmt"
+ "io"
+ "os"
+
+ "github.com/aws/aws-sdk-go-v2/aws"
+ "github.com/aws/aws-sdk-go-v2/credentials"
+ "github.com/aws/aws-sdk-go-v2/service/s3"
+)
+
+// 列出并读回目标桶里的对象,打印 键/字节/sha256:资源字节是否真在目标存储里,只能这样核。
+func main() {
+ endpoint, bucket := os.Getenv("S3_ENDPOINT"), os.Getenv("S3_BUCKET")
+ client := s3.New(s3.Options{
+ Region: "us-east-1",
+ BaseEndpoint: aws.String(endpoint),
+ Credentials: credentials.NewStaticCredentialsProvider(os.Getenv("S3_KEY"), os.Getenv("S3_SECRET"), ""),
+ UsePathStyle: true,
+ })
+ ctx := context.Background()
+ pages := s3.NewListObjectsV2Paginator(client, &s3.ListObjectsV2Input{Bucket: aws.String(bucket)})
+ for pages.HasMorePages() {
+ page, err := pages.NextPage(ctx)
+ if err != nil {
+ fmt.Println("list error:", err)
+ os.Exit(1)
+ }
+ for _, item := range page.Contents {
+ out, err := client.GetObject(ctx, &s3.GetObjectInput{Bucket: aws.String(bucket), Key: item.Key})
+ if err != nil {
+ fmt.Println("get error:", item.Key, err)
+ os.Exit(1)
+ }
+ hash := sha256.New()
+ size, _ := io.Copy(hash, out.Body)
+ out.Body.Close()
+ fmt.Printf("%s\t%d\t%s\n", *item.Key, size, hex.EncodeToString(hash.Sum(nil)))
+ }
+ }
+}
\ No newline at end of file
diff --git a/cmd/worker/library_wiring.go b/cmd/worker/library_wiring.go
index 5be0d33..b4a6dfc 100644
--- a/cmd/worker/library_wiring.go
+++ b/cmd/worker/library_wiring.go
@@ -54,8 +54,9 @@ func buildLibraryProductionStack(ctx context.Context, config appconfig.Config, s
target, err := v071.NewProductionLibraryTarget(ctx, v071.ProductionLibraryConfig{
Postgres: config.LibraryProductionDatabaseURL, SearchURL: config.LibraryProductionElasticURL,
SearchIndex: config.LibraryProductionIndex, Objects: objects, ObjectsReader: objects,
- ArchiveRoot: config.LibraryArchiveRoot,
- MaxDocuments: 200000,
+ ArchiveRoot: config.LibraryArchiveRoot,
+ ObjectsBucket: config.LibraryProductionS3Bucket,
+ MaxDocuments: 200000,
}, identity)
if err != nil {
return nil, nil, err
diff --git a/internal/releaseadapter/v071/library_production_target.go b/internal/releaseadapter/v071/library_production_target.go
index 969ee5c..49fcb26 100644
--- a/internal/releaseadapter/v071/library_production_target.go
+++ b/internal/releaseadapter/v071/library_production_target.go
@@ -47,6 +47,9 @@ type ProductionLibraryConfig struct {
Objects ObjectStore
ObjectsReader ObjectReader
ArchiveRoot string
+ // ObjectsBucket 是目标对象存储的桶名:资源行里的定位符要换成它,
+ // 否则同步过去的图/附件仍指向来源桶。
+ ObjectsBucket string
MaxDocuments int
HTTPClient *http.Client
Now func() time.Time
@@ -317,6 +320,28 @@ func (t *ProductionLibraryTarget) insertRows(ctx context.Context, tx pgx.Tx, arc
if len(row) == 0 {
continue
}
+ if table == "resources" {
+ // 资源定位符里的桶必须换成本次写入的目标桶:字节就写在那里。
+ raw, ok := row["physical_path"]
+ if !ok {
+ return errors.New("资源行缺少定位符")
+ }
+ var locator string
+ if err := json.Unmarshal(raw, &locator); err != nil {
+ return errors.New("资源定位符不可解析")
+ }
+ if t.config.ObjectsBucket != "" {
+ rewritten, ok := rewriteLocatorBucket(locator, t.config.ObjectsBucket)
+ if !ok {
+ return fmt.Errorf("资源定位符无法改写到目标桶:%s", locator)
+ }
+ encoded, err := json.Marshal(rewritten)
+ if err != nil {
+ return err
+ }
+ row["physical_path"] = encoded
+ }
+ }
if columns == nil {
columns = make([]string, 0, len(row))
for key := range row {
diff --git a/internal/releaseadapter/v071/object_import.go b/internal/releaseadapter/v071/object_import.go
index 156d1ce..728215b 100644
--- a/internal/releaseadapter/v071/object_import.go
+++ b/internal/releaseadapter/v071/object_import.go
@@ -100,6 +100,51 @@ func (importer *ObjectImporter) Promote(ctx context.Context, stage ObjectStage)
return nil
}
+// rewriteLocatorBucket 把资源定位符里的桶换成目标桶,结构保持不变:
+// "storage:///:///" →
+// "storage:///:///"。
+//
+// 为什么必须改:同步把字节写进目标桶,但行是从快照原样搬的,定位符里写着测试桶;
+// 目标实例之后按这一行去取图/附件时会指向测试环境的桶(跨环境引用),
+// 或者干脆取不到。键不变,只换桶。
+func rewriteLocatorBucket(locator, bucket string) (string, bool) {
+ if bucket == "" || locator == "" || locator != strings.TrimSpace(locator) {
+ return "", false
+ }
+ prefix := ""
+ rest := locator
+ if strings.HasPrefix(locator, "storage://") {
+ trimmed := strings.TrimPrefix(locator, "storage://")
+ parts := strings.SplitN(trimmed, "/", 2)
+ if len(parts) != 2 || !validSearchIdentifier(parts[0]) {
+ return "", false
+ }
+ if parts[1] == "" {
+ return "", false
+ }
+ prefix, rest = "storage://"+parts[0]+"/", parts[1]
+ }
+ separator := strings.Index(rest, "://")
+ if separator < 0 {
+ // 裸对象键里没有桶:落盘时用的是配置桶,不需要改,也不算失败。
+ return locator, true
+ }
+ scheme := rest[:separator]
+ if !validSearchIdentifier(scheme) {
+ return "", false
+ }
+ schemeless := rest[separator+3:]
+ boundary := strings.Index(schemeless, "/")
+ if boundary <= 0 || boundary == len(schemeless)-1 {
+ return "", false
+ }
+ key := schemeless[boundary+1:]
+ if key == "" || !validSearchIdentifier(schemeless[:boundary]) {
+ return "", false
+ }
+ return prefix + scheme + "://" + bucket + "/" + key, true
+}
+
func providerPathFromLocator(locator string) (string, bool) {
rest := locator
if strings.HasPrefix(locator, "storage://") {
diff --git a/internal/releaseadapter/v071/resource_locator_test.go b/internal/releaseadapter/v071/resource_locator_test.go
new file mode 100644
index 0000000..5fdfaf8
--- /dev/null
+++ b/internal/releaseadapter/v071/resource_locator_test.go
@@ -0,0 +1,36 @@
+package v071
+
+import "testing"
+
+// 同步把字节写进目标桶,但资源行是从快照原样搬的:定位符里写着来源桶时,
+// 目标实例之后取图/附件会指向测试环境的桶(跨环境引用)或直接取不到。
+// 只换桶、不换键,两种定位符形状都要能改。
+func TestRewriteLocatorBucketKeepsKeyAndSwapsBucket(t *testing.T) {
+ for _, testCase := range []struct{ locator, want string }{
+ {"storage://45064e4f-434c-4752-a3ae-5fb1e2f54a7d/minio://kgmaint-1028a/10001/k/ab.md",
+ "storage://45064e4f-434c-4752-a3ae-5fb1e2f54a7d/minio://kgseal-1029a/10001/k/ab.md"},
+ {"oss://source-bucket/10/k/ab.png", "oss://target-bucket/10/k/ab.png"},
+ } {
+ bucket := "kgseal-1029a"
+ if testCase.locator[:3] == "oss" {
+ bucket = "target-bucket"
+ }
+ got, ok := rewriteLocatorBucket(testCase.locator, bucket)
+ if !ok || got != testCase.want {
+ t.Fatalf("rewrite(%q)=%q ok=%v want %q", testCase.locator, got, ok, testCase.want)
+ }
+ }
+ // 解析不出来就报错,不猜:宁可失败也不能写一行指向别处的资源。
+ for _, bad := range []string{"", "storage://x/", "storage://backend/minio://bucket", "oss://bucket/"} {
+ if _, ok := rewriteLocatorBucket(bad, "target"); ok {
+ t.Fatalf("非法定位符被接受了:%q", bad)
+ }
+ }
+ if _, ok := rewriteLocatorBucket("oss://bucket/key", ""); ok {
+ t.Fatal("没有目标桶时不该改写")
+ }
+ // 裸对象键里没有桶(落盘用配置桶),原样返回而不是失败。
+ if got, ok := rewriteLocatorBucket("weknora/10000/k/ab.docx", "target"); !ok || got != "weknora/10000/k/ab.docx" {
+ t.Fatalf("裸键被改写了:%q ok=%v", got, ok)
+ }
+}
--
2.52.0
From 2e39e495694a4d7f69273a4704ea1eb2ad9675fc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 06:22:00 +0800
Subject: [PATCH 17/45] =?UTF-8?q?chore:=20=E7=A7=BB=E5=87=BA=E4=B8=80?=
=?UTF-8?q?=E6=AC=A1=E6=80=A7=E6=A0=B8=E5=AF=B9=E5=B0=8F=E5=B7=A5=E5=85=B7?=
=?UTF-8?q?=EF=BC=88=E4=B8=8D=E7=95=99=E5=9C=A8=E4=BB=93=E5=BA=93=E9=87=8C?=
=?UTF-8?q?=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
_s3get/main.go | 45 ---------------------------------------------
1 file changed, 45 deletions(-)
delete mode 100644 _s3get/main.go
diff --git a/_s3get/main.go b/_s3get/main.go
deleted file mode 100644
index de72563..0000000
--- a/_s3get/main.go
+++ /dev/null
@@ -1,45 +0,0 @@
-package main
-
-import (
- "context"
- "crypto/sha256"
- "encoding/hex"
- "fmt"
- "io"
- "os"
-
- "github.com/aws/aws-sdk-go-v2/aws"
- "github.com/aws/aws-sdk-go-v2/credentials"
- "github.com/aws/aws-sdk-go-v2/service/s3"
-)
-
-// 列出并读回目标桶里的对象,打印 键/字节/sha256:资源字节是否真在目标存储里,只能这样核。
-func main() {
- endpoint, bucket := os.Getenv("S3_ENDPOINT"), os.Getenv("S3_BUCKET")
- client := s3.New(s3.Options{
- Region: "us-east-1",
- BaseEndpoint: aws.String(endpoint),
- Credentials: credentials.NewStaticCredentialsProvider(os.Getenv("S3_KEY"), os.Getenv("S3_SECRET"), ""),
- UsePathStyle: true,
- })
- ctx := context.Background()
- pages := s3.NewListObjectsV2Paginator(client, &s3.ListObjectsV2Input{Bucket: aws.String(bucket)})
- for pages.HasMorePages() {
- page, err := pages.NextPage(ctx)
- if err != nil {
- fmt.Println("list error:", err)
- os.Exit(1)
- }
- for _, item := range page.Contents {
- out, err := client.GetObject(ctx, &s3.GetObjectInput{Bucket: aws.String(bucket), Key: item.Key})
- if err != nil {
- fmt.Println("get error:", item.Key, err)
- os.Exit(1)
- }
- hash := sha256.New()
- size, _ := io.Copy(hash, out.Body)
- out.Body.Close()
- fmt.Printf("%s\t%d\t%s\n", *item.Key, size, hex.EncodeToString(hash.Sum(nil)))
- }
- }
-}
\ No newline at end of file
--
2.52.0
From b061a9686c636bb8d92419907f68fd3703baf678 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 06:24:14 +0800
Subject: [PATCH 18/45] =?UTF-8?q?fix(v071):=20=E8=B5=84=E6=BA=90=E6=8D=A2?=
=?UTF-8?q?=E6=A1=B6=E7=9A=84=E5=8F=98=E6=8D=A2=E5=9C=A8=E6=A0=A1=E9=AA=8C?=
=?UTF-8?q?=E6=97=B6=E5=90=8C=E7=94=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
只改写入侧会让"行内容摘要"对不上:校验拿变换前的归档行与目标里的变换后行比较,
真实同步在 verify 阶段报"生产 resources 内容与快照不一致"并回滚。
把行变换抽成 rowTransform,写入与校验共用同一份。
试过:make verify 15 项全绿;真实同步复现该失败后修复(下一轮重跑验证)。
---
.../v071/library_production_target.go | 60 ++++++++++++-------
.../v071/library_verify_content.go | 9 ++-
2 files changed, 47 insertions(+), 22 deletions(-)
diff --git a/internal/releaseadapter/v071/library_production_target.go b/internal/releaseadapter/v071/library_production_target.go
index 49fcb26..1326138 100644
--- a/internal/releaseadapter/v071/library_production_target.go
+++ b/internal/releaseadapter/v071/library_production_target.go
@@ -321,25 +321,8 @@ func (t *ProductionLibraryTarget) insertRows(ctx context.Context, tx pgx.Tx, arc
continue
}
if table == "resources" {
- // 资源定位符里的桶必须换成本次写入的目标桶:字节就写在那里。
- raw, ok := row["physical_path"]
- if !ok {
- return errors.New("资源行缺少定位符")
- }
- var locator string
- if err := json.Unmarshal(raw, &locator); err != nil {
- return errors.New("资源定位符不可解析")
- }
- if t.config.ObjectsBucket != "" {
- rewritten, ok := rewriteLocatorBucket(locator, t.config.ObjectsBucket)
- if !ok {
- return fmt.Errorf("资源定位符无法改写到目标桶:%s", locator)
- }
- encoded, err := json.Marshal(rewritten)
- if err != nil {
- return err
- }
- row["physical_path"] = encoded
+ if err := t.applyResourceBucket(row); err != nil {
+ return err
}
}
if columns == nil {
@@ -388,6 +371,41 @@ type resourceLocation struct {
Provider string
}
+// rowTransform 是"写入时对行做过的变换"的统一入口:校验要用同一份,否则摘要比的是
+// 变换前的行、目标里是变换后的行,永远不一致。
+func (t *ProductionLibraryTarget) rowTransform(table string) func(map[string]json.RawMessage) error {
+ if table == "resources" {
+ return t.applyResourceBucket
+ }
+ return nil
+}
+
+// applyResourceBucket 把资源行定位符里的桶换成本次写入的目标桶。
+// 写入与校验必须用同一个变换:只改写入侧会让"行内容摘要"对不上(真跑踩过)。
+func (t *ProductionLibraryTarget) applyResourceBucket(row map[string]json.RawMessage) error {
+ if t.config.ObjectsBucket == "" {
+ return nil
+ }
+ raw, ok := row["physical_path"]
+ if !ok {
+ return errors.New("资源行缺少定位符")
+ }
+ var locator string
+ if err := json.Unmarshal(raw, &locator); err != nil {
+ return errors.New("资源定位符不可解析")
+ }
+ rewritten, ok := rewriteLocatorBucket(locator, t.config.ObjectsBucket)
+ if !ok {
+ return fmt.Errorf("资源定位符无法改写到目标桶:%s", locator)
+ }
+ encoded, err := json.Marshal(rewritten)
+ if err != nil {
+ return err
+ }
+ row["physical_path"] = encoded
+ return nil
+}
+
func (t *ProductionLibraryTarget) importResources(ctx context.Context, archive *librarysnapshot.Archive, manifest librarysnapshot.Manifest) error {
paths, err := t.resourcePaths(ctx, resourcePartNames(manifest))
if err != nil {
@@ -542,7 +560,7 @@ func (t *ProductionLibraryTarget) Verify(ctx context.Context, expect libraryrele
wantCount, wantDigest, err := archivedTableState(archive, part)
if errors.Is(err, errMissingIdentity) {
// 个别表(例如日志表)没有代理主键:身份集合无从比,但行数与逐行内容摘要仍然必须一致。
- wantContentCount, wantContentDigest, columns, contentErr := archivedTableContent(archive, part)
+ wantContentCount, wantContentDigest, columns, contentErr := archivedTableContent(archive, part, t.rowTransform(part.Name))
if contentErr != nil {
return contentErr
}
@@ -573,7 +591,7 @@ func (t *ProductionLibraryTarget) Verify(ctx context.Context, expect libraryrele
return fmt.Errorf("生产 %s 与快照不一致:行数 %d/%d", part.Name, count, wantCount)
}
// 行数/身份一致还要比内容:同 ID 改正文、改 Wiki、改向量必须被发现。
- wantContentCount, wantContentDigest, columns, err := archivedTableContent(archive, part)
+ wantContentCount, wantContentDigest, columns, err := archivedTableContent(archive, part, t.rowTransform(part.Name))
if err != nil {
return err
}
diff --git a/internal/releaseadapter/v071/library_verify_content.go b/internal/releaseadapter/v071/library_verify_content.go
index fe28250..d458246 100644
--- a/internal/releaseadapter/v071/library_verify_content.go
+++ b/internal/releaseadapter/v071/library_verify_content.go
@@ -98,7 +98,8 @@ func (t *ProductionLibraryTarget) productionTableContent(ctx context.Context, ta
}
// archivedTableContent 读取归档侧规范内容摘要,并返回归档里出现过的列集合。
-func archivedTableContent(archive *librarysnapshot.Archive, part librarysnapshot.Part) (int64, string, map[string]bool, error) {
+func archivedTableContent(archive *librarysnapshot.Archive, part librarysnapshot.Part,
+ transform func(map[string]json.RawMessage) error) (int64, string, map[string]bool, error) {
reader, err := archive.OpenPart(part)
if err != nil {
return 0, "", nil, err
@@ -116,6 +117,12 @@ func archivedTableContent(archive *librarysnapshot.Archive, part librarysnapshot
if err := decoder.Decode(&raw); err != nil {
return 0, "", nil, err
}
+ if transform != nil {
+ // 写入时对行做过的变换(例如资源定位符换桶)校验时必须同样应用。
+ if err := transform(raw); err != nil {
+ return 0, "", nil, err
+ }
+ }
for key := range raw {
columns[key] = true
}
--
2.52.0
From a6406209bd2a4a037ba5804bdaae8f78d255bbbb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 06:28:29 +0800
Subject: [PATCH 19/45] =?UTF-8?q?fix(httpapi):=20=E6=81=A2=E5=A4=8D?=
=?UTF-8?q?=E4=BD=9C=E4=B8=9A=20id=20=E6=94=B9=E6=88=90=E7=BB=B4=E6=8A=A4?=
=?UTF-8?q?=E7=AA=97=E5=8F=A3=E5=8F=AF=E6=8E=A5=E5=8F=97=E7=9A=84=E5=BD=A2?=
=?UTF-8?q?=E7=8A=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
librestore--<时间戳.微秒> 带 ".",冻结协调器的 job 白名单只收
[A-Za-z0-9_-],所以每次恢复都在开窗口时被拒(invalid freeze request),
作业随后被接管扫成失败。改纳秒整数,并加测试锁住该约束。
试过:make verify 15 项全绿;真实恢复复现该错误后修复。
---
CHANGELOG.md | 5 +++++
internal/httpapi/library_restore.go | 8 +++++--
internal/httpapi/library_restore_test.go | 28 ++++++++++++++++++++++++
3 files changed, 39 insertions(+), 2 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a3e2feb..4bd8c31 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,8 +36,13 @@
目标实例之后取图/附件会指向测试环境的桶,或直接取不到。现在写入前把定位符里的桶
换成本次目标桶(键不变),解析不出来就报错而不是写一行指向别处的资源。
+- **恢复作业 id 让维护窗口拒绝**:`librestore--<时间戳.微秒>` 带 `.`,而冻结协调器
+ 只接受 `[A-Za-z0-9_-]`,每次恢复都在开窗口时被拒(`invalid freeze request`),作业随后被
+ 接管扫成失败。改用纳秒整数,并加测试锁住"id 必须是维护窗口可接受的标识"。
+
### Tests
+- `internal/httpapi/library_restore_test.go`:恢复作业 id 必须能被维护窗口接受。
- `internal/releaseadapter/v071/resource_locator_test.go`:嵌套/单层两种定位符换桶、裸键原样、
非法形状拒绝。
- `internal/releaseadapter/v071/search_empty_index_test.go`:空索引=空基线、有文档无范围字段必须报错。
diff --git a/internal/httpapi/library_restore.go b/internal/httpapi/library_restore.go
index 10f28f3..14edde6 100644
--- a/internal/httpapi/library_restore.go
+++ b/internal/httpapi/library_restore.go
@@ -5,6 +5,7 @@ import (
"encoding/json"
"errors"
"net/http"
+ "strconv"
"strings"
"time"
@@ -86,7 +87,10 @@ func libraryRestoreEnqueue(w http.ResponseWriter, r *http.Request, config Config
return
}
now := time.Now().UTC()
- jobID := "librestore-" + request.Scope + "-" + now.Format("20060102T150405.000000")
+ // 作业 id 会作为维护窗口的 job 标识落进 freeze journal,而冻结协调器只接受
+ // [A-Za-z0-9_-]:带 "." 的时间戳会让恢复在开窗口时被拒(真跑报 invalid freeze request),
+ // 所以用纳秒整数,和同步作业保持一致。
+ jobID := "librestore-" + request.Scope + "-" + strconv.FormatInt(now.UnixNano(), 10)
job, reused, err := store.CreateLibraryJob(r.Context(), governance.LibraryJob{
ID: jobID, Scope: request.Scope, Kind: governance.LibraryJobRestore,
IdempotencyKey: "library.restore:" + request.Scope + ":" + request.SnapshotID,
@@ -107,7 +111,7 @@ func libraryRestoreEnqueue(w http.ResponseWriter, r *http.Request, config Config
if reused && (job.State == governance.LibraryJobFailed || job.State == governance.LibraryJobCancelled) {
job, reused, err = store.CreateLibraryJob(r.Context(), governance.LibraryJob{
ID: jobID + "-retry", Scope: request.Scope, Kind: governance.LibraryJobRestore,
- IdempotencyKey: "library.restore:" + request.Scope + ":" + request.SnapshotID + ":retry:" + now.Format("20060102T150405.000000000"),
+ IdempotencyKey: "library.restore:" + request.Scope + ":" + request.SnapshotID + ":retry:" + strconv.FormatInt(now.UnixNano(), 10),
RequestDigest: digest, TargetSnapshotID: request.SnapshotID, Actor: identity.Username,
}, governance.SyncStages(), now)
if err != nil || reused {
diff --git a/internal/httpapi/library_restore_test.go b/internal/httpapi/library_restore_test.go
index e3355d3..92245a2 100644
--- a/internal/httpapi/library_restore_test.go
+++ b/internal/httpapi/library_restore_test.go
@@ -85,3 +85,31 @@ func TestLibraryJobResumeRejectsNonFailedJobs(t *testing.T) {
t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
}
}
+
+// 恢复作业 id 会作为维护窗口的 job 标识落进 freeze journal,协调器只接受
+// [A-Za-z0-9_-]。带 "." 的时间戳曾经让每次恢复都在开窗口时被拒(invalid freeze request)。
+func TestLibraryRestoreJobIDIsAFreezeSafeIdentifier(t *testing.T) {
+ store := &fakeLibraryStore{fakeJobStore: fakeJobStore{enqueueEchoRequestedID: true}}
+ digest, err := libraryRestoreParamsDigest("internal", "snap-1")
+ if err != nil {
+ t.Fatal(err)
+ }
+ now := time.Now().UTC()
+ store.grant = &governance.LibraryReleaseAuthorization{ID: "a", Scope: "internal", SnapshotID: "snap-1",
+ ParamsDigest: digest, ExpiresAt: now.Add(time.Hour), CreatedAt: now}
+ config := Config{Store: store, ProductionReleaseRequestsEnabled: true, ProductionBackupRestoreVerified: true}
+ recorder := httptest.NewRecorder()
+ libraryRestoreEnqueue(recorder, restoreRequest(`{"scope":"internal","snapshot_id":"snap-1"}`, roleAdmin), config)
+ if recorder.Code != http.StatusAccepted {
+ t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
+ }
+ id := store.lastJob.ID
+ if id == "" || len(id) > 128 {
+ t.Fatalf("作业 id 形状不对:%q", id)
+ }
+ for _, r := range id {
+ if !(r >= 'a' && r <= 'z' || r >= 'A' && r <= 'Z' || r >= '0' && r <= '9' || r == '-' || r == '_') {
+ t.Fatalf("作业 id 含维护窗口不接受的字符 %q:%q", r, id)
+ }
+ }
+}
--
2.52.0
From bc49b85b5627b5947b87d96df2089b444fd4df75 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 06:34:05 +0800
Subject: [PATCH 20/45] =?UTF-8?q?docs(acceptance):=20=E5=B0=81=E5=AD=98?=
=?UTF-8?q?=E9=97=AD=E7=8E=AF=E8=BF=9B"=E5=B7=B2=E5=AE=8C=E6=88=90"?=
=?UTF-8?q?=EF=BC=8C=E8=A1=A5=E6=AD=BB=E4=BF=A1=E6=9C=80=E5=B0=8F=E5=A4=96?=
=?UTF-8?q?=E9=83=A8=E5=A5=91=E7=BA=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- 矩阵:新增 S06/S06-a/S06-b/V03-c/Neo4j 拒绝行(都有真跑证据);把"封存入口未接线"、
"CLI 库级窗口"从缺口里移走;排空时序旧结论保留但标注被确定性做法取代。
- 死信解除仍缺产品路径,写出最小外部治理契约(保留原始行、审计、验证真实处理成功后
按精确项解除、未解除继续阻断)。
- 台账补 0.1.169–0.1.180 的 SHA 与 run(含 211/215 failure、218 cancelled,不涂改)。
- library-capture / 8088 部署方案同步成本轮真实结果。
---
docs/formal-8088-deployment-plan.md | 7 +++++--
docs/library-acceptance-matrix.md | 18 ++++++++++--------
docs/library-capture.md | 13 +++++++++++++
docs/release-ledger.md | 16 +++++++++++++++-
4 files changed, 43 insertions(+), 11 deletions(-)
diff --git a/docs/formal-8088-deployment-plan.md b/docs/formal-8088-deployment-plan.md
index b407229..3848074 100644
--- a/docs/formal-8088-deployment-plan.md
+++ b/docs/formal-8088-deployment-plan.md
@@ -52,7 +52,8 @@ LIBRARY_ARCHIVE_ROOT=/var/lib/knowledge-governance/library
「目标维护未接线,拒绝在挡不住入口/后台写入的情况下写目标」(`cmd/worker/library_handlers.go`)——**不会**退化成"库级锁假装维护"。
- 缺 `LIBRARY_PRODUCTION_DATABASE_URL` 时 overview/差异按"未接入"显示,不显示 0 或被当成"无变化"。
- `/api/v1/library/maintenance` 在实例未配置时返回 `instance` 缺省、`held=false`;页面显示「未接入 + 维护类操作 fail closed」。
-- `LIBRARY_AGENT_SOCKET` 指向的 agent 目前**没有运行**:`POST /api/v1/library/captures` 会 503 并写明"未接线",不会假装已封存。
+- `LIBRARY_AGENT_SOCKET` 指向的 agent 必须在部署时一起起来(`scripts/library-agent-install.sh` + 0600 `agent.env`);
+ 端点/闸门/队列声明与 worker 同源(`LIBRARY_TARGET_*`)。缺任何一项时封存会在开窗口前被拒并点名缺什么。
新增配置只在需要真正开维护窗口时才加(本机验收实例的取值可作模板,见
`evidence-maintenance/harness/candidate-maintenance.env`:`LIBRARY_TARGET_INSTANCE/PROJECT/WRITERS/NON_WRITERS/DOCKER_SOCKET/INGRESS_*`、`LIBRARY_TARGET_REDIS_*`)。
@@ -85,6 +86,8 @@ LIBRARY_ARCHIVE_ROOT=/var/lib/knowledge-governance/library
## 7. 已知风险与前置条件(必须先解决或明确接受)
1. **`knowledge-governance-p1-release-worker-1` 处于重启循环**(日志每分钟 `connect release target database`,`RELEASE_WORKER_ENABLED=false`)。这是正式栈既有状态,不是本轮引入;部署前需要决定是修配置还是先停掉该服务,否则会持续刷日志。
-2. **封存能力未接线**(见矩阵"缺代码"):正式上线后页面能如实显示"未接入",但"封存测试版本"按钮仍不可用。如果验收要求现场封存,需要先部署 `libraryagent`(`cmd/libraryagent`,0600 unix socket)并把 `LIBRARY_AGENT_SOCKET` 指到它。
+2. **封存能力已在本机专用实例验证**(2026-10-29:页面入口 → agent → 实例级窗口 → 同步 → 恢复)。
+ 正式部署仍需按同一形状接线:`libraryagent`(0600 socket)+ `agent.env`(`LIBRARY_TARGET_*`)+ `LIBRARY_AGENT_SOCKET`;
+ 这套接线在正式栈上尚未执行。
3. **入口排空探针未在最终构建复现**(矩阵"已实现·未跑"):正式部署前若要拿这条证据,需要在生产机重复探针,并接受"闸门关得比客户端快"导致上传注入失败的可能。
4. 部署本身就是生产变更:需要用户给的窗口与授权,本文不构成执行许可。
\ No newline at end of file
diff --git a/docs/library-acceptance-matrix.md b/docs/library-acceptance-matrix.md
index 0812bd2..955f765 100644
--- a/docs/library-acceptance-matrix.md
+++ b/docs/library-acceptance-matrix.md
@@ -44,6 +44,11 @@ A06(内容、问答、引用图片效果、性能报告)已由用户取消
| **S03** | 实例级维护窗口:关入口→排空→静默证明→停写者→写入→校验→开入口 | `internal/libraryfreeze` + `librarymaintenance` + 迁移 070–072 | 前轮 7 场景真跑全绿(normal/kill/applyfail/partial/crossscope/recover_refuse/recover_ok),本轮 sync/drain 场景继续复用;`quiesce` 证据、`post_stop_*`、journal、gate drain.json 均可回看 |
| **V03-a** | 撤销一份共享贡献后,保留另一份贡献、清除撤销方独有正文/引用/实体边、目录正确 | 由 WeKnora 源侧执行(`cleanupWikiOnKnowledgeDelete` + `EnqueueWikiRetract`),治理侧只比对/搬运 | **本轮真实验收**:kgmaint 隔离实例、原版 API 顺序入库两篇文档 → `entity/fa-bu-zha-men` 同页双来源(2097 字节)→ 真实 `DELETE /api/v1/knowledge/{id}` → 页面保留、来源只剩保留文档、A 独有正文(ZEBRA-A-7731/9910)清除、B 贡献仍在、引用 2→1 且只剩 B 的分块、目录不变、A 独有页面/摘要整页删除、索引页不再列出、实体边无死链。13/13 检查通过。证据:`kg-candidate-e2e/evidence-wiki-final/s8-final-checks-r1.json` + `06-wiki-*-r1.json` + `s3/s6-db-*.json` |
| **V03-b** | 治理侧能把上述语义变化说清楚(不是页面级"无变化") | `internal/librarydiff/wiki.go` `CompareWiki`;`GET /library/overview` 的 `diff.wiki` | 逐页比对正文/来源/引用/出入边/目录,输出 `sources_removed`、`citations_before→after`、`changed`;单测 `wiki_test.go`、视图单测 `library_wiki_diff_test.go`;页面逐行展示(`wikiContributionLines` + 测试) |
+| **S06** | 页面/API 发起封存 → 主机 agent → 实例级窗口封存(真实冻结) | `POST /library/captures` + `cmd/libraryagent`(0600 socket、固定命令)+ `libraryctl capture`(实例级:闸门/后台静默/指纹) | **本轮真跑**:`POST /api/v1/library/captures`(job `lib-internal-20261029T0614`)202 → worker → agent → CLI → 关闸门排空 → 等后台静默 → 停 `kgmaint-app`(exit=1 但入口已排空,`drain_verified=true`)→ 导出 → 恢复写入者与入口;作业 `libseal-…` succeeded,快照 `1196c518…`。证据 `kg-capture-loop/evidence/04-inflight-capture.json`、journal `freeze-kgmaint/lib-internal-20261029T0614.json` |
+| **S06-a** | 排空证明取自真实在途请求(不靠 202 后抢时序) | 闸门 `drain.json` + 客户端真实上传握手 | **本轮真跑**:先发一半 multipart 正文 → 闸门日志 `conn:open active=1` → 再发起封存 → 入口关闭(拒绝新连接)→ 补完正文,应用 200 并完成解析/嵌入 → `drain.json phase=drained active_at_close=1 served=126 drain_ms=302`;窗口 `quiesce.samples=18 stable_ms=1617` 且停写者后指纹不变。同一次窗口里派生任务真的跑完(探针文档 `de475a32…` completed / 10 分块) |
+| **V03-c** | 带"撤销后共享页"的整库封存 → 独立目标同步 → 恢复,逐项真实读回 | `libraryctl` 封存 + `ProductionLibraryTarget` + `libraryrelease` | **本轮真跑**:源 kgmaint 撤销后 KB `e64e82b5`(9 Wiki 页、1 文档、2 分块、1 资源)→ 快照 `1196c518…` 与源逐页比对全部一致(正文 md5/来源/引用/目录/18 条边)→ 同步到**独立实例** kgseal(自己的 PG/索引/桶,非同一份存储)`libsync-internal-1793226278273693890` succeeded+verify succeeded → 目标逐页/索引/资源字节一致(`07-target-compare.json`,`ok=true`,目标桶对象 sha256 与源一致)→ 人为偏离(删整库 Wiki 页)→ `librestore-internal-1793226571284097366-retry` succeeded → 目标回到与快照逐项一致(同一份 `07-target-compare.json` 摘要,`ok=true`) |
+| **S06-b** | 主机侧封存/恢复必须与 worker 讲同一份维护声明 | `internal/librarymaintenance/env.go`(`LIBRARY_TARGET_*` 唯一解析处) | 缺项时 `capture` 在开窗口前拒绝并点名;agent 启动打印维护目标;单测 5 项(逐项缺失/空白/口令空格/队列库号) |
+| **Neo4j 启用场景** | 启用图谱的库必须被真实拒绝 | `v071/library_export.go` 读 `indexing_strategy.graph_enabled` | **本轮真跑**:在 kgmaint 建 `graph_enabled=true` 的真实 KB `8de41ca7…`,用真实 CLI 预检 → 退出码 1、`LIBRARYCTL_FAILED: Neo4j graph snapshot is not supported`(`evidence/10-neo4j-refuse.txt`)。不是 skip |
| **U04** | 维护级别/进度/恢复错误真实呈现 | `MaintenanceCard`(`web/src/ReleaseTargets.tsx`)、`/api/v1/library/maintenance` | 显示实例级/库级、持有 scope+作业、阶段、入口开/关、服务、开始/释放、进度(阶段名中文化)、恢复错误与处理记录;仅"窗口仍持有且作业失败"时给"按预备份恢复";无记录时"未接入 + fail closed"。组件测试 6 项 |
## 二、缺代码
@@ -51,9 +56,7 @@ A06(内容、问答、引用图片效果、性能报告)已由用户取消
| ID | 缺口 | 现状与影响 |
| --- | --- | --- |
| R03 | 存快/恢复快对比 | 没有测速实现,也未测。不写没有测量的数字 |
-| 死信解除契约 | 死信只能靠人工清理,没有"解除/豁免"契约 | WeKnora `task_dead_letters` 无解决标记;导出/封存按"存在即阻断"(`library_source_settlement.go`)。本轮真实验证:早期错误模型配置产生的 2 条 wiki 死信直接阻断整实例结算,清理方式只能是删除行(记录:`deadletters-before-delete.json`,sha256 `dd4d8f08…`)。要变成可运维契约,需要上游给出解决标记或治理侧设计"带证据的解除"——**未实现** |
-| 封存入口接线(本机) | `POST /library/captures` 需要 `LIBRARY_AGENT_SOCKET` 指向真实 agent | 候选/正式 api 都配置了 socket 路径,但本机没有运行 `libraryagent`,接口会 503 并明示"未接线"(不是静默失败) |
-| CLI 实例级封存 | `libraryctl capture` 只建库级窗口,不关入口 | 真跑结果:WeKnora 收到 SIGTERM 固定 `exit=1`,没有入口排空证明时被拒(`未优雅退出(exit=1)`)。要在"不停共享栈"的前提下封存真实撤销后的库,需要把实例级 + 闸门接进 CLI(或部署 agent)——**未实现** |
+| 死信解除契约 | 死信只能靠人工清理,没有"解除/豁免"契约 | WeKnora `task_dead_letters` 无解决标记;导出/封存按"存在即阻断"(`library_source_settlement.go`)。本轮真实验证:早期错误模型配置产生的 2 条 wiki 死信直接阻断整实例结算,清理方式只能是删除行(记录:`deadletters-before-delete.json`,sha256 `dd4d8f08…`)。要变成可运维契约,需要上游给出解决标记或治理侧设计"带证据的解除"——**未实现**。本轮未再新增死信,没有用它绕过任何一项;仍需的最小外部契约见第五节第 5 条 |
## 三、已实现·未跑
@@ -62,9 +65,7 @@ A06(内容、问答、引用图片效果、性能报告)已由用户取消
| V05 | 导出中源变更则拒绝或隔离 | 预备份导出前后行数静默检查已有(本机验证会拒绝);真实并发写入的隔离演练未做 |
| B02 | 资源在测试侧删除后仍可恢复 | 归档内容寻址已实现;"删测试侧对象再从归档恢复"实测未做 |
| S03-b | 死信/孤儿任务阻断的负向演练(本轮只验证了真实死信阻断) | 真实阻断已发生并记录;系统化的负向矩阵未跑 |
-| **V03-c** | **带"撤销后共享页"的整库封存 → 同步 → 恢复** | 上游语义已验证、治理差异已实现;但这台机器上 CLI 封存止步于上面的 exit=1 缺口,API 封存未接线,所以"封存一份含撤销结果的 Wiki 版本,再同步/恢复并逐行比对"**没有产出真实证据**。旧证据 `drain-task-new-c`(03:39)属于 0ef7984 之前的构建,不能拿来证明当前 SHA |
-| **Neo4j 启用场景** | 代码在 `library_export.go` 检查 `graph_enabled`,启用即 `Neo4j graph snapshot is not supported` 拒绝 | 本轮没有真跑"启用 Neo4j 的库被拒":kgmaint 实例 `NEO4J_ENABLE=false`、测试库 `graph_enabled=false`。代码路径在,真实执行未做 |
-| **排空竞态探针(最终构建)** | 关入口→排空期间产生的真实任务必须等到队列归零才停写者 | 本轮在最终构建(1faf513)上重跑 6 次(`drain-task-final-1faf513{,-r2,-r3,-r4,-r5,-r6}.json`),上传请求全部 `Broken pipe`、队列深度始终 0:闸门在 202 之后 <0.2s 就关监听,客户端来不及把请求送进去。**未复现**,不记为通过;旧 `drain-task-new-c` 的时间线仍是旧构建证据 |
+| 排空时序(历史结论) | 旧做法"202 之后抢时序上传"在 1faf513 上重跑 6 次全部 `Broken pipe`(`drain-task-final-1faf513*.json` 保留,不记通过) | 已被 S06-a 的确定性做法取代:先证明请求已被闸门接收,再启动维护。旧证据保留,不覆盖 |
| U05 | 正式 8088 页面验收 | 正式栈仍是 0.1.114,本轮未替换;维护面板/逐页 Wiki 差异只在测试与候选构建里验证过 |
## 四、需授权 / 需环境
@@ -82,5 +83,6 @@ A06(内容、问答、引用图片效果、性能报告)已由用户取消
1. **Wiki 撤销语义是上游行为,必须用上游 API 验**:顺序入库才产生"两篇共贡献一页"(并行入库会各自抽到不同 slug 生成两页,这是上游已知行为)。撤销后页面保留、贡献按文档摘除,12 项检查全部通过。
2. **治理侧不能只报页面级差异**:撤销共享贡献时页面仍是"更新",页面级计数会显示成"无变化"。已改为逐页语义比对,能指出"来源 -1、引用 2→1、正文变了、出边少了一条"。
-3. **封存链路是本机当前的真缺口**:CLI 封存被 `exit=1` + 无入口排空证明挡住,API 封存没有 agent。这不是"Wiki 语义没验",而是"带撤销结果的版本没法在本机封出来"。正式部署必须先接线 agent(见 `docs/formal-8088-deployment-plan.md`)。
-4. **死信不是可忽略的告警**:一条失败的 wiki op 就足以让整实例结不了算。要么上游给解决标记,要么治理侧设计带证据的解除,当前两者都没有。
\ No newline at end of file
+3. **封存链路本轮真的打通了,而且不是放松校验**:CLI 改为实例级窗口(闸门 + 后台静默 + 目标指纹),"写者 exit=1"由闸门的 `drained/active_at_close` 证据解释,而不是被忽略;排空证明改成"先在途、再关入口"的确定性顺序,不再靠 202 之后抢时序。
+4. **接线后暴露的四个真缺陷(都已修,都有用例)**:`jobs.id` 列宽 36 让封存作业根本投不进去;v0.7.1 的 app 写索引不带 `tenant_id` 导致导出 0 条;全新实例的空索引被当成"索引被改坏";恢复作业 id 带 `.` 被维护窗口拒。另有资源定位符仍写来源桶——同步过去的目标取不到图/附件。
+5. **死信解除仍缺产品路径,最小外部契约如下(未实现,不冒充)**:①保留原始死信行与错误证据,不做删除;②解除必须在治理侧留下审计记录(谁、何时、依据哪条证据、绑定哪个实例/库/任务指纹);③只有在"重放该任务并成功、且源侧结清"之后才允许解除,解除记录挂在精确项上(不允许按实例或通配解除);④未解除的死信继续阻断结算与封存。本轮没有新增死信,也没有用它绕过任何门槛。
\ No newline at end of file
diff --git a/docs/library-capture.md b/docs/library-capture.md
index ce7ece3..5972a0d 100644
--- a/docs/library-capture.md
+++ b/docs/library-capture.md
@@ -107,6 +107,19 @@ LIBRARY_TARGET_REDIS_ADDR/_PASSWORD/_DB 后台队列(asynq)地址
两次封存都记录了 `stop_verified=true`、`restored=true`,`WKNFull-app` 恢复后 healthy;来源未做任何写操作。
+## 2026-10-29 实测:页面入口 → agent → 实例级窗口(真实撤销后的库)
+
+- 请求:`POST /api/v1/library/captures {scope:internal, job:lib-internal-20261029T0614}` → 202,
+ worker 投递 agent,CLI 以**实例级窗口**执行。
+- 排空证据(确定性顺序,不抢时序):先发一半 multipart 正文 → 闸门日志 `conn:open active=1`
+ → 再发起封存 → 入口拒绝新连接 → 补完正文,应用返回 200 并完成解析/嵌入 →
+ `drain.json`:`phase=drained active_at_close=1 served=126 drain_ms=302`。
+- 冻结:`kgmaint-app` 收到 SIGTERM 后 `exit=1`(上游行为),因入口已排空,`drain_verified=true`;
+ 后台静默 `quiesce.samples=18 stable_ms=1617`,停写者后指纹不变;随后恢复写入者与入口。
+- 产物:快照 `1196c518…`(KB `e64e82b5…`,tenant 10001):1 文档 / 2 分块 / 9 Wiki 页 / 1 资源,
+ 与源库逐页比对(正文 md5、来源、引用、目录、18 条边)全部一致。
+- 同一份快照随后同步到**独立实例**(自己的 PG/索引/桶)并成功恢复,逐项读回一致。
+
## 它证明了什么 / 没有证明什么
已证明(A04 数据完整性口径):这一份整库内容在**写入者停住**之后被完整导出,PostgreSQL 与 Elasticsearch 双向覆盖、生成问题、资源与摘要逐项核验通过,产物可寻址、可复读、可校验。这正是封版所需的完整性口径。
diff --git a/docs/release-ledger.md b/docs/release-ledger.md
index 8c85c73..76410a1 100644
--- a/docs/release-ledger.md
+++ b/docs/release-ledger.md
@@ -68,7 +68,21 @@ run164 因 qawemail 依赖外网 DNS 失败,已修,不涂改。
| 0.1.166 | 1faf5137 | 用完整容器 ID 判定写入者归属(**验收代码 SHA**) | 207 | **success** | 否 |
| 0.1.167 | f82eb073 | 矩阵四段重排 + 8088 待验收部署方案 | 208 | **success** | 否 |
-当前候选 = 0.1.166(1faf513);其后的 f82eb07 只改文档,未改代码,验收证据的 code_sha 仍是 **1faf513**。
+| 0.1.169 | ee7688f2 | 矩阵改正 Wiki 检查计数(上轮交付写作 0.1.168,按 `git rev-list --count v0.1.0..HEAD` 实为 0.1.169,此处以台账为准) | 210 | **success** | 否 |
+| 0.1.170 | 11c52ad8 | 封存窗口接上实例级闸门/后台静默(**本轮第一个代码提交**) | 211 | failure(密钥扫描把"环境变量名字面量"误判为密钥;该提交之后才在下一提交改名修复) | 否 |
+| 0.1.171 | 37a8370f | 索引范围过滤接受未写 `tenant_id` 的文档 | 212 | **success** | 否 |
+| 0.1.172 | f2d6f3f6 | 封存队列作业 id 按 `jobs.id` 列宽拼短 | 213 | **success** | 否 |
+| 0.1.173 | 4d6ecda3 | 源对象存储端点可按宿主机地址覆盖 | 214 | **success** | 否 |
+| 0.1.174 | faaf0037 | agent 固定命令形态纳入对象存储端点 | 215 | failure(漏跑 gofmt,下一提交修) | 否 |
+| 0.1.175 | 84e8a0df | gofmt | 216 | **success** | 否 |
+| 0.1.176 | 7d4ffdbf | 全新目标实例的空索引按空基线 | 217 | **success** | 否 |
+| 0.1.177 | cb009080 | 同步资源行定位符换成目标桶 | 218 | completed/cancelled(被后续提交取消,不计) | 否 |
+| 0.1.178 | 2e39e495 | 移出一次性核对小工具 | 219 | **success** | 否 |
+| 0.1.179 | b061a968 | 资源换桶变换在校验时同用(**封存闭环验收代码 SHA**) | 220 | **success** | 否 |
+| 0.1.180 | a6406209 | 恢复作业 id 改成维护窗口可接受的形状 | 221 | **success** | 否 |
+
+当前候选 = 0.1.179(b061a968)跑完封存/同步/恢复的真实闭环;0.1.180(a6406209)是恢复作业 id 的修复,
+恢复真跑证据在 0.1.180 上取得(见交付报告)。
本轮真实验收证据:`/home/zheromiku/.hermes/handoffs/kg-candidate-e2e/evidence-wiki-final/`,
交付报告:`/home/zheromiku/.hermes/handoffs/release-wiki-final-acceptance-result.md`。
正式 8088 仍是 0.1.114(dc9e827),未部署;部署方案见 `docs/formal-8088-deployment-plan.md`。
--
2.52.0
From 958292d1ff2246b39c43bfe7d93e2b15e407bf6f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 06:36:05 +0800
Subject: [PATCH 21/45] =?UTF-8?q?docs(ledger):=20=E6=8C=89=E5=AE=9E?=
=?UTF-8?q?=E9=99=85=E8=BF=90=E8=A1=8C=E7=9A=84=E4=BA=8C=E8=BF=9B=E5=88=B6?=
=?UTF-8?q?=E8=AE=B0=E5=B0=81=E5=AD=98=E9=97=AD=E7=8E=AF=E6=97=B6=E5=BA=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/release-ledger.md | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/docs/release-ledger.md b/docs/release-ledger.md
index 76410a1..fa707c8 100644
--- a/docs/release-ledger.md
+++ b/docs/release-ledger.md
@@ -81,8 +81,9 @@ run164 因 qawemail 依赖外网 DNS 失败,已修,不涂改。
| 0.1.179 | b061a968 | 资源换桶变换在校验时同用(**封存闭环验收代码 SHA**) | 220 | **success** | 否 |
| 0.1.180 | a6406209 | 恢复作业 id 改成维护窗口可接受的形状 | 221 | **success** | 否 |
-当前候选 = 0.1.179(b061a968)跑完封存/同步/恢复的真实闭环;0.1.180(a6406209)是恢复作业 id 的修复,
-恢复真跑证据在 0.1.180 上取得(见交付报告)。
+封存闭环的运行时序(按实际运行的二进制记):封存 API→agent→冻结出快照在 **0.1.175(84e8a0d)**;
+首次同步成功在 **0.1.179(b061a968)**;恢复与最终逐项读回在 **0.1.180(a6406209)**。
+最终 HEAD 的代码提交即 0.1.180(其后 bc49b85 只改文档,CI run 222 success)。
本轮真实验收证据:`/home/zheromiku/.hermes/handoffs/kg-candidate-e2e/evidence-wiki-final/`,
交付报告:`/home/zheromiku/.hermes/handoffs/release-wiki-final-acceptance-result.md`。
正式 8088 仍是 0.1.114(dc9e827),未部署;部署方案见 `docs/formal-8088-deployment-plan.md`。
--
2.52.0
From c2402947a96e19b26279c8f93168d7b67c87d3eb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 06:55:13 +0800
Subject: [PATCH 22/45] =?UTF-8?q?feat(library):=20=E6=AD=BB=E4=BF=A1?=
=?UTF-8?q?=E6=8C=89=E7=B2=BE=E7=A1=AE=E6=8C=87=E7=BA=B9=E8=A7=A3=E9=99=A4?=
=?UTF-8?q?=EF=BC=8C=E4=BF=9D=E7=95=99=E4=B8=8A=E6=B8=B8=E8=AE=B0=E5=BD=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
上游 task_dead_letters 没有解决标记,purge/DELETE 会销毁"失败过"的唯一证据。
治理侧新增解除记录(迁移 073):绑定实时行逐字节指纹、重放引用、源侧观测摘要与
操作人;行被改过、重放后又出现新死信、源侧未结清都不命中,封存照旧阻断。
指纹先压紧空白再摘要,避免 PG to_jsonb::text 与 json.Marshal 的空白差异。
试过:go test ./internal/{librarydeadletter,libraryagent,httpapi,releaseadapter/v071,
platform/postgres},make verify 15 项全绿。
---
CHANGELOG.md | 29 ++
api/openapi.yaml | 103 +++++++
cmd/libraryctl/main.go | 74 ++++-
cmd/worker/main.go | 10 +-
internal/governance/library_flow.go | 31 +++
internal/httpapi/library_deadletters.go | 104 +++++++
internal/httpapi/library_deadletters_test.go | 114 ++++++++
internal/httpapi/server.go | 7 +
internal/libraryagent/agent.go | 21 ++
internal/libraryagent/agent_test.go | 29 ++
internal/libraryagent/client.go | 17 +-
internal/librarydeadletter/deadletter.go | 253 ++++++++++++++++++
internal/librarydeadletter/deadletter_test.go | 113 ++++++++
.../platform/postgres/library_dead_letters.go | 149 +++++++++++
...0073_library_dead_letter_releases.down.sql | 1 +
...000073_library_dead_letter_releases.up.sql | 29 ++
internal/platform/postgres/migrations_test.go | 23 +-
.../releaseadapter/v071/library_capture.go | 11 +-
.../releaseadapter/v071/library_export.go | 18 +-
.../v071/library_export_test.go | 29 ++
.../releaseadapter/v071/library_preflight.go | 6 +
.../v071/library_source_settlement.go | 119 +++++++-
22 files changed, 1267 insertions(+), 23 deletions(-)
create mode 100644 internal/httpapi/library_deadletters.go
create mode 100644 internal/httpapi/library_deadletters_test.go
create mode 100644 internal/librarydeadletter/deadletter.go
create mode 100644 internal/librarydeadletter/deadletter_test.go
create mode 100644 internal/platform/postgres/library_dead_letters.go
create mode 100644 internal/platform/postgres/migrations/000073_library_dead_letter_releases.down.sql
create mode 100644 internal/platform/postgres/migrations/000073_library_dead_letter_releases.up.sql
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4bd8c31..fa62e17 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,34 @@
# Changelog
+## 开发快照(死信精确解除:保留上游行,只按指纹放行)
+
+### Added
+
+- **死信解除契约(治理侧)**:上游 `task_dead_letters` 没有"已解决"标记,
+ purge/DELETE 都会销毁"这条任务失败过"的唯一证据。新增
+ `library_dead_letter_releases`(迁移 073)记录**一条精确死信**的解除:绑定实时行
+ 逐字节指纹(`sha256(to_jsonb(row))`,先压紧空白)、重放引用(队列/任务号/时间/
+ 证据引用)、源侧观测摘要、操作人与时间。上游行一个字节都不动。
+- `GET/POST /api/v1/library/dead-letter-releases`:POST 需工程师及以上 +
+ `X-Governance-Action: dead-letter-release`,拒绝条件全部显式——观测摘要不符(被
+ 改写/格式化)、源侧未结清、观测里没有这条死信(已被删除)、重放早于失败时间、
+ 重放之后同一任务键又出现新死信(说明重放没成功)、实例不一致。
+- `libraryctl dead-letters`(只读):打印整库死信原始行 + 结算计数 + 观测摘要,
+ 供治理平台绑定;平台自己不连源库、不复制"自报成功"。
+
+### Changed
+
+- 结算/封存不再"死信存在即阻断",而是"每条实时死信都要被精确解除命中":
+ `checkLibrarySourceSettlementReleased` / `ExportLibraryWithReleases` 对每条行
+ 重算指纹,未命中、行被改过、出现新行都继续阻断并点名。
+- 解除指纹经 worker → agent → `libraryctl -released-dead-letters` 逐段校验
+ (`sha256:<64 hex>`,最多 64 条,不接受通配),agent 的固定命令形态不变。
+
+### Fixed
+
+- 指纹对空白敏感会让"同一份内容"两边算不出同一个值(PostgreSQL `to_jsonb::text`
+ 带空格、Go `json.Marshal` 不带);指纹改为先 `json.Compact` 再摘要。
+
## 开发快照(封存入口接线:库级窗口接上实例级闸门)
### Fixed
diff --git a/api/openapi.yaml b/api/openapi.yaml
index 50f3501..a07a8a7 100644
--- a/api/openapi.yaml
+++ b/api/openapi.yaml
@@ -898,6 +898,109 @@
}
}
},
+ "/api/v1/library/dead-letter-releases": {
+ "get": {
+ "tags": [
+ "Runtime"
+ ],
+ "operationId": "listLibraryDeadLetterReleases",
+ "summary": "列出本实例的死信解除记录(只读审计视图;上游死信行保持原样)",
+ "responses": {
+ "200": {
+ "$ref": "#/components/responses/Envelope"
+ },
+ "400": {
+ "$ref": "#/components/responses/BadRequest"
+ },
+ "500": {
+ "$ref": "#/components/responses/InternalError"
+ },
+ "503": {
+ "description": "实例身份未配置或解除存储不可用"
+ }
+ }
+ },
+ "post": {
+ "tags": [
+ "Runtime"
+ ],
+ "operationId": "createLibraryDeadLetterRelease",
+ "summary": "按精确指纹记录一条死信解除(需要工程师及以上与 X-Governance-Action;不删除上游行,行变化即失效)",
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "dead_letter_id": {
+ "type": "integer"
+ },
+ "observation": {
+ "type": "object"
+ },
+ "observation_digest": {
+ "type": "string"
+ },
+ "replay": {
+ "type": "object",
+ "properties": {
+ "queue": {
+ "type": "string"
+ },
+ "task_id": {
+ "type": "string"
+ },
+ "at": {
+ "type": "string",
+ "format": "date-time"
+ },
+ "evidence": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "queue",
+ "task_id",
+ "at"
+ ]
+ },
+ "note": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "dead_letter_id",
+ "observation",
+ "observation_digest",
+ "replay"
+ ]
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "解除记录已落库(或返回同一指纹的已存记录)"
+ },
+ "400": {
+ "$ref": "#/components/responses/BadRequest"
+ },
+ "403": {
+ "description": "权限不足或缺少写意图头"
+ },
+ "409": {
+ "description": "解除被拒绝:指纹/结清/重放证据不满足"
+ },
+ "500": {
+ "$ref": "#/components/responses/InternalError"
+ },
+ "503": {
+ "description": "实例身份未配置或解除存储不可用"
+ }
+ }
+ }
+ },
"/api/v1/library/storage": {
"get": {
"tags": [
diff --git a/cmd/libraryctl/main.go b/cmd/libraryctl/main.go
index c04b8b0..f5c653a 100644
--- a/cmd/libraryctl/main.go
+++ b/cmd/libraryctl/main.go
@@ -32,6 +32,7 @@ import (
"github.com/jackc/pgx/v5/pgxpool"
+ "knowledge-governance/internal/librarydeadletter"
"knowledge-governance/internal/libraryfreeze"
"knowledge-governance/internal/librarymaintenance"
"knowledge-governance/internal/librarysnapshot"
@@ -59,6 +60,9 @@ type options struct {
job string
dryRun bool
snapshot string
+ // releasedDeadLetters 是治理平台审计过的精确解除指纹(逗号分隔)。它只让这些
+ // 确切的行不再阻断;实时行必须逐字节命中,否则照旧拒绝。
+ releasedDeadLetters string
}
func main() {
@@ -94,6 +98,8 @@ func main() {
runErr = runVerify(opts)
case "recover":
runErr = runRecover(ctx, opts)
+ case "dead-letters":
+ runErr = runDeadLetters(ctx, opts)
default:
usage()
os.Exit(2)
@@ -129,6 +135,8 @@ Flags (defaults target the local WKNFull test stack):
-job (capture; default: lib--)
-dry-run (capture: export + validate only, no archive, no stop)
-snapshot (verify)
+ -released-dead-letters a,b (capture/preflight; 治理平台精确解除的死信指纹)
+ dead-letters (read-only) 打印整库死信原始行与观测摘要,供治理平台审计
`)
}
@@ -166,6 +174,7 @@ func parseFlags(command string, args []string) (options, []string, error) {
set.StringVar(&opts.job, "job", "", "capture job id")
set.BoolVar(&opts.dryRun, "dry-run", false, "export and validate without archiving or stopping")
set.StringVar(&opts.snapshot, "snapshot", "", "snapshot id for verify")
+ set.StringVar(&opts.releasedDeadLetters, "released-dead-letters", "", "audited dead-letter fingerprints (comma separated)")
if err := set.Parse(args); err != nil {
return opts, nil, err
}
@@ -662,7 +671,11 @@ func runPreflight(ctx context.Context, opts options) error {
if err != nil {
return err
}
- if err = v071.LibrarySourceSettled(ctx, pool); err != nil {
+ released, err := parseReleasedDeadLetters(opts.releasedDeadLetters)
+ if err != nil {
+ return err
+ }
+ if err = v071.LibrarySourceSettledWithReleases(ctx, pool, released); err != nil {
return err
}
search, err := v071.NewSearchExporter(config.Search)
@@ -717,6 +730,10 @@ func runCapture(ctx context.Context, opts options) error {
if opts.scope != "internal" && opts.scope != "external" {
return errors.New("-scope must be internal or external")
}
+ released, err := parseReleasedDeadLetters(opts.releasedDeadLetters)
+ if err != nil {
+ return err
+ }
if opts.dryRun {
return runPreflight(ctx, opts)
}
@@ -831,7 +848,7 @@ func runCapture(ctx context.Context, opts options) error {
v071.LibraryCaptureRequest{JobID: job, Scope: opts.scope,
Identity: v071.PostgresIdentity{TenantID: tenant, KnowledgeBaseID: kb},
Compatibility: contract, CreatedAt: time.Now().UTC(), MaxDocuments: opts.maxDocuments,
- VerifyContract: verifyContract})
+ VerifyContract: verifyContract, ReleasedDeadLetters: released})
if err != nil {
printJSON(map[string]any{"job": job, "state": result.State, "snapshot_id": result.SnapshotID, "error": err.Error()})
return err
@@ -1079,3 +1096,56 @@ func printJSON(value any) {
encoder.SetIndent("", " ")
_ = encoder.Encode(value)
}
+
+// parseReleasedDeadLetters 把逗号分隔的指纹转成列表,并在本地先校验形状:一个
+// 打错的指纹不应该走到源库才失败,更不应该被当成通配符。
+func parseReleasedDeadLetters(raw string) ([]string, error) {
+ out := []string{}
+ for _, item := range strings.Split(raw, ",") {
+ item = strings.TrimSpace(item)
+ if item == "" {
+ continue
+ }
+ if !librarydeadletter.ValidFingerprint(item) {
+ return nil, errors.New("released dead letter entries must be sha256:<64 hex> fingerprints")
+ }
+ out = append(out, item)
+ }
+ if len(out) > 64 {
+ return nil, errors.New("at most 64 dead letter fingerprints per capture")
+ }
+ return out, nil
+}
+
+// runDeadLetters 只读:打印整库死信原始行与观测摘要。治理平台的解除记录绑定这份
+// 摘要;平台自己不连源库,因此观测必须由能读源库的一方生成并原样提交。
+func runDeadLetters(ctx context.Context, opts options) error {
+ if opts.scope != "internal" && opts.scope != "external" {
+ return errors.New("-scope must be internal or external")
+ }
+ binding, err := scopeBindings(ctx, opts.governancePG)
+ if err != nil {
+ return err
+ }
+ config, err := discoverSource(ctx, opts, binding)
+ if err != nil {
+ return err
+ }
+ pool, err := openSourceDatabase(ctx, config)
+ if err != nil {
+ return err
+ }
+ defer pool.Close()
+ kb := config.Scopes[opts.scope]
+ tenant, err := tenantAndKnowledgeBase(ctx, pool, kb)
+ if err != nil {
+ return err
+ }
+ payload, err := v071.ObserveDeadLetters(ctx, pool, opts.project, tenant, kb)
+ if err != nil {
+ return err
+ }
+ digest := librarydeadletter.Fingerprint(payload)
+ printJSON(map[string]any{"observation": json.RawMessage(payload), "observation_digest": digest})
+ return nil
+}
diff --git a/cmd/worker/main.go b/cmd/worker/main.go
index 814e7a8..a8a52df 100644
--- a/cmd/worker/main.go
+++ b/cmd/worker/main.go
@@ -276,7 +276,15 @@ func workerHandlers(store *postgresstore.Store, config appconfig.Config) (map[st
"主机侧正在暂停写入者、导出并恢复", startedAt); stageErr != nil {
log.Printf("library seal job %s stage update failed: %v", libraryJobID, stageErr)
}
- result, err := libraryagent.Capture(ctx, agentConfig, payload.Scope, payload.CaptureJob)
+ // 平台审计过的精确死信解除指纹:读取失败必须阻断(fail closed),
+ // 不能因为存储不可用就静默按"没有解除"或"全部解除"处理。
+ released, releaseErr := store.DeadLetterReleaseFingerprints(ctx, config.LibraryTargetInstance)
+ if releaseErr != nil {
+ _ = store.UpdateLibraryStage(ctx, libraryJobID, "export", "failed", nil, nil, nil, nil, releaseErr.Error(), time.Now().UTC())
+ _ = store.AdvanceLibraryJob(ctx, libraryJobID, governance.LibraryJobFailed, "export", "dead letter release storage unavailable", "", "", "", time.Now().UTC())
+ return fmt.Errorf("load dead letter releases: %w", releaseErr)
+ }
+ result, err := libraryagent.CaptureReleased(ctx, agentConfig, payload.Scope, payload.CaptureJob, released)
finishedAt := time.Now().UTC()
if err != nil {
// 导出失败时阶段与作业都要留痕;恢复责任在 agent,不会因为作业失败而假装来源已恢复。
diff --git a/internal/governance/library_flow.go b/internal/governance/library_flow.go
index 34f10bd..ed8bb7b 100644
--- a/internal/governance/library_flow.go
+++ b/internal/governance/library_flow.go
@@ -150,3 +150,34 @@ type LibraryReleaseAuthorization struct {
func (a LibraryReleaseAuthorization) ValidAt(now time.Time) bool {
return a.RevokedAt == nil && now.Before(a.ExpiresAt)
}
+
+// LibraryDeadLetterRelease 是治理平台对一条上游死信的精确解除记录。上游行保持原样,
+// 这条记录只说明"这一行已被审计、重放并结清";指纹一变就不再命中。
+type LibraryDeadLetterRelease struct {
+ ID string `json:"id"`
+ Instance string `json:"instance"`
+ TenantID uint64 `json:"tenant_id"`
+ KnowledgeBaseID string `json:"kb_id"`
+ DeadLetterID int64 `json:"dead_letter_id"`
+ Fingerprint string `json:"fingerprint"`
+ TaskType string `json:"task_type"`
+ Scope string `json:"scope"`
+ ScopeID string `json:"scope_id"`
+ RelatedID string `json:"related_id"`
+ ReplayQueue string `json:"replay_queue"`
+ ReplayTaskID string `json:"replay_task_id"`
+ ReplayedAt time.Time `json:"replayed_at"`
+ ReplayEvidence string `json:"replay_evidence"`
+ ObservationDigest string `json:"observation_digest"`
+ Observation json.RawMessage `json:"observation"`
+ Note string `json:"note"`
+ Actor string `json:"actor"`
+ CreatedAt time.Time `json:"created_at"`
+}
+
+// LibraryDeadLetterReleaseID 生成解除记录 ID。同一实例同一指纹永远得到同一个 ID,
+// 重复提交返回已存记录而不是造第二条审计。
+func LibraryDeadLetterReleaseID(instance, fingerprint string) string {
+ sum := sha256.Sum256([]byte(instance + "|" + fingerprint))
+ return "dldr-" + hex.EncodeToString(sum[:])[:24]
+}
diff --git a/internal/httpapi/library_deadletters.go b/internal/httpapi/library_deadletters.go
new file mode 100644
index 0000000..d879fcd
--- /dev/null
+++ b/internal/httpapi/library_deadletters.go
@@ -0,0 +1,104 @@
+package httpapi
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "strings"
+ "time"
+
+ "knowledge-governance/internal/governance"
+ "knowledge-governance/internal/librarydeadletter"
+)
+
+// 死信解除:上游 task_dead_letters 没有"已解决"标记。这里只写治理库的审计记录,
+// 永不删除上游行;解绑的是精确指纹,行一变就不再命中,封存照旧阻断。
+type deadLetterReleaseStore interface {
+ RecordDeadLetterRelease(context.Context, governance.LibraryDeadLetterRelease) (governance.LibraryDeadLetterRelease, bool, error)
+ DeadLetterReleases(context.Context, string, int) ([]governance.LibraryDeadLetterRelease, error)
+}
+
+type deadLetterReleaseRequest struct {
+ DeadLetterID int64 `json:"dead_letter_id"`
+ Replay librarydeadletter.Replay `json:"replay"`
+ Note string `json:"note"`
+ Observation json.RawMessage `json:"observation"`
+ ObservationDigest string `json:"observation_digest"`
+}
+
+func deadLetterReleaseHandlers(w http.ResponseWriter, r *http.Request, config Config) {
+ identity, ok := requireSessionIdentity(w, r)
+ if !ok {
+ return
+ }
+ store, ok := config.Store.(deadLetterReleaseStore)
+ if !ok {
+ writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": "死信解除存储不可用"})
+ return
+ }
+ instance := strings.TrimSpace(config.LibraryTargetInstance)
+ if instance == "" {
+ writeJSON(w, http.StatusServiceUnavailable, map[string]any{
+ "code": "dead_letter_release_unwired", "reason": "未接线:没有配置来源实例身份,无法绑定解除记录",
+ })
+ return
+ }
+ if r.Method == http.MethodGet {
+ releases, err := store.DeadLetterReleases(r.Context(), instance, 100)
+ if err != nil {
+ writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "读取死信解除记录失败"})
+ return
+ }
+ writeJSON(w, http.StatusOK, map[string]any{"instance": instance, "releases": releases})
+ return
+ }
+ // 写操作需要工程师及以上,并要求显式意图头:避免普通点击意外解除。
+ if roleRank(identity.Role) < roleRank(roleEngineer) {
+ writeJSON(w, http.StatusForbidden, map[string]string{"error": "forbidden"})
+ return
+ }
+ if r.Header.Get("X-Governance-Action") != "dead-letter-release" {
+ writeJSON(w, http.StatusForbidden, map[string]string{"error": "write intent required"})
+ return
+ }
+ var request deadLetterReleaseRequest
+ if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20)).Decode(&request); err != nil {
+ writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid request body"})
+ return
+ }
+ now := time.Now().UTC()
+ release, err := librarydeadletter.Verify(librarydeadletter.Request{
+ Project: instance, DeadLetterID: request.DeadLetterID, Replay: request.Replay,
+ Note: request.Note, Observation: request.Observation, Digest: request.ObservationDigest,
+ }, instance, now)
+ if err != nil {
+ writeJSON(w, http.StatusConflict, map[string]any{"code": "dead_letter_release_rejected", "error": err.Error()})
+ return
+ }
+ stored, reused, err := store.RecordDeadLetterRelease(r.Context(), governance.LibraryDeadLetterRelease{
+ ID: governance.LibraryDeadLetterReleaseID(instance, release.Fingerprint),
+ Instance: instance,
+ TenantID: release.TenantID,
+ KnowledgeBaseID: release.KnowledgeBaseID,
+ DeadLetterID: release.DeadLetterID,
+ Fingerprint: release.Fingerprint,
+ TaskType: release.TaskType,
+ Scope: release.Scope,
+ ScopeID: release.ScopeID,
+ RelatedID: release.RelatedID,
+ ReplayQueue: release.Replay.Queue,
+ ReplayTaskID: release.Replay.TaskID,
+ ReplayedAt: release.Replay.At,
+ ReplayEvidence: release.Replay.Evidence,
+ ObservationDigest: release.Digest,
+ Observation: release.Observation,
+ Note: release.Note,
+ Actor: identity.Username,
+ CreatedAt: now,
+ })
+ if err != nil {
+ writeJSON(w, http.StatusConflict, map[string]any{"code": "dead_letter_release_conflict", "error": err.Error()})
+ return
+ }
+ writeJSON(w, http.StatusOK, map[string]any{"release": stored, "reused": reused})
+}
diff --git a/internal/httpapi/library_deadletters_test.go b/internal/httpapi/library_deadletters_test.go
new file mode 100644
index 0000000..75c0769
--- /dev/null
+++ b/internal/httpapi/library_deadletters_test.go
@@ -0,0 +1,114 @@
+package httpapi
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+ "time"
+
+ "knowledge-governance/internal/governance"
+ "knowledge-governance/internal/librarydeadletter"
+)
+
+type deadLetterStoreFake struct {
+ fakeJobStore
+ releases []governance.LibraryDeadLetterRelease
+ recorded int
+}
+
+func (f *deadLetterStoreFake) RecordDeadLetterRelease(_ context.Context, release governance.LibraryDeadLetterRelease) (governance.LibraryDeadLetterRelease, bool, error) {
+ f.recorded++
+ f.releases = append(f.releases, release)
+ return release, false, nil
+}
+
+func (f *deadLetterStoreFake) DeadLetterReleases(context.Context, string, int) ([]governance.LibraryDeadLetterRelease, error) {
+ return f.releases, nil
+}
+
+func deadLetterRequest(t *testing.T, role, action string, body string) *http.Request {
+ t.Helper()
+ request := httptest.NewRequest(http.MethodPost, "/api/v1/library/dead-letter-releases", strings.NewReader(body))
+ request.Header.Set("Content-Type", "application/json")
+ if action != "" {
+ request.Header.Set("X-Governance-Action", action)
+ }
+ return request.WithContext(context.WithValue(request.Context(), sessionKey{}, sessionIdentity{Username: "tester", Role: role}))
+}
+
+const deadLetterRow = `{"id": 7, "payload": {}, "scope": "knowledge", "scope_id": "k1", "failed_at": "2026-10-28T10:00:00+00:00", "last_error": "boom", "task_type": "wiki:ingest", "tenant_id": 10001, "fail_count": 3, "related_id": "k1"}`
+
+func deadLetterBody(t *testing.T, replayAt time.Time) string {
+ t.Helper()
+ observation := librarydeadletter.Observation{
+ Project: "kgmaint-weknora", TenantID: 10001, KnowledgeBaseID: "kb-1",
+ CapturedAt: time.Now().UTC(), Rows: []json.RawMessage{json.RawMessage(deadLetterRow)},
+ }
+ raw, err := json.Marshal(observation)
+ if err != nil {
+ t.Fatal(err)
+ }
+ body, err := json.Marshal(map[string]any{
+ "dead_letter_id": 7, "observation": json.RawMessage(raw),
+ "observation_digest": librarydeadletter.Fingerprint(raw),
+ "replay": map[string]any{"queue": "default", "task_id": "task-1",
+ "at": replayAt.Format(time.RFC3339), "evidence": "run_now 200"},
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ return string(body)
+}
+
+func TestDeadLetterReleaseRequiresIntentAndRole(t *testing.T) {
+ store := &deadLetterStoreFake{}
+ config := Config{Store: store, LibraryTargetInstance: "kgmaint-weknora"}
+ recorder := httptest.NewRecorder()
+ deadLetterReleaseHandlers(recorder, deadLetterRequest(t, roleViewer, "dead-letter-release", deadLetterBody(t, time.Now().Add(-time.Hour))), config)
+ if recorder.Code != http.StatusForbidden || store.recorded != 0 {
+ t.Fatalf("viewer recorded a release: %d %s", recorder.Code, recorder.Body.String())
+ }
+ recorder = httptest.NewRecorder()
+ deadLetterReleaseHandlers(recorder, deadLetterRequest(t, roleEngineer, "", deadLetterBody(t, time.Now().Add(-time.Hour))), config)
+ if recorder.Code != http.StatusForbidden || store.recorded != 0 {
+ t.Fatalf("missing write intent recorded a release: %d", recorder.Code)
+ }
+}
+
+func TestDeadLetterReleaseRefusesUnwiredInstanceAndBadEvidence(t *testing.T) {
+ store := &deadLetterStoreFake{}
+ recorder := httptest.NewRecorder()
+ deadLetterReleaseHandlers(recorder, deadLetterRequest(t, roleEngineer, "dead-letter-release",
+ deadLetterBody(t, time.Now().Add(-time.Hour))), Config{Store: store})
+ if recorder.Code != http.StatusServiceUnavailable {
+ t.Fatalf("unwired instance accepted: %d", recorder.Code)
+ }
+ // 摘要被改写:必须拒绝,而不是"看着像就放过"。
+ config := Config{Store: store, LibraryTargetInstance: "kgmaint-weknora"}
+ broken := strings.Replace(deadLetterBody(t, time.Now().Add(-time.Hour)), "sha256:", "sha256:0", 1)
+ recorder = httptest.NewRecorder()
+ deadLetterReleaseHandlers(recorder, deadLetterRequest(t, roleEngineer, "dead-letter-release", broken), config)
+ if recorder.Code != http.StatusConflict || store.recorded != 0 {
+ t.Fatalf("tampered observation accepted: %d", recorder.Code)
+ }
+}
+
+func TestDeadLetterReleaseRecordsExactFingerprint(t *testing.T) {
+ store := &deadLetterStoreFake{}
+ config := Config{Store: store, LibraryTargetInstance: "kgmaint-weknora"}
+ recorder := httptest.NewRecorder()
+ deadLetterReleaseHandlers(recorder, deadLetterRequest(t, roleEngineer, "dead-letter-release",
+ deadLetterBody(t, time.Now().Add(-30*time.Minute))), config)
+ if recorder.Code != http.StatusOK || store.recorded != 1 {
+ t.Fatalf("release not recorded: %d %s", recorder.Code, recorder.Body.String())
+ }
+ recorded := store.releases[0]
+ if recorded.Actor != "tester" || recorded.Instance != "kgmaint-weknora" ||
+ recorded.Fingerprint != librarydeadletter.Fingerprint([]byte(deadLetterRow)) ||
+ recorded.DeadLetterID != 7 || recorded.ReplayTaskID != "task-1" {
+ t.Fatalf("release lost its audit binding: %+v", recorded)
+ }
+}
diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go
index 5f7fe6c..7b70c85 100644
--- a/internal/httpapi/server.go
+++ b/internal/httpapi/server.go
@@ -432,6 +432,13 @@ func NewHandler(config Config) (http.Handler, error) {
mux.HandleFunc("GET /api/v1/library/captures", func(w http.ResponseWriter, r *http.Request) {
libraryCaptureJobs(w, r, config)
})
+ // 死信解除:只写治理库审计,不删上游行;封存时按精确指纹放行。
+ mux.HandleFunc("GET /api/v1/library/dead-letter-releases", func(w http.ResponseWriter, r *http.Request) {
+ deadLetterReleaseHandlers(w, r, config)
+ })
+ mux.HandleFunc("POST /api/v1/library/dead-letter-releases", func(w http.ResponseWriter, r *http.Request) {
+ deadLetterReleaseHandlers(w, r, config)
+ })
// 整库状态:测试封存 / 生产生效 / 生产预备份 三类版本 + 差异 + 持久作业。
// 归档可能很大:加请求级超时,读不动就明确降级,别让页面请求挂死。
mux.HandleFunc("GET /api/v1/library/overview", func(w http.ResponseWriter, r *http.Request) {
diff --git a/internal/libraryagent/agent.go b/internal/libraryagent/agent.go
index 315b60e..8f9b6a6 100644
--- a/internal/libraryagent/agent.go
+++ b/internal/libraryagent/agent.go
@@ -63,6 +63,9 @@ type request struct {
Action string `json:"action"`
Scope string `json:"scope,omitempty"`
Job string `json:"job,omitempty"`
+ // Released 只允许精确死信指纹(sha256:<64 hex>)。它不改变固定命令形态:
+ // 还能传的只有"这些确切的行已由治理平台审计解除",CLI 会逐字节复核。
+ Released []string `json:"released,omitempty"`
}
type response struct {
@@ -76,6 +79,11 @@ type response struct {
var jobPattern = regexp.MustCompile(`^[A-Za-z0-9_-]{1,64}$`)
+// 死信解除只能按精确指纹传入,不接受通配、实例或任务类型级解除。
+var fingerprintPattern = regexp.MustCompile(`^sha256:[0-9a-f]{64}$`)
+
+const maxReleasedDeadLetters = 64
+
// Agent serves capture requests. Only one operation runs at a time: a library
// capture owns the writer group, so overlapping requests would race the window.
type Agent struct {
@@ -214,6 +222,19 @@ func (a *Agent) execute(ctx context.Context, req request) response {
if req.Job != "" {
args = append(args, "-job", req.Job)
}
+ if len(req.Released) > 0 {
+ if len(req.Released) > maxReleasedDeadLetters {
+ out.Error = "too many released dead-letter fingerprints"
+ return out
+ }
+ for _, fingerprint := range req.Released {
+ if !fingerprintPattern.MatchString(fingerprint) {
+ out.Error = "released dead letters must be sha256:<64 hex> fingerprints"
+ return out
+ }
+ }
+ args = append(args, "-released-dead-letters", strings.Join(req.Released, ","))
+ }
default:
out.Error = "unsupported action"
return out
diff --git a/internal/libraryagent/agent_test.go b/internal/libraryagent/agent_test.go
index 11774d1..15e62d5 100644
--- a/internal/libraryagent/agent_test.go
+++ b/internal/libraryagent/agent_test.go
@@ -380,3 +380,32 @@ func TestAgentPinsTheHostSideObjectEndpoint(t *testing.T) {
}
}
}
+
+// 死信解除只能按精确指纹透传:形状不对就拒绝,且固定命令其余部分不受影响。
+func TestAgentForwardsOnlyExactDeadLetterFingerprints(t *testing.T) {
+ agent, socket, calls := testAgent(t)
+ ctx, cancel := context.WithCancel(context.Background())
+ defer cancel()
+ go func() { _ = agent.Serve(ctx) }()
+ deadline := time.Now().Add(2 * time.Second)
+ for time.Now().Before(deadline) {
+ if conn, err := net.Dial("unix", socket); err == nil {
+ conn.Close()
+ break
+ }
+ time.Sleep(10 * time.Millisecond)
+ }
+ fingerprint := "sha256:" + strings.Repeat("a", 64)
+ ok := roundTrip(t, socket, `{"action":"capture","scope":"internal","job":"j1","released":["`+fingerprint+`"]}`)
+ if !ok.OK {
+ t.Fatalf("exact fingerprint refused: %s", ok.Error)
+ }
+ last := calls()[len(calls())-1]
+ if !strings.Contains(last, "-released-dead-letters "+fingerprint) {
+ t.Fatalf("fingerprint not forwarded: %s", last)
+ }
+ bad := roundTrip(t, socket, `{"action":"capture","scope":"internal","job":"j2","released":["*"]}`)
+ if bad.OK || !strings.Contains(bad.Error, "fingerprints") {
+ t.Fatalf("wildcard release accepted: %+v", bad)
+ }
+}
diff --git a/internal/libraryagent/client.go b/internal/libraryagent/client.go
index a1d2fca..78dba81 100644
--- a/internal/libraryagent/client.go
+++ b/internal/libraryagent/client.go
@@ -29,20 +29,29 @@ type Result struct {
// Capture asks the agent to seal one library scope. The job id makes the call
// idempotent: repeating it returns the already sealed candidate.
func Capture(ctx context.Context, config ClientConfig, scope, job string) (Result, error) {
- return call(ctx, config, map[string]string{"action": "capture", "scope": scope, "job": job})
+ return CaptureReleased(ctx, config, scope, job, nil)
+}
+
+// CaptureReleased 在 Capture 之上带上治理平台已审计的精确死信解除指纹。
+func CaptureReleased(ctx context.Context, config ClientConfig, scope, job string, released []string) (Result, error) {
+ request := map[string]any{"action": "capture", "scope": scope, "job": job}
+ if len(released) > 0 {
+ request["released"] = released
+ }
+ return call(ctx, config, request)
}
// Status probes the agent (source wiring, writer group, archive usage).
func Status(ctx context.Context, config ClientConfig) (Result, error) {
- return call(ctx, config, map[string]string{"action": "status"})
+ return call(ctx, config, map[string]any{"action": "status"})
}
// Recover restores writers from an interrupted freeze journal.
func Recover(ctx context.Context, config ClientConfig) (Result, error) {
- return call(ctx, config, map[string]string{"action": "recover"})
+ return call(ctx, config, map[string]any{"action": "recover"})
}
-func call(ctx context.Context, config ClientConfig, request map[string]string) (Result, error) {
+func call(ctx context.Context, config ClientConfig, request map[string]any) (Result, error) {
if config.Socket == "" {
return Result{}, errors.New("library agent socket is not configured")
}
diff --git a/internal/librarydeadletter/deadletter.go b/internal/librarydeadletter/deadletter.go
new file mode 100644
index 0000000..bf52046
--- /dev/null
+++ b/internal/librarydeadletter/deadletter.go
@@ -0,0 +1,253 @@
+// Package librarydeadletter 定义上游死信(task_dead_letters)的精确解除契约。
+//
+// 为什么需要它:WeKnora v0.7.1 的 task_dead_letters 没有"已解决"标记,导出/封存
+// 按"存在即阻断"处理。上游只提供两种运维动作——整队列 purge 与直接 DELETE,
+// 两者都会销毁"这条任务失败过"的唯一证据,不能当作产品能力。治理平台因此保留
+// 上游原始行,另外记录一条绑定到精确指纹的解除记录:指纹必须与实时行逐字节一致,
+// 行变化或新死信出现都不再命中,继续阻断。
+package librarydeadletter
+
+import (
+ "bytes"
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "strings"
+ "time"
+)
+
+// FingerprintPrefix 让指纹在日志/审计里自解释:算法一旦更换无需猜。
+const FingerprintPrefix = "sha256:"
+
+// Fingerprint 对上游用 to_jsonb(row)::text 取回的行文本求摘要。
+//
+// 为什么按原始行文本而不是逐字段重组:PostgreSQL 的 jsonb 文本已规范化(键有序),
+// 任何字段变化都会改变字节;逐字段重组会漏掉上游新增列,等于给"行被改过"开后门。
+func Fingerprint(raw []byte) string {
+ // 先压紧空白:PostgreSQL 的 to_jsonb::text 带空格,Go 的 json.Marshal 不带,
+ // 两边必须对同一份内容得到同一个指纹,否则解除永远命中不上。
+ compacted := raw
+ if len(raw) > 0 {
+ var buffer bytes.Buffer
+ if err := json.Compact(&buffer, raw); err == nil {
+ compacted = buffer.Bytes()
+ }
+ }
+ sum := sha256.Sum256(compacted)
+ return FingerprintPrefix + hex.EncodeToString(sum[:])
+}
+
+// ValidFingerprint 校验调用方传入的指纹形状,避免把通配符或截断值当解除依据。
+func ValidFingerprint(value string) bool {
+ if !strings.HasPrefix(value, FingerprintPrefix) {
+ return false
+ }
+ body := strings.TrimPrefix(value, FingerprintPrefix)
+ if len(body) != 64 {
+ return false
+ }
+ _, err := hex.DecodeString(body)
+ return err == nil
+}
+
+// Row 是 task_dead_letters 的一行。字段与上游 000041 迁移一致;Payload 保留原始
+// JSON 文本,因为任务参数本身就是证据。
+type Row struct {
+ ID int64 `json:"id"`
+ TenantID uint64 `json:"tenant_id"`
+ TaskType string `json:"task_type"`
+ Scope string `json:"scope"`
+ ScopeID string `json:"scope_id"`
+ RelatedID string `json:"related_id"`
+ Payload json.RawMessage `json:"payload"`
+ LastError string `json:"last_error"`
+ FailCount int `json:"fail_count"`
+ FailedAt time.Time `json:"failed_at"`
+}
+
+// Settlement 只记录与死信无关的两个计数:未完成文档与待办操作。死信单独成表,
+// 由指纹逐条解释,不能用"总数"含糊过去。
+type Settlement struct {
+ Unsettled int64 `json:"unsettled"`
+ PendingOps int64 `json:"pending_ops"`
+}
+
+// Observation 是主机侧(能读源库的一方)生成的只读观测。治理平台不直接连源库,
+// 因此解除记录绑定的是这份观测的摘要:平台重算摘要,换一个字节就不再接受。
+type Observation struct {
+ Project string `json:"project"`
+ TenantID uint64 `json:"tenant_id"`
+ KnowledgeBaseID string `json:"kb_id"`
+ CapturedAt time.Time `json:"captured_at"`
+ Settlement Settlement `json:"settlement"`
+ Rows []json.RawMessage `json:"dead_letters"`
+}
+
+// Replay 记录"真实重放"的引用。平台无法自己向上游发起重放(那需要源侧管理员权限,
+// 属于放大授权),所以只接受可核对的引用,并把"重放之后没有再次失败"作为机器检查项:
+// 同一任务键在重放时间之后若出现新的死信行,解除无效。
+type Replay struct {
+ Queue string `json:"queue"`
+ TaskID string `json:"task_id"`
+ At time.Time `json:"at"`
+ Evidence string `json:"evidence"`
+}
+
+// Request 是创建解除记录的输入。Observation 保持原始字节,摘要按这串字节计算。
+type Request struct {
+ Project string `json:"project"`
+ TenantID uint64 `json:"tenant_id"`
+ KnowledgeBaseID string `json:"kb_id"`
+ DeadLetterID int64 `json:"dead_letter_id"`
+ Replay Replay `json:"replay"`
+ Note string `json:"note"`
+ Observation json.RawMessage `json:"observation"`
+ Digest string `json:"observation_digest"`
+}
+
+// Release 是验证通过后落库的解除记录。
+type Release struct {
+ Project string
+ TenantID uint64
+ KnowledgeBaseID string
+ DeadLetterID int64
+ Fingerprint string
+ TaskType string
+ Scope string
+ ScopeID string
+ RelatedID string
+ Replay Replay
+ Observation json.RawMessage
+ Digest string
+ Note string
+}
+
+// Verify 检查解除请求是否可被接受。它不信任调用方自报的结论:
+// 指纹由观测里的原始行重算,结清计数必须为 0,重放时间必须晚于失败时间,
+// 且同一任务键在重放之后不得再有新的失败行。
+func Verify(req Request, expectedProject string, now time.Time) (Release, error) {
+ if expectedProject == "" {
+ return Release{}, errors.New("死信解除需要平台侧已配置的实例身份")
+ }
+ if req.Project != "" && req.Project != expectedProject {
+ return Release{}, fmt.Errorf("解除记录实例 %q 与当前实例 %q 不一致", req.Project, expectedProject)
+ }
+ if req.DeadLetterID <= 0 {
+ return Release{}, errors.New("dead_letter_id 必须指定一条精确死信")
+ }
+ if len(req.Observation) == 0 || req.Digest == "" {
+ return Release{}, errors.New("缺少源侧观测或摘要")
+ }
+ if got := Fingerprint(req.Observation); got != req.Digest {
+ return Release{}, errors.New("观测摘要与提交的观测不一致(可能被改写或格式化)")
+ }
+ var observation Observation
+ if err := json.Unmarshal(req.Observation, &observation); err != nil {
+ return Release{}, errors.New("源侧观测不是合法 JSON")
+ }
+ if observation.Project != expectedProject {
+ return Release{}, fmt.Errorf("观测实例 %q 与当前实例 %q 不一致", observation.Project, expectedProject)
+ }
+ if observation.Settlement.Unsettled != 0 || observation.Settlement.PendingOps != 0 {
+ return Release{}, fmt.Errorf("源侧尚未结清:未完成文档 %d、待办操作 %d",
+ observation.Settlement.Unsettled, observation.Settlement.PendingOps)
+ }
+ if observation.CapturedAt.IsZero() || observation.CapturedAt.After(now.Add(time.Minute)) {
+ return Release{}, errors.New("源侧观测时间缺失或晚于当前时间")
+ }
+ if req.Replay.Queue == "" || req.Replay.TaskID == "" {
+ return Release{}, errors.New("重放必须给出队列与任务号")
+ }
+ if req.Replay.At.IsZero() {
+ return Release{}, errors.New("重放必须给出实际发生时间")
+ }
+ if req.Replay.At.After(now.Add(time.Minute)) {
+ return Release{}, errors.New("重放时间晚于当前时间")
+ }
+ if req.TenantID != 0 && observation.TenantID != 0 && req.TenantID != observation.TenantID {
+ return Release{}, errors.New("请求租户与观测租户不一致")
+ }
+ if req.KnowledgeBaseID != "" && observation.KnowledgeBaseID != "" && req.KnowledgeBaseID != observation.KnowledgeBaseID {
+ return Release{}, errors.New("请求知识库与观测知识库不一致")
+ }
+
+ var target *Row
+ var targetFingerprint string
+ for _, raw := range observation.Rows {
+ var row Row
+ if err := json.Unmarshal(raw, &row); err != nil {
+ return Release{}, errors.New("观测里的死信行不是合法 JSON")
+ }
+ if row.ID != req.DeadLetterID {
+ continue
+ }
+ if target != nil {
+ return Release{}, errors.New("观测里出现重复的死信 id")
+ }
+ copied := row
+ target = &copied
+ targetFingerprint = Fingerprint(raw)
+ }
+ if target == nil {
+ return Release{}, errors.New("观测里没有这条死信:上游记录可能已被删除,不能用解除掩盖删除")
+ }
+ if target.FailedAt.After(req.Replay.At) {
+ return Release{}, errors.New("重放时间早于这条死信的失败时间")
+ }
+ // 重放失败会再写一条死信行(asynq 中间件对每次耗尽都落一行)。同一任务键在
+ // 重放之后仍有新行,说明重放没有成功,或者又失败了一次。
+ for _, raw := range observation.Rows {
+ var row Row
+ if err := json.Unmarshal(raw, &row); err != nil {
+ return Release{}, errors.New("观测里的死信行不是合法 JSON")
+ }
+ if row.ID == target.ID {
+ continue
+ }
+ if sameKey(row, *target) && row.FailedAt.After(req.Replay.At) {
+ return Release{}, fmt.Errorf("重放之后同一任务仍产生新死信(id=%d),不能解除", row.ID)
+ }
+ }
+ if target.TenantID != observation.TenantID {
+ return Release{}, errors.New("死信租户与观测租户不一致")
+ }
+ return Release{
+ Project: observation.Project,
+ TenantID: target.TenantID,
+ KnowledgeBaseID: observation.KnowledgeBaseID,
+ DeadLetterID: target.ID,
+ Fingerprint: targetFingerprint,
+ TaskType: target.TaskType,
+ Scope: target.Scope,
+ ScopeID: target.ScopeID,
+ RelatedID: target.RelatedID,
+ Replay: req.Replay,
+ Observation: req.Observation,
+ Digest: req.Digest,
+ Note: req.Note,
+ }, nil
+}
+
+func sameKey(a, b Row) bool {
+ return a.TenantID == b.TenantID && a.TaskType == b.TaskType && a.Scope == b.Scope &&
+ a.ScopeID == b.ScopeID && a.RelatedID == b.RelatedID
+}
+
+// Unreleased 返回没有被精确解除记录覆盖的死信指纹。任何一行不匹配都阻断:
+// 行被改过、出现新行、或解除记录缺失,三种情况都必须看得见。
+func Unreleased(rows [][]byte, released map[string]bool) ([]string, error) {
+ missing := make([]string, 0, len(rows))
+ for _, raw := range rows {
+ var row Row
+ if err := json.Unmarshal(raw, &row); err != nil {
+ return nil, errors.New("源库死信行无法解析,按阻断处理")
+ }
+ digest := Fingerprint(raw)
+ if !released[digest] {
+ missing = append(missing, fmt.Sprintf("%d:%s", row.ID, digest))
+ }
+ }
+ return missing, nil
+}
diff --git a/internal/librarydeadletter/deadletter_test.go b/internal/librarydeadletter/deadletter_test.go
new file mode 100644
index 0000000..398bbb4
--- /dev/null
+++ b/internal/librarydeadletter/deadletter_test.go
@@ -0,0 +1,113 @@
+package librarydeadletter
+
+import (
+ "encoding/json"
+ "strings"
+ "testing"
+ "time"
+)
+
+const sampleRow = `{"id": 7, "payload": {"id": "k1"}, "scope": "knowledge", "scope_id": "k1", "failed_at": "2026-10-28T10:00:00+00:00", "last_error": "boom", "task_type": "wiki:ingest", "tenant_id": 10001, "fail_count": 3, "related_id": "k1"}`
+
+func observation(t *testing.T, rows ...string) (json.RawMessage, string) {
+ t.Helper()
+ value := Observation{
+ Project: "kgmaint-weknora", TenantID: 10001, KnowledgeBaseID: "kb-1",
+ CapturedAt: time.Date(2026, 10, 29, 7, 0, 0, 0, time.UTC),
+ Settlement: Settlement{Unsettled: 0, PendingOps: 0},
+ }
+ for _, row := range rows {
+ value.Rows = append(value.Rows, json.RawMessage(row))
+ }
+ raw, err := json.Marshal(value)
+ if err != nil {
+ t.Fatalf("marshal observation: %v", err)
+ }
+ return raw, Fingerprint(raw)
+}
+
+func request(t *testing.T, raw json.RawMessage, digest string) Request {
+ t.Helper()
+ return Request{
+ Project: "kgmaint-weknora", DeadLetterID: 7,
+ Replay: Replay{Queue: "default", TaskID: "task-1", At: time.Date(2026, 10, 29, 6, 30, 0, 0, time.UTC),
+ Evidence: "run_now 200"},
+ Observation: raw, Digest: digest,
+ }
+}
+
+func TestVerifyAcceptsExactReleasedDeadLetter(t *testing.T) {
+ raw, digest := observation(t, sampleRow)
+ release, err := Verify(request(t, raw, digest), "kgmaint-weknora", time.Date(2026, 10, 29, 7, 5, 0, 0, time.UTC))
+ if err != nil {
+ t.Fatalf("exact release rejected: %v", err)
+ }
+ if release.DeadLetterID != 7 || release.Fingerprint != Fingerprint([]byte(sampleRow)) ||
+ release.TaskType != "wiki:ingest" || release.TenantID != 10001 {
+ t.Fatalf("release lost its binding: %+v", release)
+ }
+}
+
+func TestVerifyRejectsUnsafeReleases(t *testing.T) {
+ cases := []struct {
+ name string
+ mutate func(*Request, *Observation)
+ want string
+ }{
+ {"观察摘要被改写", func(r *Request, _ *Observation) { r.Digest = Fingerprint([]byte("other")) }, "观测摘要"},
+ {"未结清", func(_ *Request, o *Observation) { o.Settlement.PendingOps = 1 }, "尚未结清"},
+ {"断言的死信不存在", func(r *Request, _ *Observation) { r.DeadLetterID = 8 }, "没有这条死信"},
+ {"重放早于失败", func(r *Request, _ *Observation) {
+ r.Replay.At = time.Date(2026, 10, 28, 9, 0, 0, 0, time.UTC)
+ }, "早于"},
+ {"重放没有队列", func(r *Request, _ *Observation) { r.Replay.Queue = "" }, "队列"},
+ {"重放后同一任务又失败", func(_ *Request, o *Observation) {
+ o.Rows = append(o.Rows, json.RawMessage(
+ `{"id": 9, "payload": {"id": "k1"}, "scope": "knowledge", "scope_id": "k1", "failed_at": "2026-10-29T06:45:00+00:00", "last_error": "boom", "task_type": "wiki:ingest", "tenant_id": 10001, "fail_count": 3, "related_id": "k1"}`))
+ }, "新死信"},
+ {"实例不一致", func(r *Request, _ *Observation) { r.Project = "other" }, "不一致"},
+ }
+ for _, test := range cases {
+ t.Run(test.name, func(t *testing.T) {
+ raw, digest := observation(t, sampleRow)
+ var body Observation
+ if err := json.Unmarshal(raw, &body); err != nil {
+ t.Fatal(err)
+ }
+ req := request(t, raw, digest)
+ test.mutate(&req, &body)
+ if test.name == "重放后同一任务又失败" || test.name == "未结清" {
+ reserialized, err := json.Marshal(body)
+ if err != nil {
+ t.Fatal(err)
+ }
+ req.Observation, req.Digest = reserialized, Fingerprint(reserialized)
+ }
+ if _, err := Verify(req, "kgmaint-weknora", time.Date(2026, 10, 29, 7, 5, 0, 0, time.UTC)); err == nil ||
+ !strings.Contains(err.Error(), test.want) {
+ t.Fatalf("unsafe release accepted: %v", err)
+ }
+ })
+ }
+}
+
+func TestVerifyRejectsUnconfiguredInstance(t *testing.T) {
+ raw, digest := observation(t, sampleRow)
+ if _, err := Verify(request(t, raw, digest), "", time.Now()); err == nil {
+ t.Fatal("release accepted without a configured instance")
+ }
+}
+
+func TestUnreleasedNamesEveryRow(t *testing.T) {
+ rows := [][]byte{[]byte(sampleRow), []byte(strings.Replace(sampleRow, `"id": 7`, `"id": 8`, 1))}
+ missing, err := Unreleased(rows, map[string]bool{Fingerprint(rows[0]): true})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(missing) != 1 || !strings.HasPrefix(missing[0], "8:sha256:") {
+ t.Fatalf("unexpected coverage: %v", missing)
+ }
+ if _, err := Unreleased([][]byte{[]byte("not json")}, nil); err == nil {
+ t.Fatal("unparseable row was treated as released")
+ }
+}
diff --git a/internal/platform/postgres/library_dead_letters.go b/internal/platform/postgres/library_dead_letters.go
new file mode 100644
index 0000000..bd7960d
--- /dev/null
+++ b/internal/platform/postgres/library_dead_letters.go
@@ -0,0 +1,149 @@
+package postgres
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "time"
+
+ "github.com/jackc/pgx/v5"
+
+ "knowledge-governance/internal/governance"
+)
+
+// 死信解除只写治理库:上游 task_dead_letters 一个字节都不动。为什么这样:
+// 上游没有"已解决"标记,purge/DELETE 会销毁失败证据;治理侧保留审计并绑定
+// 实时行指纹,行变了就不会再命中,阻断自动恢复。
+
+// RecordDeadLetterRelease 幂等写入一条解除记录。同实例同指纹重复提交返回已存记录,
+// 但内容不一致(重放引用/观测摘要不同)必须报冲突,不能悄悄覆盖审计。
+func (s *Store) RecordDeadLetterRelease(ctx context.Context, release governance.LibraryDeadLetterRelease) (governance.LibraryDeadLetterRelease, bool, error) {
+ if release.ID == "" || release.Instance == "" || release.Fingerprint == "" || release.Actor == "" {
+ return governance.LibraryDeadLetterRelease{}, false, errors.New("dead letter release requires identity, fingerprint and actor")
+ }
+ observation := release.Observation
+ if len(observation) == 0 {
+ observation = json.RawMessage(`{}`)
+ }
+ var id string
+ err := s.db.QueryRow(ctx, `
+INSERT INTO library_dead_letter_releases (id, instance, tenant_id, kb_id, dead_letter_id, fingerprint,
+ task_type, scope, scope_id, related_id, replay_queue, replay_task_id, replayed_at, replay_evidence,
+ observation_digest, observation, note, actor, created_at)
+VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19)
+ON CONFLICT (instance, fingerprint) DO NOTHING
+RETURNING id`,
+ release.ID, release.Instance, release.TenantID, release.KnowledgeBaseID, release.DeadLetterID,
+ release.Fingerprint, release.TaskType, release.Scope, release.ScopeID, release.RelatedID,
+ release.ReplayQueue, release.ReplayTaskID, release.ReplayedAt.UTC(), release.ReplayEvidence,
+ release.ObservationDigest, observation, release.Note, release.Actor, release.CreatedAt.UTC()).Scan(&id)
+ if err == nil {
+ stored, loadErr := s.DeadLetterRelease(ctx, id)
+ return stored, false, loadErr
+ }
+ if !errors.Is(err, pgx.ErrNoRows) {
+ return governance.LibraryDeadLetterRelease{}, false, fmt.Errorf("record dead letter release: %w", err)
+ }
+ existing, loadErr := s.deadLetterReleaseByFingerprint(ctx, release.Instance, release.Fingerprint)
+ if loadErr != nil {
+ return governance.LibraryDeadLetterRelease{}, false, loadErr
+ }
+ if existing.ObservationDigest != release.ObservationDigest || existing.ReplayTaskID != release.ReplayTaskID ||
+ !existing.ReplayedAt.Equal(release.ReplayedAt.UTC()) {
+ return existing, false, governance.ErrLibraryJobIdempotencyConflict
+ }
+ return existing, true, nil
+}
+
+func (s *Store) deadLetterReleaseByFingerprint(ctx context.Context, instance, fingerprint string) (governance.LibraryDeadLetterRelease, error) {
+ var id string
+ if err := s.db.QueryRow(ctx, `SELECT id FROM library_dead_letter_releases WHERE instance=$1 AND fingerprint=$2`,
+ instance, fingerprint).Scan(&id); err != nil {
+ if errors.Is(err, pgx.ErrNoRows) {
+ return governance.LibraryDeadLetterRelease{}, errors.New("dead letter release not found")
+ }
+ return governance.LibraryDeadLetterRelease{}, fmt.Errorf("load dead letter release: %w", err)
+ }
+ return s.DeadLetterRelease(ctx, id)
+}
+
+func (s *Store) DeadLetterRelease(ctx context.Context, id string) (governance.LibraryDeadLetterRelease, error) {
+ var release governance.LibraryDeadLetterRelease
+ var observation []byte
+ err := s.db.QueryRow(ctx, `
+SELECT id, instance, tenant_id, kb_id, dead_letter_id, fingerprint, task_type, scope, scope_id, related_id,
+ replay_queue, replay_task_id, replayed_at, replay_evidence, observation_digest, observation, note, actor, created_at
+FROM library_dead_letter_releases WHERE id=$1`, id).Scan(&release.ID, &release.Instance, &release.TenantID,
+ &release.KnowledgeBaseID, &release.DeadLetterID, &release.Fingerprint, &release.TaskType, &release.Scope,
+ &release.ScopeID, &release.RelatedID, &release.ReplayQueue, &release.ReplayTaskID, &release.ReplayedAt,
+ &release.ReplayEvidence, &release.ObservationDigest, &observation, &release.Note, &release.Actor, &release.CreatedAt)
+ if err != nil {
+ if errors.Is(err, pgx.ErrNoRows) {
+ return governance.LibraryDeadLetterRelease{}, err
+ }
+ return governance.LibraryDeadLetterRelease{}, fmt.Errorf("load dead letter release: %w", err)
+ }
+ release.Observation = json.RawMessage(observation)
+ return release, nil
+}
+
+// DeadLetterReleases 按实例倒序列出解除记录(审计视图)。
+func (s *Store) DeadLetterReleases(ctx context.Context, instance string, limit int) ([]governance.LibraryDeadLetterRelease, error) {
+ if instance == "" {
+ return nil, errors.New("dead letter releases require an instance")
+ }
+ if limit <= 0 || limit > 200 {
+ limit = 50
+ }
+ rows, err := s.db.Query(ctx, `
+SELECT id FROM library_dead_letter_releases WHERE instance=$1 ORDER BY created_at DESC LIMIT $2`, instance, limit)
+ if err != nil {
+ return nil, fmt.Errorf("list dead letter releases: %w", err)
+ }
+ defer rows.Close()
+ ids := []string{}
+ for rows.Next() {
+ var id string
+ if err := rows.Scan(&id); err != nil {
+ return nil, fmt.Errorf("list dead letter releases: %w", err)
+ }
+ ids = append(ids, id)
+ }
+ if rows.Err() != nil {
+ return nil, fmt.Errorf("list dead letter releases: %w", rows.Err())
+ }
+ result := make([]governance.LibraryDeadLetterRelease, 0, len(ids))
+ for _, id := range ids {
+ release, loadErr := s.DeadLetterRelease(ctx, id)
+ if loadErr != nil {
+ return nil, loadErr
+ }
+ result = append(result, release)
+ }
+ return result, nil
+}
+
+// DeadLetterReleaseFingerprints 是封存执行侧需要的唯一投影:只给指纹,不给证据。
+// worker 把它原样传给 agent,CLI 再对实时行逐字节复核。
+func (s *Store) DeadLetterReleaseFingerprints(ctx context.Context, instance string) ([]string, error) {
+ if instance == "" {
+ return nil, errors.New("dead letter release fingerprints require an instance")
+ }
+ rows, err := s.db.Query(ctx, `SELECT fingerprint FROM library_dead_letter_releases WHERE instance=$1 ORDER BY created_at`, instance)
+ if err != nil {
+ return nil, fmt.Errorf("list dead letter release fingerprints: %w", err)
+ }
+ defer rows.Close()
+ result := []string{}
+ for rows.Next() {
+ var fingerprint string
+ if err := rows.Scan(&fingerprint); err != nil {
+ return nil, fmt.Errorf("list dead letter release fingerprints: %w", err)
+ }
+ result = append(result, fingerprint)
+ }
+ return result, rows.Err()
+}
+
+var _ = time.Time{}
diff --git a/internal/platform/postgres/migrations/000073_library_dead_letter_releases.down.sql b/internal/platform/postgres/migrations/000073_library_dead_letter_releases.down.sql
new file mode 100644
index 0000000..25e895e
--- /dev/null
+++ b/internal/platform/postgres/migrations/000073_library_dead_letter_releases.down.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS library_dead_letter_releases;
\ No newline at end of file
diff --git a/internal/platform/postgres/migrations/000073_library_dead_letter_releases.up.sql b/internal/platform/postgres/migrations/000073_library_dead_letter_releases.up.sql
new file mode 100644
index 0000000..4c609e3
--- /dev/null
+++ b/internal/platform/postgres/migrations/000073_library_dead_letter_releases.up.sql
@@ -0,0 +1,29 @@
+-- 死信解除:上游 task_dead_letters 没有"已解决"标记,purge/DELETE 都会销毁失败证据。
+-- 这里只记录"某条精确死信已被审计解除",不复制也不删除上游行:解除绑定实时行的
+-- 逐字节指纹、真实重放引用、源侧观测摘要与操作人;行被改过或出现新行都不会命中。
+CREATE TABLE library_dead_letter_releases (
+ id VARCHAR(64) PRIMARY KEY,
+ instance VARCHAR(128) NOT NULL,
+ tenant_id BIGINT NOT NULL,
+ kb_id VARCHAR(64) NOT NULL,
+ dead_letter_id BIGINT NOT NULL,
+ fingerprint VARCHAR(80) NOT NULL,
+ task_type VARCHAR(64) NOT NULL DEFAULT '',
+ scope VARCHAR(32) NOT NULL DEFAULT '',
+ scope_id VARCHAR(64) NOT NULL DEFAULT '',
+ related_id VARCHAR(64) NOT NULL DEFAULT '',
+ replay_queue VARCHAR(64) NOT NULL,
+ replay_task_id VARCHAR(128) NOT NULL,
+ replayed_at TIMESTAMPTZ NOT NULL,
+ replay_evidence TEXT NOT NULL,
+ observation_digest VARCHAR(80) NOT NULL,
+ observation JSONB NOT NULL,
+ note TEXT NOT NULL DEFAULT '',
+ actor VARCHAR(128) NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL,
+ -- 同一个实例里同一条死信只能解除一次;重复提交返回已存记录。
+ UNIQUE (instance, fingerprint)
+);
+
+CREATE INDEX idx_library_dead_letter_releases_instance
+ ON library_dead_letter_releases (instance, created_at DESC);
\ No newline at end of file
diff --git a/internal/platform/postgres/migrations_test.go b/internal/platform/postgres/migrations_test.go
index 6e64155..f0c76f1 100644
--- a/internal/platform/postgres/migrations_test.go
+++ b/internal/platform/postgres/migrations_test.go
@@ -11,35 +11,40 @@ func TestEmbeddedMigrationsAreVersionSorted(t *testing.T) {
if err != nil {
t.Fatalf("loadMigrations() error = %v", err)
}
- if len(migrations) != 72 {
- t.Fatalf("migration count = %d, want 72", len(migrations))
+ if len(migrations) != 73 {
+ t.Fatalf("migration count = %d, want 73", len(migrations))
+ }
+ // 73 记录死信精确解除:保留上游行,只绑定指纹、重放引用与观测摘要。
+ if release := migrations[len(migrations)-1]; release.Version != 73 ||
+ !strings.Contains(release.UpSQL, "library_dead_letter_releases") {
+ t.Fatalf("migration 73 = %#v", release)
}
// 72 让维护占用按实例互斥(internal/external 不再各有各的锁)。
- if instance := migrations[len(migrations)-1]; instance.Version != 72 ||
+ if instance := migrations[len(migrations)-2]; instance.Version != 72 ||
!strings.Contains(instance.UpSQL, "library_instance_maintenance") {
t.Fatalf("migration 72 = %#v", instance)
}
// 71 让维护记录能区分实例级维护与仅治理库互斥。
- if level := migrations[len(migrations)-2]; level.Version != 71 ||
+ if level := migrations[len(migrations)-3]; level.Version != 71 ||
!strings.Contains(level.UpSQL, "level") || !strings.Contains(level.UpSQL, "ingress_state") {
t.Fatalf("migration 71 = %#v", level)
}
- if maint := migrations[len(migrations)-3]; maint.Version != 70 || !strings.Contains(maint.UpSQL, "library_maintenance") {
+ if maint := migrations[len(migrations)-4]; maint.Version != 70 || !strings.Contains(maint.UpSQL, "library_maintenance") {
t.Fatalf("migration 70 = %#v", maint)
}
- if tail := migrations[len(migrations)-4]; tail.Version != 69 ||
+ if tail := migrations[len(migrations)-5]; tail.Version != 69 ||
!strings.Contains(tail.UpSQL, "library_jobs_write_target") {
t.Fatalf("migration 69 = %#v", tail)
}
- if restore := migrations[len(migrations)-5]; restore.Version != 68 || !strings.Contains(restore.UpSQL, "restore") {
+ if restore := migrations[len(migrations)-6]; restore.Version != 68 || !strings.Contains(restore.UpSQL, "restore") {
t.Fatalf("migration 68 = %#v", restore)
}
- if last := migrations[len(migrations)-6]; last.Version != 67 ||
+ if last := migrations[len(migrations)-7]; last.Version != 67 ||
!strings.Contains(last.UpSQL, "library_release_authorizations") ||
!strings.Contains(last.UpSQL, "params_digest") {
t.Fatalf("migration 67 = %#v", last)
}
- if flow := migrations[len(migrations)-7]; flow.Version != 66 ||
+ if flow := migrations[len(migrations)-8]; flow.Version != 66 ||
!strings.Contains(flow.UpSQL, "CREATE TABLE library_versions") ||
!strings.Contains(flow.UpSQL, "library_jobs_active") {
t.Fatalf("migration 66 = %#v", flow)
diff --git a/internal/releaseadapter/v071/library_capture.go b/internal/releaseadapter/v071/library_capture.go
index f3c72bb..51a5425 100644
--- a/internal/releaseadapter/v071/library_capture.go
+++ b/internal/releaseadapter/v071/library_capture.go
@@ -20,6 +20,9 @@ type LibraryCaptureRequest struct {
// it differs from Compatibility, so a model/index change between the
// preflight read and the maintenance window cannot be sealed silently.
VerifyContract func(context.Context) error
+ // ReleasedDeadLetters 是治理平台已审计的精确解除指纹。它只把"这些确切的行"
+ // 从死信阻断里摘出来:实时行必须逐字节命中,否则照旧阻断。
+ ReleasedDeadLetters []string
}
// CaptureLibrary connects maintenance to the actual PG/PIT/object archive path.
@@ -33,7 +36,7 @@ func CaptureLibrary(ctx context.Context, freeze *libraryfreeze.Coordinator, arch
return libraryfreeze.Result{}, errors.New("invalid library capture configuration")
}
result, err := freeze.RunPrepared(ctx, req.JobID, func(ctx context.Context) error {
- if err := checkLibrarySourceSettlement(ctx, db); err != nil {
+ if err := checkLibrarySourceSettlementReleased(ctx, db, req.ReleasedDeadLetters); err != nil {
return err
}
if err := sourceReady(ctx); err != nil {
@@ -41,10 +44,10 @@ func CaptureLibrary(ctx context.Context, freeze *libraryfreeze.Coordinator, arch
}
// Check readiness before a maintenance window, then repeat the export inside
// that window: work can arrive between preflight and the graceful stop.
- _, err := ExportLibrary(ctx, db, req.Identity)
+ _, err := ExportLibraryWithReleases(ctx, db, req.Identity, req.ReleasedDeadLetters)
return err
}, func(ctx context.Context) (string, error) {
- if err := checkLibrarySourceSettlement(ctx, db); err != nil {
+ if err := checkLibrarySourceSettlementReleased(ctx, db, req.ReleasedDeadLetters); err != nil {
return "", err
}
if err := sourceReady(ctx); err != nil {
@@ -55,7 +58,7 @@ func CaptureLibrary(ctx context.Context, freeze *libraryfreeze.Coordinator, arch
return "", err
}
}
- pg, err := ExportLibrary(ctx, db, req.Identity)
+ pg, err := ExportLibraryWithReleases(ctx, db, req.Identity, req.ReleasedDeadLetters)
if err != nil {
return "", err
}
diff --git a/internal/releaseadapter/v071/library_export.go b/internal/releaseadapter/v071/library_export.go
index 7993325..c1ff3c1 100644
--- a/internal/releaseadapter/v071/library_export.go
+++ b/internal/releaseadapter/v071/library_export.go
@@ -15,6 +15,12 @@ type librarySnapshotDB interface {
// It does not certify semantic quality, freeze Elasticsearch/objects, or authorize
// publication. Those require a separately verified, complete library version.
func ExportLibrary(ctx context.Context, db librarySnapshotDB, identity PostgresIdentity) (PostgresSnapshot, error) {
+ return ExportLibraryWithReleases(ctx, db, identity, nil)
+}
+
+// ExportLibraryWithReleases 与 ExportLibrary 相同,但允许调用方带上精确解除的死信
+// 指纹(只影响死信这一项判定,其余结算条件不变)。
+func ExportLibraryWithReleases(ctx context.Context, db librarySnapshotDB, identity PostgresIdentity, released []string) (PostgresSnapshot, error) {
if db == nil || identity.TenantID == 0 || !validSearchIdentifier(identity.KnowledgeBaseID) || identity.KnowledgeID != "" {
return PostgresSnapshot{}, errors.New("invalid library snapshot scope")
}
@@ -40,7 +46,17 @@ func ExportLibrary(ctx context.Context, db librarySnapshotDB, identity PostgresI
return PostgresSnapshot{}, errors.New("read library settlement")
}
if unsettled != 0 || pending != 0 || failed != 0 {
- return PostgresSnapshot{}, errors.New("library has unfinished or failed processing; semantic acceptance is still required after settlement")
+ if failed != 0 && unsettled == 0 && pending == 0 {
+ rows, rowsErr := sourceDeadLetterRows(ctx, tx, identity.TenantID, identity.KnowledgeBaseID)
+ if rowsErr != nil {
+ return PostgresSnapshot{}, rowsErr
+ }
+ if releasedErr := requireReleased(rows, released); releasedErr != nil {
+ return PostgresSnapshot{}, releasedErr
+ }
+ } else {
+ return PostgresSnapshot{}, errors.New("library has unfinished or failed processing; semantic acceptance is still required after settlement")
+ }
}
exporter := PostgresExporter{db: tx}
var snapshot PostgresSnapshot
diff --git a/internal/releaseadapter/v071/library_export_test.go b/internal/releaseadapter/v071/library_export_test.go
index 4293d20..4b8a012 100644
--- a/internal/releaseadapter/v071/library_export_test.go
+++ b/internal/releaseadapter/v071/library_export_test.go
@@ -4,6 +4,7 @@ import (
"context"
"encoding/json"
"errors"
+ "knowledge-governance/internal/librarydeadletter"
"strings"
"testing"
@@ -102,9 +103,16 @@ func (d *libraryFixtureTx) Query(_ context.Context, q string, _ ...any) (pgx.Row
if d.queryError {
return nil, errors.New("fixture failure")
}
+ // 死信行按真实形状返回:解除判定必须逐字节比对指纹,空结果会让"存在即阻断"失效。
+ if strings.Contains(q, "to_jsonb(d)") && d.failed > 0 {
+ return &jsonRows{values: []json.RawMessage{json.RawMessage(fixtureDeadLetter)}}, nil
+ }
return &jsonRows{values: []json.RawMessage{}}, nil
}
+// fixtureDeadLetter 与 PostgreSQL to_jsonb(task_dead_letters) 的键序/形状一致。
+const fixtureDeadLetter = `{"id": 1, "payload": {"knowledge_id": "deleted-doc"}, "scope": "knowledge", "scope_id": "deleted-doc", "failed_at": "2026-10-28T10:00:00+00:00", "last_error": "llm timeout", "task_type": "wiki:ingest", "tenant_id": 10000, "fail_count": 3, "related_id": "deleted-doc"}`
+
type libraryFixtureRow struct {
d *libraryFixtureTx
sql string
@@ -128,3 +136,24 @@ func (r libraryFixtureRow) Scan(dest ...any) error {
}
return nil
}
+
+// 解除只能按精确指纹生效:同一条死信换个字节(或没有解除)都必须继续阻断。
+func TestLibraryExportReleasesOnlyExactDeadLetterFingerprint(t *testing.T) {
+ db := newLibraryFixture()
+ db.tx.failed = 1
+ identity := PostgresIdentity{TenantID: 10000, KnowledgeBaseID: "kb-safe"}
+ if _, err := ExportLibrary(context.Background(), db, identity); err == nil {
+ t.Fatal("unreleased dead letter did not block the export")
+ }
+ if _, err := ExportLibraryWithReleases(context.Background(), db, identity,
+ []string{"sha256:0000000000000000000000000000000000000000000000000000000000000000"}); err == nil {
+ t.Fatal("a stale fingerprint released the dead letter")
+ }
+ released := librarydeadletter.Fingerprint([]byte(fixtureDeadLetter))
+ if _, err := ExportLibraryWithReleases(context.Background(), db, identity, []string{released}); err != nil {
+ t.Fatalf("exact released fingerprint still blocked: %v", err)
+ }
+ if !db.tx.committed {
+ t.Fatal("released export did not commit its snapshot")
+ }
+}
diff --git a/internal/releaseadapter/v071/library_preflight.go b/internal/releaseadapter/v071/library_preflight.go
index abf2f31..2fcad04 100644
--- a/internal/releaseadapter/v071/library_preflight.go
+++ b/internal/releaseadapter/v071/library_preflight.go
@@ -24,6 +24,12 @@ func LibrarySourceSettled(ctx context.Context, db *pgxpool.Pool) error {
return checkLibrarySourceSettlement(ctx, db)
}
+// LibrarySourceSettledWithReleases 是同一检查,但带上治理平台已审计的精确死信解除
+// 指纹:只有逐字节命中的行不再阻断。
+func LibrarySourceSettledWithReleases(ctx context.Context, db *pgxpool.Pool, released []string) error {
+ return checkLibrarySourceSettlementReleased(ctx, db, released)
+}
+
// ValidateLibraryCandidateForPreflight runs the candidate validator used by
// ArchiveLibraryCandidate (identity, bidirectional content coverage, generated
// question coverage, resources and digests) without archiving anything.
diff --git a/internal/releaseadapter/v071/library_source_settlement.go b/internal/releaseadapter/v071/library_source_settlement.go
index 541a317..d5f687a 100644
--- a/internal/releaseadapter/v071/library_source_settlement.go
+++ b/internal/releaseadapter/v071/library_source_settlement.go
@@ -2,9 +2,15 @@ package v071
import (
"context"
+ "encoding/json"
"errors"
+ "fmt"
+ "strings"
+ "time"
"github.com/jackc/pgx/v5"
+
+ "knowledge-governance/internal/librarydeadletter"
)
// A maintenance window stops a shared writer, not a single KB. Check its entire
@@ -13,7 +19,14 @@ import (
// This only establishes recorded processing settlement, never Wiki semantics or
// the absence of unrecorded/remote work; CaptureLibrary still requires the
// deployment's ingress and background-worker readiness callback.
+//
+// 死信不再"存在即阻断":允许调用方带上一组精确解除指纹。每条实时行都要被逐字节
+// 命中,行被改过、出现新行或没有解除记录都仍然阻断。这里不删除任何上游行。
func checkLibrarySourceSettlement(ctx context.Context, db librarySnapshotDB) error {
+ return checkLibrarySourceSettlementReleased(ctx, db, nil)
+}
+
+func checkLibrarySourceSettlementReleased(ctx context.Context, db librarySnapshotDB, released []string) error {
tx, err := db.BeginTx(ctx, pgx.TxOptions{IsoLevel: pgx.RepeatableRead, AccessMode: pgx.ReadOnly})
if err != nil {
return errors.New("begin library source settlement")
@@ -23,16 +36,118 @@ func checkLibrarySourceSettlement(ctx context.Context, db librarySnapshotDB) err
if err := tx.QueryRow(ctx, librarySourceSettlementSQL).Scan(&unsettled, &pending, &failed); err != nil {
return errors.New("read library source settlement")
}
- if unsettled != 0 || pending != 0 || failed != 0 {
+ if unsettled != 0 || pending != 0 {
return errors.New("library source has unfinished or failed processing")
}
+ if failed != 0 {
+ rows, err := sourceDeadLetterRows(ctx, tx, 0, "")
+ if err != nil {
+ return err
+ }
+ if err := requireReleased(rows, released); err != nil {
+ return err
+ }
+ }
if err := tx.Commit(ctx); err != nil {
return errors.New("commit library source settlement")
}
return nil
}
-const librarySourceSettlementSQL = `SELECT /* library-source-settlement */
+const librarySourceSettlementSQL = `SELECT /* library-source-settlement */
(SELECT count(*) FROM knowledges WHERE deleted_at IS NULL AND (parse_status IS DISTINCT FROM 'completed' OR pending_subtasks_count IS NULL OR pending_subtasks_count<>0)),
(SELECT count(*) FROM task_pending_ops),
(SELECT count(*) FROM task_dead_letters)`
+
+// sourceDeadLetterRows 读原始行文本(to_jsonb 已规范化),指纹直接对字节求摘要。
+// tenant=0 表示整库(维护窗口的粒度),否则按知识库范围。
+func sourceDeadLetterRows(ctx context.Context, q interface {
+ Query(context.Context, string, ...any) (pgx.Rows, error)
+}, tenant uint64, kb string) ([][]byte, error) {
+ statement := `SELECT to_jsonb(d)::text FROM task_dead_letters d`
+ args := []any{}
+ if tenant != 0 {
+ statement += ` WHERE d.tenant_id=$1 AND ((d.scope='knowledge_base' AND d.scope_id=$2) OR
+ (d.scope='knowledge' AND d.scope_id IN (SELECT id FROM knowledges WHERE tenant_id=$1 AND knowledge_base_id=$2)))`
+ args = append(args, tenant, kb)
+ }
+ statement += ` ORDER BY d.id`
+ rows, err := q.Query(ctx, statement, args...)
+ if err != nil {
+ return nil, errors.New("read library dead letters")
+ }
+ defer rows.Close()
+ var result [][]byte
+ for rows.Next() {
+ var raw []byte
+ if err := rows.Scan(&raw); err != nil {
+ return nil, errors.New("read library dead letters")
+ }
+ result = append(result, raw)
+ }
+ if rows.Err() != nil {
+ return nil, errors.New("read library dead letters")
+ }
+ return result, nil
+}
+
+func releasedSet(released []string) map[string]bool {
+ set := make(map[string]bool, len(released))
+ for _, fingerprint := range released {
+ set[fingerprint] = true
+ }
+ return set
+}
+
+func requireReleased(rows [][]byte, released []string) error {
+ missing, err := librarydeadletter.Unreleased(rows, releasedSet(released))
+ if err != nil {
+ return err
+ }
+ if len(missing) > 0 {
+ shown := missing
+ if len(shown) > 5 {
+ shown = shown[:5]
+ }
+ return fmt.Errorf("source has %d dead letter(s) without a verified release: %s", len(missing), strings.Join(shown, ", "))
+ }
+ return nil
+}
+
+// ObserveDeadLetters 生成主机侧只读观测:整库结算计数 + 每条死信原始行。
+// 解除记录绑定这份观测的字节摘要,平台侧不复制"自报成功"的结论。
+func ObserveDeadLetters(ctx context.Context, db librarySnapshotDB, project string, tenant uint64, kb string) ([]byte, error) {
+ if project == "" || kb == "" || tenant == 0 {
+ return nil, errors.New("observation requires project, tenant and knowledge base")
+ }
+ tx, err := db.BeginTx(ctx, pgx.TxOptions{IsoLevel: pgx.RepeatableRead, AccessMode: pgx.ReadOnly})
+ if err != nil {
+ return nil, errors.New("begin dead letter observation")
+ }
+ defer tx.Rollback(context.WithoutCancel(ctx))
+ var unsettled, pending, failed int64
+ if err := tx.QueryRow(ctx, librarySourceSettlementSQL).Scan(&unsettled, &pending, &failed); err != nil {
+ return nil, errors.New("read library source settlement")
+ }
+ rows, err := sourceDeadLetterRows(ctx, tx, 0, "")
+ if err != nil {
+ return nil, err
+ }
+ observation := librarydeadletter.Observation{
+ Project: project, TenantID: tenant, KnowledgeBaseID: kb,
+ CapturedAt: time.Now().UTC().Truncate(time.Second),
+ Settlement: librarydeadletter.Settlement{Unsettled: unsettled, PendingOps: pending},
+ Rows: make([]json.RawMessage, 0, len(rows)),
+ }
+ for _, raw := range rows {
+ observation.Rows = append(observation.Rows, json.RawMessage(raw))
+ }
+ payload, err := json.Marshal(observation)
+ if err != nil {
+ return nil, errors.New("encode dead letter observation")
+ }
+ if err := tx.Commit(ctx); err != nil {
+ return nil, errors.New("commit dead letter observation")
+ }
+ return payload, nil
+}
--
2.52.0
From 1aecd9d6af0e2f7e8da6710f9bc73711ecb76e81 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 07:04:45 +0800
Subject: [PATCH 23/45] =?UTF-8?q?fix(library):=20=E8=B5=84=E6=BA=90?=
=?UTF-8?q?=E5=AE=9A=E4=BD=8D=E7=AC=A6=E5=90=8C=E6=97=B6=E6=94=B9=E5=88=B0?=
=?UTF-8?q?=E7=9B=AE=E6=A0=87=E5=AD=98=E5=82=A8=E5=90=8E=E7=AB=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
storage:// 是来源实例 storage_backends 的主键;只换桶不改 id 时,目标原版
应用以 storage backend not found 落回默认服务并拒绝整条路径(真实下载 500
code1007)。写入前按租户+目标桶解析目标后端,写入与校验共用同一份行变换;
解析不到就拒绝写入,不再产出目标读不出来的定位符。
试过:目标实例真实同步后 /api/v1/knowledge/{id}/download 读回 500 → 修后复测;
go test ./internal/releaseadapter/v071 与 make verify 15 项全绿。
---
CHANGELOG.md | 5 ++
.../v071/library_production_target.go | 47 +++++++++++++++++--
internal/releaseadapter/v071/object_import.go | 15 ++++++
.../v071/resource_locator_test.go | 41 +++++++++++++++-
4 files changed, 103 insertions(+), 5 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fa62e17..d231c2d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,6 +26,11 @@
### Fixed
+- **同步过去的资源行指向来源实例的存储后端 id**:`storage:///minio:///`
+ 里的 `` 是来源 `storage_backends` 的主键,目标实例没有这条行。只换桶不改 id 时,
+ 原版应用落回默认存储服务并拒绝整条路径(真实下载 500 `code 1007
+ invalid MinIO file path`)。现在写入前按"租户 + 目标桶名"在目标库解析后端 id,
+ 写入与校验共用同一份行变换;解析不到就拒绝写入,不产出目标读不出来的定位符。
- 指纹对空白敏感会让"同一份内容"两边算不出同一个值(PostgreSQL `to_jsonb::text`
带空格、Go `json.Marshal` 不带);指纹改为先 `json.Compact` 再摘要。
diff --git a/internal/releaseadapter/v071/library_production_target.go b/internal/releaseadapter/v071/library_production_target.go
index 1326138..781221c 100644
--- a/internal/releaseadapter/v071/library_production_target.go
+++ b/internal/releaseadapter/v071/library_production_target.go
@@ -50,9 +50,12 @@ type ProductionLibraryConfig struct {
// ObjectsBucket 是目标对象存储的桶名:资源行里的定位符要换成它,
// 否则同步过去的图/附件仍指向来源桶。
ObjectsBucket string
- MaxDocuments int
- HTTPClient *http.Client
- Now func() time.Time
+ // ObjectsBackendID 是目标实例 storage_backends 的主键。留空则按租户+桶名在
+ // 目标库里解析;定位符里的来源后端 id 在目标实例不存在,原版应用会 500。
+ ObjectsBackendID string
+ MaxDocuments int
+ HTTPClient *http.Client
+ Now func() time.Time
}
func (config ProductionLibraryConfig) validate(scope ProductionScope) error {
@@ -81,6 +84,36 @@ type ProductionLibraryTarget struct {
scope ProductionScope
search *SearchExporter
now func() time.Time
+ // storageBackend 是本次写入使用的目标存储后端 id(写入与校验共用)。
+ storageBackend string
+}
+
+// resolveStorageBackend 在目标库里找本次写入的存储后端。找不到就报错:宁可不写,
+// 也不写一条目标应用读不出来的定位符(上轮就是这样同步"成功"了却下载 500)。
+func (t *ProductionLibraryTarget) resolveStorageBackend(ctx context.Context) error {
+ if t.config.ObjectsBucket == "" {
+ return nil
+ }
+ if t.config.ObjectsBackendID != "" {
+ if !validSearchIdentifier(t.config.ObjectsBackendID) {
+ return errors.New("目标存储后端 id 形状不合法")
+ }
+ t.storageBackend = t.config.ObjectsBackendID
+ return nil
+ }
+ var id string
+ err := t.pool.QueryRow(ctx, `
+SELECT id FROM storage_backends
+WHERE tenant_id=$1 AND coalesce(config->>'bucket_name','')=$2
+ORDER BY created_at LIMIT 1`, t.scope.TenantID, t.config.ObjectsBucket).Scan(&id)
+ if err != nil {
+ return errors.New("目标实例没有与目标桶匹配的存储后端,拒绝写入不可解析的资源定位符")
+ }
+ if !validSearchIdentifier(id) {
+ return errors.New("目标存储后端 id 形状不合法")
+ }
+ t.storageBackend = id
+ return nil
}
func NewProductionLibraryTarget(ctx context.Context, config ProductionLibraryConfig, scope ProductionScope) (*ProductionLibraryTarget, error) {
@@ -223,6 +256,9 @@ func digestIDs(ids []string) string {
// Apply 把一类数据从归档写进生产;database 与 wiki 走同一个知识域事务。
func (t *ProductionLibraryTarget) Apply(ctx context.Context, stage libraryrelease.Stage, snapshotID string) error {
+ if err := t.resolveStorageBackend(ctx); err != nil {
+ return err
+ }
archive, err := librarysnapshot.Open(t.config.ArchiveRoot, 256*1024*1024)
if err != nil {
return errors.New("归档不可用")
@@ -394,7 +430,7 @@ func (t *ProductionLibraryTarget) applyResourceBucket(row map[string]json.RawMes
if err := json.Unmarshal(raw, &locator); err != nil {
return errors.New("资源定位符不可解析")
}
- rewritten, ok := rewriteLocatorBucket(locator, t.config.ObjectsBucket)
+ rewritten, ok := rewriteLocatorTarget(locator, t.storageBackend, t.config.ObjectsBucket)
if !ok {
return fmt.Errorf("资源定位符无法改写到目标桶:%s", locator)
}
@@ -537,6 +573,9 @@ func (t *ProductionLibraryTarget) importIndex(ctx context.Context, archive *libr
// Verify 用行数 + 身份集合摘要 + 索引条数核对生产与预发布快照是否一致。
func (t *ProductionLibraryTarget) Verify(ctx context.Context, expect libraryrelease.Expectation) error {
+ if err := t.resolveStorageBackend(ctx); err != nil {
+ return err
+ }
archive, err := librarysnapshot.Open(t.config.ArchiveRoot, 256*1024*1024)
if err != nil {
return errors.New("归档不可用")
diff --git a/internal/releaseadapter/v071/object_import.go b/internal/releaseadapter/v071/object_import.go
index 728215b..a439a6f 100644
--- a/internal/releaseadapter/v071/object_import.go
+++ b/internal/releaseadapter/v071/object_import.go
@@ -108,6 +108,15 @@ func (importer *ObjectImporter) Promote(ctx context.Context, stage ObjectStage)
// 目标实例之后按这一行去取图/附件时会指向测试环境的桶(跨环境引用),
// 或者干脆取不到。键不变,只换桶。
func rewriteLocatorBucket(locator, bucket string) (string, bool) {
+ return rewriteLocatorTarget(locator, "", bucket)
+}
+
+// rewriteLocatorTarget 同时改写定位符里的存储后端 id 与桶。
+//
+// 为什么后端 id 也要改:storage:///minio:/// 里的 id 是来源实例
+// storage_backends 的主键。目标实例有自己的行;只改桶不改 id,原版应用会以
+// "storage backend not found" 落到默认服务,然后拒绝整条路径(真跑 500 code1007)。
+func rewriteLocatorTarget(locator, backendID, bucket string) (string, bool) {
if bucket == "" || locator == "" || locator != strings.TrimSpace(locator) {
return "", false
}
@@ -122,6 +131,12 @@ func rewriteLocatorBucket(locator, bucket string) (string, bool) {
if parts[1] == "" {
return "", false
}
+ if backendID != "" {
+ if !validSearchIdentifier(backendID) {
+ return "", false
+ }
+ parts[0] = backendID
+ }
prefix, rest = "storage://"+parts[0]+"/", parts[1]
}
separator := strings.Index(rest, "://")
diff --git a/internal/releaseadapter/v071/resource_locator_test.go b/internal/releaseadapter/v071/resource_locator_test.go
index 5fdfaf8..7c3c2bc 100644
--- a/internal/releaseadapter/v071/resource_locator_test.go
+++ b/internal/releaseadapter/v071/resource_locator_test.go
@@ -1,6 +1,9 @@
package v071
-import "testing"
+import (
+ "encoding/json"
+ "testing"
+)
// 同步把字节写进目标桶,但资源行是从快照原样搬的:定位符里写着来源桶时,
// 目标实例之后取图/附件会指向测试环境的桶(跨环境引用)或直接取不到。
@@ -34,3 +37,39 @@ func TestRewriteLocatorBucketKeepsKeyAndSwapsBucket(t *testing.T) {
t.Fatalf("裸键被改写了:%q ok=%v", got, ok)
}
}
+
+// 只换桶不够:storage:// 是来源实例 storage_backends 的主键。目标实例没有这条行时,
+// 原版应用会以 storage backend not found 落到默认服务并拒绝整条路径(真跑 500 code1007),
+// 所以后端 id 必须一起换成本次写入解析到的目标 id。
+func TestRewriteLocatorSwapsStorageBackendWithBucket(t *testing.T) {
+ got, ok := rewriteLocatorTarget("storage://source-backend/minio://kgmaint-1028a/10001/k/ab.md",
+ "target-backend", "kgseal-1029a")
+ if !ok || got != "storage://target-backend/minio://kgseal-1029a/10001/k/ab.md" {
+ t.Fatalf("rewrite=%q ok=%v", got, ok)
+ }
+ // 没有解析到后端时不猜:保留原 id(调用方在没有目标桶时不会走到这里)。
+ got, ok = rewriteLocatorTarget("storage://source-backend/minio://b/k", "", "b2")
+ if !ok || got != "storage://source-backend/minio://b2/k" {
+ t.Fatalf("rewrite without backend=%q ok=%v", got, ok)
+ }
+ if _, ok := rewriteLocatorTarget("storage://x/minio://b/k", "../evil", "b2"); ok {
+ t.Fatal("非法后端 id 被接受了")
+ }
+}
+
+// 行变换用解析到的目标后端与目标桶:写入与校验共用这一份,摘要才不会两边打架。
+func TestResourceRowTransformRewritesBackendAndBucket(t *testing.T) {
+ target := &ProductionLibraryTarget{config: ProductionLibraryConfig{ObjectsBucket: "kgseal-1029a"},
+ storageBackend: "target-backend"}
+ row := map[string]json.RawMessage{"physical_path": json.RawMessage(`"storage://source-backend/minio://kgmaint-1028a/10001/k/ab.md"`)}
+ if err := target.rowTransform("resources")(row); err != nil {
+ t.Fatalf("row transform failed: %v", err)
+ }
+ var got string
+ if err := json.Unmarshal(row["physical_path"], &got); err != nil {
+ t.Fatal(err)
+ }
+ if got != "storage://target-backend/minio://kgseal-1029a/10001/k/ab.md" {
+ t.Fatalf("transform=%q", got)
+ }
+}
--
2.52.0
From c542a1333a869cfe1c8ef855c8e22640a9607419 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 07:08:39 +0800
Subject: [PATCH 24/45] =?UTF-8?q?fix(library):=20=E8=B5=84=E6=BA=90?=
=?UTF-8?q?=E8=A1=8C=E7=9A=84=E5=AD=98=E5=82=A8=E5=90=8E=E7=AB=AF=E5=88=97?=
=?UTF-8?q?=E4=B9=9F=E6=94=B9=E5=88=B0=E7=9B=AE=E6=A0=87=E5=AE=9E=E4=BE=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
原版应用先按 resources.storage_backend_id 找文件服务;只改定位符不改这一列,
目标仍报 storage backend not found 并拒绝整条路径(真实下载 500 code1007)。
行变换同时改写该列,写入与校验共用。
试过:目标同步后 /api/v1/knowledge/{id}/download 500 → 修后复测读回 507B 且
sha256 与源对象一致;go test ./internal/releaseadapter/v071 与 make verify 全绿。
---
CHANGELOG.md | 3 ++-
.../v071/library_production_target.go | 15 +++++++++++++
.../v071/resource_locator_test.go | 21 +++++++++++++++++++
3 files changed, 38 insertions(+), 1 deletion(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d231c2d..7bcdb71 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,11 +26,12 @@
### Fixed
-- **同步过去的资源行指向来源实例的存储后端 id**:`storage:///minio:///`
+- **同步过去的资源行指向来源实例的存储后端 id(定位符与独立列两处)**:`storage:///minio:///`
里的 `` 是来源 `storage_backends` 的主键,目标实例没有这条行。只换桶不改 id 时,
原版应用落回默认存储服务并拒绝整条路径(真实下载 500 `code 1007
invalid MinIO file path`)。现在写入前按"租户 + 目标桶名"在目标库解析后端 id,
写入与校验共用同一份行变换;解析不到就拒绝写入,不产出目标读不出来的定位符。
+ `resources.storage_backend_id` 这一列同样要换(应用先按它找文件服务)。
- 指纹对空白敏感会让"同一份内容"两边算不出同一个值(PostgreSQL `to_jsonb::text`
带空格、Go `json.Marshal` 不带);指纹改为先 `json.Compact` 再摘要。
diff --git a/internal/releaseadapter/v071/library_production_target.go b/internal/releaseadapter/v071/library_production_target.go
index 781221c..79a63fb 100644
--- a/internal/releaseadapter/v071/library_production_target.go
+++ b/internal/releaseadapter/v071/library_production_target.go
@@ -439,6 +439,21 @@ func (t *ProductionLibraryTarget) applyResourceBucket(row map[string]json.RawMes
return err
}
row["physical_path"] = encoded
+ // 原版应用先按 resources.storage_backend_id 找存储后端,再回落到 KB,再落默认服务。
+ // 这一列留着来源 id,目标仍然 500(真跑:storage backend not found → invalid path)。
+ if t.storageBackend == "" {
+ return nil
+ }
+ if raw, ok := row["storage_backend_id"]; ok {
+ var current string
+ if json.Unmarshal(raw, ¤t) == nil && current != "" && current != t.storageBackend {
+ encodedBackend, err := json.Marshal(t.storageBackend)
+ if err != nil {
+ return err
+ }
+ row["storage_backend_id"] = encodedBackend
+ }
+ }
return nil
}
diff --git a/internal/releaseadapter/v071/resource_locator_test.go b/internal/releaseadapter/v071/resource_locator_test.go
index 7c3c2bc..a504e97 100644
--- a/internal/releaseadapter/v071/resource_locator_test.go
+++ b/internal/releaseadapter/v071/resource_locator_test.go
@@ -73,3 +73,24 @@ func TestResourceRowTransformRewritesBackendAndBucket(t *testing.T) {
t.Fatalf("transform=%q", got)
}
}
+
+// 存储后端 id 在 resources 表里还有独立一列:原版应用按它找文件服务。
+// 只改定位符不改这一列,目标仍是 storage backend not found(真跑 500)。
+func TestResourceRowTransformRewritesBackendColumn(t *testing.T) {
+ target := &ProductionLibraryTarget{config: ProductionLibraryConfig{ObjectsBucket: "kgseal-1029a"},
+ storageBackend: "target-backend"}
+ row := map[string]json.RawMessage{
+ "physical_path": json.RawMessage(`"storage://source-backend/minio://kgmaint-1028a/1/k/ab.md"`),
+ "storage_backend_id": json.RawMessage(`"source-backend"`),
+ }
+ if err := target.rowTransform("resources")(row); err != nil {
+ t.Fatalf("row transform failed: %v", err)
+ }
+ var backend string
+ if err := json.Unmarshal(row["storage_backend_id"], &backend); err != nil {
+ t.Fatal(err)
+ }
+ if backend != "target-backend" {
+ t.Fatalf("storage_backend_id=%q", backend)
+ }
+}
--
2.52.0
From e508abd958834d93515e86add2fa2e89a5b09e4c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 07:13:18 +0800
Subject: [PATCH 25/45] =?UTF-8?q?fix(library):=20=E6=AD=BB=E4=BF=A1?=
=?UTF-8?q?=E8=A7=A3=E9=99=A4=E7=BB=91=E5=AE=9A=E5=B0=81=E5=AD=98=E6=BA=90?=
=?UTF-8?q?=E5=AE=9E=E4=BE=8B=E8=80=8C=E4=B8=8D=E6=98=AF=E5=90=8C=E6=AD=A5?=
=?UTF-8?q?=E7=9B=AE=E6=A0=87?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
同步目标与封存源常常不是同一个实例(kgseal vs kgmaint);用目标名去绑来源死信,
真实观测的 project 永远对不上,解除会被一律拒绝。新增 LIBRARY_SOURCE_INSTANCE,
留空回落到目标实例名,API 写记录与 worker 取指纹共用同一个来源实例名。
试过:真实 API GET/POST、go test ./internal/{httpapi,appconfig} 与 make verify 全绿。
---
CHANGELOG.md | 3 +++
cmd/api/main.go | 1 +
cmd/worker/main.go | 2 +-
internal/appconfig/config.go | 15 ++++++++++++++-
internal/httpapi/library_deadletters.go | 2 +-
internal/httpapi/server.go | 11 +++++++++++
6 files changed, 31 insertions(+), 3 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7bcdb71..9fbd316 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,9 @@
### Changed
+- 死信解除绑定 `LIBRARY_SOURCE_INSTANCE`(封存源),留空回落到 `LIBRARY_TARGET_INSTANCE`:
+ 同步目标与封存源常常不是同一个实例,用目标名去绑来源死信会让真实观测永远对不上
+ (拒绝而不是误放行)。worker 取指纹、API 写记录用同一个来源实例名。
- 结算/封存不再"死信存在即阻断",而是"每条实时死信都要被精确解除命中":
`checkLibrarySourceSettlementReleased` / `ExportLibraryWithReleases` 对每条行
重算指纹,未命中、行被改过、出现新行都继续阻断并点名。
diff --git a/cmd/api/main.go b/cmd/api/main.go
index 4b8e8c7..23dad2d 100644
--- a/cmd/api/main.go
+++ b/cmd/api/main.go
@@ -203,6 +203,7 @@ func run(ctx context.Context, getenv func(string) string) error {
VersionHistoryRepo: versionHistoryRepo,
LibraryArchiveRoot: config.LibraryArchiveRoot,
LibraryTargetInstance: config.LibraryTargetInstance,
+ LibrarySourceInstance: config.SourceInstance(),
LibraryAgentSocket: config.LibraryAgentSocket,
LibraryCapacityBudgetBytes: config.LibraryCapacityBudgetBytes,
LibraryProductionDatabaseURL: config.LibraryProductionDatabaseURL,
diff --git a/cmd/worker/main.go b/cmd/worker/main.go
index a8a52df..6e5b1eb 100644
--- a/cmd/worker/main.go
+++ b/cmd/worker/main.go
@@ -278,7 +278,7 @@ func workerHandlers(store *postgresstore.Store, config appconfig.Config) (map[st
}
// 平台审计过的精确死信解除指纹:读取失败必须阻断(fail closed),
// 不能因为存储不可用就静默按"没有解除"或"全部解除"处理。
- released, releaseErr := store.DeadLetterReleaseFingerprints(ctx, config.LibraryTargetInstance)
+ released, releaseErr := store.DeadLetterReleaseFingerprints(ctx, config.SourceInstance())
if releaseErr != nil {
_ = store.UpdateLibraryStage(ctx, libraryJobID, "export", "failed", nil, nil, nil, nil, releaseErr.Error(), time.Now().UTC())
_ = store.AdvanceLibraryJob(ctx, libraryJobID, governance.LibraryJobFailed, "export", "dead letter release storage unavailable", "", "", "", time.Now().UTC())
diff --git a/internal/appconfig/config.go b/internal/appconfig/config.go
index 097703d..1bd8e59 100644
--- a/internal/appconfig/config.go
+++ b/internal/appconfig/config.go
@@ -96,7 +96,10 @@ type Config struct {
LibraryRetentionDays int
// 目标维护(实例级):同步/恢复期间关闭目标入口、停下写入者、排空在途请求。
// 任一项留空即"未接线",生产写入会被拒绝——只锁治理库 scope 不算维护。
- LibraryTargetInstance string
+ LibraryTargetInstance string
+ // LibrarySourceInstance 是死信解除记录绑定的"来源实例"名字(封存源,不是同步目标)。
+ // 留空时回落到 LibraryTargetInstance,保持单实例部署的旧行为。
+ LibrarySourceInstance string
LibraryTargetProject string
LibraryTargetWriters []string
LibraryTargetNonWriters map[string]string
@@ -199,6 +202,7 @@ func Load(getenv func(string) string) (Config, error) {
LibraryProductionS3AccessKey: strings.TrimSpace(getenv("LIBRARY_PRODUCTION_S3_ACCESS_KEY")),
LibraryProductionS3SecretKey: strings.TrimSpace(getenv("LIBRARY_PRODUCTION_S3_SECRET_KEY")),
LibraryTargetInstance: strings.TrimSpace(getenv("LIBRARY_TARGET_INSTANCE")),
+ LibrarySourceInstance: strings.TrimSpace(getenv("LIBRARY_SOURCE_INSTANCE")),
LibraryTargetProject: strings.TrimSpace(getenv("LIBRARY_TARGET_PROJECT")),
LibraryTargetWriters: splitList(getenv("LIBRARY_TARGET_WRITERS")),
LibraryTargetNonWriters: splitDeclarations(getenv("LIBRARY_TARGET_NON_WRITERS")),
@@ -562,3 +566,12 @@ func positiveInt64OrDefault(value string, fallback int64) (int64, error) {
}
return parsed, nil
}
+
+// SourceInstance 是死信解除记录绑定的实例名:封存源与同步目标常常不是同一个实例,
+// 用目标名去绑来源死信会让真实观测永远对不上(拒绝而不是误放行)。
+func (config Config) SourceInstance() string {
+ if config.LibrarySourceInstance != "" {
+ return config.LibrarySourceInstance
+ }
+ return config.LibraryTargetInstance
+}
diff --git a/internal/httpapi/library_deadletters.go b/internal/httpapi/library_deadletters.go
index d879fcd..38efbfd 100644
--- a/internal/httpapi/library_deadletters.go
+++ b/internal/httpapi/library_deadletters.go
@@ -36,7 +36,7 @@ func deadLetterReleaseHandlers(w http.ResponseWriter, r *http.Request, config Co
writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": "死信解除存储不可用"})
return
}
- instance := strings.TrimSpace(config.LibraryTargetInstance)
+ instance := strings.TrimSpace(config.SourceInstance())
if instance == "" {
writeJSON(w, http.StatusServiceUnavailable, map[string]any{
"code": "dead_letter_release_unwired", "reason": "未接线:没有配置来源实例身份,无法绑定解除记录",
diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go
index 7b70c85..caf8b0d 100644
--- a/internal/httpapi/server.go
+++ b/internal/httpapi/server.go
@@ -148,6 +148,8 @@ type Config struct {
// LibraryTargetInstance 是实例级维护的目标实例名;留空即"未接线",
// 页面不能发起按预备份恢复,接口返回原因而不是假装能恢复。
LibraryTargetInstance string
+ // LibrarySourceInstance 是死信解除记录的来源实例名(封存源),留空回落到目标实例名。
+ LibrarySourceInstance string
// LibraryAgentSocket 是主机侧封存 agent 的 unix socket;留空即页面不能发起封存。
LibraryAgentSocket string
// LibraryCapacityBudgetBytes 是整库归档容量预算;0 = 未设置(容量门禁不放行)。
@@ -2807,3 +2809,12 @@ func writeJSON(w http.ResponseWriter, status int, value any) {
w.WriteHeader(status)
_ = json.NewEncoder(w).Encode(value)
}
+
+// SourceInstance 是死信解除记录绑定的实例名:来源实例与同步目标常常不是同一个,
+// 用目标名去绑来源死信会让真实观测永远对不上。
+func (config Config) SourceInstance() string {
+ if config.LibrarySourceInstance != "" {
+ return config.LibrarySourceInstance
+ }
+ return config.LibraryTargetInstance
+}
--
2.52.0
From a06945516fe8de5a41c0bc7ae765627d536fb02d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 07:22:16 +0800
Subject: [PATCH 26/45] =?UTF-8?q?docs(acceptance):=20V03=20=E6=92=A4?=
=?UTF-8?q?=E9=94=80=E8=AF=AD=E4=B9=89=E4=B8=8D=E9=80=9A=E8=BF=87=EF=BC=8C?=
=?UTF-8?q?=E8=A1=A5=20B02/V05/=E6=AD=BB=E4=BF=A1=E5=AE=9E=E6=B5=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
按父审后重跑的真实结果改写验收矩阵:V03-a 单列"失败/不通过"(共享页正文仍带
撤销方独有事实);V05 并发阻断、B02 删源对象后目标应用读回、死信精确解除的
"已做/未演练"分开放;记 R03 实测耗时与正式栈 socket 风险;台账补 0.1.181–0.1.186
与 run 222–227。
---
docs/library-acceptance-matrix.md | 45 ++++++++++++++++++++++++-------
docs/release-ledger.md | 11 ++++++++
2 files changed, 46 insertions(+), 10 deletions(-)
diff --git a/docs/library-acceptance-matrix.md b/docs/library-acceptance-matrix.md
index 955f765..557c443 100644
--- a/docs/library-acceptance-matrix.md
+++ b/docs/library-acceptance-matrix.md
@@ -1,6 +1,7 @@
# 整库同步验收矩阵(真实证据对照,2026-10-29 重排)
本文件是**唯一口径**:状态只写实际发生的事,四类严格分开,不用"部分通过"含糊过去。
+**2026-10-29 父审后重跑:V03-a(Wiki 撤销语义)不通过,单独列在「一·补」,不在「已完成」表里。**
| 口径 | 含义 |
| --- | --- |
@@ -42,28 +43,35 @@ A06(内容、问答、引用图片效果、性能报告)已由用户取消
| D05 | 容量门禁 | `CheckCapacity` + sync gate | 预算未设置→阻断;超预算→阻断并给预计字节 |
| D06 | 测试残留口径 | 未引用 blob 统计 | 真实归档未引用 blob 为 0(口径,不等于扫过全部残留) |
| **S03** | 实例级维护窗口:关入口→排空→静默证明→停写者→写入→校验→开入口 | `internal/libraryfreeze` + `librarymaintenance` + 迁移 070–072 | 前轮 7 场景真跑全绿(normal/kill/applyfail/partial/crossscope/recover_refuse/recover_ok),本轮 sync/drain 场景继续复用;`quiesce` 证据、`post_stop_*`、journal、gate drain.json 均可回看 |
-| **V03-a** | 撤销一份共享贡献后,保留另一份贡献、清除撤销方独有正文/引用/实体边、目录正确 | 由 WeKnora 源侧执行(`cleanupWikiOnKnowledgeDelete` + `EnqueueWikiRetract`),治理侧只比对/搬运 | **本轮真实验收**:kgmaint 隔离实例、原版 API 顺序入库两篇文档 → `entity/fa-bu-zha-men` 同页双来源(2097 字节)→ 真实 `DELETE /api/v1/knowledge/{id}` → 页面保留、来源只剩保留文档、A 独有正文(ZEBRA-A-7731/9910)清除、B 贡献仍在、引用 2→1 且只剩 B 的分块、目录不变、A 独有页面/摘要整页删除、索引页不再列出、实体边无死链。13/13 检查通过。证据:`kg-candidate-e2e/evidence-wiki-final/s8-final-checks-r1.json` + `06-wiki-*-r1.json` + `s3/s6-db-*.json` |
| **V03-b** | 治理侧能把上述语义变化说清楚(不是页面级"无变化") | `internal/librarydiff/wiki.go` `CompareWiki`;`GET /library/overview` 的 `diff.wiki` | 逐页比对正文/来源/引用/出入边/目录,输出 `sources_removed`、`citations_before→after`、`changed`;单测 `wiki_test.go`、视图单测 `library_wiki_diff_test.go`;页面逐行展示(`wikiContributionLines` + 测试) |
-| **S06** | 页面/API 发起封存 → 主机 agent → 实例级窗口封存(真实冻结) | `POST /library/captures` + `cmd/libraryagent`(0600 socket、固定命令)+ `libraryctl capture`(实例级:闸门/后台静默/指纹) | **本轮真跑**:`POST /api/v1/library/captures`(job `lib-internal-20261029T0614`)202 → worker → agent → CLI → 关闸门排空 → 等后台静默 → 停 `kgmaint-app`(exit=1 但入口已排空,`drain_verified=true`)→ 导出 → 恢复写入者与入口;作业 `libseal-…` succeeded,快照 `1196c518…`。证据 `kg-capture-loop/evidence/04-inflight-capture.json`、journal `freeze-kgmaint/lib-internal-20261029T0614.json` |
-| **S06-a** | 排空证明取自真实在途请求(不靠 202 后抢时序) | 闸门 `drain.json` + 客户端真实上传握手 | **本轮真跑**:先发一半 multipart 正文 → 闸门日志 `conn:open active=1` → 再发起封存 → 入口关闭(拒绝新连接)→ 补完正文,应用 200 并完成解析/嵌入 → `drain.json phase=drained active_at_close=1 served=126 drain_ms=302`;窗口 `quiesce.samples=18 stable_ms=1617` 且停写者后指纹不变。同一次窗口里派生任务真的跑完(探针文档 `de475a32…` completed / 10 分块) |
-| **V03-c** | 带"撤销后共享页"的整库封存 → 独立目标同步 → 恢复,逐项真实读回 | `libraryctl` 封存 + `ProductionLibraryTarget` + `libraryrelease` | **本轮真跑**:源 kgmaint 撤销后 KB `e64e82b5`(9 Wiki 页、1 文档、2 分块、1 资源)→ 快照 `1196c518…` 与源逐页比对全部一致(正文 md5/来源/引用/目录/18 条边)→ 同步到**独立实例** kgseal(自己的 PG/索引/桶,非同一份存储)`libsync-internal-1793226278273693890` succeeded+verify succeeded → 目标逐页/索引/资源字节一致(`07-target-compare.json`,`ok=true`,目标桶对象 sha256 与源一致)→ 人为偏离(删整库 Wiki 页)→ `librestore-internal-1793226571284097366-retry` succeeded → 目标回到与快照逐项一致(同一份 `07-target-compare.json` 摘要,`ok=true`) |
+| **S06** | 页面/API 发起封存 → 主机 agent → 实例级窗口封存(真实冻结) | `POST /library/captures` + `cmd/libraryagent`(0600 socket、固定命令)+ `libraryctl capture`(实例级:闸门/后台静默/指纹) | **本轮终态(0.1.186 e508abd)真跑**:`POST /api/v1/library/captures`(job `lib-internal-20261029T0716`)202 → worker → agent → CLI → 关闸门排空 → 等后台静默 → 停 `kgmaint-app`(exit=1、`drain_verified=true`、`stop_verified=true`、`restored=true`)→ 导出 → 恢复写入者与入口;作业 `libseal-lib-internal-20261029T0716` succeeded,快照 `0f0a3b68…`。证据 `kg-final-gaps/evidence/04-inflight-v05-final.json`、journal `freeze-kgmaint/lib-internal-20261029T0716.json` |
+| **S06-a** | 排空证明取自真实在途请求(不靠 202 后抢时序) | 闸门 `drain.json` + 客户端真实上传握手 | **本轮终态真跑**:先发一半 multipart 正文 → 闸门 `conn:open active=1` → 再发起封存 → 入口关闭 → 补完正文,应用 200 并完成解析/嵌入 → `drain.json phase=drained active_at_close=1 served=143 drain_ms=352`;journal `quiesce.samples=18 stable_ms=1617` 且停写者后指纹不变(`post_stop_digest` == `digest`)。窗口内派生任务真的跑完(探针文档 `f7fed988…` completed / 7 分块),且该文档出现在被封存的快照里 |
+| **V03-c** | 带"撤销后共享页"的整库封存 → 独立目标同步 → 恢复,逐项真实读回 | `libraryctl` 封存 + `ProductionLibraryTarget` + `libraryrelease` | **本轮终态真跑(字节一致性,不是撤销语义)**:KB `e64e82b5`(9 Wiki 页、1 文档、2 分块、1 资源)→ 快照 `0f0a3b68…` 与源逐页一致(`05-snapshot-compare.json` ok=True)→ 同步到独立实例 kgseal `libsync-internal-1793229249632461601` succeeded → 目标逐页/索引/资源字节一致(`07-target-compare.json` ok=True,含目标桶对象 sha256)→ `librestore-internal-1793229274077866298` succeeded → 目标仍逐项一致。**注意**:该共享页正文仍带撤销方残留(见 V03-a 不通过),本行只证明"搬运/恢复逐字节一致" |
| **S06-b** | 主机侧封存/恢复必须与 worker 讲同一份维护声明 | `internal/librarymaintenance/env.go`(`LIBRARY_TARGET_*` 唯一解析处) | 缺项时 `capture` 在开窗口前拒绝并点名;agent 启动打印维护目标;单测 5 项(逐项缺失/空白/口令空格/队列库号) |
| **Neo4j 启用场景** | 启用图谱的库必须被真实拒绝 | `v071/library_export.go` 读 `indexing_strategy.graph_enabled` | **本轮真跑**:在 kgmaint 建 `graph_enabled=true` 的真实 KB `8de41ca7…`,用真实 CLI 预检 → 退出码 1、`LIBRARYCTL_FAILED: Neo4j graph snapshot is not supported`(`evidence/10-neo4j-refuse.txt`)。不是 skip |
| **U04** | 维护级别/进度/恢复错误真实呈现 | `MaintenanceCard`(`web/src/ReleaseTargets.tsx`)、`/api/v1/library/maintenance` | 显示实例级/库级、持有 scope+作业、阶段、入口开/关、服务、开始/释放、进度(阶段名中文化)、恢复错误与处理记录;仅"窗口仍持有且作业失败"时给"按预备份恢复";无记录时"未接入 + fail closed"。组件测试 6 项 |
+| **V05** | 导出中源变更必须被入口/写入者阻断,切点一致 | 闸门 `drain.json` + 真实并发客户端 | **本轮终态真跑**:入口关闭的同一刻(固定协调点,非 sleep)对专用源发 8 写 + 4 读 → 8 写全部失败(7 `URLError`/1 `RemoteDisconnected`)、4 读 `RemoteDisconnected`;写入者被停下的那一刻(轮询容器状态捕获 `running→exited→running`)再发 4 写 + 2 读 → 全部 `URLError`。事后源库 `v05` 文档 0 / 分块 0,快照与源逐项一致(ok=True),在途文档 `f7fed988…` completed/7 分块且出现在快照里。证据 `04-inflight-v05-final.json` |
+| **B02** | 源测试桶删对象后,归档自包含且目标应用能读回同样字节 | 归档 `resource` 部件 + 目标应用下载接口 | **本轮终态真跑**:源对象 `10001/d4fbe69d…/ab2b628f….md`(507B,sha256 `25a55cd8…`)先备份再 `mc rm`(stat 已 404)→ 同步仍 succeeded(字节只可能来自归档)→ 目标桶 `kgseal-1029a` 同键 507B、sha256 一致 → **目标应用自己的** `GET /api/v1/knowledge/{id}/download` 恢复前后都 200 / 507B / sha256 `25a55cd8…`。修复前该接口真实 500(`code 1007 invalid MinIO file path`),见 0.1.184/0.1.185 两条修复。证据 `11-b02-delete-and-sync.json`、`12-b02-restore-download.json`、`07-target-compare.json` |
+| **死信精确解除(治理侧)** | 保留上游死信行,只按精确指纹解除 | 迁移 073 + `internal/librarydeadletter` + `POST/GET /library/dead-letter-releases` + `libraryctl dead-letters` + `-released-dead-letters` | **已实现并有真实验证的部分**:`libraryctl dead-letters` 在真实源上读出 0 条死信与观测摘要;治理 API `GET` 返回 `instance=kgmaint-weknora`、`releases=[]`;`POST` 无写意图头 403;带真实观测但引用不存在的死信 → 409「观测里没有这条死信」。单测覆盖:摘要被改写、源侧未结清、重放早于失败、重放后又出现同键新死信、实例不一致、通配指纹。**未演练**:真实死信→重放→解除→放行(本轮没有死信,也没有源侧管理员凭据) |
+
+## 一·补 失败 / 不通过(不得标通过)
+
+| ID | 要点 | 承载位置 | 本轮真实结果 |
+| --- | --- | --- | --- |
+| **V03-a** | 撤销一份共享贡献后,保留另一份贡献、清除撤销方独有正文/引用/实体边、目录正确 | 由 WeKnora 源侧执行(`cleanupWikiOnKnowledgeDelete` + `EnqueueWikiRetract`),治理侧只比对/搬运 | **本轮不通过(2026-10-29 重跑)**:真实 `DELETE /api/v1/knowledge/{id}` 后,共享页 `entity/fa-bu-zha-men` 的来源/引用/边/目录都按上游 retract 更新(source_refs 只剩保留文档、引用 2→1、9 页/18 边无死链),**但正文仍保留撤销方独有的两句事实 `ZEBRA-A-7731`/`ZEBRA-A-9910`**(version=3、3733 字节、sha256 `5fd27348…`)。封存逐字节一致只说明"存了真实状态",不等于撤销语义通过。证据 `kg-final-gaps/evidence/14-wiki-residue-evidence.json` + `01-wiki-source-after-r3.json` |
+
## 二、缺代码
| ID | 缺口 | 现状与影响 |
| --- | --- | --- |
-| R03 | 存快/恢复快对比 | 没有测速实现,也未测。不写没有测量的数字 |
-| 死信解除契约 | 死信只能靠人工清理,没有"解除/豁免"契约 | WeKnora `task_dead_letters` 无解决标记;导出/封存按"存在即阻断"(`library_source_settlement.go`)。本轮真实验证:早期错误模型配置产生的 2 条 wiki 死信直接阻断整实例结算,清理方式只能是删除行(记录:`deadletters-before-delete.json`,sha256 `dd4d8f08…`)。要变成可运维契约,需要上游给出解决标记或治理侧设计"带证据的解除"——**未实现**。本轮未再新增死信,没有用它绕过任何一项;仍需的最小外部契约见第五节第 5 条 |
+| R03 | 存快/恢复快对比 | A06 性能报告已由用户取消,不作为门槛。**已记实测耗时**(小测试库,不是压测):封存 15.8s(含停写~5s)、同步 13.6s(预备份 13.4s 占主要)、恢复 13.8s;证据 `13-r03-durations.json`。没有做高负载压测,也不写没有测量的数字 |
+| 死信解除·真实重放演练 | 没有可解除的真实死信,也没有源侧系统管理员凭据 | 契约与执行侧已实现(见下节新增行):上游保留原行、治理侧审计+指纹绑定、未结清/变化/新死信仍阻断。**本轮没有真实死信**(`dead_letters=0`),无法演练"真实重放成功→解除→放行"整条链路;上游只有 `系统管理 runtime run_now`(需要源侧管理员权限)与整队列 purge(销毁证据,不采用)。治理平台故意不持有源侧管理员凭据(放大授权),因此这一步**阻塞在真实死信 + 重放执行方**,不伪造成功 |
## 三、已实现·未跑
| ID | 要点 | 为什么未跑 |
| --- | --- | --- |
-| V05 | 导出中源变更则拒绝或隔离 | 预备份导出前后行数静默检查已有(本机验证会拒绝);真实并发写入的隔离演练未做 |
-| B02 | 资源在测试侧删除后仍可恢复 | 归档内容寻址已实现;"删测试侧对象再从归档恢复"实测未做 |
| S03-b | 死信/孤儿任务阻断的负向演练(本轮只验证了真实死信阻断) | 真实阻断已发生并记录;系统化的负向矩阵未跑 |
| 排空时序(历史结论) | 旧做法"202 之后抢时序上传"在 1faf513 上重跑 6 次全部 `Broken pipe`(`drain-task-final-1faf513*.json` 保留,不记通过) | 已被 S06-a 的确定性做法取代:先证明请求已被闸门接收,再启动维护。旧证据保留,不覆盖 |
| U05 | 正式 8088 页面验收 | 正式栈仍是 0.1.114,本轮未替换;维护面板/逐页 Wiki 差异只在测试与候选构建里验证过 |
@@ -77,12 +85,29 @@ A06(内容、问答、引用图片效果、性能报告)已由用户取消
| 生产目标维护 | 对共享业务栈开维护窗口 | 本轮明确不停 `WKNFull-app`;维护只在 kgmaint 专用实例上跑 |
| 生产封存/同步真实链路 | 需要在生产机部署 `libraryagent` 并接线 | 需要用户批准的部署窗口与凭据录入 |
+### 四·补 运维风险(本轮核对,未擅自处理)
+
+正式 8088 栈(`knowledge-governance-p1-api-1` / `-worker-1`)**当前引用同一个 agent socket**:
+api env `LIBRARY_AGENT_SOCKET=/run/library-agent/agent.sock`,worker 挂载
+`/home/zheromiku/.local/share/knowledge-governance/agent -> /run/library-agent`。而主机侧 user 单元
+`~/.config/systemd/user/knowledge-governance-library-agent.service` 本轮已把目标改成 kgmaint 验收实例
+(`-source-app kgmaint-app`、`-project kgmaint-weknora`、`-archive /tmp/kg-e2e/archive`,
+原 WKNFull 版备份为 `*.wkfull.bak`)。后果:**从正式 8088 发起封存会冻结测试实例,并把快照写进
+正式 API 看不到的归档目录**(正式 api 的 `LIBRARY_ARCHIVE_ROOT=/var/lib/knowledge-governance/library`)。
+本轮没有启动任何共享维护,也没有改回该单元——需要用户决定:正式上线前把单元恢复为 WKNFull 版
+(备份已在位),或给候选构建单独的 socket 路径。证据 `00-identity-final.json` 的 `formal_stack` 段。
+
+另外:`knowledge-governance-p1-release-worker-1` 自 2026-10-10 起就在崩溃重启(`exit=1`、
+`RestartCount≈1233`,日志只有 `connect release target database`),与本轮改动无关(它没有挂 agent socket),
+但正式栈的发布 worker 实际不可用,需要单独处理。
+
---
## 五、本轮新增结论(写在这里而不是报告顶部)
-1. **Wiki 撤销语义是上游行为,必须用上游 API 验**:顺序入库才产生"两篇共贡献一页"(并行入库会各自抽到不同 slug 生成两页,这是上游已知行为)。撤销后页面保留、贡献按文档摘除,12 项检查全部通过。
+1. **Wiki 撤销语义本轮不通过,且不是治理侧能自己补的**:上游 retract 走 LLM 重写,重跑一次留下两句撤销方独有事实(`ZEBRA-A-7731`/`ZEBRA-A-9910`),另有 r1 轮次把两句清掉的记录——同一输入两次结果不同。原版 v0.7.1 的 Wiki API 只有页 CRUD、`rebuild-links`(只重算 `[[slug]]` 边,metadata-only)、`auto-fix`(只修 lint 可修项),**没有"按剩余来源重算页面正文"的安全 API**(`internal/router/router.go:2354` 起的路由表 + `service/wiki_page.go:759`)。因此:①不得把 V03 标通过;②不得用关键词硬删掩盖;③可选方案见交付报告(外部最小治理:保留旧版本+关联撤销作业+受影响页重建或阻断发布+验证与审计,需用户拍板产品语义)。
2. **治理侧不能只报页面级差异**:撤销共享贡献时页面仍是"更新",页面级计数会显示成"无变化"。已改为逐页语义比对,能指出"来源 -1、引用 2→1、正文变了、出边少了一条"。
3. **封存链路本轮真的打通了,而且不是放松校验**:CLI 改为实例级窗口(闸门 + 后台静默 + 目标指纹),"写者 exit=1"由闸门的 `drained/active_at_close` 证据解释,而不是被忽略;排空证明改成"先在途、再关入口"的确定性顺序,不再靠 202 之后抢时序。
4. **接线后暴露的四个真缺陷(都已修,都有用例)**:`jobs.id` 列宽 36 让封存作业根本投不进去;v0.7.1 的 app 写索引不带 `tenant_id` 导致导出 0 条;全新实例的空索引被当成"索引被改坏";恢复作业 id 带 `.` 被维护窗口拒。另有资源定位符仍写来源桶——同步过去的目标取不到图/附件。
-5. **死信解除仍缺产品路径,最小外部契约如下(未实现,不冒充)**:①保留原始死信行与错误证据,不做删除;②解除必须在治理侧留下审计记录(谁、何时、依据哪条证据、绑定哪个实例/库/任务指纹);③只有在"重放该任务并成功、且源侧结清"之后才允许解除,解除记录挂在精确项上(不允许按实例或通配解除);④未解除的死信继续阻断结算与封存。本轮没有新增死信,也没有用它绕过任何门槛。
\ No newline at end of file
+5. **死信解除已从"缺代码"变成"有代码、真实验证了一半"**:迁移 073 记录精确解除(保留上游行、绑定实时行指纹、重放引用、源侧观测摘要、操作人);封存时每条实时死信都必须被精确解除命中,行变化/新行/未结清照旧阻断;`libraryctl dead-letters` 生成只读观测,`libraryctl -released-dead-letters` 逐字节复核。**没有演练的部分**是"真实死信→重放→解除→放行":本轮源侧 `dead_letters=0`,且重放需要源侧系统管理员权限(`/system/admin/runtime/queues/{queue}/tasks/{id}/actions/run_now`),治理平台故意不持有该凭据。不伪造成功,也不 SQL 删行冒充。
+6. **同步过去的资源"能被应用读出来"是这轮才真正验的**:资源行里既有 `physical_path` 也有独立的 `storage_backend_id` 列,两者都指向来源实例的 `storage_backends` 主键;只换桶或不换列,目标应用都 500(`code 1007 invalid MinIO file path`)。已在同一份行变换里同时改后端 id 与桶,解析不到就拒绝写入。
\ No newline at end of file
diff --git a/docs/release-ledger.md b/docs/release-ledger.md
index fa707c8..df03124 100644
--- a/docs/release-ledger.md
+++ b/docs/release-ledger.md
@@ -80,6 +80,17 @@ run164 因 qawemail 依赖外网 DNS 失败,已修,不涂改。
| 0.1.178 | 2e39e495 | 移出一次性核对小工具 | 219 | **success** | 否 |
| 0.1.179 | b061a968 | 资源换桶变换在校验时同用(**封存闭环验收代码 SHA**) | 220 | **success** | 否 |
| 0.1.180 | a6406209 | 恢复作业 id 改成维护窗口可接受的形状 | 221 | **success** | 否 |
+| 0.1.181 | bc49b85 | 文档:封存闭环进"已完成"、补死信最小外部契约 | 222 | **success** | 否 |
+| 0.1.182 | 958292d | 文档:按实际运行的二进制记封存闭环时序 | 223 | **success** | 否 |
+| 0.1.183 | c2402947 | 死信按精确指纹解除(保留上游行、审计、指纹绑定) | 224 | **success** | 否 |
+| 0.1.184 | 1aecd9d6 | 资源定位符同时改到目标存储后端 | 225 | **success** | 否 |
+| 0.1.185 | c542a133 | 资源行 storage_backend_id 列也改到目标实例 | 226 | **success** | 否 |
+| 0.1.186 | e508abd9 | 死信解除绑定封存源实例(LIBRARY_SOURCE_INSTANCE) | 227 | **success** | 否 |
+
+本轮(父审后)真实验收运行的最终代码 SHA 是 **0.1.186(e508abd9)**:封存→同步→恢复、
+B02 删源对象后目标应用读回、V05 并发阻断都在这一份构建上跑完(PID/exe/revision 绑定见
+`kg-final-gaps/evidence/00-identity-final.json`)。0.1.181–0.1.183 是同一轮内的连续修复,
+不作为最终验收 SHA。CI run 204(958292d,本轮起点)success。
封存闭环的运行时序(按实际运行的二进制记):封存 API→agent→冻结出快照在 **0.1.175(84e8a0d)**;
首次同步成功在 **0.1.179(b061a968)**;恢复与最终逐项读回在 **0.1.180(a6406209)**。
--
2.52.0
From 47eb23cf6873e3c3487ef3b07cbfd547e43dd5f9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 13:01:37 +0800
Subject: [PATCH 27/45] =?UTF-8?q?feat(library):=20=E5=B0=81=E5=AD=98?=
=?UTF-8?q?=E6=89=A7=E8=A1=8C=E5=99=A8=E5=8F=AF=E7=94=A8=E6=80=A7=E4=B8=8E?=
=?UTF-8?q?=E8=BF=98=E5=8E=9F=E6=9D=A1=E4=BB=B6=E6=9D=A5=E8=87=AA=E7=9C=9F?=
=?UTF-8?q?=E5=AE=9E=E8=A7=82=E6=B5=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
页面上的"可发起封存"原来只判 LIBRARY_AGENT_SOCKET 非空:正式栈的 API 根本没挂
那个 socket,而 agent 曾顶着正式单元名冻结候选实例——配置非空、页面可点、真发起
却封错库。
现在:agent 新增 health 动作(不占封存操作锁、不跑子进程,只回答身份/降级/忙),
worker 每 30 秒探测并写入迁移 074 的 library_executor_status;overview、快照列表与
POST /library/captures 共用同一份判定(过期、不可达、实例不符、降级、正忙都拒绝并
给原因)。封存结果由 agent 附上自报身份,worker 在停写入者之前再探测一次、执行后
用结果复核,不一致就不登记测试封存——心跳只能证明"刚才"。
期望身份用 LIBRARY_SOURCE_*(封存源),不是 LIBRARY_TARGET_*(同步目标),否则
正确的执行器会被判成不匹配。另加 GET /library/restore-availability:恢复能否执行由
双闸、该快照的恢复授权与实例维护状态决定,页面不再写死 disabled。
真跑(候选隔离栈,两处 socket 隔离不变):overview 返回 executor
{kgmaint-weknora/kgmaint-app};停 agent 后转不可达并 503 带原因;重启后恢复。
---
api/openapi.yaml | 45 +++++
cmd/api/main.go | 2 +
cmd/worker/library_capture_identity.go | 89 +++++++++
cmd/worker/library_capture_identity_test.go | 98 ++++++++++
cmd/worker/library_executor_status.go | 52 +++++
cmd/worker/main.go | 33 ++--
internal/appconfig/config.go | 31 ++-
internal/httpapi/library_capture.go | 18 +-
internal/httpapi/library_capture_test.go | 31 +--
internal/httpapi/library_executor.go | 77 ++++++++
internal/httpapi/library_executor_test.go | 184 ++++++++++++++++++
internal/httpapi/library_flow.go | 11 +-
internal/httpapi/library_restore.go | 58 ++++++
internal/httpapi/library_snapshots.go | 9 +-
internal/httpapi/server.go | 9 +
internal/httpapi/server_test.go | 51 ++---
internal/libraryagent/agent.go | 114 +++++++++--
internal/libraryagent/client.go | 6 +
internal/libraryagent/health_test.go | 108 ++++++++++
internal/libraryexecutor/executor.go | 122 ++++++++++++
internal/libraryexecutor/executor_test.go | 133 +++++++++++++
.../postgres/library_executor_status.go | 71 +++++++
...ibrary_executor_status_integration_test.go | 70 +++++++
.../000074_library_executor_status.down.sql | 1 +
.../000074_library_executor_status.up.sql | 16 ++
internal/platform/postgres/migrations_test.go | 25 ++-
26 files changed, 1351 insertions(+), 113 deletions(-)
create mode 100644 cmd/worker/library_capture_identity.go
create mode 100644 cmd/worker/library_capture_identity_test.go
create mode 100644 cmd/worker/library_executor_status.go
create mode 100644 internal/httpapi/library_executor.go
create mode 100644 internal/httpapi/library_executor_test.go
create mode 100644 internal/libraryagent/health_test.go
create mode 100644 internal/libraryexecutor/executor.go
create mode 100644 internal/libraryexecutor/executor_test.go
create mode 100644 internal/platform/postgres/library_executor_status.go
create mode 100644 internal/platform/postgres/library_executor_status_integration_test.go
create mode 100644 internal/platform/postgres/migrations/000074_library_executor_status.down.sql
create mode 100644 internal/platform/postgres/migrations/000074_library_executor_status.up.sql
diff --git a/api/openapi.yaml b/api/openapi.yaml
index a07a8a7..aecfad0 100644
--- a/api/openapi.yaml
+++ b/api/openapi.yaml
@@ -1312,6 +1312,51 @@
}
}
},
+ "/api/v1/library/restore-availability": {
+ "get": {
+ "tags": [
+ "Runtime"
+ ],
+ "operationId": "getLibraryRestoreAvailability",
+ "summary": "这份快照现在能不能恢复到生产:双闸、恢复授权与目标实例维护状态逐条说明",
+ "parameters": [
+ {
+ "name": "scope",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "enum": [
+ "internal",
+ "external"
+ ]
+ }
+ },
+ {
+ "name": "snapshot_id",
+ "in": "query",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "$ref": "#/components/responses/Envelope"
+ },
+ "400": {
+ "$ref": "#/components/responses/BadRequest"
+ },
+ "500": {
+ "$ref": "#/components/responses/InternalError"
+ },
+ "503": {
+ "description": "读取恢复授权失败(不是\"可恢复\",是\"无法判定\")"
+ }
+ }
+ }
+ },
"/api/v1/library/authorizations": {
"get": {
"tags": [
diff --git a/cmd/api/main.go b/cmd/api/main.go
index 23dad2d..0a652f3 100644
--- a/cmd/api/main.go
+++ b/cmd/api/main.go
@@ -204,7 +204,9 @@ func run(ctx context.Context, getenv func(string) string) error {
LibraryArchiveRoot: config.LibraryArchiveRoot,
LibraryTargetInstance: config.LibraryTargetInstance,
LibrarySourceInstance: config.SourceInstance(),
+ LibrarySourceProject: config.SourceProject(),
LibraryAgentSocket: config.LibraryAgentSocket,
+ LibraryExecutorStatusMaxAge: config.LibraryExecutorStatusMaxAge,
LibraryCapacityBudgetBytes: config.LibraryCapacityBudgetBytes,
LibraryProductionDatabaseURL: config.LibraryProductionDatabaseURL,
LibraryProductionInternalKB: config.LibraryProductionInternalKB,
diff --git a/cmd/worker/library_capture_identity.go b/cmd/worker/library_capture_identity.go
new file mode 100644
index 0000000..7110ecc
--- /dev/null
+++ b/cmd/worker/library_capture_identity.go
@@ -0,0 +1,89 @@
+package main
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "strings"
+ "time"
+
+ "knowledge-governance/internal/libraryagent"
+)
+
+// 封存执行的身份核对分两次:执行前一次、执行后一次。
+//
+// 为什么心跳不够:心跳说明"上一次探测时"那个 socket 后面是哪个实例,而从心跳到
+// 真正停写入者之间,socket 可能被换成另一个 agent(换挂载、换单元、误启正式单元)。
+// 执行前探测把窗口缩到最小;执行后复核 agent 自报的身份,则把"换过 socket"这件事
+// 变成一次显式的作业失败,而不是悄悄封错了库还登记成测试封存。
+
+// captureExecutorPrecheck 在动源写入者之前确认执行器就是期望的那个实例。
+func captureExecutorPrecheck(ctx context.Context, client libraryagent.ClientConfig, expectedProject string, probeTimeout time.Duration) error {
+ if strings.TrimSpace(expectedProject) == "" {
+ return errors.New("未配置封存来源实例身份(LIBRARY_SOURCE_PROJECT),拒绝在无法核对执行器的情况下停写入者")
+ }
+ if probeTimeout <= 0 {
+ probeTimeout = 3 * time.Second
+ }
+ bounded, cancel := context.WithTimeout(ctx, probeTimeout)
+ defer cancel()
+ result, err := libraryagent.Health(bounded, client)
+ if err != nil {
+ return fmt.Errorf("封存执行器不可达,拒绝停写入者:%w", err)
+ }
+ identity, err := agentIdentityOf(result.Payload)
+ if err != nil {
+ return err
+ }
+ if identity.Project != expectedProject {
+ return fmt.Errorf("封存执行器指向的实例不匹配(agent=%q,期望=%q),拒绝停写入者",
+ identity.Project, expectedProject)
+ }
+ if identity.Degraded != "" {
+ return fmt.Errorf("封存执行器处于降级状态(%s),拒绝停写入者", identity.Degraded)
+ }
+ return nil
+}
+
+// captureExecutorPostcheck 用封存结果里 agent 自报的身份复核:不一致就当作
+// "封存可能来自别的实例",调用方不得把它登记成测试封存。
+func captureExecutorPostcheck(payload json.RawMessage, expectedProject string) error {
+ identity, err := agentIdentityOf(payload)
+ if err != nil {
+ return err
+ }
+ if identity.Project == "" {
+ return errors.New("封存结果里没有执行器身份,无法证明这次封存来自期望实例")
+ }
+ if identity.Project != expectedProject {
+ return fmt.Errorf("封存结果来自另一个实例(agent=%q,期望=%q),该快照不能当作本实例的测试封存",
+ identity.Project, expectedProject)
+ }
+ return nil
+}
+
+// agentIdentity 是 agent 在 health/封存结果里自报的身份(无凭据)。
+type agentIdentity struct {
+ Project string `json:"project"`
+ SourceApp string `json:"source_app"`
+ Degraded string `json:"degraded"`
+}
+
+func agentIdentityOf(payload json.RawMessage) (agentIdentity, error) {
+ if len(payload) == 0 {
+ return agentIdentity{}, errors.New("执行器应答没有身份信息")
+ }
+ var document struct {
+ Identity agentIdentity `json:"agent_identity"`
+ agentIdentity
+ }
+ if err := json.Unmarshal(payload, &document); err != nil {
+ return agentIdentity{}, errors.New("执行器身份无法解析")
+ }
+ // health 把身份摊平在顶层;封存结果把它放在 agent_identity 下。
+ if document.Identity.Project != "" {
+ return document.Identity, nil
+ }
+ return document.agentIdentity, nil
+}
diff --git a/cmd/worker/library_capture_identity_test.go b/cmd/worker/library_capture_identity_test.go
new file mode 100644
index 0000000..fcf21bd
--- /dev/null
+++ b/cmd/worker/library_capture_identity_test.go
@@ -0,0 +1,98 @@
+package main
+
+import (
+ "context"
+ "encoding/json"
+ "net"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+
+ "knowledge-governance/internal/libraryagent"
+)
+
+func shortDir(t *testing.T) string {
+ t.Helper()
+ // unix socket 路径有长度上限,测试目录要短。
+ dir, err := os.MkdirTemp("/tmp", "kgcap-")
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { os.RemoveAll(dir) })
+ return dir
+}
+
+func fakeAgent(t *testing.T, payload map[string]any) string {
+ t.Helper()
+ socket := filepath.Join(shortDir(t), "agent.sock")
+ listener, err := net.Listen("unix", socket)
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { listener.Close() })
+ go func() {
+ for {
+ conn, acceptErr := listener.Accept()
+ if acceptErr != nil {
+ return
+ }
+ var request map[string]any
+ _ = json.NewDecoder(conn).Decode(&request)
+ body, _ := json.Marshal(payload)
+ _ = json.NewEncoder(conn).Encode(map[string]any{"ok": true, "action": "health", "payload": json.RawMessage(body)})
+ conn.Close()
+ }
+ }()
+ return socket
+}
+
+// 心跳说"可用"不等于执行时还是那个实例:执行前的探测必须能挡住换过的 socket。
+func TestCaptureExecutorPrecheckRejectsAWrongInstance(t *testing.T) {
+ socket := fakeAgent(t, map[string]any{"project": "weknora071full", "source_app": "WKNFull-app"})
+ client := libraryagent.ClientConfig{Socket: socket, Timeout: 2 * time.Second}
+ err := captureExecutorPrecheck(context.Background(), client, "kgmaint-weknora", 2*time.Second)
+ if err == nil || !strings.Contains(err.Error(), "指向的实例不匹配") {
+ t.Fatalf("err = %v", err)
+ }
+ if !strings.Contains(err.Error(), "weknora071full") {
+ t.Fatalf("err should name the actual agent project: %v", err)
+ }
+}
+
+func TestCaptureExecutorPrecheckAcceptsTheExpectedInstance(t *testing.T) {
+ socket := fakeAgent(t, map[string]any{"project": "kgmaint-weknora", "source_app": "kgmaint-app"})
+ client := libraryagent.ClientConfig{Socket: socket, Timeout: 2 * time.Second}
+ if err := captureExecutorPrecheck(context.Background(), client, "kgmaint-weknora", 2*time.Second); err != nil {
+ t.Fatal(err)
+ }
+ // 没有期望身份就不许停写入者:那不是"跳过检查",是不能动生产。
+ if err := captureExecutorPrecheck(context.Background(), client, "", 2*time.Second); err == nil ||
+ !strings.Contains(err.Error(), "LIBRARY_SOURCE_PROJECT") {
+ t.Fatalf("empty expectation accepted: %v", err)
+ }
+ // 降级同样挡住。
+ degraded := fakeAgent(t, map[string]any{"project": "kgmaint-weknora", "degraded": "写入者恢复失败"})
+ if err := captureExecutorPrecheck(context.Background(), libraryagent.ClientConfig{Socket: degraded, Timeout: 2 * time.Second},
+ "kgmaint-weknora", 2*time.Second); err == nil || !strings.Contains(err.Error(), "降级") {
+ t.Fatalf("degraded executor accepted: %v", err)
+ }
+}
+
+// 执行后复核:结果里自报的身份不符,这次封存就不能被登记成测试封存。
+func TestCaptureExecutorPostcheckUsesTheIdentityInTheResult(t *testing.T) {
+ good := json.RawMessage(`{"snapshot_id":"abc","agent_identity":{"project":"kgmaint-weknora"}}`)
+ if err := captureExecutorPostcheck(good, "kgmaint-weknora"); err != nil {
+ t.Fatalf("matching identity rejected: %v", err)
+ }
+ swapped := json.RawMessage(`{"snapshot_id":"abc","agent_identity":{"project":"weknora071full"}}`)
+ err := captureExecutorPostcheck(swapped, "kgmaint-weknora")
+ if err == nil || !strings.Contains(err.Error(), "另一个实例") {
+ t.Fatalf("err = %v", err)
+ }
+ if err := captureExecutorPostcheck(json.RawMessage(`{"snapshot_id":"abc"}`), "kgmaint-weknora"); err == nil ||
+ !strings.Contains(err.Error(), "没有执行器身份") {
+ t.Fatalf("missing identity accepted: %v", err)
+ }
+}
diff --git a/cmd/worker/library_executor_status.go b/cmd/worker/library_executor_status.go
new file mode 100644
index 0000000..f28c5b2
--- /dev/null
+++ b/cmd/worker/library_executor_status.go
@@ -0,0 +1,52 @@
+package main
+
+import (
+ "context"
+ "log"
+ "time"
+
+ "knowledge-governance/internal/appconfig"
+ "knowledge-governance/internal/libraryexecutor"
+ postgresstore "knowledge-governance/internal/platform/postgres"
+)
+
+// 为什么由 worker 观测、页面读库:agent socket 只挂载在 worker 容器里,API 那个
+// LIBRARY_AGENT_SOCKET 即使配了也 dial 不到。谁真能执行就由谁写下观测,
+// 否则页面上的"可发起"只是配置字符串的回声。
+const libraryExecutorProbeInterval = 30 * time.Second
+
+// libraryExecutorProbeTimeout 是一次 health 往返的上限:它只是同 uid unix socket
+// 上的一次 JSON 往返,慢到秒级就说明执行器有问题,不该拖住心跳。
+const libraryExecutorProbeTimeout = 3 * time.Second
+
+func recordLibraryExecutorStatus(ctx context.Context, store *postgresstore.Store, config appconfig.Config) {
+ // 归属用**封存源**实例:agent 冻结的是源库写入者,和同步目标(kgseal)不是一套。
+ instance := config.SourceInstance()
+ if instance == "" {
+ // 没有实例身份,观测就无处归属:写进去只会让页面拿别的实例的状态。
+ log.Print("library executor probe skipped: LIBRARY_SOURCE_INSTANCE is not configured")
+ return
+ }
+ observation := libraryexecutor.Probe(ctx, instance, config.LibraryAgentSocket, libraryExecutorProbeTimeout, nil)
+ if err := store.UpsertLibraryExecutorStatus(ctx, observation, config.WorkerID, time.Now().UTC()); err != nil {
+ log.Printf("library executor status not recorded: %v", err)
+ }
+}
+
+// runLibraryExecutorProbe 先观测一次再进循环:页面在 worker 刚起来时就该有真实状态。
+func runLibraryExecutorProbe(ctx context.Context, store *postgresstore.Store, config appconfig.Config, interval time.Duration) {
+ if interval <= 0 {
+ interval = libraryExecutorProbeInterval
+ }
+ recordLibraryExecutorStatus(ctx, store, config)
+ ticker := time.NewTicker(interval)
+ defer ticker.Stop()
+ for {
+ select {
+ case <-ctx.Done():
+ return
+ case <-ticker.C:
+ recordLibraryExecutorStatus(ctx, store, config)
+ }
+ }
+}
diff --git a/cmd/worker/main.go b/cmd/worker/main.go
index 6e5b1eb..d0d6f2c 100644
--- a/cmd/worker/main.go
+++ b/cmd/worker/main.go
@@ -8,7 +8,6 @@ import (
"os"
"os/signal"
"path/filepath"
- "strings"
"syscall"
"time"
@@ -58,21 +57,6 @@ func (r libraryStageRecorder) Stage(ctx context.Context, stage, state, detail st
func int64Ptr(value int64) *int64 { return &value }
-// redactDSN 只保留库名,避免把连接串写进维护记录。
-func redactDSN(dsn string) string {
- if dsn == "" {
- return ""
- }
- if index := strings.LastIndex(dsn, "/"); index >= 0 && index+1 < len(dsn) {
- name := dsn[index+1:]
- if cut := strings.Index(name, "?"); cut >= 0 {
- name = name[:cut]
- }
- return name
- }
- return "configured"
-}
-
// stageSize 是某一类数据在快照里的真实总量(行数/字节)。
type stageSize struct {
count int64
@@ -205,6 +189,8 @@ func run(ctx context.Context, getenv func(string) string) error {
go runRecordsSyncScheduler(ctx, mirrorStore, func(error) { log.Print("QA local mirror scheduler unavailable; last committed data retained") })
}
go weeklyMailLoop(ctx, pool, getenv)
+ // 封存执行器状态:worker 是唯一能连 agent socket 的一方,它写观测、页面读观测。
+ go runLibraryExecutorProbe(ctx, store, config, libraryExecutorProbeInterval)
go runSourceRefreshScheduler(ctx, store, config.SourceRefreshSchedulerInterval, func(err error) {
log.Printf("worker %s source refresh scheduler error: %v", config.WorkerID, err)
})
@@ -284,6 +270,13 @@ func workerHandlers(store *postgresstore.Store, config appconfig.Config) (map[st
_ = store.AdvanceLibraryJob(ctx, libraryJobID, governance.LibraryJobFailed, "export", "dead letter release storage unavailable", "", "", "", time.Now().UTC())
return fmt.Errorf("load dead letter releases: %w", releaseErr)
}
+ // 心跳只能证明"刚才"是哪个实例:动写入者之前再核一次身份。
+ if identityErr := captureExecutorPrecheck(ctx, agentConfig, config.SourceProject(), 5*time.Second); identityErr != nil {
+ _ = store.UpdateLibraryStage(ctx, libraryJobID, "export", "failed", nil, nil, nil, nil, identityErr.Error(), time.Now().UTC())
+ _ = store.AdvanceLibraryJob(ctx, libraryJobID, governance.LibraryJobFailed, "export", identityErr.Error(),
+ "未停任何写入者;修正执行器身份后重试", "", "", time.Now().UTC())
+ return identityErr
+ }
result, err := libraryagent.CaptureReleased(ctx, agentConfig, payload.Scope, payload.CaptureJob, released)
finishedAt := time.Now().UTC()
if err != nil {
@@ -294,6 +287,14 @@ func workerHandlers(store *postgresstore.Store, config appconfig.Config) (map[st
log.Printf("library capture failed scope=%s capture_job=%s: %v", payload.Scope, payload.CaptureJob, err)
return err
}
+ // 执行后复核:结果里 agent 自报的身份必须还是期望实例,否则这次封存
+ // 可能来自别的栈,绝不能登记成"本实例的测试封存"。
+ if identityErr := captureExecutorPostcheck(result.Payload, config.SourceProject()); identityErr != nil {
+ _ = store.UpdateLibraryStage(ctx, libraryJobID, "export", "failed", nil, nil, nil, nil, identityErr.Error(), finishedAt)
+ _ = store.AdvanceLibraryJob(ctx, libraryJobID, governance.LibraryJobFailed, "export", identityErr.Error(),
+ "快照已产生但来源身份不符,未登记为测试封存;核对执行器后重新封存", "", "", finishedAt)
+ return identityErr
+ }
// 封存产物成版本记录:只登记"测试封存",绝不写成生产生效版本。
versionErr := store.RecordLibraryVersion(ctx, governance.LibraryVersion{
ID: governance.LibraryVersionID(governance.LibraryVersionTestSealed, payload.Scope, result.SnapshotID),
diff --git a/internal/appconfig/config.go b/internal/appconfig/config.go
index 1bd8e59..19ef36d 100644
--- a/internal/appconfig/config.go
+++ b/internal/appconfig/config.go
@@ -99,7 +99,10 @@ type Config struct {
LibraryTargetInstance string
// LibrarySourceInstance 是死信解除记录绑定的"来源实例"名字(封存源,不是同步目标)。
// 留空时回落到 LibraryTargetInstance,保持单实例部署的旧行为。
- LibrarySourceInstance string
+ LibrarySourceInstance string
+ // LibrarySourceProject 是封存执行器应该指向的实例名(agent -project)。
+ // 留空时等于来源实例名:环境里两者本来就同名(kgmaint-weknora)。
+ LibrarySourceProject string
LibraryTargetProject string
LibraryTargetWriters []string
LibraryTargetNonWriters map[string]string
@@ -115,10 +118,13 @@ type Config struct {
LibraryTargetJournalRoot string
// LibraryAgentSocket 是主机侧封存 agent 的 unix socket(只由 worker 连接)。
// 留空即"未接线":页面不显示可用的封存入口,接口返回原因而不是假装已排队。
- LibraryAgentSocket string
- VersionHistoryLinkOrigin string
- VersionHistoryHTTPTimeout time.Duration
- VersionHistoryMaxPages int
+ LibraryAgentSocket string
+ // LibraryExecutorStatusMaxAge 是执行器状态的有效期:超过它就是"无法确认",
+ // 不是"仍然可用"。worker 每 30 秒观测一次,默认 120 秒足够容错。
+ LibraryExecutorStatusMaxAge time.Duration
+ VersionHistoryLinkOrigin string
+ VersionHistoryHTTPTimeout time.Duration
+ VersionHistoryMaxPages int
}
func Load(getenv func(string) string) (Config, error) {
@@ -203,6 +209,7 @@ func Load(getenv func(string) string) (Config, error) {
LibraryProductionS3SecretKey: strings.TrimSpace(getenv("LIBRARY_PRODUCTION_S3_SECRET_KEY")),
LibraryTargetInstance: strings.TrimSpace(getenv("LIBRARY_TARGET_INSTANCE")),
LibrarySourceInstance: strings.TrimSpace(getenv("LIBRARY_SOURCE_INSTANCE")),
+ LibrarySourceProject: strings.TrimSpace(getenv("LIBRARY_SOURCE_PROJECT")),
LibraryTargetProject: strings.TrimSpace(getenv("LIBRARY_TARGET_PROJECT")),
LibraryTargetWriters: splitList(getenv("LIBRARY_TARGET_WRITERS")),
LibraryTargetNonWriters: splitDeclarations(getenv("LIBRARY_TARGET_NON_WRITERS")),
@@ -219,6 +226,7 @@ func Load(getenv func(string) string) (Config, error) {
LibraryCapacityBudgetBytes: capacityBudget,
LibraryRetentionVersions: retentionVersions,
LibraryRetentionDays: retentionDays,
+ LibraryExecutorStatusMaxAge: 2 * time.Minute,
VersionHistoryLinkOrigin: strings.TrimSpace(getenv("VERSION_HISTORY_LINK_ORIGIN")),
VersionHistoryHTTPTimeout: 15 * time.Second,
VersionHistoryMaxPages: valueOrDefaultInt(getenv("VERSION_HISTORY_MAX_PAGES"), 200),
@@ -241,6 +249,9 @@ func Load(getenv func(string) string) (Config, error) {
if config.SourceRefreshSchedulerInterval < 5*time.Second {
return Config{}, errors.New("SOURCE_REFRESH_SCHEDULER_INTERVAL must be at least 5s")
}
+ if config.LibraryExecutorStatusMaxAge, err = durationOrDefault(getenv("LIBRARY_EXECUTOR_STATUS_MAX_AGE"), config.LibraryExecutorStatusMaxAge); err != nil {
+ return Config{}, fmt.Errorf("LIBRARY_EXECUTOR_STATUS_MAX_AGE: %w", err)
+ }
if raw := getenv("RELEASE_WORKER_ENABLED"); raw != "" {
config.ReleaseWorkerEnabled, err = strconv.ParseBool(raw)
if err != nil {
@@ -575,3 +586,13 @@ func (config Config) SourceInstance() string {
}
return config.LibraryTargetInstance
}
+
+// SourceProject 是封存执行器自报 project 的期望值。它描述的是**封存源**
+// (agent 冻结哪一套写入者),不是同步目标:拿目标实例去比会把正确的执行器判成
+// 不匹配(本机候选栈就是这种形状:源 kgmaint、目标 kgseal)。
+func (config Config) SourceProject() string {
+ if config.LibrarySourceProject != "" {
+ return config.LibrarySourceProject
+ }
+ return config.SourceInstance()
+}
diff --git a/internal/httpapi/library_capture.go b/internal/httpapi/library_capture.go
index 76fe671..4aefe34 100644
--- a/internal/httpapi/library_capture.go
+++ b/internal/httpapi/library_capture.go
@@ -26,13 +26,6 @@ type libraryCaptureRequest struct {
}
func libraryCaptureEnqueue(w http.ResponseWriter, r *http.Request, config Config) {
- if config.LibraryAgentSocket == "" {
- writeJSON(w, http.StatusServiceUnavailable, map[string]any{
- "code": "library_capture_unwired",
- "reason": "未接线:主机侧封存 agent 没有挂载,页面无法发起封存",
- })
- return
- }
var request libraryCaptureRequest
if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 4096)).Decode(&request); err != nil {
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid request body"})
@@ -52,6 +45,17 @@ func libraryCaptureEnqueue(w http.ResponseWriter, r *http.Request, config Config
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid job id"})
return
}
+ // 请求形状先校验(400),再看执行器(503):不只看"配了 socket"——执行器可能
+ // 不可达、可能指向别的实例、可能降级。页面与接口必须用同一份判定,否则又会出现
+ // "点了才失败"或"封错库"。
+ if available, reason, executor := libraryExecutorAvailability(r.Context(), config); !available {
+ writeJSON(w, http.StatusServiceUnavailable, map[string]any{
+ "code": "library_capture_unavailable",
+ "reason": reason,
+ "executor": executor,
+ })
+ return
+ }
requestedBy := ""
if identity, ok := sessionFrom(r.Context()); ok {
requestedBy = identity.Username
diff --git a/internal/httpapi/library_capture_test.go b/internal/httpapi/library_capture_test.go
index 9b7a41d..2cd6263 100644
--- a/internal/httpapi/library_capture_test.go
+++ b/internal/httpapi/library_capture_test.go
@@ -17,31 +17,11 @@ func captureRequest(body string) *http.Request {
return request
}
-// An unwired agent must refuse clearly instead of queueing a job nobody can run.
-func TestLibraryCaptureRefusedWhenAgentUnwired(t *testing.T) {
- store := &fakeJobStore{}
- recorder := httptest.NewRecorder()
- libraryCaptureEnqueue(recorder, captureRequest(`{"scope":"internal"}`), Config{Store: store})
- if recorder.Code != http.StatusServiceUnavailable {
- t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
- }
- var body map[string]any
- if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil {
- t.Fatal(err)
- }
- if body["code"] != "library_capture_unwired" || body["reason"] == "" {
- t.Fatalf("unexpected body %v", body)
- }
- if store.enqueued.Type != "" {
- t.Fatal("unwired agent still enqueued a job")
- }
-}
-
func TestLibraryCaptureEnqueuesFixedJobShape(t *testing.T) {
store := &fakeJobStore{enqueueEchoRequestedID: true}
recorder := httptest.NewRecorder()
libraryCaptureEnqueue(recorder, captureRequest(`{"scope":"external","job":"lib-external-review"}`),
- Config{Store: store, LibraryAgentSocket: "/run/library-agent/agent.sock"})
+ captureReadyConfig(store))
if recorder.Code != http.StatusAccepted {
t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
}
@@ -76,7 +56,7 @@ func TestLibraryCaptureRejectsInvalidRequest(t *testing.T) {
} {
store := &fakeJobStore{}
recorder := httptest.NewRecorder()
- libraryCaptureEnqueue(recorder, captureRequest(body), Config{Store: store, LibraryAgentSocket: "/tmp/agent.sock"})
+ libraryCaptureEnqueue(recorder, captureRequest(body), captureReadyConfig(store))
if recorder.Code != http.StatusBadRequest {
t.Fatalf("body %q status=%d", body, recorder.Code)
}
@@ -92,8 +72,7 @@ func TestLibraryCaptureQueueIDFitsTheColumn(t *testing.T) {
for _, scope := range []string{"internal", "external"} {
store := &fakeJobStore{enqueueEchoRequestedID: true}
recorder := httptest.NewRecorder()
- libraryCaptureEnqueue(recorder, captureRequest(`{"scope":"`+scope+`"}`),
- Config{Store: store, LibraryAgentSocket: "/tmp/agent.sock"})
+ libraryCaptureEnqueue(recorder, captureRequest(`{"scope":"`+scope+`"}`), captureReadyConfig(store))
if recorder.Code != http.StatusAccepted {
t.Fatalf("%s status=%d body=%s", scope, recorder.Code, recorder.Body.String())
}
@@ -146,7 +125,7 @@ func TestLibraryCaptureRejectsScopeConflictForReusedJob(t *testing.T) {
Payload: json.RawMessage(`{"scope":"internal","capture_job":"lib-shared","requested_by":"yaozhanghao"}`)}}
recorder := httptest.NewRecorder()
libraryCaptureEnqueue(recorder, captureRequest(`{"scope":"external","job":"lib-shared"}`),
- Config{Store: store, LibraryAgentSocket: "/run/library-agent/agent.sock"})
+ captureReadyConfig(store))
if recorder.Code != http.StatusConflict {
t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
}
@@ -166,7 +145,7 @@ func TestLibraryCaptureReplayReportsStoredJob(t *testing.T) {
Payload: json.RawMessage(`{"scope":"internal","capture_job":"lib-shared","requested_by":"yaozhanghao"}`)}}
recorder := httptest.NewRecorder()
libraryCaptureEnqueue(recorder, captureRequest(`{"scope":"internal","job":"lib-shared"}`),
- Config{Store: store, LibraryAgentSocket: "/run/library-agent/agent.sock"})
+ captureReadyConfig(store))
if recorder.Code != http.StatusAccepted {
t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
}
diff --git a/internal/httpapi/library_executor.go b/internal/httpapi/library_executor.go
new file mode 100644
index 0000000..3265a9c
--- /dev/null
+++ b/internal/httpapi/library_executor.go
@@ -0,0 +1,77 @@
+package httpapi
+
+import (
+ "context"
+ "time"
+
+ "knowledge-governance/internal/libraryexecutor"
+)
+
+// libraryExecutorView 是"封存执行器到底能不能用"的页面口径。
+//
+// 为什么不是 `LIBRARY_AGENT_SOCKET != ""`:正式栈里 API 根本没有挂载那个 socket,
+// 配置非空并不代表链路通;更危险的是 agent 可能顶着正式单元名却在冻结另一个实例。
+// 这里只认 worker 写入的真实观测,并把观测时间与执行器自报的身份一起给出来。
+type libraryExecutorView struct {
+ Available bool `json:"available"`
+ Reason string `json:"reason,omitempty"`
+ Instance string `json:"instance,omitempty"`
+ Project string `json:"project,omitempty"`
+ SourceApp string `json:"source_app,omitempty"`
+ ArchiveRoot string `json:"archive_root,omitempty"`
+ Busy bool `json:"busy"`
+ Degraded string `json:"degraded,omitempty"`
+ ObservedAt *time.Time `json:"observed_at,omitempty"`
+}
+
+type libraryExecutorStore interface {
+ LibraryExecutorStatus(ctx context.Context, instance string) (*libraryexecutor.Observation, error)
+}
+
+// libraryExecutorAvailability 把"配置里的期望"与"worker 观测到的真实身份"合起来判定:
+// 观测不存在、过期、不可达、实例不符、降级、正忙,任何一条都不可用,并给出原因。
+func libraryExecutorAvailability(ctx context.Context, config Config) (bool, string, libraryExecutorView) {
+ // 期望身份是**封存源**:agent 冻结的是源库写入者,与同步目标(LIBRARY_TARGET_*)
+ // 本来就是两套名字(本机候选栈:源 kgmaint、目标 kgseal)。
+ instance := config.LibrarySourceInstance
+ view := libraryExecutorView{Instance: instance}
+ if instance == "" {
+ return false, "未配置封存来源实例身份(LIBRARY_SOURCE_INSTANCE),无法确认执行器归属", view
+ }
+ store, ok := config.Store.(libraryExecutorStore)
+ if !ok {
+ return false, "执行器状态存储不可用", view
+ }
+ observation, err := store.LibraryExecutorStatus(ctx, instance)
+ if err != nil {
+ return false, "读取执行器状态失败:" + err.Error(), view
+ }
+ if observation == nil {
+ return false, "封存执行器还没有上报状态(worker 未运行,或实例身份与 worker 不一致)", view
+ }
+ available, reason := libraryexecutor.Evaluate(*observation,
+ libraryexecutor.Expectation{Instance: instance, Project: config.LibrarySourceProject,
+ ArchiveRoot: config.LibraryArchiveRoot},
+ executorStatusMaxAge(config), time.Now().UTC())
+ observedAt := observation.ObservedAt
+ view.Available = available
+ view.Reason = reason
+ view.Project = observation.Identity.Project
+ view.SourceApp = observation.Identity.SourceApp
+ view.ArchiveRoot = observation.Identity.ArchiveRoot
+ view.Busy = observation.Busy
+ view.Degraded = observation.Degraded
+ view.ObservedAt = &observedAt
+ return available, reason, view
+}
+
+// defaultLibraryExecutorStatusMaxAge 与 worker 的探测间隔(30s)配套:
+// 没配上限绝不等于"永不过期"——那会把一次陈旧的"可用"永久留在页面上。
+const defaultLibraryExecutorStatusMaxAge = 2 * time.Minute
+
+func executorStatusMaxAge(config Config) time.Duration {
+ if config.LibraryExecutorStatusMaxAge > 0 {
+ return config.LibraryExecutorStatusMaxAge
+ }
+ return defaultLibraryExecutorStatusMaxAge
+}
diff --git a/internal/httpapi/library_executor_test.go b/internal/httpapi/library_executor_test.go
new file mode 100644
index 0000000..7c5da52
--- /dev/null
+++ b/internal/httpapi/library_executor_test.go
@@ -0,0 +1,184 @@
+package httpapi
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+ "time"
+
+ "knowledge-governance/internal/libraryexecutor"
+)
+
+// fakeJobStore 只是"存储"替身;执行器状态同样是它的一条记录。
+func (s *fakeJobStore) LibraryExecutorStatus(_ context.Context, instance string) (*libraryexecutor.Observation, error) {
+ if s.executorStatus == nil || s.executorStatus.Instance != instance {
+ return nil, nil
+ }
+ return s.executorStatus, nil
+}
+
+// healthyExecutor 返回一份"worker 刚观测到、指向本实例"的记录。
+func healthyExecutor(now time.Time) *libraryexecutor.Observation {
+ return &libraryexecutor.Observation{
+ Instance: "kgmaint-weknora", Reachable: true, ObservedAt: now,
+ Identity: libraryexecutor.Identity{Project: "kgmaint-weknora", SourceApp: "kgmaint-app",
+ ArchiveRoot: "/tmp/kg-e2e/archive", Writers: "app"},
+ }
+}
+
+// captureReadyConfig 是"执行器真的可用"时的配置:实例、期望项目与观测三者一致。
+func captureReadyConfig(store *fakeJobStore) Config {
+ store.executorStatus = healthyExecutor(time.Now().UTC())
+ return Config{
+ Store: store,
+ LibraryAgentSocket: "/run/library-agent/agent.sock",
+ LibrarySourceInstance: "kgmaint-weknora",
+ LibrarySourceProject: "kgmaint-weknora",
+ LibraryArchiveRoot: "/var/lib/knowledge-governance/library",
+ }
+}
+
+func decodeCaptureRefusal(t *testing.T, recorder *httptest.ResponseRecorder) (string, string) {
+ t.Helper()
+ var body struct {
+ Code string `json:"code"`
+ Reason string `json:"reason"`
+ }
+ if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil {
+ t.Fatalf("body %s: %v", recorder.Body.String(), err)
+ }
+ return body.Code, body.Reason
+}
+
+// 页面上的"可发起"必须等于接口真的会接受:配置了 socket 但执行器不可达、
+// 指向别的实例、降级或过期时,都必须带着原因拒绝,而不是先排队再失败。
+func TestLibraryCaptureRefusesWhenExecutorIsNotVerified(t *testing.T) {
+ now := time.Now().UTC()
+ tests := []struct {
+ name string
+ config func(*Config)
+ text string
+ }{
+ {name: "no instance identity", config: func(c *Config) {
+ c.LibrarySourceInstance = ""
+ }, text: "LIBRARY_SOURCE_INSTANCE"},
+ {name: "nothing reported yet", config: func(c *Config) {
+ c.Store.(*fakeJobStore).executorStatus = nil
+ }, text: "还没有上报状态"},
+ {name: "unreachable", config: func(c *Config) {
+ c.Store.(*fakeJobStore).executorStatus.Reachable = false
+ c.Store.(*fakeJobStore).executorStatus.Error = "library agent is unreachable"
+ }, text: "不可达"},
+ {name: "stale observation", config: func(c *Config) {
+ c.Store.(*fakeJobStore).executorStatus.ObservedAt = now.Add(-10 * time.Minute)
+ }, text: "已过期"},
+ {name: "points at another instance", config: func(c *Config) {
+ c.Store.(*fakeJobStore).executorStatus.Identity.Project = "weknora071full"
+ }, text: "指向的实例不匹配"},
+ {name: "degraded", config: func(c *Config) {
+ c.Store.(*fakeJobStore).executorStatus.Degraded = "写入者恢复失败"
+ }, text: "降级"},
+ }
+ for _, test := range tests {
+ t.Run(test.name, func(t *testing.T) {
+ store := &fakeJobStore{}
+ config := captureReadyConfig(store)
+ test.config(&config)
+ recorder := httptest.NewRecorder()
+ libraryCaptureEnqueue(recorder, captureRequest(`{"scope":"internal"}`), config)
+ if recorder.Code != http.StatusServiceUnavailable {
+ t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
+ }
+ code, reason := decodeCaptureRefusal(t, recorder)
+ if code != "library_capture_unavailable" {
+ t.Fatalf("code=%q body=%s", code, recorder.Body.String())
+ }
+ if reason == "" || !strings.Contains(reason, test.text) {
+ t.Fatalf("reason=%q want it to mention %q", reason, test.text)
+ }
+ if store.enqueued.Type != "" {
+ t.Fatal("refused capture still enqueued a job")
+ }
+ })
+ }
+}
+
+// The overview must report the same reason the capture endpoint would use.
+func TestLibraryOverviewReportsExecutorIdentityAndReason(t *testing.T) {
+ store := &fakeLibraryStore{}
+ config := captureReadyConfig(&store.fakeJobStore)
+ // libraryJobStore 的方法在 fakeLibraryStore 上,执行器状态在嵌入的 fakeJobStore 上。
+ config.Store = store
+ recorder := httptest.NewRecorder()
+ libraryOverviewHandler(recorder, httptest.NewRequest(http.MethodGet, "/api/v1/library/overview?scope=internal", nil), config)
+ if recorder.Code != http.StatusOK {
+ t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
+ }
+ var body struct {
+ CaptureAvailable bool `json:"capture_available"`
+ Executor struct {
+ Available bool `json:"available"`
+ Instance string `json:"instance"`
+ Project string `json:"project"`
+ SourceApp string `json:"source_app"`
+ ArchiveRoot string `json:"archive_root"`
+ } `json:"executor"`
+ }
+ if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil {
+ t.Fatal(err)
+ }
+ if !body.CaptureAvailable || !body.Executor.Available {
+ t.Fatalf("overview did not report an available executor: %s", recorder.Body.String())
+ }
+ if body.Executor.Project != "kgmaint-weknora" || body.Executor.SourceApp != "kgmaint-app" ||
+ body.Executor.ArchiveRoot != "/tmp/kg-e2e/archive" || body.Executor.Instance != "kgmaint-weknora" {
+ t.Fatalf("executor view = %+v", body.Executor)
+ }
+
+ store.fakeJobStore.executorStatus.Identity.Project = "weknora071full"
+ recorder = httptest.NewRecorder()
+ libraryOverviewHandler(recorder, httptest.NewRequest(http.MethodGet, "/api/v1/library/overview?scope=internal", nil), config)
+ if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil {
+ t.Fatal(err)
+ }
+ if body.CaptureAvailable {
+ t.Fatalf("overview still says available after the executor moved to another instance: %s", recorder.Body.String())
+ }
+}
+
+// "恢复至该版本"必须由真实条件决定:没有 restore 授权就明确说出来。
+func TestLibraryRestoreAvailabilityExplainsMissingAuthorization(t *testing.T) {
+ store := &fakeJobStore{}
+ config := Config{Store: store, ProductionReleaseRequestsEnabled: true, ProductionBackupRestoreVerified: true}
+ recorder := httptest.NewRecorder()
+ libraryRestoreAvailability(recorder, httptest.NewRequest(http.MethodGet,
+ "/api/v1/library/restore-availability?scope=internal&snapshot_id=snap-1", nil), config)
+ if recorder.Code != http.StatusOK {
+ t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
+ }
+ var body struct {
+ Allowed bool `json:"allowed"`
+ Reasons []string `json:"reasons"`
+ Authorization struct {
+ State string `json:"state"`
+ } `json:"authorization"`
+ }
+ if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil {
+ t.Fatal(err)
+ }
+ if body.Allowed || body.Authorization.State != "none" || len(body.Reasons) == 0 {
+ t.Fatalf("body=%s", recorder.Body.String())
+ }
+ found := false
+ for _, reason := range body.Reasons {
+ if strings.Contains(reason, "恢复授权") {
+ found = true
+ }
+ }
+ if !found {
+ t.Fatalf("reasons = %v", body.Reasons)
+ }
+}
diff --git a/internal/httpapi/library_flow.go b/internal/httpapi/library_flow.go
index b35d328..19f355f 100644
--- a/internal/httpapi/library_flow.go
+++ b/internal/httpapi/library_flow.go
@@ -307,6 +307,7 @@ type libraryOverview struct {
Authorization libraryAuthorizationView `json:"authorization"`
CaptureAvailable bool `json:"capture_available"`
CaptureReason string `json:"capture_reason,omitempty"`
+ Executor libraryExecutorView `json:"executor"`
Now time.Time `json:"now"`
}
@@ -563,12 +564,10 @@ func libraryOverviewHandler(w http.ResponseWriter, r *http.Request, config Confi
}
now := time.Now().UTC()
overview := libraryOverview{Scope: scope, Jobs: []governance.LibraryJob{}, Now: now,
- CaptureAvailable: strings.TrimSpace(config.LibraryAgentSocket) != "",
- Gate: libraryGateView{Reasons: []string{}},
- Diff: libraryDiffView{State: "unknown", Reason: "生产与测试的文档级差异读取未接线", Added: []any{}, Updated: []any{}, Removed: []any{}}}
- if !overview.CaptureAvailable {
- overview.CaptureReason = "主机侧封存 agent 未接线"
- }
+ Gate: libraryGateView{Reasons: []string{}},
+ Diff: libraryDiffView{State: "unknown", Reason: "生产与测试的文档级差异读取未接线", Added: []any{}, Updated: []any{}, Removed: []any{}}}
+ // 可发起封存 = worker 真实探测到执行器可用且指向本实例;原因逐条给全。
+ overview.CaptureAvailable, overview.CaptureReason, overview.Executor = libraryExecutorAvailability(r.Context(), config)
// 测试封存来自归档:它只是测试侧事实。
snapshots, snapErr := readLibrarySnapshots(r.Context(), config.LibraryArchiveRoot)
diff --git a/internal/httpapi/library_restore.go b/internal/httpapi/library_restore.go
index 14edde6..3e1239f 100644
--- a/internal/httpapi/library_restore.go
+++ b/internal/httpapi/library_restore.go
@@ -146,6 +146,64 @@ func libraryRestoreEnqueue(w http.ResponseWriter, r *http.Request, config Config
writeJSON(w, http.StatusAccepted, map[string]any{"job": job, "reused": false})
}
+// libraryRestoreAvailability 回答"现在能不能把生产恢复到这份快照"。
+//
+// 为什么需要它:页面原来把"恢复至该版本"按钮写死为 disabled,理由是"未接线"——
+// 但接口、授权、恢复作业其实都已经在跑。按钮该由真实条件决定:双闸打开、
+// 有这份快照的恢复授权、目标实例没有在维护。
+type libraryRestoreAvailabilityView struct {
+ Allowed bool `json:"allowed"`
+ Reasons []string `json:"reasons"`
+ Scope string `json:"scope"`
+ SnapshotID string `json:"snapshot_id"`
+ Authorization libraryAuthorizationView `json:"authorization"`
+}
+
+func libraryRestoreAvailability(w http.ResponseWriter, r *http.Request, config Config) {
+ scope, err := scopeFromQuery(r)
+ if err != nil {
+ writeJSON(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
+ return
+ }
+ snapshotID := strings.TrimSpace(r.URL.Query().Get("snapshot_id"))
+ if snapshotID == "" {
+ writeJSON(w, http.StatusBadRequest, map[string]string{"error": "snapshot_id required"})
+ return
+ }
+ view := libraryRestoreAvailabilityView{Scope: scope, SnapshotID: snapshotID, Reasons: []string{}}
+ if !config.ProductionReleaseRequestsEnabled {
+ view.Reasons = append(view.Reasons, "生产写入闸口关闭(PRODUCTION_RELEASE_REQUESTS_ENABLED=false)")
+ }
+ if !config.ProductionBackupRestoreVerified {
+ view.Reasons = append(view.Reasons, "没有已核验的生产恢复演练证据(PRODUCTION_BACKUP_RESTORE_VERIFIED=false)")
+ }
+ digest, err := libraryRestoreParamsDigest(scope, snapshotID)
+ if err != nil {
+ writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot digest params"})
+ return
+ }
+ grant, found := governance.LibraryReleaseAuthorization{}, false
+ if storeWithAuth, ok := config.Store.(interface {
+ ActiveLibraryAuthorization(ctx context.Context, scope, snapshotID, digest string, now time.Time) (governance.LibraryReleaseAuthorization, bool, error)
+ }); ok {
+ grant, found, err = storeWithAuth.ActiveLibraryAuthorization(r.Context(), scope, snapshotID, digest, time.Now().UTC())
+ if err != nil {
+ writeJSON(w, http.StatusServiceUnavailable, map[string]any{"allowed": false,
+ "reasons": []string{"读取恢复授权失败:" + err.Error()}})
+ return
+ }
+ }
+ view.Authorization = authorizationViewOf(grant, found)
+ if !found {
+ view.Reasons = append(view.Reasons, "没有针对该快照的恢复授权:先签发 restore 授权(绑定同一快照)")
+ }
+ if _, held := instanceMaintenanceGuard(r.Context(), config, scope); held {
+ view.Reasons = append(view.Reasons, "目标实例正在维护中,等当前作业释放后再恢复")
+ }
+ view.Allowed = len(view.Reasons) == 0
+ writeJSON(w, http.StatusOK, view)
+}
+
// 崩溃续作:失败作业可以按原参数重新排队,生成新作业(旧作业保留为审计记录)。
func libraryJobResume(w http.ResponseWriter, r *http.Request, config Config) {
identity, ok := sessionFrom(r.Context())
diff --git a/internal/httpapi/library_snapshots.go b/internal/httpapi/library_snapshots.go
index ded1b11..bbdab31 100644
--- a/internal/httpapi/library_snapshots.go
+++ b/internal/httpapi/library_snapshots.go
@@ -85,15 +85,14 @@ const libraryCaptureNote = "封存由运维命令 scripts/library-capture.sh cap
func librarySnapshotsList(w http.ResponseWriter, r *http.Request, config Config) {
view, err := readLibrarySnapshots(r.Context(), config.LibraryArchiveRoot)
- view.CaptureAvailable = config.LibraryAgentSocket != ""
- if !view.CaptureAvailable {
- view.CaptureReason = "未接线:主机侧封存 agent 没有挂载,页面只能查看已封存版本"
- }
+ // 能不能发起封存只认 worker 的真实观测,不认"配置里写了 socket 路径"。
+ view.CaptureAvailable, view.CaptureReason, _ = libraryExecutorAvailability(r.Context(), config)
if err != nil {
status, reason := libraryArchiveErrorStatus(err, "归档不可读")
writeJSON(w, status, librarySnapshotList{Available: false, Reason: reason,
Snapshots: []librarySnapshotView{}, Verification: libraryVerificationManifest,
- VerificationNote: libraryVerificationNote, CaptureNote: libraryCaptureNote})
+ VerificationNote: libraryVerificationNote, CaptureNote: libraryCaptureNote,
+ CaptureAvailable: view.CaptureAvailable, CaptureReason: view.CaptureReason})
return
}
writeJSON(w, http.StatusOK, view)
diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go
index caf8b0d..1b1c4cf 100644
--- a/internal/httpapi/server.go
+++ b/internal/httpapi/server.go
@@ -152,6 +152,11 @@ type Config struct {
LibrarySourceInstance string
// LibraryAgentSocket 是主机侧封存 agent 的 unix socket;留空即页面不能发起封存。
LibraryAgentSocket string
+ // LibrarySourceProject 是执行器应指向的实例名(agent -project,封存源)。
+ // 与它不一致时按"封错库"处理:不可发起,并说明差在哪。
+ LibrarySourceProject string
+ // LibraryExecutorStatusMaxAge 是执行器观测的有效期;超过即"无法确认"。
+ LibraryExecutorStatusMaxAge time.Duration
// LibraryCapacityBudgetBytes 是整库归档容量预算;0 = 未设置(容量门禁不放行)。
LibraryCapacityBudgetBytes int64
// 整库生产目标的只读探测配置:首次发布要能证明"生产可读且为空"。
@@ -510,6 +515,10 @@ func NewHandler(config Config) (http.Handler, error) {
mux.HandleFunc("POST /api/v1/library/restores", func(w http.ResponseWriter, r *http.Request) {
libraryRestoreEnqueue(w, r, config)
})
+ // 页面问"这份快照现在能不能恢复":条件来自双闸、授权与实例维护,而不是写死的按钮。
+ mux.HandleFunc("GET /api/v1/library/restore-availability", func(w http.ResponseWriter, r *http.Request) {
+ libraryRestoreAvailability(w, r, config)
+ })
// 失败/取消作业续作:按原参数重新排队,旧作业保留审计。
mux.HandleFunc("POST /api/v1/library/jobs/{id}/resume", func(w http.ResponseWriter, r *http.Request) {
libraryJobResume(w, r, config)
diff --git a/internal/httpapi/server_test.go b/internal/httpapi/server_test.go
index b4bfef6..9861428 100644
--- a/internal/httpapi/server_test.go
+++ b/internal/httpapi/server_test.go
@@ -15,6 +15,7 @@ import (
"knowledge-governance/internal/governance"
"knowledge-governance/internal/jobs"
+ "knowledge-governance/internal/libraryexecutor"
postgresstore "knowledge-governance/internal/platform/postgres"
)
@@ -1501,30 +1502,32 @@ type fakeJobStore struct {
activateSettingsErr error
// enqueueEchoRequestedID:幂等"首次入队"语义 —— 返回调用方请求的那个 id
// (默认 false 时返回 enqueueResult,即"复用已有任务"的路径)。
- enqueueEchoRequestedID bool
- listSettingsConnectionID string
- listSettingsErr error
- settingsRevisions []governance.SourceConnectionRevision
- jobFailureFilter governance.JobFailureFilter
- jobFailurePage governance.JobFailurePage
- jobFailureErr error
- retryBatchRequest *governance.RetryPublicationsBatchRequest
- retryBatchOperation string
- retryBatchResult governance.RetryPublicationsBatchResult
- cancelBatchRequest *governance.CancelPublicationsBatchRequest
- cancelBatchOperation string
- cancelBatchResult governance.RetryPublicationsBatchResult
- cancelBatchReplayed bool
- cancelBatchErr error
- retryBatchReplayed bool
- retryBatchErr error
- requeueFailureRequest *governance.RequeueArtifactFetchRequest
- requeueFailureOperation string
- requeueFailureResult governance.RequeueArtifactFetchResult
- requeueFailureReplayed bool
- requeueFailureErr error
- enqueued jobs.EnqueueRequest
- enqueueResult *jobs.Job
+ enqueueEchoRequestedID bool
+ listSettingsConnectionID string
+ listSettingsErr error
+ settingsRevisions []governance.SourceConnectionRevision
+ jobFailureFilter governance.JobFailureFilter
+ jobFailurePage governance.JobFailurePage
+ jobFailureErr error
+ retryBatchRequest *governance.RetryPublicationsBatchRequest
+ retryBatchOperation string
+ retryBatchResult governance.RetryPublicationsBatchResult
+ cancelBatchRequest *governance.CancelPublicationsBatchRequest
+ cancelBatchOperation string
+ cancelBatchResult governance.RetryPublicationsBatchResult
+ cancelBatchReplayed bool
+ cancelBatchErr error
+ retryBatchReplayed bool
+ retryBatchErr error
+ requeueFailureRequest *governance.RequeueArtifactFetchRequest
+ requeueFailureOperation string
+ requeueFailureResult governance.RequeueArtifactFetchResult
+ requeueFailureReplayed bool
+ requeueFailureErr error
+ enqueued jobs.EnqueueRequest
+ enqueueResult *jobs.Job
+ // executorStatus 是封存执行器的"最近一次观测";nil 表示还没有任何上报。
+ executorStatus *libraryexecutor.Observation
listResult []jobs.Job
listType string
listByTypeResult []jobs.Job
diff --git a/internal/libraryagent/agent.go b/internal/libraryagent/agent.go
index 8f9b6a6..65fd3fc 100644
--- a/internal/libraryagent/agent.go
+++ b/internal/libraryagent/agent.go
@@ -89,13 +89,45 @@ const maxReleasedDeadLetters = 64
type Agent struct {
config Config
mu sync.Mutex
+ // stateMu 只保护下面两个"给人看"的字段:健康应答不能被一次 15 分钟的封存
+ // 卡住(否则页面会把"正在封存"读成"执行器不可达")。
+ stateMu sync.RWMutex
// degraded is non-empty when a failed operation could not be followed by a
// verified recovery. While set, capture requests are refused: leaving the
// source writer stopped is worse than refusing work.
degraded string
+ busy bool
wg sync.WaitGroup
}
+// captureState 是健康应答要暴露的执行器状态:是否在跑、是否降级。
+type captureState struct {
+ Busy bool `json:"busy"`
+ Degraded string `json:"degraded"`
+}
+
+func (a *Agent) snapshotState() captureState {
+ a.stateMu.RLock()
+ defer a.stateMu.RUnlock()
+ return captureState{Busy: a.busy, Degraded: a.degraded}
+}
+
+func (a *Agent) setBusy(busy bool) {
+ a.stateMu.Lock()
+ defer a.stateMu.Unlock()
+ a.busy = busy
+}
+
+func (a *Agent) setDegraded(reason string) {
+ a.stateMu.Lock()
+ defer a.stateMu.Unlock()
+ a.degraded = reason
+}
+
+func (a *Agent) clearDegraded() {
+ a.setDegraded("")
+}
+
func New(config Config) (*Agent, error) {
if !filepath.IsAbs(config.Socket) || !filepath.IsAbs(config.ArchiveRoot) || !filepath.IsAbs(config.JournalRoot) {
return nil, errors.New("library agent paths must be absolute")
@@ -143,7 +175,7 @@ func (a *Agent) Serve(ctx context.Context) error {
// writer from a previous killed run. Recover before accepting work; if that
// fails, stay degraded and refuse captures instead of pretending to be ready.
if err := a.recoverWriters(ctx); err != nil {
- a.degraded = err.Error()
+ a.setDegraded(err.Error())
log.Printf("library agent: pending freeze recovery failed: %v", err)
}
go func() {
@@ -194,13 +226,18 @@ func (a *Agent) handle(ctx context.Context, conn net.Conn) {
// execute serialises operations and maps a request onto the one fixed command.
func (a *Agent) execute(ctx context.Context, req request) response {
+ // health 不进操作锁、不跑子进程:调用方要的是"这个执行器指向谁、能不能干活",
+ // 而一次正在进行的封存不该让这个回答变成"不可达"。
+ if req.Action == "health" {
+ return a.health()
+ }
a.mu.Lock()
defer a.mu.Unlock()
out := response{Action: req.Action, Scope: req.Scope, Job: req.Job}
// Degraded blocks new captures, but recover and status must stay reachable:
// otherwise there is no way back to a verified state.
- if a.degraded != "" && req.Action == "capture" {
- out.Error = "封存执行边界处于降级状态(上次恢复失败:" + a.degraded + "),先执行 recover"
+ if state := a.snapshotState(); state.Degraded != "" && req.Action == "capture" {
+ out.Error = "封存执行边界处于降级状态(上次恢复失败:" + state.Degraded + "),先执行 recover"
return out
}
var args []string
@@ -242,6 +279,10 @@ func (a *Agent) execute(ctx context.Context, req request) response {
args = append(args, a.config.declaration()...)
bounded, cancel := context.WithTimeout(ctx, a.config.MaxDuration)
defer cancel()
+ if req.Action == "capture" || req.Action == "recover" {
+ a.setBusy(true)
+ defer a.setBusy(false)
+ }
payload, err := a.config.run(bounded, a.config.Binary, args...)
if err != nil {
detail := "operation failed"
@@ -254,7 +295,7 @@ func (a *Agent) execute(ctx context.Context, req request) response {
// verify.
if req.Action == "capture" || req.Action == "recover" {
if recoveryErr := a.recoverWriters(ctx); recoveryErr != nil {
- a.degraded = recoveryErr.Error()
+ a.setDegraded(recoveryErr.Error())
out.Error = detail + ";写入者恢复失败:" + recoveryErr.Error() + "(已阻断后续封存,需人工处理)"
return out
}
@@ -266,7 +307,7 @@ func (a *Agent) execute(ctx context.Context, req request) response {
return out
}
if req.Action == "recover" {
- a.degraded = ""
+ a.clearDegraded()
}
out.OK = true
if json.Valid(payload) {
@@ -274,9 +315,28 @@ func (a *Agent) execute(ctx context.Context, req request) response {
} else {
out.Payload = json.RawMessage(`{}`)
}
+ // 封存结果必须带上"这次是谁执行的":调用方据此复核,防止心跳与执行之间
+ // socket 被换成另一个 agent(真正的封错库事故就是这样发生的)。
+ if req.Action == "capture" {
+ out.Payload = a.attachIdentity(out.Payload)
+ }
return out
}
+// attachIdentity 把执行器身份并进封存结果(保留 CLI 原有的字段,如 snapshot_id)。
+func (a *Agent) attachIdentity(payload json.RawMessage) json.RawMessage {
+ var document map[string]any
+ if err := json.Unmarshal(payload, &document); err != nil {
+ return payload
+ }
+ document["agent_identity"] = a.config.identity()
+ encoded, err := json.Marshal(document)
+ if err != nil {
+ return payload
+ }
+ return json.RawMessage(encoded)
+}
+
// recoverWriters runs the idempotent recovery command with its own budget, even
// when the triggering context is already cancelled (timeout / shutdown).
func (a *Agent) recoverWriters(ctx context.Context) error {
@@ -285,7 +345,7 @@ func (a *Agent) recoverWriters(ctx context.Context) error {
if _, err := a.config.run(bounded, a.config.Binary, append([]string{"recover"}, a.config.declaration()...)...); err != nil {
return err
}
- a.degraded = ""
+ a.clearDegraded()
return nil
}
@@ -332,12 +392,38 @@ func (c Config) run(ctx context.Context, name string, args ...string) ([]byte, e
// Describe returns a redacted view for logs and health checks.
func (a *Agent) Describe() map[string]any {
- return map[string]any{
- "socket": a.config.Socket,
- "archive_root": a.config.ArchiveRoot,
- "journal_root": a.config.JournalRoot,
- "project": a.config.Project,
- "writers": a.config.Writers,
- "scope_choice": "request may select internal or external only",
- }
+ view := a.config.identity()
+ view["scope_choice"] = "request may select internal or external only"
+ return view
+}
+
+// health 是"这个执行器指向谁、现在能不能干活"的唯一回答。它只暴露容器名、
+// 路径与声明,不含任何凭据;调用方据此核对源身份,而不是靠配置猜。
+func (a *Agent) health() response {
+ state := a.snapshotState()
+ payload := a.config.identity()
+ payload["busy"] = state.Busy
+ payload["degraded"] = state.Degraded
+ encoded, err := json.Marshal(payload)
+ if err != nil {
+ return response{Action: "health", Error: "cannot encode health"}
+ }
+ return response{OK: true, Action: "health", Payload: json.RawMessage(encoded)}
+}
+
+// identity 被日志与健康应答共用一份,避免两处描述漂移。
+func (c Config) identity() map[string]any {
+ identity := map[string]any{
+ "project": c.Project,
+ "archive_root": c.ArchiveRoot,
+ "journal_root": c.JournalRoot,
+ "source_app": c.SourceApp,
+ "source_pg": c.SourcePG,
+ "source_es": c.SourceES,
+ "writers": c.Writers,
+ }
+ if c.SourceS3Endpoint != "" {
+ identity["source_s3_endpoint"] = c.SourceS3Endpoint
+ }
+ return identity
}
diff --git a/internal/libraryagent/client.go b/internal/libraryagent/client.go
index 78dba81..8822718 100644
--- a/internal/libraryagent/client.go
+++ b/internal/libraryagent/client.go
@@ -46,6 +46,12 @@ func Status(ctx context.Context, config ClientConfig) (Result, error) {
return call(ctx, config, map[string]any{"action": "status"})
}
+// Health 只问三件事:这个执行器指向谁(project/容器/归档)、是否在跑、是否降级。
+// 它不跑子进程、不占操作锁,所以可以当心跳用;Status 会去查源库,代价高得多。
+func Health(ctx context.Context, config ClientConfig) (Result, error) {
+ return call(ctx, config, map[string]any{"action": "health"})
+}
+
// Recover restores writers from an interrupted freeze journal.
func Recover(ctx context.Context, config ClientConfig) (Result, error) {
return call(ctx, config, map[string]any{"action": "recover"})
diff --git a/internal/libraryagent/health_test.go b/internal/libraryagent/health_test.go
new file mode 100644
index 0000000..d682105
--- /dev/null
+++ b/internal/libraryagent/health_test.go
@@ -0,0 +1,108 @@
+package libraryagent
+
+import (
+ "context"
+ "encoding/json"
+ "os"
+ "testing"
+ "time"
+)
+
+func serveAgent(t *testing.T, agent *Agent, socket string) {
+ t.Helper()
+ ctx, cancel := context.WithCancel(context.Background())
+ t.Cleanup(cancel)
+ go func() { _ = agent.Serve(ctx) }()
+ deadline := time.Now().Add(2 * time.Second)
+ for {
+ if _, err := os.Stat(socket); err == nil {
+ return
+ }
+ if time.Now().After(deadline) {
+ t.Fatal("agent socket never appeared")
+ }
+ time.Sleep(10 * time.Millisecond)
+ }
+}
+
+// 健康应答必须不排队等正在跑的封存:一次封存最长 15 分钟,如果 health 也去抢
+// 操作锁,页面就会把"正在封存"看成"执行器不可达",进而误导运维。
+func TestHealthAnswersWhileACaptureHoldsTheOperationLock(t *testing.T) {
+ agent, socket, calls := testAgent(t)
+ serveAgent(t, agent, socket)
+ // 占住操作锁并置 busy,模拟一次正在进行的封存。
+ agent.mu.Lock()
+ defer agent.mu.Unlock()
+ agent.setBusy(true)
+ defer agent.setBusy(false)
+
+ ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+ defer cancel()
+ result, err := Health(ctx, ClientConfig{Socket: socket, Timeout: 2 * time.Second})
+ if err != nil {
+ t.Fatalf("health while busy: %v", err)
+ }
+ var payload struct {
+ Project string `json:"project"`
+ Busy bool `json:"busy"`
+ }
+ if err = json.Unmarshal(result.Payload, &payload); err != nil {
+ t.Fatalf("health payload: %v", err)
+ }
+ if payload.Project != "weknora071full" || !payload.Busy {
+ t.Fatalf("health payload = %+v", payload)
+ }
+ if len(captureCalls(calls())) != 0 {
+ t.Fatalf("health must not run the capture binary, calls = %v", calls())
+ }
+}
+
+// 降级状态必须能被调用方看见:否则页面只能看到"可发起",而真发起会被拒。
+func TestHealthReportsDegradedState(t *testing.T) {
+ agent, socket, _ := testAgent(t)
+ serveAgent(t, agent, socket)
+ // 启动恢复成功会清空降级;这里在它之后模拟"恢复失败"留下的降级状态。
+ agent.setDegraded("写入者恢复失败")
+ ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+ defer cancel()
+ result, err := Health(ctx, ClientConfig{Socket: socket, Timeout: 2 * time.Second})
+ if err != nil {
+ t.Fatal(err)
+ }
+ var payload struct {
+ Degraded string `json:"degraded"`
+ SourceApp string `json:"source_app"`
+ Writers string `json:"writers"`
+ }
+ if err = json.Unmarshal(result.Payload, &payload); err != nil {
+ t.Fatal(err)
+ }
+ if payload.Degraded != "写入者恢复失败" || payload.SourceApp != "WKNFull-app" || payload.Writers != "app" {
+ t.Fatalf("health payload = %+v", payload)
+ }
+}
+
+// 封存结果必须自带"这次是谁执行的":调用方据此在事后复核,防止心跳与执行之间
+// socket 被换成另一个实例。
+func TestCaptureResultCarriesTheAgentIdentity(t *testing.T) {
+ agent, socket, _ := testAgent(t)
+ serveAgent(t, agent, socket)
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer cancel()
+ result, err := Capture(ctx, ClientConfig{Socket: socket, Timeout: 5 * time.Second}, "internal", "lib-internal-identity")
+ if err != nil {
+ t.Fatal(err)
+ }
+ var payload struct {
+ SnapshotID string `json:"snapshot_id"`
+ Identity struct {
+ Project string `json:"project"`
+ } `json:"agent_identity"`
+ }
+ if err = json.Unmarshal(result.Payload, &payload); err != nil {
+ t.Fatal(err)
+ }
+ if payload.SnapshotID != "abc" || payload.Identity.Project != "weknora071full" {
+ t.Fatalf("payload = %s", result.Payload)
+ }
+}
diff --git a/internal/libraryexecutor/executor.go b/internal/libraryexecutor/executor.go
new file mode 100644
index 0000000..1bf8fe7
--- /dev/null
+++ b/internal/libraryexecutor/executor.go
@@ -0,0 +1,122 @@
+// Package libraryexecutor 回答一个问题:主机侧封存执行器现在是不是真的可用,
+// 而且是不是指向我们这个实例。
+//
+// 为什么不能在页面里读一个配置字符串了事:正式栈曾经出现过"agent 顶着正式单元名
+// 却在冻结候选实例"的事故——配置非空、页面显示可发起、真发起却封错了库。可用的
+// 定义必须是**运行时观测**:socket 通、执行器自报的实例与期望一致、没有降级。
+package libraryexecutor
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "time"
+
+ "knowledge-governance/internal/libraryagent"
+)
+
+// Identity 是执行器自报的身份:它要冻结哪个容器的写入者、归档写到哪。
+// 只有容器名与路径,没有任何凭据。
+type Identity struct {
+ Project string `json:"project"`
+ ArchiveRoot string `json:"archive_root"`
+ JournalRoot string `json:"journal_root"`
+ SourceApp string `json:"source_app"`
+ SourcePG string `json:"source_pg"`
+ SourceES string `json:"source_es"`
+ Writers string `json:"writers"`
+ SourceS3Endpoint string `json:"source_s3_endpoint,omitempty"`
+}
+
+// Observation 是一次真实探测的结果,会被落库供页面读取。
+type Observation struct {
+ Instance string `json:"instance"`
+ Reachable bool `json:"reachable"`
+ Busy bool `json:"busy"`
+ Degraded string `json:"degraded,omitempty"`
+ Identity Identity `json:"identity"`
+ Error string `json:"error,omitempty"`
+ ObservedAt time.Time `json:"observed_at"`
+}
+
+// Expectation 是治理侧对执行器的要求。ArchiveRoot 不参与判定:容器里的路径是
+// 挂载后的路径,和宿主机上的真实路径本来就不是一个字符串;用它当门禁只会造成
+// 永久误报,所以只作为观测值展示给运维比对。
+type Expectation struct {
+ Instance string
+ Project string
+ ArchiveRoot string
+}
+
+// Probe 用一次短超时的 health 往返取回执行器身份。它不跑子进程、不碰源库,
+// 所以可以当心跳反复调用。instance 是"这次观测属于哪个实例",由调用方的
+// LIBRARY_TARGET_INSTANCE 决定。
+func Probe(ctx context.Context, instance, socket string, timeout time.Duration, now func() time.Time) Observation {
+ if now == nil {
+ now = time.Now
+ }
+ observation := Observation{Instance: instance, ObservedAt: now().UTC()}
+ if socket == "" {
+ observation.Error = "未配置主机侧封存 agent socket(LIBRARY_AGENT_SOCKET)"
+ return observation
+ }
+ if timeout <= 0 {
+ timeout = 3 * time.Second
+ }
+ result, err := libraryagent.Health(ctx, libraryagent.ClientConfig{Socket: socket, Timeout: timeout})
+ if err != nil {
+ observation.Error = err.Error()
+ return observation
+ }
+ var payload struct {
+ Identity
+ Busy bool `json:"busy"`
+ Degraded string `json:"degraded"`
+ }
+ if err = json.Unmarshal(result.Payload, &payload); err != nil {
+ observation.Error = "执行器健康应答无法解析"
+ return observation
+ }
+ observation.Reachable = true
+ observation.Busy = payload.Busy
+ observation.Degraded = payload.Degraded
+ observation.Identity = payload.Identity
+ return observation
+}
+
+// Evaluate 把"观测 + 期望 + 新鲜度"换算成页面上的可用性与原因。
+// 返回的原因必须能直接告诉运维该去改什么,而不是"不可用"三个字。
+func Evaluate(observation Observation, want Expectation, maxAge time.Duration, now time.Time) (bool, string) {
+ if want.Instance == "" {
+ return false, "未配置封存来源实例身份(LIBRARY_SOURCE_INSTANCE),无法确认执行器归属"
+ }
+ if observation.Instance != want.Instance {
+ return false, fmt.Sprintf("执行器状态来自另一个实例(%q),不是 %q", observation.Instance, want.Instance)
+ }
+ age := now.Sub(observation.ObservedAt)
+ if maxAge > 0 && age > maxAge {
+ return false, fmt.Sprintf("执行器状态已过期:%d 秒前的观测,上限 %d 秒(worker 未上报?)",
+ int(age.Seconds()), int(maxAge.Seconds()))
+ }
+ if !observation.Reachable {
+ reason := "主机侧封存执行器不可达"
+ if observation.Error != "" {
+ reason += ":" + observation.Error
+ }
+ return false, reason
+ }
+ if want.Project == "" {
+ return false, "未配置执行器源身份(LIBRARY_SOURCE_PROJECT),无法核对 agent 指向哪个实例"
+ }
+ if observation.Identity.Project != want.Project {
+ return false, fmt.Sprintf("执行器指向的实例不匹配:agent=%q,期望=%q",
+ observation.Identity.Project, want.Project)
+ }
+ if observation.Degraded != "" {
+ return false, "执行器处于降级状态(上次恢复失败):" + observation.Degraded
+ }
+ if observation.Busy {
+ return false, "执行器正在执行另一个封存/恢复,等它结束再发起"
+ }
+ return true, ""
+}
diff --git a/internal/libraryexecutor/executor_test.go b/internal/libraryexecutor/executor_test.go
new file mode 100644
index 0000000..dbfcef6
--- /dev/null
+++ b/internal/libraryexecutor/executor_test.go
@@ -0,0 +1,133 @@
+package libraryexecutor
+
+import (
+ "context"
+ "encoding/json"
+ "net"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+)
+
+func shortSocketDir(t *testing.T) string {
+ t.Helper()
+ // unix socket 路径上限 ~104 字节,TMPDIR(本机是 .hermes/cache/scratch)太长,
+ // 测试里用一个短目录并立刻清理。
+ dir, err := os.MkdirTemp("/tmp", "kgex-")
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { os.RemoveAll(dir) })
+ return dir
+}
+
+// 可用性必须来自运行时观测,而不是"配置里写了 socket 路径"。
+func TestProbeReadsIdentityFromTheAgentOverTheSocket(t *testing.T) {
+ root := shortSocketDir(t)
+ socket := filepath.Join(root, "agent.sock")
+ listener, err := net.Listen("unix", socket)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer listener.Close()
+ go func() {
+ for {
+ conn, acceptErr := listener.Accept()
+ if acceptErr != nil {
+ return
+ }
+ var request map[string]any
+ _ = json.NewDecoder(conn).Decode(&request)
+ payload, _ := json.Marshal(map[string]any{
+ "project": "kgmaint-weknora", "archive_root": "/tmp/kg-e2e/archive",
+ "journal_root": "/tmp/kg-e2e/journal", "source_app": "kgmaint-app",
+ "source_pg": "kgmaint-postgres", "source_es": "WKNFull-elasticsearch",
+ "writers": "app", "busy": true, "degraded": "",
+ })
+ _ = json.NewEncoder(conn).Encode(map[string]any{"ok": true, "action": "health", "payload": json.RawMessage(payload)})
+ conn.Close()
+ }
+ }()
+
+ observation := Probe(context.Background(), "kgmaint-weknora", socket, 2*time.Second, nil)
+ if !observation.Reachable {
+ t.Fatalf("observation = %+v", observation)
+ }
+ if observation.Identity.Project != "kgmaint-weknora" || observation.Identity.SourceApp != "kgmaint-app" || !observation.Busy {
+ t.Fatalf("identity = %+v", observation.Identity)
+ }
+ if observation.Instance != "kgmaint-weknora" || observation.ObservedAt.IsZero() {
+ t.Fatalf("observation = %+v", observation)
+ }
+}
+
+func TestProbeReportsUnreachableAgentWithoutFakingSuccess(t *testing.T) {
+ observation := Probe(context.Background(), "kgmaint-weknora", filepath.Join(t.TempDir(), "absent.sock"), time.Second, nil)
+ if observation.Reachable || observation.Error == "" {
+ t.Fatalf("observation = %+v", observation)
+ }
+ available, reason := Evaluate(observation, Expectation{Instance: "kgmaint-weknora", Project: "kgmaint-weknora"},
+ time.Minute, time.Now().UTC())
+ if available || !strings.Contains(reason, "不可达") {
+ t.Fatalf("available=%v reason=%q", available, reason)
+ }
+}
+
+func TestEvaluateRejectsEveryIdentityAndFreshnessProblem(t *testing.T) {
+ now := time.Date(2026, 10, 29, 8, 0, 0, 0, time.UTC)
+ healthy := Observation{
+ Instance: "kgmaint-weknora", Reachable: true, ObservedAt: now,
+ Identity: Identity{Project: "kgmaint-weknora", SourceApp: "kgmaint-app"},
+ }
+ want := Expectation{Instance: "kgmaint-weknora", Project: "kgmaint-weknora"}
+ if available, reason := Evaluate(healthy, want, 2*time.Minute, now); !available || reason != "" {
+ t.Fatalf("healthy executor rejected: %v %q", available, reason)
+ }
+
+ tests := []struct {
+ name string
+ mut func(*Observation)
+ want func(Expectation) Expectation
+ text string
+ }{
+ {name: "missing instance config", want: func(Expectation) Expectation { return expectEmptyInstance },
+ text: "LIBRARY_SOURCE_INSTANCE"},
+ {name: "row from another instance", mut: func(o *Observation) { o.Instance = "someone-else" },
+ text: "另一个实例"},
+ {name: "stale", mut: func(o *Observation) { o.ObservedAt = now.Add(-10 * time.Minute) },
+ text: "已过期"},
+ {name: "unreachable", mut: func(o *Observation) { o.Reachable = false; o.Error = "socket missing" },
+ text: "不可达:socket missing"},
+ {name: "project not configured", want: func(Expectation) Expectation { return Expectation{Instance: "kgmaint-weknora"} },
+ text: "LIBRARY_SOURCE_PROJECT"},
+ {name: "wrong source project", mut: func(o *Observation) { o.Identity.Project = "weknora071full" },
+ text: "指向的实例不匹配"},
+ {name: "degraded", mut: func(o *Observation) { o.Degraded = "写入者恢复失败" },
+ text: "降级状态"},
+ {name: "busy", mut: func(o *Observation) { o.Busy = true },
+ text: "正在执行另一个封存"},
+ }
+ for _, test := range tests {
+ t.Run(test.name, func(t *testing.T) {
+ observation := healthy
+ if test.mut != nil {
+ test.mut(&observation)
+ }
+ expectation := want
+ if test.want != nil {
+ expectation = test.want(want)
+ }
+ available, reason := Evaluate(observation, expectation, 2*time.Minute, now)
+ if available {
+ t.Fatalf("accepted: %+v", observation)
+ }
+ if !strings.Contains(reason, test.text) {
+ t.Fatalf("reason = %q, want it to mention %q", reason, test.text)
+ }
+ })
+ }
+}
+
+var expectEmptyInstance = Expectation{Project: "kgmaint-weknora"}
diff --git a/internal/platform/postgres/library_executor_status.go b/internal/platform/postgres/library_executor_status.go
new file mode 100644
index 0000000..a77f98c
--- /dev/null
+++ b/internal/platform/postgres/library_executor_status.go
@@ -0,0 +1,71 @@
+package postgres
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "time"
+
+ "github.com/jackc/pgx/v5"
+
+ "knowledge-governance/internal/libraryexecutor"
+)
+
+// 为什么落库而不是 API 直接探测:agent socket 只挂在 worker 容器里,API 那个
+// LIBRARY_AGENT_SOCKET 即使配了也 dial 不到。谁真能执行就由谁观测,页面读结果。
+const executorStatusColumns = `instance, reachable, busy, degraded, identity, status_error, observed_at`
+
+// UpsertLibraryExecutorStatus 记录一次真实探测。降级/不可达同样要写:
+// "最新一次观测是什么"比"最后一条好消息"更有用。
+func (s *Store) UpsertLibraryExecutorStatus(ctx context.Context, observation libraryexecutor.Observation, observer string, now time.Time) error {
+ identity, err := json.Marshal(observation.Identity)
+ if err != nil {
+ return fmt.Errorf("encode library executor identity: %w", err)
+ }
+ if observation.Instance == "" {
+ return errors.New("library executor observation needs an instance")
+ }
+ observedAt := observation.ObservedAt
+ if observedAt.IsZero() {
+ observedAt = now
+ }
+ _, err = s.db.Exec(ctx, `
+INSERT INTO library_executor_status (instance, reachable, busy, degraded, identity, status_error, observer, observed_at)
+VALUES ($1,$2,$3,$4,$5::jsonb,$6,$7,$8)
+ON CONFLICT (instance) DO UPDATE SET
+ reachable = EXCLUDED.reachable,
+ busy = EXCLUDED.busy,
+ degraded = EXCLUDED.degraded,
+ identity = EXCLUDED.identity,
+ status_error = EXCLUDED.status_error,
+ observer = EXCLUDED.observer,
+ observed_at = EXCLUDED.observed_at`,
+ observation.Instance, observation.Reachable, observation.Busy, observation.Degraded,
+ string(identity), observation.Error, observer, observedAt.UTC())
+ if err != nil {
+ return fmt.Errorf("record library executor status: %w", err)
+ }
+ return nil
+}
+
+// LibraryExecutorStatus 读某个实例最近一次观测;没有记录返回 nil(不是"可用")。
+func (s *Store) LibraryExecutorStatus(ctx context.Context, instance string) (*libraryexecutor.Observation, error) {
+ row := s.db.QueryRow(ctx, `SELECT `+executorStatusColumns+` FROM library_executor_status WHERE instance=$1`, instance)
+ var observation libraryexecutor.Observation
+ var raw []byte
+ err := row.Scan(&observation.Instance, &observation.Reachable, &observation.Busy, &observation.Degraded,
+ &raw, &observation.Error, &observation.ObservedAt)
+ if errors.Is(err, pgx.ErrNoRows) {
+ return nil, nil
+ }
+ if err != nil {
+ return nil, fmt.Errorf("read library executor status: %w", err)
+ }
+ if len(raw) > 0 {
+ if err := json.Unmarshal(raw, &observation.Identity); err != nil {
+ return nil, fmt.Errorf("library executor identity unreadable: %w", err)
+ }
+ }
+ return &observation, nil
+}
diff --git a/internal/platform/postgres/library_executor_status_integration_test.go b/internal/platform/postgres/library_executor_status_integration_test.go
new file mode 100644
index 0000000..8f81388
--- /dev/null
+++ b/internal/platform/postgres/library_executor_status_integration_test.go
@@ -0,0 +1,70 @@
+package postgres
+
+import (
+ "context"
+ "os"
+ "testing"
+ "time"
+
+ "github.com/jackc/pgx/v5/pgxpool"
+
+ "knowledge-governance/internal/libraryexecutor"
+)
+
+// 执行器状态是"最新一次观测",不是"最后一条好消息":
+// 降级与不可达必须覆盖上一次的健康记录,否则页面会一直显示可发起。
+func TestLibraryExecutorStatusKeepsTheLatestObservation(t *testing.T) {
+ databaseURL := isolatedIntegrationDatabaseURL(t, os.Getenv("TEST_DATABASE_URL"))
+ if databaseURL == "" {
+ t.Skip("TEST_DATABASE_URL is not set")
+ }
+ ctx := context.Background()
+ pool, err := pgxpool.New(ctx, databaseURL)
+ if err != nil {
+ t.Fatalf("connect: %v", err)
+ }
+ defer pool.Close()
+ if err := ApplyMigrations(ctx, pool); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ store := NewStore(pool)
+ now := time.Date(2026, 10, 29, 8, 0, 0, 0, time.UTC)
+
+ if missing, err := store.LibraryExecutorStatus(ctx, "kgmaint-weknora"); err != nil || missing != nil {
+ t.Fatalf("missing row = %+v, %v", missing, err)
+ }
+
+ healthy := libraryexecutor.Observation{
+ Instance: "kgmaint-weknora", Reachable: true, ObservedAt: now,
+ Identity: libraryexecutor.Identity{Project: "kgmaint-weknora", SourceApp: "kgmaint-app", ArchiveRoot: "/tmp/kg-e2e/archive"},
+ }
+ if err := store.UpsertLibraryExecutorStatus(ctx, healthy, "worker-1", now); err != nil {
+ t.Fatalf("upsert healthy: %v", err)
+ }
+ read, err := store.LibraryExecutorStatus(ctx, "kgmaint-weknora")
+ if err != nil {
+ t.Fatalf("read healthy: %v", err)
+ }
+ if read == nil || !read.Reachable || read.Identity.Project != "kgmaint-weknora" || read.Identity.SourceApp != "kgmaint-app" {
+ t.Fatalf("healthy row = %+v", read)
+ }
+ if !read.ObservedAt.Equal(now) {
+ t.Fatalf("observed_at = %v, want %v", read.ObservedAt, now)
+ }
+
+ degraded := healthy
+ degraded.Reachable = false
+ degraded.ObservedAt = now.Add(30 * time.Second)
+ degraded.Degraded = ""
+ degraded.Error = "library agent is unreachable"
+ if err := store.UpsertLibraryExecutorStatus(ctx, degraded, "worker-1", degraded.ObservedAt); err != nil {
+ t.Fatalf("upsert unreachable: %v", err)
+ }
+ read, err = store.LibraryExecutorStatus(ctx, "kgmaint-weknora")
+ if err != nil || read == nil {
+ t.Fatalf("read after unreachable: %+v %v", read, err)
+ }
+ if read.Reachable || read.Error != "library agent is unreachable" || !read.ObservedAt.Equal(degraded.ObservedAt) {
+ t.Fatalf("row kept a stale good state: %+v", read)
+ }
+}
diff --git a/internal/platform/postgres/migrations/000074_library_executor_status.down.sql b/internal/platform/postgres/migrations/000074_library_executor_status.down.sql
new file mode 100644
index 0000000..5441531
--- /dev/null
+++ b/internal/platform/postgres/migrations/000074_library_executor_status.down.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS library_executor_status;
\ No newline at end of file
diff --git a/internal/platform/postgres/migrations/000074_library_executor_status.up.sql b/internal/platform/postgres/migrations/000074_library_executor_status.up.sql
new file mode 100644
index 0000000..cf92a02
--- /dev/null
+++ b/internal/platform/postgres/migrations/000074_library_executor_status.up.sql
@@ -0,0 +1,16 @@
+-- 封存执行器的运行时状态:页面上的"可以发起封存"必须来自真实观测,而不是
+-- "配置里写了 socket 路径"。正式栈曾出现过 agent 顶着正式单元名却在冻结候选实例:
+-- 配置非空、页面显示可发起、真发起却封错了库。
+--
+-- worker 探测 agent 的 health(不跑子进程、不碰源库),把"它指向哪个实例、
+-- 是否降级/正在跑、什么时候观测的"落库;API 只读这张表并核对身份,不再猜。
+CREATE TABLE IF NOT EXISTS library_executor_status (
+ instance VARCHAR(128) PRIMARY KEY,
+ reachable BOOLEAN NOT NULL DEFAULT FALSE,
+ busy BOOLEAN NOT NULL DEFAULT FALSE,
+ degraded TEXT NOT NULL DEFAULT '',
+ identity JSONB NOT NULL DEFAULT '{}'::jsonb,
+ status_error TEXT NOT NULL DEFAULT '',
+ observer VARCHAR(64) NOT NULL DEFAULT '',
+ observed_at TIMESTAMPTZ NOT NULL
+);
\ No newline at end of file
diff --git a/internal/platform/postgres/migrations_test.go b/internal/platform/postgres/migrations_test.go
index f0c76f1..e15f24e 100644
--- a/internal/platform/postgres/migrations_test.go
+++ b/internal/platform/postgres/migrations_test.go
@@ -11,40 +11,45 @@ func TestEmbeddedMigrationsAreVersionSorted(t *testing.T) {
if err != nil {
t.Fatalf("loadMigrations() error = %v", err)
}
- if len(migrations) != 73 {
- t.Fatalf("migration count = %d, want 73", len(migrations))
+ if len(migrations) != 74 {
+ t.Fatalf("migration count = %d, want 74", len(migrations))
+ }
+ // 74 记录封存执行器的运行时状态:页面可用性来自真实观测,不来自配置字符串。
+ if executor := migrations[len(migrations)-1]; executor.Version != 74 ||
+ !strings.Contains(executor.UpSQL, "library_executor_status") {
+ t.Fatalf("migration 74 = %#v", executor)
}
// 73 记录死信精确解除:保留上游行,只绑定指纹、重放引用与观测摘要。
- if release := migrations[len(migrations)-1]; release.Version != 73 ||
+ if release := migrations[len(migrations)-2]; release.Version != 73 ||
!strings.Contains(release.UpSQL, "library_dead_letter_releases") {
t.Fatalf("migration 73 = %#v", release)
}
// 72 让维护占用按实例互斥(internal/external 不再各有各的锁)。
- if instance := migrations[len(migrations)-2]; instance.Version != 72 ||
+ if instance := migrations[len(migrations)-3]; instance.Version != 72 ||
!strings.Contains(instance.UpSQL, "library_instance_maintenance") {
t.Fatalf("migration 72 = %#v", instance)
}
// 71 让维护记录能区分实例级维护与仅治理库互斥。
- if level := migrations[len(migrations)-3]; level.Version != 71 ||
+ if level := migrations[len(migrations)-4]; level.Version != 71 ||
!strings.Contains(level.UpSQL, "level") || !strings.Contains(level.UpSQL, "ingress_state") {
t.Fatalf("migration 71 = %#v", level)
}
- if maint := migrations[len(migrations)-4]; maint.Version != 70 || !strings.Contains(maint.UpSQL, "library_maintenance") {
+ if maint := migrations[len(migrations)-5]; maint.Version != 70 || !strings.Contains(maint.UpSQL, "library_maintenance") {
t.Fatalf("migration 70 = %#v", maint)
}
- if tail := migrations[len(migrations)-5]; tail.Version != 69 ||
+ if tail := migrations[len(migrations)-6]; tail.Version != 69 ||
!strings.Contains(tail.UpSQL, "library_jobs_write_target") {
t.Fatalf("migration 69 = %#v", tail)
}
- if restore := migrations[len(migrations)-6]; restore.Version != 68 || !strings.Contains(restore.UpSQL, "restore") {
+ if restore := migrations[len(migrations)-7]; restore.Version != 68 || !strings.Contains(restore.UpSQL, "restore") {
t.Fatalf("migration 68 = %#v", restore)
}
- if last := migrations[len(migrations)-7]; last.Version != 67 ||
+ if last := migrations[len(migrations)-8]; last.Version != 67 ||
!strings.Contains(last.UpSQL, "library_release_authorizations") ||
!strings.Contains(last.UpSQL, "params_digest") {
t.Fatalf("migration 67 = %#v", last)
}
- if flow := migrations[len(migrations)-8]; flow.Version != 66 ||
+ if flow := migrations[len(migrations)-9]; flow.Version != 66 ||
!strings.Contains(flow.UpSQL, "CREATE TABLE library_versions") ||
!strings.Contains(flow.UpSQL, "library_jobs_active") {
t.Fatalf("migration 66 = %#v", flow)
--
2.52.0
From c40696145b43a47ea0cef6d83ae2fbe00bb3677f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 13:01:46 +0800
Subject: [PATCH 28/45] =?UTF-8?q?feat(library-web):=20=E6=81=A2=E5=A4=8D?=
=?UTF-8?q?=E5=85=A5=E5=8F=A3=E6=8C=89=E7=9C=9F=E5=AE=9E=E6=9D=A1=E4=BB=B6?=
=?UTF-8?q?=E5=90=AF=E7=94=A8=E5=B9=B6=E6=94=AF=E6=8C=81=E7=AD=BE=E5=8F=91?=
=?UTF-8?q?=E6=81=A2=E5=A4=8D=E6=8E=88=E6=9D=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
原来"恢复至该版本"写死 disabled,标题还写"生产恢复未接线"——而 POST /library/restores
与授权接口早已可用,等于把整库还原的唯一入口藏起来。
现在页面按 GET /library/restore-availability 启用:缺授权时管理员可签发 30 分钟
有效期的 restore 授权(固定期限,没有"永久授权"),条件满足才可点恢复;工程师只看到
条件与"仅管理员可发起"。封存不可发起时也不再写死"通道未接线",而是显示接口原因、
执行器身份与观测时间。
---
web/src/ReleaseTargets.test.tsx | 81 +++++++++++++--
web/src/ReleaseTargets.tsx | 170 ++++++++++++++++++++++++++++++--
web/src/libraryRestore.test.ts | 87 ++++++++++++++++
web/src/librarySnapshots.ts | 109 ++++++++++++++++++++
4 files changed, 433 insertions(+), 14 deletions(-)
create mode 100644 web/src/libraryRestore.test.ts
diff --git a/web/src/ReleaseTargets.test.tsx b/web/src/ReleaseTargets.test.tsx
index 2a967cf..6e18f6d 100644
--- a/web/src/ReleaseTargets.test.tsx
+++ b/web/src/ReleaseTargets.test.tsx
@@ -149,6 +149,13 @@ const base: ViewProps = {
pendingCapture: false,
canCapture: true,
canWrite: true,
+ canRestore: false,
+ restore: null,
+ restoreNotice: null,
+ pendingRestore: false,
+ pendingGrant: false,
+ onGrantRestore: vi.fn(),
+ onRestore: vi.fn(),
maintenance: null,
now: new Date('2026-10-28T03:35:00Z').getTime(),
onRefresh: vi.fn(),
@@ -239,18 +246,62 @@ describe('ReleaseTargetsView(确认稿布局)', () => {
expect(html).toContain('列表只校验清单自身,字节级复核在同步/恢复执行前进行')
})
- it('版本与快照抽屉按 scope 列出全部历史并区分测试封存/不可直接恢复', () => {
- const html = render({ drawerOpen: true, expandedSnapshot: internalSnapshot.snapshot_id })
+ it('版本与快照抽屉按 scope 列出全部历史,并把恢复条件交给接口判定', () => {
+ const html = render({ drawerOpen: true, expandedSnapshot: internalSnapshot.snapshot_id, canRestore: true })
expect(html).toContain('版本与快照')
expect(html).toContain('封存 f992d64ea45b')
expect(html).toContain('测试封存')
- expect(html).toContain('不可直接恢复')
+ expect(html).toContain('恢复条件见下方')
expect(html).toContain('恢复至该版本')
expect(html).toMatch(/恢复至该版本[^<]*<\/button>/)
expect(html).toContain('分项数量 / 字节 / 摘要(2 项)')
expect(html).toContain('不支持只选择 Wiki 或某张数据表恢复')
})
+ it('管理员在缺授权时看到签发入口,恢复按钮按接口给出的原因禁用', () => {
+ const html = render({
+ drawerOpen: true,
+ expandedSnapshot: internalSnapshot.snapshot_id,
+ canRestore: true,
+ restore: {
+ allowed: false,
+ reasons: ['没有针对该快照的恢复授权:先签发 restore 授权(绑定同一快照)'],
+ scope: 'internal',
+ snapshot_id: internalSnapshot.snapshot_id,
+ authorization: { state: 'none' },
+ },
+ })
+ expect(html).toContain('签发恢复授权(30 分钟)')
+ expect(html).toContain('没有针对该快照的恢复授权')
+ expect(html).toMatch(/rel-danger[^>]*disabled/)
+ // 不能再说"未接线":条件不满足要给出具体原因
+ expect(html).not.toContain('生产恢复未接线')
+ })
+
+ it('条件全满足时恢复按钮可用,并写明授权有效期', () => {
+ const html = render({
+ drawerOpen: true,
+ expandedSnapshot: internalSnapshot.snapshot_id,
+ canRestore: true,
+ restore: {
+ allowed: true,
+ reasons: [],
+ scope: 'internal',
+ snapshot_id: internalSnapshot.snapshot_id,
+ authorization: { state: 'active', authorized_by: 'yaozhanghao', expires_at: '2026-10-28T04:10:00Z' },
+ },
+ })
+ expect(html).toContain('条件已满足')
+ expect(html).toContain('有效至')
+ expect(html).not.toMatch(/rel-danger[^>]*disabled/)
+ })
+
+ it('工程师看不到恢复入口,只看到权限说明', () => {
+ const html = render({ drawerOpen: true, expandedSnapshot: internalSnapshot.snapshot_id, canRestore: false })
+ expect(html).toContain('按版本恢复仅管理员可发起')
+ expect(html).not.toContain('签发恢复授权')
+ })
+
it('抽屉只展示当前选中库的历史', () => {
const html = render({ drawerOpen: true, scope: 'external' })
expect(html).toContain('封存 01343b0b310b')
@@ -277,14 +328,30 @@ describe('ReleaseTargetsView(确认稿布局)', () => {
expect(html).toContain('主机侧正在暂停写入者、导出并恢复')
})
- it('无权限时不给封存入口,未接线时说明通道状态', () => {
+ it('无权限时不给封存入口;不可发起时给出接口返回的真实原因与执行器身份', () => {
expect(render({ canCapture: false, canWrite: false })).toContain('封存需要知识工程师及以上权限')
- const unwired = render({
+ const unavailable = render({
canCapture: false,
canWrite: true,
- page: { ...page, capture_available: false, capture_reason: '主机侧封存 agent 未接线' },
+ page: { ...page, capture_available: false },
+ overview: {
+ ...overview,
+ capture_available: false,
+ capture_reason: '执行器指向的实例不匹配:agent="weknora071full",期望="kgmaint-weknora"',
+ executor: {
+ available: false,
+ busy: false,
+ project: 'weknora071full',
+ source_app: 'WKNFull-app',
+ observed_at: '2026-10-28T03:34:00Z',
+ },
+ },
})
- expect(unwired).toContain('封存通道未接线')
+ expect(unavailable).toContain('执行器指向的实例不匹配')
+ expect(unavailable).toContain('执行器 weknora071full / WKNFull-app')
+ expect(unavailable).toContain('观测于')
+ // 通道可用/不可用都不许用写死的"未接线"糊过去
+ expect(unavailable).not.toContain('封存通道未接线')
})
it('无封存时给出“尚无封存”而不是空表', () => {
diff --git a/web/src/ReleaseTargets.tsx b/web/src/ReleaseTargets.tsx
index 1c4f952..32a2a0e 100644
--- a/web/src/ReleaseTargets.tsx
+++ b/web/src/ReleaseTargets.tsx
@@ -1,10 +1,13 @@
import { useCallback, useEffect, useState } from 'react'
import {
+ createLibraryRestoreAuthorization,
enqueueLibraryCapture,
enqueueLibraryRecovery,
+ enqueueLibraryRestore,
fetchLibraryCaptures,
fetchLibraryMaintenance,
fetchLibraryOverview,
+ fetchLibraryRestoreAvailability,
fetchLibrarySnapshots,
formatBytes,
scopeLabel,
@@ -12,6 +15,7 @@ import {
type LibraryJobRecord,
type LibraryMaintenanceView,
type LibraryOverview,
+ type LibraryRestoreAvailability,
type LibrarySnapshot,
type LibrarySnapshotList,
type LibraryStageRow,
@@ -85,6 +89,14 @@ interface ViewProps {
pendingCapture: boolean
canCapture: boolean
canWrite: boolean
+ // 按版本恢复是管理员动作:工程师看得到条件,但拿不到恢复入口。
+ canRestore: boolean
+ restore: LibraryRestoreAvailability | null
+ restoreNotice: string | null
+ pendingRestore: boolean
+ pendingGrant: boolean
+ onGrantRestore: () => void
+ onRestore: () => void
overview: LibraryOverview | null
maintenance: LibraryMaintenanceView | null
now: number
@@ -118,6 +130,20 @@ function scopeView(
const scopeName = (scope: Scope) => (scope === 'internal' ? '对内知识库' : '对外知识库')
+// 不可发起时必须说清是哪一条不满足:读的是接口给出的真实原因(执行器不可达、
+// 指向别的实例、降级、观测过期),不是一句写死的"通道未接线"。
+function captureHint(view: ScopeView, canWrite: boolean): string {
+ if (!canWrite) return '封存需要知识工程师及以上权限'
+ const executor = view.overview?.executor
+ const reason = view.overview?.capture_reason || executor?.reason
+ const observed = executor?.observed_at ? `(观测于 ${stamp(executor.observed_at)})` : ''
+ const identity = executor?.project
+ ? `执行器 ${executor.project}${executor.source_app ? ` / ${executor.source_app}` : ''} · `
+ : ''
+ if (reason) return `${identity}封存通道不可用:${reason}${observed}`
+ return '封存通道状态未知:还没有读到执行器观测'
+}
+
function statusOf(view: ScopeView) {
const job = view.job
if (job && (job.state === 'running' || job.state === 'pending')) {
@@ -629,7 +655,7 @@ function ReadyBody({
{pendingCapture ? '投递中…' : '封存测试版本'}
) : (
- {canWrite ? '封存通道未接线' : '封存需要知识工程师及以上权限'}
+ {captureHint(view, canWrite)}
)}
>
@@ -822,8 +848,16 @@ interface DrawerProps {
onExpand: (id: string | null) => void
onClose: () => void
canCapture: boolean
+ canRestore: boolean
pendingCapture: boolean
onCapture: () => void
+ // 恢复条件来自容器(真实接口判定):双闸 / 该快照的授权 / 目标是否在维护。
+ restore: LibraryRestoreAvailability | null
+ restoreNotice: string | null
+ pendingRestore: boolean
+ pendingGrant: boolean
+ onGrantRestore: () => void
+ onRestore: () => void
}
function Drawer({
@@ -835,8 +869,15 @@ function Drawer({
onExpand,
onClose,
canCapture,
+ canRestore,
pendingCapture,
onCapture,
+ restore,
+ restoreNotice,
+ pendingRestore,
+ pendingGrant,
+ onGrantRestore,
+ onRestore,
}: DrawerProps) {
if (!open) return null
const listing = view.history
@@ -919,8 +960,12 @@ function Drawer({
>
{isSelected ? '收起快照' : '查看快照'}
-
-
+
查看校验记录
-
- 恢复至该版本
-
+ {canRestore && restore && restore.authorization.state !== 'active' ? (
+
+ {pendingGrant ? '签发中…' : '签发恢复授权(30 分钟)'}
+
+ ) : null}
+ {canRestore ? (
+
+ {pendingRestore ? '投递中…' : '恢复至该版本'}
+
+ ) : (
+ 按版本恢复仅管理员可发起
+ )}
+ {restore && !restore.allowed ? (
+
+ {restore.reasons.map((reason) => (
+ - {reason}
+ ))}
+
+ ) : null}
+ {restore?.allowed ? (
+
+ 条件已满足:生产写入闸口打开、这份快照有恢复授权
+ {restore.authorization.expires_at ? `(有效至 ${stamp(restore.authorization.expires_at)})` : ''}
+ 、目标实例未在维护。
+
+ ) : null}
+ {restore === null ? 正在读取恢复条件…
: null}
+ {restoreNotice ? {restoreNotice}
: null}
) : null}
@@ -1047,6 +1127,13 @@ export function ReleaseTargetsView(props: ViewProps) {
pendingCapture,
canCapture,
canWrite,
+ canRestore,
+ restore,
+ restoreNotice,
+ pendingRestore,
+ pendingGrant,
+ onGrantRestore,
+ onRestore,
now,
maintenance,
onRefresh,
@@ -1241,8 +1328,15 @@ export function ReleaseTargetsView(props: ViewProps) {
onExpand={onExpandSnapshot}
onClose={() => onDrawer(false)}
canCapture={canCapture}
+ canRestore={canRestore}
pendingCapture={pendingCapture}
onCapture={onCapture}
+ restore={restore}
+ restoreNotice={restoreNotice}
+ pendingRestore={pendingRestore}
+ pendingGrant={pendingGrant}
+ onGrantRestore={onGrantRestore}
+ onRestore={onRestore}
/>
)
@@ -1313,8 +1407,63 @@ export function ReleaseTargets() {
const role = auth?.identity?.role
const canWrite = role === 'engineer' || role === 'admin'
+ // 恢复写的是整套生产知识状态,接口只认管理员;页面必须与它一致。
+ const canRestore = role === 'admin'
const canCapture = canWrite && page?.capture_available === true
+ // 恢复条件随"展开的那份快照"变化:闸口、该快照的授权、实例是否在维护都由接口判定。
+ const [restore, setRestore] = useState(null)
+ const [restoreNotice, setRestoreNotice] = useState(null)
+ const [pendingRestore, setPendingRestore] = useState(false)
+ const [pendingGrant, setPendingGrant] = useState(false)
+ const [restoreRound, setRestoreRound] = useState(0)
+ const restoreSnapshot = expandedSnapshot ?? ''
+ useEffect(() => {
+ if (!drawerOpen || !restoreSnapshot) {
+ setRestore(null)
+ return
+ }
+ const controller = new AbortController()
+ void fetchLibraryRestoreAvailability(scope, restoreSnapshot, controller.signal)
+ .then((value) => setRestore(value))
+ .catch(() => setRestore(null))
+ return () => controller.abort()
+ }, [drawerOpen, restoreSnapshot, scope, restoreRound])
+
+ const grantRestore = async () => {
+ if (!restoreSnapshot) return
+ setPendingGrant(true)
+ setRestoreNotice(null)
+ try {
+ const grant = await createLibraryRestoreAuthorization(scope, restoreSnapshot)
+ setRestoreNotice(
+ `已签发恢复授权${grant.authorized_by ? `(${grant.authorized_by})` : ''},有效至 ${stamp(grant.expires_at)}`
+ )
+ setRestoreRound((round) => round + 1)
+ await load()
+ } catch (grantError) {
+ setRestoreNotice(grantError instanceof Error ? grantError.message : '签发恢复授权失败')
+ } finally {
+ setPendingGrant(false)
+ }
+ }
+
+ const startRestore = async () => {
+ if (!restoreSnapshot) return
+ setPendingRestore(true)
+ setRestoreNotice(null)
+ try {
+ const accepted = await enqueueLibraryRestore(scope, restoreSnapshot)
+ setRestoreNotice(`已投递恢复:${accepted.job_id}(整套生产知识状态回到该快照)`)
+ setRestoreRound((round) => round + 1)
+ await load()
+ } catch (restoreError) {
+ setRestoreNotice(restoreError instanceof Error ? restoreError.message : '发起恢复失败')
+ } finally {
+ setPendingRestore(false)
+ }
+ }
+
const startCapture = async () => {
setPendingCapture(true)
setNotice(null)
@@ -1364,6 +1513,13 @@ export function ReleaseTargets() {
pendingCapture={pendingCapture}
canCapture={canCapture}
canWrite={canWrite}
+ canRestore={canRestore}
+ restore={restore}
+ restoreNotice={restoreNotice}
+ pendingRestore={pendingRestore}
+ pendingGrant={pendingGrant}
+ onGrantRestore={() => void grantRestore()}
+ onRestore={() => void startRestore()}
maintenance={maintenances[scope]}
now={now}
onRefresh={() => void load()}
diff --git a/web/src/libraryRestore.test.ts b/web/src/libraryRestore.test.ts
new file mode 100644
index 0000000..5707df3
--- /dev/null
+++ b/web/src/libraryRestore.test.ts
@@ -0,0 +1,87 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+ createLibraryRestoreAuthorization,
+ enqueueLibraryRestore,
+ fetchLibraryRestoreAvailability,
+} from './librarySnapshots'
+
+const jsonResponse = (body: unknown, status = 200) =>
+ new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } })
+
+afterEach(() => {
+ vi.unstubAllGlobals()
+})
+
+describe('整库恢复的前端契约', () => {
+ it('读取恢复条件时把原因与授权状态原样带回来', async () => {
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn().mockResolvedValue(
+ jsonResponse({
+ allowed: false,
+ reasons: ['没有针对该快照的恢复授权:先签发 restore 授权(绑定同一快照)'],
+ scope: 'internal',
+ snapshot_id: 'snap-1',
+ authorization: { state: 'none', reason: '没有与目标快照匹配的有效发布授权' },
+ })
+ )
+ )
+ const availability = await fetchLibraryRestoreAvailability('internal', 'snap-1')
+ expect(availability?.allowed).toBe(false)
+ expect(availability?.reasons).toHaveLength(1)
+ expect(availability?.authorization.state).toBe('none')
+ const requested = (vi.mocked(fetch).mock.calls[0]?.[0] as string) ?? ''
+ expect(requested).toContain('scope=internal')
+ expect(requested).toContain('snapshot_id=snap-1')
+ })
+
+ it('签发恢复授权必须声明 action=restore 与有限有效期', async () => {
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn().mockResolvedValue(
+ jsonResponse(
+ {
+ authorization: {
+ id: 'libauth-restore-1',
+ authorized_by: 'yaozhanghao',
+ expires_at: '2026-10-29T09:00:00Z',
+ },
+ },
+ 201
+ )
+ )
+ )
+ const grant = await createLibraryRestoreAuthorization('internal', 'snap-1')
+ expect(grant.id).toBe('libauth-restore-1')
+ const init = vi.mocked(fetch).mock.calls[0]?.[1] as RequestInit
+ const body = JSON.parse(String(init.body)) as Record
+ expect(body.action).toBe('restore')
+ expect(body.expires_in_minutes).toBe(30)
+ })
+
+ it('恢复被拒时把逐条原因说给用户,而不是只说 HTTP 状态', async () => {
+ vi.stubGlobal(
+ 'fetch',
+ vi
+ .fn()
+ .mockResolvedValue(
+ jsonResponse({ code: 'library_restore_blocked', reasons: ['生产写入闸口关闭', '没有该快照的恢复授权'] }, 503)
+ )
+ )
+ await expect(enqueueLibraryRestore('internal', 'snap-1')).rejects.toThrow('生产写入闸口关闭;没有该快照的恢复授权')
+ })
+
+ it('投递成功时返回作业号,供页面显示真实进度', async () => {
+ vi.stubGlobal(
+ 'fetch',
+ vi
+ .fn()
+ .mockResolvedValue(
+ jsonResponse({ job: { id: 'librestore-internal-1', scope: 'internal' }, reused: false }, 202)
+ )
+ )
+ const accepted = await enqueueLibraryRestore('internal', 'snap-1')
+ expect(accepted.job_id).toBe('librestore-internal-1')
+ expect(accepted.reused).toBe(false)
+ })
+})
diff --git a/web/src/librarySnapshots.ts b/web/src/librarySnapshots.ts
index 679c3ca..50441c6 100644
--- a/web/src/librarySnapshots.ts
+++ b/web/src/librarySnapshots.ts
@@ -185,6 +185,101 @@ export async function enqueueLibraryCapture(scope: string): Promise {
+ const query = `scope=${encodeURIComponent(scope)}&snapshot_id=${encodeURIComponent(snapshotID)}`
+ const response = await fetch(`/api/v1/library/restore-availability?${query}`, {
+ headers: { Accept: 'application/json' },
+ signal,
+ })
+ const value = (await response.json().catch(() => null)) as unknown
+ if (!record(value)) return null
+ return {
+ allowed: bool(value.allowed),
+ reasons: Array.isArray(value.reasons) ? value.reasons.map(text).filter(Boolean) : [],
+ scope: text(value.scope),
+ snapshot_id: text(value.snapshot_id),
+ authorization: record(value.authorization)
+ ? {
+ state: text(value.authorization.state) === 'active' ? 'active' : 'none',
+ authorized_by: text(value.authorization.authorized_by) || undefined,
+ expires_at: text(value.authorization.expires_at) || undefined,
+ reason: text(value.authorization.reason) || undefined,
+ }
+ : { state: 'none' },
+ }
+}
+
+// 恢复整套生产知识状态:同一份快照的文档、分块、索引、资源与 Wiki 一起回放。
+export interface LibraryRestoreAccepted {
+ job_id: string
+ scope: string
+ reused: boolean
+}
+
+export async function enqueueLibraryRestore(scope: string, snapshotID: string): Promise {
+ const response = await fetch('/api/v1/library/restores', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+ body: JSON.stringify({ scope, snapshot_id: snapshotID }),
+ })
+ const value = (await response.json().catch(() => null)) as unknown
+ if (!response.ok) {
+ if (response.status === 403) throw new Error('按版本恢复仅管理员可发起。')
+ if (response.status === 503 && record(value)) {
+ const reasons = Array.isArray(value.reasons) ? value.reasons.map(text).filter(Boolean) : []
+ throw new Error(reasons.length > 0 ? reasons.join(';') : text(value.error) || '恢复条件不满足')
+ }
+ if (response.status === 409 && record(value)) throw new Error(text(value.error) || '该目标已有在飞作业')
+ throw new Error(`发起恢复失败(HTTP ${response.status})`)
+ }
+ if (!record(value) || !record(value.job)) throw new Error('恢复作业响应无效')
+ return { job_id: text(value.job.id), scope: text(value.job.scope), reused: bool(value.reused) }
+}
+
+export interface LibraryRestoreGrant {
+ id: string
+ authorized_by: string
+ expires_at: string
+}
+
+// 恢复授权与执行是两件事:授权把"目标 + 快照 + 参数"钉死并给很短的有效期,
+// 同步授权不能顶替恢复授权(摘要不同)。
+export async function createLibraryRestoreAuthorization(
+ scope: string,
+ snapshotID: string,
+ minutes = 30
+): Promise {
+ const response = await fetch('/api/v1/library/authorizations', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+ body: JSON.stringify({ scope, snapshot_id: snapshotID, action: 'restore', expires_in_minutes: minutes }),
+ })
+ const value = (await response.json().catch(() => null)) as unknown
+ if (!response.ok) {
+ if (response.status === 403) throw new Error('生产发布授权仅管理员可签发。')
+ throw new Error(`签发恢复授权失败(HTTP ${response.status})`)
+ }
+ if (!record(value) || !record(value.authorization)) throw new Error('授权响应无效')
+ return {
+ id: text(value.authorization.id),
+ authorized_by: text(value.authorization.authorized_by),
+ expires_at: text(value.authorization.expires_at),
+ }
+}
+
export async function fetchLibraryCaptures(signal?: AbortSignal): Promise {
const response = await fetch('/api/v1/library/captures', {
headers: { Accept: 'application/json' },
@@ -391,6 +486,18 @@ export interface LibraryGate {
reasons: string[]
}
+export interface LibraryExecutorView {
+ available: boolean
+ reason?: string
+ instance?: string
+ project?: string
+ source_app?: string
+ archive_root?: string
+ busy: boolean
+ degraded?: string
+ observed_at?: string
+}
+
export interface LibraryOverview {
scope: string
test_sealed?: LibrarySnapshot
@@ -404,6 +511,8 @@ export interface LibraryOverview {
authorization: LibraryAuthorizationView
capture_available: boolean
capture_reason?: string
+ // 执行器是 worker 的真实观测:指向哪个实例、何时观测、是否降级/在跑。
+ executor?: LibraryExecutorView
now: string
}
--
2.52.0
From cfad0034995de0fdd4a437de336502dc574fb0b3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 13:01:46 +0800
Subject: [PATCH 29/45] =?UTF-8?q?fix(release-worker):=20=E5=90=AF=E5=8A=A8?=
=?UTF-8?q?=E5=A4=B1=E8=B4=A5=E5=B8=A6=E7=AB=AF=E7=82=B9=E4=B8=8E=E8=84=B1?=
=?UTF-8?q?=E6=95=8F=E5=8E=9F=E5=9B=A0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
正式 release-worker 崩溃重启时日志只有一句 connect release target database,
主机名、库名和底层原因都不在里面。现在错误里带 host:port/db、路由标识与原因。
端点去口令不等于整条日志安全:pgx 的解析错误可能原样回显连接串。新增
internal/pgdsn.Redact(按已知口令精确替换 + 按 URL/keyword 形状兜底),
错误保留 Unwrap 以便 errors.Is/As,技术原因不丢。cmd/worker 里只留库名的旧实现
换成同一个包,避免两份脱敏逻辑。libraryctl 用法补上 dead-letters。
---
cmd/libraryctl/main.go | 4 +-
cmd/release-worker/diagnosis_test.go | 57 ++++++++++++++++
cmd/release-worker/runtime.go | 29 ++++++++-
cmd/worker/library_handlers.go | 3 +-
internal/pgdsn/dsn.go | 81 +++++++++++++++++++++++
internal/pgdsn/dsn_test.go | 97 ++++++++++++++++++++++++++++
6 files changed, 267 insertions(+), 4 deletions(-)
create mode 100644 cmd/release-worker/diagnosis_test.go
create mode 100644 internal/pgdsn/dsn.go
create mode 100644 internal/pgdsn/dsn_test.go
diff --git a/cmd/libraryctl/main.go b/cmd/libraryctl/main.go
index f5c653a..7b2206b 100644
--- a/cmd/libraryctl/main.go
+++ b/cmd/libraryctl/main.go
@@ -111,7 +111,7 @@ func main() {
}
func usage() {
- fmt.Fprint(os.Stderr, `libraryctl [flags]
+ fmt.Fprint(os.Stderr, `libraryctl [flags]
status probe the real source and print what is configured / blocked
preflight read the source, run settlement + candidate validation (no writes, no stop)
@@ -119,6 +119,8 @@ func usage() {
list list sealed candidates and stored bytes
verify re-verify one sealed candidate (digests, coverage, identity)
recover restore writers from an interrupted freeze journal
+ dead-letters print the source's live dead letters (read-only) with a digest the
+ governance platform binds a precise release to
Flags (defaults target the local WKNFull test stack):
-source-app WKNFull-app container whose env describes the source
diff --git a/cmd/release-worker/diagnosis_test.go b/cmd/release-worker/diagnosis_test.go
new file mode 100644
index 0000000..e0b7c1b
--- /dev/null
+++ b/cmd/release-worker/diagnosis_test.go
@@ -0,0 +1,57 @@
+package main
+
+import (
+ "errors"
+ "fmt"
+ "strings"
+ "testing"
+)
+
+// 正式栈的 release-worker 启动失败时只打一句 "connect release target database",
+// 主机名、库名与底层原因都不在日志里。修好之后仍然要证明:可诊断 ≠ 泄露凭据,
+// 因为 pgx 的解析/连接错误会把连接串原样带回来。
+var diagnosisSecret = "rel" + "ease-s3cret-value"
+
+func TestReleaseDatabaseErrorNamesTheEndpointWithoutCredentials(t *testing.T) {
+ cause := errors.New("dial tcp 127.0.0.1:1: connect: connection refused")
+ message := releaseDatabaseError("target",
+ "postgres://postgres:ignored@prod-pg:25432/weknora_test?sslmode=disable", "kb-release-diagnosis", cause).Error()
+ for _, want := range []string{"connect release target database", "prod-pg:25432/weknora_test",
+ "kb-release-diagnosis", "connection refused"} {
+ if !strings.Contains(message, want) {
+ t.Fatalf("error %q does not mention %q", message, want)
+ }
+ }
+ source := releaseDatabaseError("source", "postgres://u:p@WKNFull-postgres:5432/weknora_full", "kb-1", cause).Error()
+ if !strings.Contains(source, "WKNFull-postgres:5432/weknora_full") {
+ t.Fatalf("source error = %q", source)
+ }
+}
+
+// cause 原样回显 DSN(pgx 在解析/连接失败时确实可能这样)是最危险的一种:
+// 端点脱敏救不了它,整条错误里都藏着口令。
+func TestReleaseDatabaseErrorRedactsACauseThatEchoesTheDSN(t *testing.T) {
+ cases := []string{
+ "postgres://postgres:" + diagnosisSecret + "@127.0.0.1:notaport/weknora_test",
+ "host=127.0.0.1 port=5432 user=postgres password=" + diagnosisSecret + " dbname=weknora_test sslmode=bogus",
+ }
+ for _, dsn := range cases {
+ cause := fmt.Errorf("cannot parse `%s`: invalid port after host", dsn)
+ message := releaseDatabaseError("target", dsn, "kb-release-diagnosis", cause).Error()
+ if strings.Contains(message, diagnosisSecret) {
+ t.Fatalf("error leaked the password: %q", message)
+ }
+ if !strings.Contains(message, "invalid port after host") {
+ t.Fatalf("error lost the underlying reason: %q", message)
+ }
+ }
+}
+
+// 保留 Unwrap:调用方仍然可以用 errors.Is/As 判断原因;只是文本被脱敏。
+func TestReleaseDatabaseErrorKeepsTheCauseChain(t *testing.T) {
+ sentinel := errors.New("boom")
+ err := releaseDatabaseError("target", "postgres://u:p@h:1/db", "kb-1", sentinel)
+ if !errors.Is(err, sentinel) {
+ t.Fatalf("cause chain broken: %v", err)
+ }
+}
diff --git a/cmd/release-worker/runtime.go b/cmd/release-worker/runtime.go
index e4430af..2b34acb 100644
--- a/cmd/release-worker/runtime.go
+++ b/cmd/release-worker/runtime.go
@@ -3,6 +3,7 @@ package main
import (
"context"
"errors"
+ "fmt"
"net/url"
"path/filepath"
"strconv"
@@ -11,6 +12,7 @@ import (
"github.com/jackc/pgx/v5/pgxpool"
+ "knowledge-governance/internal/pgdsn"
"knowledge-governance/internal/platform/weknora"
v071 "knowledge-governance/internal/releaseadapter/v071"
"knowledge-governance/internal/releasesnapshot"
@@ -63,13 +65,13 @@ func buildReleaseRoute(ctx context.Context, archiveRoot string, snapshot release
}
sourcePool, err := openReleasePool(ctx, sourceDatabaseURL)
if err != nil {
- return nil, nil, errors.New("connect release source database")
+ return nil, nil, releaseDatabaseError("source", sourceDatabaseURL, route.KnowledgeBaseID, err)
}
pools := []*pgxpool.Pool{sourcePool}
targetPool, err := openReleasePool(ctx, targetDatabaseURL)
if err != nil {
sourcePool.Close()
- return nil, nil, errors.New("connect release target database")
+ return nil, nil, releaseDatabaseError("target", targetDatabaseURL, route.KnowledgeBaseID, err)
}
pools = append(pools, targetPool)
cleanup := func(err error) (releaseworkflow.Publisher, []*pgxpool.Pool, error) {
@@ -207,6 +209,29 @@ func readOptionalRestrictedValue(path string) (string, error) {
return readRestrictedValue(path)
}
+// releaseDatabaseError 是"连不上某个库"的唯一措辞:端点 + 路由 + 底层原因。
+//
+// 为什么不用 %w 直接拼原因:pgx 的错误里可能原样带着连接串(含口令),
+// 只在端点脱敏证明不了整条日志安全。这里把原因文本交给 pgdsn.Redact 抹口令,
+// 同时保留 Unwrap,调用方仍能用 errors.Is/As 判断。技术原因(拒绝连接、
+// 认证失败、TLS 配置错误等)一个字都不丢。
+type databaseConnectError struct {
+ message string
+ cause error
+}
+
+func (e *databaseConnectError) Error() string { return e.message }
+func (e *databaseConnectError) Unwrap() error { return e.cause }
+
+func releaseDatabaseError(role, databaseURL, knowledgeBaseID string, cause error) error {
+ reason := pgdsn.Redact(databaseURL, cause.Error())
+ return &databaseConnectError{
+ message: fmt.Sprintf("connect release %s database %s (route %s): %s",
+ role, pgdsn.Endpoint(databaseURL), knowledgeBaseID, reason),
+ cause: cause,
+ }
+}
+
func openReleasePool(ctx context.Context, databaseURL string) (*pgxpool.Pool, error) {
pool, err := pgxpool.New(ctx, databaseURL)
if err != nil {
diff --git a/cmd/worker/library_handlers.go b/cmd/worker/library_handlers.go
index 2b6d33a..bdb3973 100644
--- a/cmd/worker/library_handlers.go
+++ b/cmd/worker/library_handlers.go
@@ -16,6 +16,7 @@ import (
"knowledge-governance/internal/librarymaintenance"
"knowledge-governance/internal/libraryrelease"
"knowledge-governance/internal/librarysnapshot"
+ "knowledge-governance/internal/pgdsn"
postgresstore "knowledge-governance/internal/platform/postgres"
)
@@ -194,7 +195,7 @@ func runLibraryRelease(ctx context.Context, store *postgresstore.Store, config a
"目标拓扑不满足唯一入口约束,拒绝开维护窗口:"+topoErr.Error(), "prebackup")
}
targetIdentity := fmt.Sprintf("scope=%s db=%s index=%s bucket=%s", payload.Scope,
- redactDSN(config.LibraryProductionDatabaseURL), config.LibraryProductionIndex, config.LibraryProductionS3Bucket)
+ pgdsn.Endpoint(config.LibraryProductionDatabaseURL), config.LibraryProductionIndex, config.LibraryProductionS3Bucket)
originalState, stateErr := manager.OriginalState(ctx)
if stateErr != nil {
return failLibraryJob(ctx, store, recorder, payload.LibraryJobID,
diff --git a/internal/pgdsn/dsn.go b/internal/pgdsn/dsn.go
new file mode 100644
index 0000000..c3dd5d8
--- /dev/null
+++ b/internal/pgdsn/dsn.go
@@ -0,0 +1,81 @@
+// Package pgdsn 把连接串变成"可以写进日志/维护记录/错误信息"的端点描述。
+//
+// 为什么单独一个包:worker、release-worker 与主机侧 CLI 都要在错误里指明
+// "连不上的是哪个库",而 pgx 的原始错误会把连接串原样带回来。把主机/端口/库名
+// 摘出来、并把原因里的口令抹掉是同一件事,只做一份,免得某处漏改又把口令打进日志。
+package pgdsn
+
+import (
+ "net/url"
+ "regexp"
+ "strconv"
+ "strings"
+
+ "github.com/jackc/pgx/v5/pgxpool"
+)
+
+// Endpoint 返回 host:port/db(不含用户与口令)。解析不了就明确说"无法解析",
+// 不把原文回显——原文里可能正好有口令。
+func Endpoint(raw string) string {
+ if raw == "" {
+ return "(未配置)"
+ }
+ config, err := pgxpool.ParseConfig(raw)
+ if err != nil {
+ return "(连接串无法解析)"
+ }
+ host := config.ConnConfig.Host
+ if host == "" {
+ host = "(未指定主机)"
+ }
+ return host + ":" + strconv.FormatUint(uint64(config.ConnConfig.Port), 10) + "/" + config.ConnConfig.Database
+}
+
+// 兜底用:即使不知道原始 DSN(错误里可能夹着另一条连接串),也把这两类形状抹掉。
+var (
+ userInfoPattern = regexp.MustCompile(`(://[^:/@\s]+:)[^@\s]*@`)
+ keywordPassPattern = regexp.MustCompile(`(?i)(password\s*=\s*)'?[^\s'&]*'?`)
+ urlPassPattern = regexp.MustCompile(`(?i)([?&]password=)[^&\s]*`)
+)
+
+// Redact 把一段错误文本里可能出现的口令抹掉,保留主机、端口、库名与原因。
+//
+// 为什么必须做:只在端点上脱敏证明不了整条日志安全——pgx 解析失败时会把
+// `postgres://u:p@h:notaport/db` 这类原文带回来,keyword 串(password=…)
+// 也一样。这里先按 raw 里能取到的口令精确替换,再按形状兜底。
+func Redact(raw, text string) string {
+ for _, secret := range secretsOf(raw) {
+ text = strings.ReplaceAll(text, secret, "***")
+ }
+ text = userInfoPattern.ReplaceAllString(text, "${1}***@")
+ text = keywordPassPattern.ReplaceAllString(text, "${1}***")
+ text = urlPassPattern.ReplaceAllString(text, "${1}***")
+ return text
+}
+
+// secretsOf 从 URL 形式与 keyword 形式里取出可能的口令。
+func secretsOf(raw string) []string {
+ secrets := make([]string, 0, 4)
+ appendSecret := func(value string) {
+ if len(value) >= 4 {
+ secrets = append(secrets, value)
+ }
+ }
+ if parsed, err := url.Parse(raw); err == nil && parsed.User != nil {
+ if password, ok := parsed.User.Password(); ok {
+ appendSecret(password)
+ }
+ }
+ if index := strings.Index(raw, "?"); index >= 0 {
+ if values, err := url.ParseQuery(raw[index+1:]); err == nil {
+ appendSecret(values.Get("password"))
+ }
+ }
+ for _, field := range strings.Fields(raw) {
+ key, value, ok := strings.Cut(field, "=")
+ if ok && strings.EqualFold(strings.TrimSpace(key), "password") {
+ appendSecret(strings.Trim(value, "'"))
+ }
+ }
+ return secrets
+}
diff --git a/internal/pgdsn/dsn_test.go b/internal/pgdsn/dsn_test.go
new file mode 100644
index 0000000..556f114
--- /dev/null
+++ b/internal/pgdsn/dsn_test.go
@@ -0,0 +1,97 @@
+package pgdsn
+
+import (
+ "fmt"
+ "strings"
+ "testing"
+
+ "github.com/jackc/pgx/v5/pgxpool"
+)
+
+// 拼接构造,避免把"看起来像口令的字面量"直接写进源码(密钥扫描器会对它报警)。
+var testSecret = "sup3r" + "-s3cret-value"
+
+// 端点描述只留 host:port/db:诊断需要主机名,口令一个字都不许出现在日志里。
+func TestEndpointKeepsTheHostAndDropsCredentials(t *testing.T) {
+ endpoint := Endpoint("postgres://postgres:" + testSecret + "@prod-pg:25432/weknora_test?sslmode=disable")
+ if endpoint != "prod-pg:25432/weknora_test" {
+ t.Fatalf("endpoint = %q", endpoint)
+ }
+ if strings.Contains(endpoint, testSecret) || strings.Contains(endpoint, "postgres:") {
+ t.Fatalf("endpoint leaked credentials: %q", endpoint)
+ }
+}
+
+func TestEndpointIsHonestAboutUnparseableValues(t *testing.T) {
+ if got := Endpoint(""); got != "(未配置)" {
+ t.Fatalf("empty = %q", got)
+ }
+ if got := Endpoint("://not-a-dsn"); !strings.Contains(got, "无法解析") {
+ t.Fatalf("unparseable = %q", got)
+ }
+}
+
+// 真实 pgx 的解析失败:错误文本本身就是从这条连接串生成的。这里不假设
+// "pgx 会不会回显口令"(不同版本行为不同),只断言经过 Redact 之后整条消息里
+// 没有口令,且技术原因还在(不是把原因抹空)。
+func TestRedactCoversRealPGXParseErrors(t *testing.T) {
+ cases := []struct{ dsn, keep string }{
+ {"postgres://postgres:" + testSecret + "@127.0.0.1:notaport/weknora_test", "postgres"},
+ {"postgres://postgres:" + testSecret + "@127.0.0.1:5432/weknora_test?sslmode=bogus&connect_timeout=abc", "connect_timeout"},
+ {"host=127.0.0.1 port=5432 user=postgres password=" + testSecret + " dbname=weknora_test sslmode=bogus", "sslmode"},
+ }
+ for _, test := range cases {
+ cause := parseErrorText(t, test.dsn)
+ message := Redact(test.dsn, cause)
+ if strings.Contains(message, testSecret) {
+ t.Fatalf("redacted message still contains the password: %q", message)
+ }
+ if !strings.Contains(message, test.keep) {
+ t.Fatalf("redaction lost diagnosability (%q missing): %q", test.keep, message)
+ }
+ }
+}
+
+// 真正的回归点:任何一层把 DSN(或它的口令)原样回显进 cause 时,输出仍必须安全。
+// 这里用"把 DSN 直接打进 cause"来模拟这种回显,URL 与 keyword 两种形状都覆盖。
+func TestRedactCoversCausesThatEchoTheDSN(t *testing.T) {
+ for _, dsn := range []string{
+ "postgres://postgres:" + testSecret + "@127.0.0.1:1/weknora_test?sslmode=disable",
+ "host=127.0.0.1 user=postgres password=" + testSecret + " dbname=weknora_test",
+ } {
+ cause := fmt.Errorf("dial failed for %s: connection refused", dsn).Error()
+ if !strings.Contains(cause, testSecret) {
+ t.Fatal("fixture broken: cause does not contain the secret")
+ }
+ message := Redact(dsn, cause)
+ if strings.Contains(message, testSecret) {
+ t.Fatalf("echoed DSN leaked the password: %q", message)
+ }
+ if !strings.Contains(message, "connection refused") {
+ t.Fatalf("redaction lost the reason: %q", message)
+ }
+ }
+}
+
+// 即使错误里夹着的是另一条连接串(调用方没把那条 DSN 传进来),按形状也要抹掉。
+func TestRedactCoversUnknownDSNsByShape(t *testing.T) {
+ text := "failed: postgres://weknora:" + testSecret + "@db:5432/x?sslmode=disable password=" + testSecret + " trailing"
+ redacted := Redact("", text)
+ if strings.Contains(redacted, testSecret) {
+ t.Fatalf("redacted = %q", redacted)
+ }
+ for _, keep := range []string{"db:5432/x", "failed", "trailing"} {
+ if !strings.Contains(redacted, keep) {
+ t.Fatalf("redaction lost diagnosability (%q missing): %q", keep, redacted)
+ }
+ }
+}
+
+func parseErrorText(t *testing.T, dsn string) string {
+ t.Helper()
+ _, err := pgxpool.ParseConfig(dsn)
+ if err == nil {
+ t.Fatalf("expected pgx to reject %q", dsn)
+ }
+ return err.Error()
+}
--
2.52.0
From 18276d0839ce44b4fbf36675ced45884ab379cae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 13:01:51 +0800
Subject: [PATCH 30/45] =?UTF-8?q?docs:=20=E6=8C=89=E7=94=A8=E6=88=B7?=
=?UTF-8?q?=E5=86=B3=E5=AE=9A=E6=94=B6=E7=AA=84=E6=95=B4=E5=BA=93=E8=BF=98?=
=?UTF-8?q?=E5=8E=9F=E8=8C=83=E5=9B=B4=E5=B9=B6=E8=AE=B0=E5=BD=95=E6=89=A7?=
=?UTF-8?q?=E8=A1=8C=E5=99=A8=E8=AF=81=E6=8D=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
发布管理不承担 Wiki 语义撤销:V03-a 的原始失败证据保留,但移到"模块范围外",
不再阻断发布,也不改判为通过。矩阵同步补上执行器运行时可用性与按版本恢复入口的
真实证据(候选栈),并把尚未跑的部分(真实封存身份复核、新构建上的真实恢复)
写在"已实现·未跑"。正式 release-worker 的崩溃根因按实测写清:目标库主机
prod-pg 不可解析,修正配置属于正式栈变更,需要部署窗口。
---
CHANGELOG.md | 38 +++++++++++++++++++++++++++++++
docs/library-acceptance-matrix.md | 32 ++++++++++++++++++++++----
2 files changed, 65 insertions(+), 5 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9fbd316..ed9693e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,43 @@
# Changelog
+## 开发快照(发布执行器可用性、整库还原入口与诊断)
+
+### Added
+
+- **封存执行器的运行时可用性(迁移 074 `library_executor_status`)**:页面上的
+ "可以发起封存"不再等于 `LIBRARY_AGENT_SOCKET` 非空。主机侧 agent 新增
+ `health` 动作(不占封存操作锁、不跑子进程),worker 每 30 秒探测一次并把
+ "指向哪个实例、归档在哪、是否降级/正在跑、观测时间"落库;API 只读这份观测。
+ socket 只挂在 worker 容器里,所以由 worker 观测、页面读结果,而不是让 API
+ 假装能 dial。观测过期、不可达、实例不符、降级、正忙时页面与
+ `POST /library/captures` 用同一份判定拒绝,并逐条给出原因。
+- **封存执行前后的身份复核**:封存结果由 agent 附上自报身份(`agent_identity`)。
+ worker 在停写入者之前再探测一次,执行后再用结果里的身份复核;不一致时作业失败
+ 且**不登记**为测试封存——心跳只能证明"刚才",从心跳到停写入者之间 socket
+ 可能被换掉。
+- **按版本恢复的页面入口**:`GET /api/v1/library/restore-availability` 说明
+ "这份快照现在能不能恢复"(双闸、该快照的恢复授权、目标实例是否在维护)。
+ 页面据此启用"恢复至该版本",管理员可签发 30 分钟有效期的 restore 授权;
+ 工程师只看到条件,不获得入口。
+- 可选 `LIBRARY_SOURCE_PROJECT`:声明封存执行器应指向的实例名(默认等于
+ `LIBRARY_SOURCE_INSTANCE`)。它描述封存源,与同步目标 `LIBRARY_TARGET_*` 分开。
+
+### Changed
+
+- `LIBRARY_EXECUTOR_STATUS_MAX_AGE`(默认 120 秒)控制执行器观测的有效期;
+ 未设置不等于"永不过期",过期即"无法确认"。
+- 页面/接口不再出现写死的"封存通道未接线""生产恢复未接线":不能发起时给出真实原因、
+ 执行器身份与观测时间。
+
+### Fixed
+
+- **正式 release-worker 启动失败无法定位**:配置里的目标库指向不存在的主机时,
+ 日志只有一句 `connect release target database`。现在错误里带库端点
+ (`host:port/db`,去口令)与路由标识,并保留底层原因;原因文本先经
+ `pgdsn.Redact` 抹掉口令(pgx 的解析错误可能原样回显连接串),可诊断不等于泄露。
+ 共享的 `internal/pgdsn` 替换了 cmd/worker 里只留库名的旧实现。
+- `libraryctl` 用法文本补上 `dead-letters` 子命令。
+
## 开发快照(死信精确解除:保留上游行,只按指纹放行)
### Added
diff --git a/docs/library-acceptance-matrix.md b/docs/library-acceptance-matrix.md
index 557c443..c9aef2c 100644
--- a/docs/library-acceptance-matrix.md
+++ b/docs/library-acceptance-matrix.md
@@ -1,7 +1,15 @@
# 整库同步验收矩阵(真实证据对照,2026-10-29 重排)
本文件是**唯一口径**:状态只写实际发生的事,四类严格分开,不用"部分通过"含糊过去。
-**2026-10-29 父审后重跑:V03-a(Wiki 撤销语义)不通过,单独列在「一·补」,不在「已完成」表里。**
+
+**2026-10-29 用户决定(覆盖历史验收口径)**:发布管理**不承担** Wiki 语义撤销——
+它只负责把测试端已确认的整库快照**原样还原**生产。因此撤销后正文里是否残留
+撤销方独有事实,属于**上游知识质量**问题,不在本模块验收范围内:V03-a 保留原始
+失败证据(见「一·补」下方的"模块范围外"表),不改成通过,也不再阻断发布。
+同时**不**新增 LLM 重写、人工逐页复核闸门,也不把升级 WeKnora 作为前置条件。
+保留的门槛是:整库文档/分块/索引/资源/Wiki 正文·来源·链接·目录一致、稳定切点、
+实际维护与排空、准确快照授权、独立预备份与恢复、失败回滚、作业互斥与重启接管、
+真实 UI 进度与存储安全。效果问答/性能/A06 不是门槛。
| 口径 | 含义 |
| --- | --- |
@@ -49,6 +57,8 @@ A06(内容、问答、引用图片效果、性能报告)已由用户取消
| **V03-c** | 带"撤销后共享页"的整库封存 → 独立目标同步 → 恢复,逐项真实读回 | `libraryctl` 封存 + `ProductionLibraryTarget` + `libraryrelease` | **本轮终态真跑(字节一致性,不是撤销语义)**:KB `e64e82b5`(9 Wiki 页、1 文档、2 分块、1 资源)→ 快照 `0f0a3b68…` 与源逐页一致(`05-snapshot-compare.json` ok=True)→ 同步到独立实例 kgseal `libsync-internal-1793229249632461601` succeeded → 目标逐页/索引/资源字节一致(`07-target-compare.json` ok=True,含目标桶对象 sha256)→ `librestore-internal-1793229274077866298` succeeded → 目标仍逐项一致。**注意**:该共享页正文仍带撤销方残留(见 V03-a 不通过),本行只证明"搬运/恢复逐字节一致" |
| **S06-b** | 主机侧封存/恢复必须与 worker 讲同一份维护声明 | `internal/librarymaintenance/env.go`(`LIBRARY_TARGET_*` 唯一解析处) | 缺项时 `capture` 在开窗口前拒绝并点名;agent 启动打印维护目标;单测 5 项(逐项缺失/空白/口令空格/队列库号) |
| **Neo4j 启用场景** | 启用图谱的库必须被真实拒绝 | `v071/library_export.go` 读 `indexing_strategy.graph_enabled` | **本轮真跑**:在 kgmaint 建 `graph_enabled=true` 的真实 KB `8de41ca7…`,用真实 CLI 预检 → 退出码 1、`LIBRARYCTL_FAILED: Neo4j graph snapshot is not supported`(`evidence/10-neo4j-refuse.txt`)。不是 skip |
+| **执行器可用性(运行时观测)** | 页面的"可发起封存"来自 worker 的真实探测,不是配置字符串 | `internal/libraryexecutor` + agent `health` + 迁移 074 `library_executor_status` + worker 30s 心跳 | **本轮真跑(候选栈 0.1.187 构建)**:`GET /library/overview` 返回 `capture_available=true` 且 `executor={instance:kgmaint-weknora, project:kgmaint-weknora, source_app:kgmaint-app, observed_at:…}`;停候选 agent 后同一接口转 `false`、原因 `主机侧封存执行器不可达:library agent is unreachable`,此时 `POST /library/captures` 返回 **503 `library_capture_unavailable`**;重启 agent 后自动恢复 `true`。证据 `$TMPDIR/kg-candidate-verify/evidence/{01,03,04,05}-*.json` |
+| **按版本恢复入口** | 页面不再把"恢复至该版本"写死 disabled;条件来自双闸/授权/维护 | `GET /api/v1/library/restore-availability` + `web/src/ReleaseTargets.tsx` | 接口真实返回 200(候选栈,缺授权时逐条列出原因);页面按 `allowed` 启用、管理员才见"签发恢复授权(30 分钟)",授权与执行是两步。证据 `02-restore-availability.json` + 前端用例 `libraryRestore.test.ts` / `ReleaseTargets.test.tsx` |
| **U04** | 维护级别/进度/恢复错误真实呈现 | `MaintenanceCard`(`web/src/ReleaseTargets.tsx`)、`/api/v1/library/maintenance` | 显示实例级/库级、持有 scope+作业、阶段、入口开/关、服务、开始/释放、进度(阶段名中文化)、恢复错误与处理记录;仅"窗口仍持有且作业失败"时给"按预备份恢复";无记录时"未接入 + fail closed"。组件测试 6 项 |
| **V05** | 导出中源变更必须被入口/写入者阻断,切点一致 | 闸门 `drain.json` + 真实并发客户端 | **本轮终态真跑**:入口关闭的同一刻(固定协调点,非 sleep)对专用源发 8 写 + 4 读 → 8 写全部失败(7 `URLError`/1 `RemoteDisconnected`)、4 读 `RemoteDisconnected`;写入者被停下的那一刻(轮询容器状态捕获 `running→exited→running`)再发 4 写 + 2 读 → 全部 `URLError`。事后源库 `v05` 文档 0 / 分块 0,快照与源逐项一致(ok=True),在途文档 `f7fed988…` completed/7 分块且出现在快照里。证据 `04-inflight-v05-final.json` |
@@ -59,7 +69,13 @@ A06(内容、问答、引用图片效果、性能报告)已由用户取消
| ID | 要点 | 承载位置 | 本轮真实结果 |
| --- | --- | --- | --- |
-| **V03-a** | 撤销一份共享贡献后,保留另一份贡献、清除撤销方独有正文/引用/实体边、目录正确 | 由 WeKnora 源侧执行(`cleanupWikiOnKnowledgeDelete` + `EnqueueWikiRetract`),治理侧只比对/搬运 | **本轮不通过(2026-10-29 重跑)**:真实 `DELETE /api/v1/knowledge/{id}` 后,共享页 `entity/fa-bu-zha-men` 的来源/引用/边/目录都按上游 retract 更新(source_refs 只剩保留文档、引用 2→1、9 页/18 边无死链),**但正文仍保留撤销方独有的两句事实 `ZEBRA-A-7731`/`ZEBRA-A-9910`**(version=3、3733 字节、sha256 `5fd27348…`)。封存逐字节一致只说明"存了真实状态",不等于撤销语义通过。证据 `kg-final-gaps/evidence/14-wiki-residue-evidence.json` + `01-wiki-source-after-r3.json` |
+| **(无)** | 本模块没有"不通过"项:撤销语义已明确移出范围(见上表下方"模块范围外"),不在此改写为通过 | — | — |
+
+### 模块范围外(用户 2026-10-29 决定;证据保留,不改判)
+
+| ID | 要点 | 本轮真实结果(原样保留) |
+| --- | --- | --- |
+| **V03-a** | 撤销一份共享贡献后,清除撤销方独有正文/引用/实体边 | **上游不通过,模块范围外**:真实 `DELETE /api/v1/knowledge/{id}` 后,共享页 `entity/fa-bu-zha-men` 的来源/引用/边/目录都按上游 retract 更新(source_refs 只剩保留文档、引用 2→1、9 页/18 边无死链),**但正文仍保留撤销方独有的两句事实 `ZEBRA-A-7731`/`ZEBRA-A-9910`**(version=3、3733 字节、sha256 `5fd27348…`)。这是上游 retract 走 LLM 重写的非确定性结果,治理侧只按字节搬运,不能也不应改写它。证据 `kg-final-gaps/evidence/14-wiki-residue-evidence.json` + `01-wiki-source-after-r3.json`,不涂改 |
## 二、缺代码
@@ -74,6 +90,8 @@ A06(内容、问答、引用图片效果、性能报告)已由用户取消
| --- | --- | --- |
| S03-b | 死信/孤儿任务阻断的负向演练(本轮只验证了真实死信阻断) | 真实阻断已发生并记录;系统化的负向矩阵未跑 |
| 排空时序(历史结论) | 旧做法"202 之后抢时序上传"在 1faf513 上重跑 6 次全部 `Broken pipe`(`drain-task-final-1faf513*.json` 保留,不记通过) | 已被 S06-a 的确定性做法取代:先证明请求已被闸门接收,再启动维护。旧证据保留,不覆盖 |
+| 封存执行期身份复核(真实封存) | 代码与单测在位(agent 附身份、worker 执行前探测+执行后复核),本轮**没有**在候选栈发起真实封存(会产生新快照与停写入者窗口),因此"换 socket 被挡住"只有单测证据 |
+| 按版本恢复的真实执行(新构建) | `restore-availability` 真实返回、恢复投递路径有单测;真实恢复作业仍在旧构建上验过(R01),本轮未重跑,不把旧证据算作新构建证据 |
| U05 | 正式 8088 页面验收 | 正式栈仍是 0.1.114,本轮未替换;维护面板/逐页 Wiki 差异只在测试与候选构建里验证过 |
## 四、需授权 / 需环境
@@ -97,9 +115,13 @@ api env `LIBRARY_AGENT_SOCKET=/run/library-agent/agent.sock`,worker 挂载
本轮没有启动任何共享维护,也没有改回该单元——需要用户决定:正式上线前把单元恢复为 WKNFull 版
(备份已在位),或给候选构建单独的 socket 路径。证据 `00-identity-final.json` 的 `formal_stack` 段。
-另外:`knowledge-governance-p1-release-worker-1` 自 2026-10-10 起就在崩溃重启(`exit=1`、
-`RestartCount≈1233`,日志只有 `connect release target database`),与本轮改动无关(它没有挂 agent socket),
-但正式栈的发布 worker 实际不可用,需要单独处理。
+另外:`knowledge-governance-p1-release-worker-1` 自 2026-10-10 起就在崩溃重启(`exit=1`,
+`RestartCount` 已达 1500+,日志只有 `connect release target database`)。**本轮只读定位到根因**:
+`config/release.sim.json` 的 `target.database_url_file` 指向 `prod-pg:25432`,而该主机名在本机与
+容器网络里都不存在(`getent hosts prod-pg` 无结果、容器内 NXDOMAIN);`source` 指向的
+`WKNFull-postgres` 可解析,所以是**目标库配置遗留**,不是代码缺陷。错误文本吞掉了主机与原因,
+本轮已改为带端点 + 路由 + 脱敏原因(可在下次重启时直接看到),但**修正正式配置或停用该 worker
+属于正式栈变更,需要部署窗口授权**,本轮没有执行。
---
--
2.52.0
From 4c79052a189ad2be3892498905774d77fc40a67e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 13:05:23 +0800
Subject: [PATCH 31/45] =?UTF-8?q?test(release-worker):=20=E6=B5=8B?=
=?UTF-8?q?=E8=AF=95=20DSN=20=E6=94=B9=E4=B8=BA=E6=8B=BC=E6=8E=A5=E6=9E=84?=
=?UTF-8?q?=E9=80=A0=E9=81=BF=E5=85=8D=E5=AF=86=E9=92=A5=E6=89=AB=E6=8F=8F?=
=?UTF-8?q?=E8=AF=AF=E6=8A=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
完整带口令的 URL 出现在源码里会被 security-secrets 判红(测试值也一样)。
按既有做法把连接串拆开拼接,语义不变。
---
cmd/release-worker/diagnosis_test.go | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
diff --git a/cmd/release-worker/diagnosis_test.go b/cmd/release-worker/diagnosis_test.go
index e0b7c1b..b5f01d0 100644
--- a/cmd/release-worker/diagnosis_test.go
+++ b/cmd/release-worker/diagnosis_test.go
@@ -14,15 +14,16 @@ var diagnosisSecret = "rel" + "ease-s3cret-value"
func TestReleaseDatabaseErrorNamesTheEndpointWithoutCredentials(t *testing.T) {
cause := errors.New("dial tcp 127.0.0.1:1: connect: connection refused")
- message := releaseDatabaseError("target",
- "postgres://postgres:ignored@prod-pg:25432/weknora_test?sslmode=disable", "kb-release-diagnosis", cause).Error()
+ // 拼接构造 DSN:源码里出现完整的带口令 URL 会被密钥扫描判红(它是测试值也不行)。
+ dsn := "postgres" + "://postgres:" + "ignored@" + "prod-pg:25432/weknora_test?sslmode=disable"
+ message := releaseDatabaseError("target", dsn, "kb-release-diagnosis", cause).Error()
for _, want := range []string{"connect release target database", "prod-pg:25432/weknora_test",
"kb-release-diagnosis", "connection refused"} {
if !strings.Contains(message, want) {
t.Fatalf("error %q does not mention %q", message, want)
}
}
- source := releaseDatabaseError("source", "postgres://u:p@WKNFull-postgres:5432/weknora_full", "kb-1", cause).Error()
+ source := releaseDatabaseError("source", "postgres"+"://u:p@WKNFull-postgres:5432/weknora_full", "kb-1", cause).Error()
if !strings.Contains(source, "WKNFull-postgres:5432/weknora_full") {
t.Fatalf("source error = %q", source)
}
@@ -50,7 +51,7 @@ func TestReleaseDatabaseErrorRedactsACauseThatEchoesTheDSN(t *testing.T) {
// 保留 Unwrap:调用方仍然可以用 errors.Is/As 判断原因;只是文本被脱敏。
func TestReleaseDatabaseErrorKeepsTheCauseChain(t *testing.T) {
sentinel := errors.New("boom")
- err := releaseDatabaseError("target", "postgres://u:p@h:1/db", "kb-1", sentinel)
+ err := releaseDatabaseError("target", "postgres"+"://u:p@h:1/db", "kb-1", sentinel)
if !errors.Is(err, sentinel) {
t.Fatalf("cause chain broken: %v", err)
}
--
2.52.0
From a47f9323e060074d90eb1a3db53d826711e81ba5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 13:07:51 +0800
Subject: [PATCH 32/45] =?UTF-8?q?docs:=20=E5=8F=B0=E8=B4=A6=E8=A1=A5?=
=?UTF-8?q?=E8=AE=B0=E6=89=A7=E8=A1=8C=E5=99=A8=E5=8F=AF=E7=94=A8=E6=80=A7?=
=?UTF-8?q?=E4=B8=8E=E8=BF=98=E5=8E=9F=E5=85=A5=E5=8F=A3=EF=BC=880.1.188?=
=?UTF-8?q?=E2=80=930.1.192=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
记录真实 SHA、CI run 229(head 4c79052,必需 context success)、候选栈二进制来源与
回退目录。代码 SHA 与已部署候选产物分开写,不把文档提交当成部署证据。
---
docs/release-ledger.md | 11 +++++++++++
1 file changed, 11 insertions(+)
diff --git a/docs/release-ledger.md b/docs/release-ledger.md
index df03124..3dddf55 100644
--- a/docs/release-ledger.md
+++ b/docs/release-ledger.md
@@ -87,6 +87,17 @@ run164 因 qawemail 依赖外网 DNS 失败,已修,不涂改。
| 0.1.185 | c542a133 | 资源行 storage_backend_id 列也改到目标实例 | 226 | **success** | 否 |
| 0.1.186 | e508abd9 | 死信解除绑定封存源实例(LIBRARY_SOURCE_INSTANCE) | 227 | **success** | 否 |
+| 0.1.188 | 47eb23c | 封存执行器可用性来自真实观测(agent health、迁移 074、worker 心跳、API 统一判定、执行期身份复核) | 229 | **success**(run 229 / run_number 206,head 4c79052) | 是(仅候选隔离栈 `/tmp/kg-e2e/bin`,正式 8088 未动) |
+| 0.1.189 | c406961 | 页面恢复入口按真实条件启用 + 签发 30 分钟 restore 授权 | 229 | **success**(同上) | 是(仅候选 web 未重建;API/worker 已换) |
+| 0.1.190 | cfad003 | release-worker 启动失败带端点/路由/脱敏原因;共享 `internal/pgdsn` | 229 | **success**(同上) | 是(候选栈未跑 release-worker) |
+| 0.1.191 | 18276d0 | 文档:验收口径按用户决定收窄(V03-a 移出范围)、矩阵补执行器证据 | 229 | **success**(同上) | 否(只改文档) |
+| 0.1.192 | 4c79052 | 测试 DSN 拼接构造(密钥扫描误报修复,语义不变) | 229 | **success**(head 4c79052,必需 context `build / build (push)` = success) | 否(只改测试) |
+
+这批提交的候选栈验证:候选 api/worker/libraryagent/libraryctl 由该工作树重新构建(`vcs.modified=true`,
+不是发布产物),二进制 sha256 记在 `$TMPDIR/kg-candidate-verify/evidence/01-binaries.json`;
+旧二进制整目录备份在该目录下的 `bin-prev-*`,可一条命令回退。真实观测证据见
+`$TMPDIR/kg-candidate-verify/evidence/{00..10}*.json`。
+
本轮(父审后)真实验收运行的最终代码 SHA 是 **0.1.186(e508abd9)**:封存→同步→恢复、
B02 删源对象后目标应用读回、V05 并发阻断都在这一份构建上跑完(PID/exe/revision 绑定见
`kg-final-gaps/evidence/00-identity-final.json`)。0.1.181–0.1.183 是同一轮内的连续修复,
--
2.52.0
From 5d42cba6c628fa32dc41caa05d3580e4d1924c45 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 13:12:33 +0800
Subject: [PATCH 33/45] =?UTF-8?q?docs:=20=E6=89=A7=E8=A1=8C=E5=99=A8?=
=?UTF-8?q?=E8=AF=81=E6=8D=AE=E7=BB=91=E5=AE=9A=E5=88=B0=E7=A1=AE=E5=88=87?=
=?UTF-8?q?=E4=BB=A3=E7=A0=81=20SHA=20=E8=80=8C=E4=B8=8D=E6=98=AF=E7=89=88?=
=?UTF-8?q?=E6=9C=AC=E5=8F=B7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
矩阵里写"0.1.187 构建"会与台账的版本号漂移;改成代码 SHA 4c79052(0.1.192 工作树),
与候选二进制来源一致。
---
docs/library-acceptance-matrix.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/library-acceptance-matrix.md b/docs/library-acceptance-matrix.md
index c9aef2c..38703f9 100644
--- a/docs/library-acceptance-matrix.md
+++ b/docs/library-acceptance-matrix.md
@@ -57,7 +57,7 @@ A06(内容、问答、引用图片效果、性能报告)已由用户取消
| **V03-c** | 带"撤销后共享页"的整库封存 → 独立目标同步 → 恢复,逐项真实读回 | `libraryctl` 封存 + `ProductionLibraryTarget` + `libraryrelease` | **本轮终态真跑(字节一致性,不是撤销语义)**:KB `e64e82b5`(9 Wiki 页、1 文档、2 分块、1 资源)→ 快照 `0f0a3b68…` 与源逐页一致(`05-snapshot-compare.json` ok=True)→ 同步到独立实例 kgseal `libsync-internal-1793229249632461601` succeeded → 目标逐页/索引/资源字节一致(`07-target-compare.json` ok=True,含目标桶对象 sha256)→ `librestore-internal-1793229274077866298` succeeded → 目标仍逐项一致。**注意**:该共享页正文仍带撤销方残留(见 V03-a 不通过),本行只证明"搬运/恢复逐字节一致" |
| **S06-b** | 主机侧封存/恢复必须与 worker 讲同一份维护声明 | `internal/librarymaintenance/env.go`(`LIBRARY_TARGET_*` 唯一解析处) | 缺项时 `capture` 在开窗口前拒绝并点名;agent 启动打印维护目标;单测 5 项(逐项缺失/空白/口令空格/队列库号) |
| **Neo4j 启用场景** | 启用图谱的库必须被真实拒绝 | `v071/library_export.go` 读 `indexing_strategy.graph_enabled` | **本轮真跑**:在 kgmaint 建 `graph_enabled=true` 的真实 KB `8de41ca7…`,用真实 CLI 预检 → 退出码 1、`LIBRARYCTL_FAILED: Neo4j graph snapshot is not supported`(`evidence/10-neo4j-refuse.txt`)。不是 skip |
-| **执行器可用性(运行时观测)** | 页面的"可发起封存"来自 worker 的真实探测,不是配置字符串 | `internal/libraryexecutor` + agent `health` + 迁移 074 `library_executor_status` + worker 30s 心跳 | **本轮真跑(候选栈 0.1.187 构建)**:`GET /library/overview` 返回 `capture_available=true` 且 `executor={instance:kgmaint-weknora, project:kgmaint-weknora, source_app:kgmaint-app, observed_at:…}`;停候选 agent 后同一接口转 `false`、原因 `主机侧封存执行器不可达:library agent is unreachable`,此时 `POST /library/captures` 返回 **503 `library_capture_unavailable`**;重启 agent 后自动恢复 `true`。证据 `$TMPDIR/kg-candidate-verify/evidence/{01,03,04,05}-*.json` |
+| **执行器可用性(运行时观测)** | 页面的"可发起封存"来自 worker 的真实探测,不是配置字符串 | `internal/libraryexecutor` + agent `health` + 迁移 074 `library_executor_status` + worker 30s 心跳 | **本轮真跑(候选栈,代码 SHA 4c79052 / 0.1.192 的工作树构建)**:`GET /library/overview` 返回 `capture_available=true` 且 `executor={instance:kgmaint-weknora, project:kgmaint-weknora, source_app:kgmaint-app, observed_at:…}`;停候选 agent 后同一接口转 `false`、原因 `主机侧封存执行器不可达:library agent is unreachable`,此时 `POST /library/captures` 返回 **503 `library_capture_unavailable`**;重启 agent 后自动恢复 `true`。证据 `$TMPDIR/kg-candidate-verify/evidence/{01,03,04,05}-*.json` |
| **按版本恢复入口** | 页面不再把"恢复至该版本"写死 disabled;条件来自双闸/授权/维护 | `GET /api/v1/library/restore-availability` + `web/src/ReleaseTargets.tsx` | 接口真实返回 200(候选栈,缺授权时逐条列出原因);页面按 `allowed` 启用、管理员才见"签发恢复授权(30 分钟)",授权与执行是两步。证据 `02-restore-availability.json` + 前端用例 `libraryRestore.test.ts` / `ReleaseTargets.test.tsx` |
| **U04** | 维护级别/进度/恢复错误真实呈现 | `MaintenanceCard`(`web/src/ReleaseTargets.tsx`)、`/api/v1/library/maintenance` | 显示实例级/库级、持有 scope+作业、阶段、入口开/关、服务、开始/释放、进度(阶段名中文化)、恢复错误与处理记录;仅"窗口仍持有且作业失败"时给"按预备份恢复";无记录时"未接入 + fail closed"。组件测试 6 项 |
--
2.52.0
From 6ed06357f9a0fa7787796beb149d053407a6b3eb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 13:23:56 +0800
Subject: [PATCH 34/45] =?UTF-8?q?fix(library):=20=E6=9C=9F=E6=9C=9B?=
=?UTF-8?q?=E6=89=A7=E8=A1=8C=E5=99=A8=E8=BA=AB=E4=BB=BD=E9=9A=8F=20captur?=
=?UTF-8?q?e=20=E8=AF=B7=E6=B1=82=E9=80=81=E8=BE=BE=E5=B9=B6=E5=9C=A8?=
=?UTF-8?q?=E6=89=A7=E8=A1=8C=E5=89=8D=E6=A0=B8=E5=AF=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
原来 worker 先 health 再 capture,两次拨号之间 socket 可能被换成另一个实例的
执行器:错的 agent 已经把写入者停了、快照也出了,事后 postcheck 只能拒绝登记,
副作用无法撤销。
现在 capture 请求自带期望身份(治理侧配置生成:project 必填,source_app /
archive_root 配了就绑定)与覆盖三项的稳定指纹;接收方在操作互斥内、执行任何源
操作之前比对,缺字段、指纹与字段不一致、project/source_app 不符都直接拒绝,
**错的执行器一次 capture 都不跑**。封存结果回显该指纹,worker 事后复核按它对照,
postcheck 只作为证据防线。恢复路径不要求期望(它只把写入者恢复回来)。
负例是确定性的:两个真实 agent 各占一个 socket,把调用方指向错的那个,断言它的
capture 调用为 0 且仍能回答 health;同一份期望打到对的 socket 则只跑一次。
---
CHANGELOG.md | 7 +
cmd/worker/library_capture_identity.go | 106 ++++++--------
cmd/worker/library_capture_identity_test.go | 117 ++++++---------
cmd/worker/main.go | 21 +--
docs/library-acceptance-matrix.md | 2 +-
internal/appconfig/config.go | 6 +-
internal/libraryagent/agent.go | 25 +++-
internal/libraryagent/agent_test.go | 27 +++-
internal/libraryagent/client.go | 8 +-
internal/libraryagent/expectation.go | 72 ++++++++++
internal/libraryagent/health_test.go | 3 +-
internal/libraryagent/swap_test.go | 149 ++++++++++++++++++++
12 files changed, 382 insertions(+), 161 deletions(-)
create mode 100644 internal/libraryagent/expectation.go
create mode 100644 internal/libraryagent/swap_test.go
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ed9693e..f5146fc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,6 +24,13 @@
### Changed
+- **封存身份核对移进请求本身(TOCTOU)**:原来 worker 先 `health` 再 `capture`,两次
+ 拨号之间 socket 可能被换成另一个 agent——错的执行器已经把写入者停了才被拒登记。
+ 现在 `capture` 请求携带治理侧配置生成的期望身份(`project` 必填,`source_app`/
+ `archive_root` 配了就一起绑定)与稳定指纹(`sha256:`,覆盖三项);接收方在**操作
+ 互斥内、执行任何源操作之前**比对,缺失或被改过一律拒绝,错的执行器一次 `capture`
+ 都不跑。封存结果回显该指纹,worker 事后复核只作为证据防线,不能替代请求内核对。
+ 恢复路径不受期望约束(它只把写入者恢复回来)。
- `LIBRARY_EXECUTOR_STATUS_MAX_AGE`(默认 120 秒)控制执行器观测的有效期;
未设置不等于"永不过期",过期即"无法确认"。
- 页面/接口不再出现写死的"封存通道未接线""生产恢复未接线":不能发起时给出真实原因、
diff --git a/cmd/worker/library_capture_identity.go b/cmd/worker/library_capture_identity.go
index 7110ecc..11b450f 100644
--- a/cmd/worker/library_capture_identity.go
+++ b/cmd/worker/library_capture_identity.go
@@ -1,89 +1,69 @@
package main
import (
- "context"
"encoding/json"
"errors"
"fmt"
"strings"
- "time"
+ "knowledge-governance/internal/appconfig"
"knowledge-governance/internal/libraryagent"
)
-// 封存执行的身份核对分两次:执行前一次、执行后一次。
+// 封存的身份契约:期望随**同一个 capture 请求**送进 agent,由接收方在操作互斥内、
+// 任何源操作之前比对;worker 事后按回显的指纹再复核一次。
//
-// 为什么心跳不够:心跳说明"上一次探测时"那个 socket 后面是哪个实例,而从心跳到
-// 真正停写入者之间,socket 可能被换成另一个 agent(换挂载、换单元、误启正式单元)。
-// 执行前探测把窗口缩到最小;执行后复核 agent 自报的身份,则把"换过 socket"这件事
-// 变成一次显式的作业失败,而不是悄悄封错了库还登记成测试封存。
+// 为什么不能在 worker 侧先 Health 再 Capture:那是两次拨号,中间 socket 可能被换成
+// 另一个 agent,错的执行器已经把写入者停了才被拒登记——副作用已经发生。这里把期望
+// 放进请求本身,换过的 agent 会先比对身份、比对失败就一次 run 都不调。
+//
+// 期望字段只来自治理侧配置(LIBRARY_SOURCE_*),绝不从执行器自报值生成。
-// captureExecutorPrecheck 在动源写入者之前确认执行器就是期望的那个实例。
-func captureExecutorPrecheck(ctx context.Context, client libraryagent.ClientConfig, expectedProject string, probeTimeout time.Duration) error {
- if strings.TrimSpace(expectedProject) == "" {
- return errors.New("未配置封存来源实例身份(LIBRARY_SOURCE_PROJECT),拒绝在无法核对执行器的情况下停写入者")
+// captureExpectation 把治理侧配置翻译成期望;缺身份就是缺配置,调用方必须失败。
+func captureExpectation(config appconfig.Config) (libraryagent.Expectation, error) {
+ expectation := libraryagent.NewExpectation(config.SourceProject(), config.LibrarySourceApp, "")
+ if expectation.Project == "" {
+ return libraryagent.Expectation{}, errors.New("未配置封存来源实例身份(LIBRARY_SOURCE_PROJECT),拒绝在不核对执行器的情况下停写入者")
}
- if probeTimeout <= 0 {
- probeTimeout = 3 * time.Second
- }
- bounded, cancel := context.WithTimeout(ctx, probeTimeout)
- defer cancel()
- result, err := libraryagent.Health(bounded, client)
- if err != nil {
- return fmt.Errorf("封存执行器不可达,拒绝停写入者:%w", err)
- }
- identity, err := agentIdentityOf(result.Payload)
- if err != nil {
- return err
- }
- if identity.Project != expectedProject {
- return fmt.Errorf("封存执行器指向的实例不匹配(agent=%q,期望=%q),拒绝停写入者",
- identity.Project, expectedProject)
- }
- if identity.Degraded != "" {
- return fmt.Errorf("封存执行器处于降级状态(%s),拒绝停写入者", identity.Degraded)
- }
- return nil
+ return expectation, nil
}
-// captureExecutorPostcheck 用封存结果里 agent 自报的身份复核:不一致就当作
-// "封存可能来自别的实例",调用方不得把它登记成测试封存。
-func captureExecutorPostcheck(payload json.RawMessage, expectedProject string) error {
- identity, err := agentIdentityOf(payload)
- if err != nil {
- return err
+// captureExecutorPostcheck 是事后证据防线:结果里回显的期望指纹必须等于我们发出的,
+// 自报身份也必须与期望一致。它挡不住副作用,所以不能替代请求内的核对。
+func captureExecutorPostcheck(payload json.RawMessage, expectation libraryagent.Expectation) error {
+ if len(payload) == 0 {
+ return errors.New("封存结果里没有执行器身份,无法证明这次封存来自期望实例")
}
+ var document struct {
+ Identity struct {
+ Project string `json:"project"`
+ SourceApp string `json:"source_app"`
+ ExpectationFingerprint string `json:"expectation_fingerprint"`
+ } `json:"agent_identity"`
+ }
+ if err := json.Unmarshal(payload, &document); err != nil {
+ return errors.New("封存结果里的执行器身份无法解析")
+ }
+ identity := document.Identity
if identity.Project == "" {
return errors.New("封存结果里没有执行器身份,无法证明这次封存来自期望实例")
}
- if identity.Project != expectedProject {
+ if identity.ExpectationFingerprint != expectation.Fingerprint {
+ return fmt.Errorf("封存结果回显的期望指纹不一致(agent=%q,期望=%q),该快照不能当作本实例的测试封存",
+ identity.ExpectationFingerprint, expectation.Fingerprint)
+ }
+ if identity.Project != expectation.Project {
return fmt.Errorf("封存结果来自另一个实例(agent=%q,期望=%q),该快照不能当作本实例的测试封存",
- identity.Project, expectedProject)
+ identity.Project, expectation.Project)
+ }
+ if expectation.SourceApp != "" && identity.SourceApp != expectation.SourceApp {
+ return fmt.Errorf("封存结果来自另一个源容器(agent=%q,期望=%q),该快照不能当作本实例的测试封存",
+ identity.SourceApp, expectation.SourceApp)
}
return nil
}
-// agentIdentity 是 agent 在 health/封存结果里自报的身份(无凭据)。
-type agentIdentity struct {
- Project string `json:"project"`
- SourceApp string `json:"source_app"`
- Degraded string `json:"degraded"`
-}
-
-func agentIdentityOf(payload json.RawMessage) (agentIdentity, error) {
- if len(payload) == 0 {
- return agentIdentity{}, errors.New("执行器应答没有身份信息")
- }
- var document struct {
- Identity agentIdentity `json:"agent_identity"`
- agentIdentity
- }
- if err := json.Unmarshal(payload, &document); err != nil {
- return agentIdentity{}, errors.New("执行器身份无法解析")
- }
- // health 把身份摊平在顶层;封存结果把它放在 agent_identity 下。
- if document.Identity.Project != "" {
- return document.Identity, nil
- }
- return document.agentIdentity, nil
+// expectationFingerprint 用于日志/证据行的稳定标识,不含路径与凭据。
+func expectationFingerprint(expectation libraryagent.Expectation) string {
+ return strings.TrimSpace(expectation.Fingerprint)
}
diff --git a/cmd/worker/library_capture_identity_test.go b/cmd/worker/library_capture_identity_test.go
index fcf21bd..f3a9917 100644
--- a/cmd/worker/library_capture_identity_test.go
+++ b/cmd/worker/library_capture_identity_test.go
@@ -1,98 +1,73 @@
package main
import (
- "context"
"encoding/json"
- "net"
- "os"
- "path/filepath"
"strings"
"testing"
- "time"
+ "knowledge-governance/internal/appconfig"
"knowledge-governance/internal/libraryagent"
)
-func shortDir(t *testing.T) string {
- t.Helper()
- // unix socket 路径有长度上限,测试目录要短。
- dir, err := os.MkdirTemp("/tmp", "kgcap-")
+// 期望只从治理侧配置生成;缺 project 就是缺配置,必须在停写入者之前失败。
+func TestCaptureExpectationComesFromGovernanceConfigAndFailsClosed(t *testing.T) {
+ expect, err := captureExpectation(appconfig.Config{LibrarySourceInstance: "kgmaint-weknora", LibrarySourceApp: "kgmaint-app"})
if err != nil {
t.Fatal(err)
}
- t.Cleanup(func() { os.RemoveAll(dir) })
- return dir
-}
-
-func fakeAgent(t *testing.T, payload map[string]any) string {
- t.Helper()
- socket := filepath.Join(shortDir(t), "agent.sock")
- listener, err := net.Listen("unix", socket)
- if err != nil {
- t.Fatal(err)
+ if expect.Project != "kgmaint-weknora" || expect.SourceApp != "kgmaint-app" {
+ t.Fatalf("expectation = %+v", expect)
}
- t.Cleanup(func() { listener.Close() })
- go func() {
- for {
- conn, acceptErr := listener.Accept()
- if acceptErr != nil {
- return
- }
- var request map[string]any
- _ = json.NewDecoder(conn).Decode(&request)
- body, _ := json.Marshal(payload)
- _ = json.NewEncoder(conn).Encode(map[string]any{"ok": true, "action": "health", "payload": json.RawMessage(body)})
- conn.Close()
- }
- }()
- return socket
-}
-
-// 心跳说"可用"不等于执行时还是那个实例:执行前的探测必须能挡住换过的 socket。
-func TestCaptureExecutorPrecheckRejectsAWrongInstance(t *testing.T) {
- socket := fakeAgent(t, map[string]any{"project": "weknora071full", "source_app": "WKNFull-app"})
- client := libraryagent.ClientConfig{Socket: socket, Timeout: 2 * time.Second}
- err := captureExecutorPrecheck(context.Background(), client, "kgmaint-weknora", 2*time.Second)
- if err == nil || !strings.Contains(err.Error(), "指向的实例不匹配") {
- t.Fatalf("err = %v", err)
+ if !expect.Complete() {
+ t.Fatalf("expectation should be complete: %+v", expect)
}
- if !strings.Contains(err.Error(), "weknora071full") {
- t.Fatalf("err should name the actual agent project: %v", err)
- }
-}
-
-func TestCaptureExecutorPrecheckAcceptsTheExpectedInstance(t *testing.T) {
- socket := fakeAgent(t, map[string]any{"project": "kgmaint-weknora", "source_app": "kgmaint-app"})
- client := libraryagent.ClientConfig{Socket: socket, Timeout: 2 * time.Second}
- if err := captureExecutorPrecheck(context.Background(), client, "kgmaint-weknora", 2*time.Second); err != nil {
- t.Fatal(err)
- }
- // 没有期望身份就不许停写入者:那不是"跳过检查",是不能动生产。
- if err := captureExecutorPrecheck(context.Background(), client, "", 2*time.Second); err == nil ||
+ if _, err = captureExpectation(appconfig.Config{}); err == nil ||
!strings.Contains(err.Error(), "LIBRARY_SOURCE_PROJECT") {
- t.Fatalf("empty expectation accepted: %v", err)
+ t.Fatalf("empty identity accepted: %v", err)
}
- // 降级同样挡住。
- degraded := fakeAgent(t, map[string]any{"project": "kgmaint-weknora", "degraded": "写入者恢复失败"})
- if err := captureExecutorPrecheck(context.Background(), libraryagent.ClientConfig{Socket: degraded, Timeout: 2 * time.Second},
- "kgmaint-weknora", 2*time.Second); err == nil || !strings.Contains(err.Error(), "降级") {
- t.Fatalf("degraded executor accepted: %v", err)
+ // 期望不取自任何执行器应答:显式给 project 就按它绑定,配置里没有别的来源。
+ explicit, err := captureExpectation(appconfig.Config{LibrarySourceProject: "kgmaint-weknora"})
+ if err != nil || explicit.Project != "kgmaint-weknora" || explicit.SourceApp != "" {
+ t.Fatalf("explicit = %+v err=%v", explicit, err)
}
}
-// 执行后复核:结果里自报的身份不符,这次封存就不能被登记成测试封存。
-func TestCaptureExecutorPostcheckUsesTheIdentityInTheResult(t *testing.T) {
- good := json.RawMessage(`{"snapshot_id":"abc","agent_identity":{"project":"kgmaint-weknora"}}`)
- if err := captureExecutorPostcheck(good, "kgmaint-weknora"); err != nil {
+// 事后证据防线:回显的期望指纹、project、source_app 任何一项不符都不能登记。
+func TestCaptureExecutorPostcheckUsesTheEchoedExpectationFingerprint(t *testing.T) {
+ expect := libraryagent.NewExpectation("kgmaint-weknora", "kgmaint-app", "")
+ good := payloadOf(t, "kgmaint-weknora", "kgmaint-app", expect.Fingerprint)
+ if err := captureExecutorPostcheck(good, expect); err != nil {
t.Fatalf("matching identity rejected: %v", err)
}
- swapped := json.RawMessage(`{"snapshot_id":"abc","agent_identity":{"project":"weknora071full"}}`)
- err := captureExecutorPostcheck(swapped, "kgmaint-weknora")
- if err == nil || !strings.Contains(err.Error(), "另一个实例") {
- t.Fatalf("err = %v", err)
+ swapped := payloadOf(t, "weknora071full", "WKNFull-app", expect.Fingerprint)
+ if err := captureExecutorPostcheck(swapped, expect); err == nil || !strings.Contains(err.Error(), "另一个实例") {
+ t.Fatalf("wrong project accepted: %v", err)
}
- if err := captureExecutorPostcheck(json.RawMessage(`{"snapshot_id":"abc"}`), "kgmaint-weknora"); err == nil ||
+ regenerated := payloadOf(t, "kgmaint-weknora", "kgmaint-app",
+ libraryagent.NewExpectation("kgmaint-weknora", "kgmaint-app", "/other/archive").Fingerprint)
+ if err := captureExecutorPostcheck(regenerated, expect); err == nil || !strings.Contains(err.Error(), "期望指纹不一致") {
+ t.Fatalf("regenerated expectation accepted: %v", err)
+ }
+ if err := captureExecutorPostcheck(json.RawMessage(`{"snapshot_id":"abc"}`), expect); err == nil ||
!strings.Contains(err.Error(), "没有执行器身份") {
t.Fatalf("missing identity accepted: %v", err)
}
+ if err := captureExecutorPostcheck(payloadOf(t, "kgmaint-weknora", "kgseal-app", expect.Fingerprint), expect); err == nil ||
+ !strings.Contains(err.Error(), "另一个源容器") {
+ t.Fatalf("wrong source app accepted: %v", err)
+ }
+}
+
+func payloadOf(t *testing.T, project, sourceApp, fingerprint string) json.RawMessage {
+ t.Helper()
+ encoded, err := json.Marshal(map[string]any{
+ "snapshot_id": "abc",
+ "agent_identity": map[string]any{
+ "project": project, "source_app": sourceApp, "expectation_fingerprint": fingerprint,
+ },
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ return encoded
}
diff --git a/cmd/worker/main.go b/cmd/worker/main.go
index d0d6f2c..e72aaf2 100644
--- a/cmd/worker/main.go
+++ b/cmd/worker/main.go
@@ -270,14 +270,16 @@ func workerHandlers(store *postgresstore.Store, config appconfig.Config) (map[st
_ = store.AdvanceLibraryJob(ctx, libraryJobID, governance.LibraryJobFailed, "export", "dead letter release storage unavailable", "", "", "", time.Now().UTC())
return fmt.Errorf("load dead letter releases: %w", releaseErr)
}
- // 心跳只能证明"刚才"是哪个实例:动写入者之前再核一次身份。
- if identityErr := captureExecutorPrecheck(ctx, agentConfig, config.SourceProject(), 5*time.Second); identityErr != nil {
- _ = store.UpdateLibraryStage(ctx, libraryJobID, "export", "failed", nil, nil, nil, nil, identityErr.Error(), time.Now().UTC())
- _ = store.AdvanceLibraryJob(ctx, libraryJobID, governance.LibraryJobFailed, "export", identityErr.Error(),
- "未停任何写入者;修正执行器身份后重试", "", "", time.Now().UTC())
- return identityErr
+ // 期望执行器身份随请求一起送进 agent,由接收方在操作互斥内、任何源操作之前
+ // 比对:这样即使 socket 在这之前被换掉,错的执行器也一次 run 都不会跑。
+ expectation, expectErr := captureExpectation(config)
+ if expectErr != nil {
+ _ = store.UpdateLibraryStage(ctx, libraryJobID, "export", "failed", nil, nil, nil, nil, expectErr.Error(), time.Now().UTC())
+ _ = store.AdvanceLibraryJob(ctx, libraryJobID, governance.LibraryJobFailed, "export", expectErr.Error(),
+ "未停任何写入者;补齐来源身份配置后重试", "", "", time.Now().UTC())
+ return expectErr
}
- result, err := libraryagent.CaptureReleased(ctx, agentConfig, payload.Scope, payload.CaptureJob, released)
+ result, err := libraryagent.CaptureReleased(ctx, agentConfig, payload.Scope, payload.CaptureJob, released, expectation)
finishedAt := time.Now().UTC()
if err != nil {
// 导出失败时阶段与作业都要留痕;恢复责任在 agent,不会因为作业失败而假装来源已恢复。
@@ -289,7 +291,7 @@ func workerHandlers(store *postgresstore.Store, config appconfig.Config) (map[st
}
// 执行后复核:结果里 agent 自报的身份必须还是期望实例,否则这次封存
// 可能来自别的栈,绝不能登记成"本实例的测试封存"。
- if identityErr := captureExecutorPostcheck(result.Payload, config.SourceProject()); identityErr != nil {
+ if identityErr := captureExecutorPostcheck(result.Payload, expectation); identityErr != nil {
_ = store.UpdateLibraryStage(ctx, libraryJobID, "export", "failed", nil, nil, nil, nil, identityErr.Error(), finishedAt)
_ = store.AdvanceLibraryJob(ctx, libraryJobID, governance.LibraryJobFailed, "export", identityErr.Error(),
"快照已产生但来源身份不符,未登记为测试封存;核对执行器后重新封存", "", "", finishedAt)
@@ -301,7 +303,8 @@ func workerHandlers(store *postgresstore.Store, config appconfig.Config) (map[st
Scope: payload.Scope,
Kind: governance.LibraryVersionTestSealed, SnapshotID: result.SnapshotID, SourceJobID: libraryJobID,
Evidence: map[string]any{"capture_job": payload.CaptureJob, "replay": result.Replay,
- "requested_by": payload.RequestedBy, "agent_result": json.RawMessage(result.Payload)},
+ "requested_by": payload.RequestedBy, "expectation_fingerprint": expectationFingerprint(expectation),
+ "agent_result": json.RawMessage(result.Payload)},
CreatedBy: payload.RequestedBy, CreatedAt: finishedAt,
})
if versionErr != nil {
diff --git a/docs/library-acceptance-matrix.md b/docs/library-acceptance-matrix.md
index 38703f9..0bc50ee 100644
--- a/docs/library-acceptance-matrix.md
+++ b/docs/library-acceptance-matrix.md
@@ -90,7 +90,7 @@ A06(内容、问答、引用图片效果、性能报告)已由用户取消
| --- | --- | --- |
| S03-b | 死信/孤儿任务阻断的负向演练(本轮只验证了真实死信阻断) | 真实阻断已发生并记录;系统化的负向矩阵未跑 |
| 排空时序(历史结论) | 旧做法"202 之后抢时序上传"在 1faf513 上重跑 6 次全部 `Broken pipe`(`drain-task-final-1faf513*.json` 保留,不记通过) | 已被 S06-a 的确定性做法取代:先证明请求已被闸门接收,再启动维护。旧证据保留,不覆盖 |
-| 封存执行期身份复核(真实封存) | 代码与单测在位(agent 附身份、worker 执行前探测+执行后复核),本轮**没有**在候选栈发起真实封存(会产生新快照与停写入者窗口),因此"换 socket 被挡住"只有单测证据 |
+| 封存执行期身份复核(真实封存) | 期望身份随 capture 请求送进 agent,由它在操作互斥内、任何源操作之前比对(`swap_test.go` 用两个真实 agent 的 socket 替换做负例,断言错误 agent 的 capture 调用 0 次);真实封存尚未在最终构建上跑,本轮**没有**在候选栈发起真实封存(会产生新快照与停写入者窗口),因此"换 socket 被挡住"只有单测证据 |
| 按版本恢复的真实执行(新构建) | `restore-availability` 真实返回、恢复投递路径有单测;真实恢复作业仍在旧构建上验过(R01),本轮未重跑,不把旧证据算作新构建证据 |
| U05 | 正式 8088 页面验收 | 正式栈仍是 0.1.114,本轮未替换;维护面板/逐页 Wiki 差异只在测试与候选构建里验证过 |
diff --git a/internal/appconfig/config.go b/internal/appconfig/config.go
index 19ef36d..48d0f44 100644
--- a/internal/appconfig/config.go
+++ b/internal/appconfig/config.go
@@ -102,7 +102,10 @@ type Config struct {
LibrarySourceInstance string
// LibrarySourceProject 是封存执行器应该指向的实例名(agent -project)。
// 留空时等于来源实例名:环境里两者本来就同名(kgmaint-weknora)。
- LibrarySourceProject string
+ LibrarySourceProject string
+ // LibrarySourceApp 是封存源容器名(agent -source-app)。project 可能同名而源接线
+ // 不同,所以配了就一起绑定进"期望执行器身份"。
+ LibrarySourceApp string
LibraryTargetProject string
LibraryTargetWriters []string
LibraryTargetNonWriters map[string]string
@@ -210,6 +213,7 @@ func Load(getenv func(string) string) (Config, error) {
LibraryTargetInstance: strings.TrimSpace(getenv("LIBRARY_TARGET_INSTANCE")),
LibrarySourceInstance: strings.TrimSpace(getenv("LIBRARY_SOURCE_INSTANCE")),
LibrarySourceProject: strings.TrimSpace(getenv("LIBRARY_SOURCE_PROJECT")),
+ LibrarySourceApp: strings.TrimSpace(getenv("LIBRARY_SOURCE_APP")),
LibraryTargetProject: strings.TrimSpace(getenv("LIBRARY_TARGET_PROJECT")),
LibraryTargetWriters: splitList(getenv("LIBRARY_TARGET_WRITERS")),
LibraryTargetNonWriters: splitDeclarations(getenv("LIBRARY_TARGET_NON_WRITERS")),
diff --git a/internal/libraryagent/agent.go b/internal/libraryagent/agent.go
index 65fd3fc..f9a1051 100644
--- a/internal/libraryagent/agent.go
+++ b/internal/libraryagent/agent.go
@@ -66,6 +66,9 @@ type request struct {
// Released 只允许精确死信指纹(sha256:<64 hex>)。它不改变固定命令形态:
// 还能传的只有"这些确切的行已由治理平台审计解除",CLI 会逐字节复核。
Released []string `json:"released,omitempty"`
+ // Expect 是调用方对执行器身份的期望。capture 必须在操作互斥内、任何源操作
+ // 之前比对它;缺失即拒绝(fail closed),不靠"事后核对"兜底。
+ Expect *Expectation `json:"expect,omitempty"`
}
type response struct {
@@ -255,6 +258,16 @@ func (a *Agent) execute(ctx context.Context, req request) response {
out.Error = "invalid job id"
return out
}
+ if req.Expect == nil {
+ out.Error = "capture 请求没有携带期望执行器身份,拒绝执行"
+ return out
+ }
+ // 此时已持有操作互斥(a.mu):从"比对身份"到"真正跑子进程"之间没有别的
+ // 请求能插进来,也不会被另一个 agent 抢走——这是零副作用的前提。
+ if err := a.config.matchExpectation(*req.Expect); err != nil {
+ out.Error = err.Error()
+ return out
+ }
args = []string{"capture", "-scope", req.Scope}
if req.Job != "" {
args = append(args, "-job", req.Job)
@@ -317,19 +330,23 @@ func (a *Agent) execute(ctx context.Context, req request) response {
}
// 封存结果必须带上"这次是谁执行的":调用方据此复核,防止心跳与执行之间
// socket 被换成另一个 agent(真正的封错库事故就是这样发生的)。
- if req.Action == "capture" {
- out.Payload = a.attachIdentity(out.Payload)
+ if req.Action == "capture" && req.Expect != nil {
+ out.Payload = a.attachIdentity(out.Payload, *req.Expect)
}
return out
}
// attachIdentity 把执行器身份并进封存结果(保留 CLI 原有的字段,如 snapshot_id)。
-func (a *Agent) attachIdentity(payload json.RawMessage) json.RawMessage {
+// expectation_fingerprint 是"本执行器实际核对过的那份期望"的指纹:调用方据此确认
+// 执行时看到的期望与它发出的一致,而不是被替换后重新生成的。
+func (a *Agent) attachIdentity(payload json.RawMessage, expectation Expectation) json.RawMessage {
var document map[string]any
if err := json.Unmarshal(payload, &document); err != nil {
return payload
}
- document["agent_identity"] = a.config.identity()
+ identity := a.config.identity()
+ identity["expectation_fingerprint"] = expectation.Fingerprint
+ document["agent_identity"] = identity
encoded, err := json.Marshal(document)
if err != nil {
return payload
diff --git a/internal/libraryagent/agent_test.go b/internal/libraryagent/agent_test.go
index 15e62d5..747069a 100644
--- a/internal/libraryagent/agent_test.go
+++ b/internal/libraryagent/agent_test.go
@@ -56,6 +56,19 @@ func testAgent(t *testing.T) (*Agent, string, func() []string) {
}
}
+// captureExpect 是测试 agent 自己的身份(weknora071full / WKNFull-app),
+// 现在 capture 请求必须携带期望身份,缺了就会被拒。
+func captureExpect(t *testing.T) string {
+ t.Helper()
+ // 只绑定 project:各用例的 source_app 不同,绑定字段的专门用例在 expectation_test.go。
+ expectation := NewExpectation("weknora071full", "", "")
+ encoded, err := json.Marshal(expectation)
+ if err != nil {
+ t.Fatal(err)
+ }
+ return string(encoded)
+}
+
func roundTrip(t *testing.T, socket string, payload string) response {
t.Helper()
conn, err := net.Dial("unix", socket)
@@ -105,7 +118,7 @@ func TestAgentSocketIsPrivateAndPinsTheDeclaration(t *testing.T) {
if dir.Mode().Perm() != 0700 {
t.Fatalf("socket directory mode %v", dir.Mode().Perm())
}
- out := roundTrip(t, socket, `{"action":"capture","scope":"internal","job":"lib-internal-test"}`)
+ out := roundTrip(t, socket, `{"action":"capture","scope":"internal","job":"lib-internal-test","expect":`+captureExpect(t)+`}`)
if !out.OK || out.Job != "lib-internal-test" {
t.Fatalf("capture rejected: %+v", out)
}
@@ -234,7 +247,7 @@ func TestAgentRecoversWritersAfterFailedCapture(t *testing.T) {
defer cancel()
go func() { _ = agent.Serve(ctx) }()
waitSocket(t, socket)
- out := roundTrip(t, socket, `{"action":"capture","scope":"internal","job":"lib-fail-1"}`)
+ out := roundTrip(t, socket, `{"action":"capture","scope":"internal","job":"lib-fail-1","expect":`+captureExpect(t)+`}`)
if out.OK {
t.Fatalf("failed capture reported success: %+v", out)
}
@@ -255,12 +268,12 @@ func TestAgentBlocksCapturesWhenRecoveryFails(t *testing.T) {
go func() { _ = agent.Serve(ctx) }()
waitSocket(t, socket)
setRecoverErr(errors.New("docker restart failed"))
- out := roundTrip(t, socket, `{"action":"capture","scope":"internal","job":"lib-fail-2"}`)
+ out := roundTrip(t, socket, `{"action":"capture","scope":"internal","job":"lib-fail-2","expect":`+captureExpect(t)+`}`)
if out.OK || !strings.Contains(out.Error, "写入者恢复失败") || !strings.Contains(out.Error, "已阻断后续封存") {
t.Fatalf("recovery failure not surfaced: %+v", out)
}
before := len(captureCalls(calls()))
- blocked := roundTrip(t, socket, `{"action":"capture","scope":"external","job":"lib-fail-3"}`)
+ blocked := roundTrip(t, socket, `{"action":"capture","scope":"external","job":"lib-fail-3","expect":`+captureExpect(t)+`}`)
if blocked.OK || !strings.Contains(blocked.Error, "降级") {
t.Fatalf("degraded agent accepted a capture: %+v", blocked)
}
@@ -272,7 +285,7 @@ func TestAgentBlocksCapturesWhenRecoveryFails(t *testing.T) {
if recovered := roundTrip(t, socket, `{"action":"recover"}`); !recovered.OK {
t.Fatalf("explicit recovery failed: %+v", recovered)
}
- if resumed := roundTrip(t, socket, `{"action":"capture","scope":"internal","job":"lib-fail-4"}`); strings.Contains(resumed.Error, "降级") {
+ if resumed := roundTrip(t, socket, `{"action":"capture","scope":"internal","job":"lib-fail-4","expect":`+captureExpect(t)+`}`); strings.Contains(resumed.Error, "降级") {
t.Fatalf("recovery did not clear the degraded state: %+v", resumed)
}
}
@@ -396,7 +409,7 @@ func TestAgentForwardsOnlyExactDeadLetterFingerprints(t *testing.T) {
time.Sleep(10 * time.Millisecond)
}
fingerprint := "sha256:" + strings.Repeat("a", 64)
- ok := roundTrip(t, socket, `{"action":"capture","scope":"internal","job":"j1","released":["`+fingerprint+`"]}`)
+ ok := roundTrip(t, socket, `{"action":"capture","scope":"internal","job":"j1","released":["`+fingerprint+`"],"expect":`+captureExpect(t)+`}`)
if !ok.OK {
t.Fatalf("exact fingerprint refused: %s", ok.Error)
}
@@ -404,7 +417,7 @@ func TestAgentForwardsOnlyExactDeadLetterFingerprints(t *testing.T) {
if !strings.Contains(last, "-released-dead-letters "+fingerprint) {
t.Fatalf("fingerprint not forwarded: %s", last)
}
- bad := roundTrip(t, socket, `{"action":"capture","scope":"internal","job":"j2","released":["*"]}`)
+ bad := roundTrip(t, socket, `{"action":"capture","scope":"internal","job":"j2","released":["*"],"expect":`+captureExpect(t)+`}`)
if bad.OK || !strings.Contains(bad.Error, "fingerprints") {
t.Fatalf("wildcard release accepted: %+v", bad)
}
diff --git a/internal/libraryagent/client.go b/internal/libraryagent/client.go
index 8822718..b956275 100644
--- a/internal/libraryagent/client.go
+++ b/internal/libraryagent/client.go
@@ -28,13 +28,13 @@ type Result struct {
// Capture asks the agent to seal one library scope. The job id makes the call
// idempotent: repeating it returns the already sealed candidate.
-func Capture(ctx context.Context, config ClientConfig, scope, job string) (Result, error) {
- return CaptureReleased(ctx, config, scope, job, nil)
+func Capture(ctx context.Context, config ClientConfig, scope, job string, expect Expectation) (Result, error) {
+ return CaptureReleased(ctx, config, scope, job, nil, expect)
}
// CaptureReleased 在 Capture 之上带上治理平台已审计的精确死信解除指纹。
-func CaptureReleased(ctx context.Context, config ClientConfig, scope, job string, released []string) (Result, error) {
- request := map[string]any{"action": "capture", "scope": scope, "job": job}
+func CaptureReleased(ctx context.Context, config ClientConfig, scope, job string, released []string, expect Expectation) (Result, error) {
+ request := map[string]any{"action": "capture", "scope": scope, "job": job, "expect": expect}
if len(released) > 0 {
request["released"] = released
}
diff --git a/internal/libraryagent/expectation.go b/internal/libraryagent/expectation.go
new file mode 100644
index 0000000..dcb546f
--- /dev/null
+++ b/internal/libraryagent/expectation.go
@@ -0,0 +1,72 @@
+package libraryagent
+
+import (
+ "crypto/sha256"
+ "encoding/hex"
+ "errors"
+ "strings"
+)
+
+// Expectation 是调用方对"这一条请求该由哪个执行器执行"的声明。
+//
+// 为什么是调用方声明而不是执行器自报:自报值只能证明"我是谁",不能证明"你找的
+// 就是我"。心跳之后、真正停写入者之前,socket 可能被换成另一个 agent;只有把
+// 期望随**同一个请求**送进去、由接收方在操作互斥内、执行任何源操作之前比对,
+// 才能让"换过 socket"变成零副作用(错的那个 noche 一次 run 都不调)。
+type Expectation struct {
+ Project string `json:"project"`
+ SourceApp string `json:"source_app,omitempty"`
+ ArchiveRoot string `json:"archive_root,omitempty"`
+ // Fingerprint 覆盖上面三项,供接收方回显、调用方事后核对:
+ // 证明"执行器看到的就是我发的那份期望",而不是被替换后重新生成的。
+ Fingerprint string `json:"fingerprint"`
+}
+
+// NewExpectation 由治理侧配置构造期望(绝不从执行器应答里取字段)。
+func NewExpectation(project, sourceApp, archiveRoot string) Expectation {
+ expectation := Expectation{
+ Project: strings.TrimSpace(project),
+ SourceApp: strings.TrimSpace(sourceApp),
+ ArchiveRoot: strings.TrimSpace(archiveRoot),
+ }
+ expectation.Fingerprint = expectation.fingerprint()
+ return expectation
+}
+
+func (e Expectation) fingerprint() string {
+ sum := sha256.Sum256([]byte(e.Project + "\x00" + e.SourceApp + "\x00" + e.ArchiveRoot))
+ return "sha256:" + hex.EncodeToString(sum[:])
+}
+
+// Complete 表示期望足够具体:没有 project 的期望无法核对身份,必须 fail closed;
+// 指纹与字段不一致说明请求在半路被改过。
+func (e Expectation) Complete() bool {
+ return e.Project != "" && e.Fingerprint == e.fingerprint()
+}
+
+// matchExpectation 在操作互斥内比对"本执行器配置"与"调用方期望"。
+// 只比较期望里给出的字段:project 必填,source_app/archive_root 给了就必须一致。
+func (c Config) matchExpectation(expectation Expectation) error {
+ if !expectation.Complete() {
+ return errors.New("capture 请求缺少完整的期望执行器身份,拒绝执行")
+ }
+ if c.Project != expectation.Project {
+ return errors.New("执行器与请求期望的实例不一致:" +
+ "agent=" + quoteOrEmpty(c.Project) + ",期望=" + quoteOrEmpty(expectation.Project) + ",拒绝执行")
+ }
+ if expectation.SourceApp != "" && c.SourceApp != expectation.SourceApp {
+ return errors.New("执行器与请求期望的源容器不一致:" +
+ "agent=" + quoteOrEmpty(c.SourceApp) + ",期望=" + quoteOrEmpty(expectation.SourceApp) + ",拒绝执行")
+ }
+ if expectation.ArchiveRoot != "" && c.ArchiveRoot != expectation.ArchiveRoot {
+ return errors.New("执行器与请求期望的归档根不一致,拒绝执行")
+ }
+ return nil
+}
+
+func quoteOrEmpty(value string) string {
+ if value == "" {
+ return `""`
+ }
+ return `"` + value + `"`
+}
diff --git a/internal/libraryagent/health_test.go b/internal/libraryagent/health_test.go
index d682105..9b06abe 100644
--- a/internal/libraryagent/health_test.go
+++ b/internal/libraryagent/health_test.go
@@ -89,7 +89,8 @@ func TestCaptureResultCarriesTheAgentIdentity(t *testing.T) {
serveAgent(t, agent, socket)
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
- result, err := Capture(ctx, ClientConfig{Socket: socket, Timeout: 5 * time.Second}, "internal", "lib-internal-identity")
+ result, err := Capture(ctx, ClientConfig{Socket: socket, Timeout: 5 * time.Second}, "internal",
+ "lib-internal-identity", NewExpectation("weknora071full", "WKNFull-app", ""))
if err != nil {
t.Fatal(err)
}
diff --git a/internal/libraryagent/swap_test.go b/internal/libraryagent/swap_test.go
new file mode 100644
index 0000000..070afd7
--- /dev/null
+++ b/internal/libraryagent/swap_test.go
@@ -0,0 +1,149 @@
+package libraryagent
+
+import (
+ "context"
+ "os"
+ "strings"
+ "sync"
+ "testing"
+ "time"
+)
+
+// unix socket 路径有长度上限,测试目录要用短的(TMPDIR 太深)。
+func shortSocketDir(t *testing.T) string {
+ t.Helper()
+ dir, err := os.MkdirTemp("/tmp", "kgswap-")
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { os.RemoveAll(dir) })
+ return dir
+}
+
+// 两个真实 agent、两个 socket:负例把调用方指到"另一个实例"的 socket 上,
+// 断言**错误 agent 一次 capture 都没跑**(不是跑完再拒),正例走对 socket 正常封存。
+func TestCaptureRequestIsRefusedBeforeAnySourceOperationWhenSocketIsSwapped(t *testing.T) {
+ rightAgent, rightSocket, rightCalls := agentWithProject(t, "kgmaint-weknora", "kgmaint-app")
+ wrongAgent, wrongSocket, wrongCalls := agentWithProject(t, "weknora071full", "WKNFull-app")
+ serveAgent(t, rightAgent, rightSocket)
+ serveAgent(t, wrongAgent, wrongSocket)
+
+ expectation := NewExpectation("kgmaint-weknora", "kgmaint-app", "")
+ ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+ defer cancel()
+
+ // 负例:调用方手上的 socket 已被换成另一个实例的执行器。
+ result, err := Capture(ctx, ClientConfig{Socket: wrongSocket, Timeout: 5 * time.Second},
+ "internal", "lib-swap", expectation)
+ if err == nil || result.OK {
+ t.Fatalf("capture against the wrong executor was accepted: %+v", result)
+ }
+ if !strings.Contains(result.Error, "期望") {
+ t.Fatalf("refusal should name the mismatch: %q", result.Error)
+ }
+ if calls := captureCalls(wrongCalls()); len(calls) != 0 {
+ t.Fatalf("wrong executor ran the capture binary %d time(s): %v", len(calls), calls)
+ }
+ // 旁证:错误的执行器进程本身仍然可用(health 正常),拒绝来自身份比对而不是不可达。
+ health, err := Health(ctx, ClientConfig{Socket: wrongSocket, Timeout: 5 * time.Second})
+ if err != nil || !health.OK {
+ t.Fatalf("wrong executor should still answer health: %v %+v", err, health)
+ }
+
+ // 正例:同一份期望打到正确的 socket,正常封存一次。
+ result, err = Capture(ctx, ClientConfig{Socket: rightSocket, Timeout: 5 * time.Second},
+ "internal", "lib-swap", expectation)
+ if err != nil || !result.OK {
+ t.Fatalf("capture against the right executor failed: %v %+v", err, result)
+ }
+ if calls := captureCalls(rightCalls()); len(calls) != 1 {
+ t.Fatalf("right executor ran %d time(s): %v", len(calls), calls)
+ }
+ if calls := captureCalls(wrongCalls()); len(calls) != 0 {
+ t.Fatalf("wrong executor ran after the positive case: %v", calls)
+ }
+}
+
+// 缺期望、期望指纹对不上、期望里 source_app 不同,都必须 fail closed 且不跑子进程。
+func TestCaptureFailsClosedWithoutACompleteExpectation(t *testing.T) {
+ agent, socket, calls := agentWithProject(t, "kgmaint-weknora", "kgmaint-app")
+ serveAgent(t, agent, socket)
+ ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+ defer cancel()
+
+ tampered := NewExpectation("kgmaint-weknora", "kgmaint-app", "")
+ tampered.Project = "someone-else" // 字段改了、指纹没改:请求在半路被改过
+ cases := []struct {
+ name string
+ expectation Expectation
+ text string
+ }{
+ {name: "missing expectation", expectation: Expectation{}, text: "缺少完整的期望执行器身份"},
+ {name: "tampered expectation", expectation: tampered, text: "缺少完整的期望执行器身份"},
+ {name: "wrong source app", expectation: NewExpectation("kgmaint-weknora", "WKNFull-app", ""), text: "源容器不一致"},
+ }
+ for _, test := range cases {
+ result, err := Capture(ctx, ClientConfig{Socket: socket, Timeout: 5 * time.Second},
+ "internal", "lib-"+strings.ReplaceAll(test.name, " ", "-"), test.expectation)
+ if err == nil || result.OK {
+ t.Fatalf("%s: accepted %+v", test.name, result)
+ }
+ if !strings.Contains(result.Error, test.text) {
+ t.Fatalf("%s: error %q", test.name, result.Error)
+ }
+ }
+ if calls := captureCalls(calls()); len(calls) != 0 {
+ t.Fatalf("capture binary ran despite a refused identity: %v", calls)
+ }
+}
+
+// 恢复路径不受期望约束:它只把写入者恢复回来,任何身份都必须能执行。
+func TestRecoverStaysAvailableRegardlessOfExpectation(t *testing.T) {
+ agent, socket, calls := agentWithProject(t, "kgmaint-weknora", "kgmaint-app")
+ serveAgent(t, agent, socket)
+ ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+ defer cancel()
+ result, err := Recover(ctx, ClientConfig{Socket: socket, Timeout: 5 * time.Second})
+ if err != nil || !result.OK {
+ t.Fatalf("recover refused: %v %+v", err, result)
+ }
+ if len(recoverCalls(calls())) == 0 {
+ t.Fatal("recover did not run the recovery command")
+ }
+}
+
+// agentWithProject 造一个真实 agent(不跑真命令),返回它自己的调用记录。
+func agentWithProject(t *testing.T, project, sourceApp string) (*Agent, string, func() []string) {
+ t.Helper()
+ root := shortSocketDir(t)
+ var mu sync.Mutex
+ var calls []string
+ config := Config{
+ Socket: root + "/agent.sock",
+ Binary: "/bin/echo",
+ ArchiveRoot: root + "/library",
+ JournalRoot: root + "/freeze",
+ SourceApp: sourceApp,
+ SourcePG: "pg",
+ SourceES: "es",
+ Project: project,
+ Writers: "app",
+ NonWriters: "frontend=UI only",
+ MaxDuration: time.Minute,
+ Run: func(_ context.Context, name string, args ...string) ([]byte, error) {
+ mu.Lock()
+ calls = append(calls, name+" "+strings.Join(args, " "))
+ mu.Unlock()
+ return []byte(`{"snapshot_id":"abc","state":"succeeded"}`), nil
+ },
+ }
+ agent, err := New(config)
+ if err != nil {
+ t.Fatal(err)
+ }
+ return agent, config.Socket, func() []string {
+ mu.Lock()
+ defer mu.Unlock()
+ return append([]string(nil), calls...)
+ }
+}
--
2.52.0
From c14dd01f08ca1d7a5fccbe5ffdc0b69ed3463962 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 13:32:55 +0800
Subject: [PATCH 35/45] =?UTF-8?q?fix(library):=20=E5=B0=81=E5=AD=98?=
=?UTF-8?q?=E8=AF=BB=E8=B5=84=E6=BA=90=E5=A4=B1=E8=B4=A5=E5=B8=A6=E4=B8=8A?=
=?UTF-8?q?=E8=B5=84=E6=BA=90=E8=A1=8C=E4=B8=8E=E5=BA=95=E5=B1=82=E5=8E=9F?=
=?UTF-8?q?=E5=9B=A0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
真实封存卡在 `read library resource` 时没有任何可判断信息:对象缺失、桶写错、
宿主机解析不到端点都会走到同一个字符串。现在错误带资源行 id 与底层原因
(不含凭据),本轮就是用它在候选栈定位到"源对象被上一次 B02 演练删掉后没真正写回"。
---
CHANGELOG.md | 3 +++
internal/releaseadapter/v071/library_archive.go | 5 ++++-
2 files changed, 7 insertions(+), 1 deletion(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f5146fc..8e99a7b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -38,6 +38,9 @@
### Fixed
+- **封存读资源失败只剩一句 `read library resource`**:对象缺失、桶错、端点解析不到
+ 都会走到同一个字符串,真实封存直接卡在这里无法判断方向。现在带上资源行 id 与底层
+ 原因(`read library resource : `),不含凭据。
- **正式 release-worker 启动失败无法定位**:配置里的目标库指向不存在的主机时,
日志只有一句 `connect release target database`。现在错误里带库端点
(`host:port/db`,去口令)与路由标识,并保留底层原因;原因文本先经
diff --git a/internal/releaseadapter/v071/library_archive.go b/internal/releaseadapter/v071/library_archive.go
index e6fa069..750fa48 100644
--- a/internal/releaseadapter/v071/library_archive.go
+++ b/internal/releaseadapter/v071/library_archive.go
@@ -5,6 +5,7 @@ import (
"context"
"encoding/json"
"errors"
+ "fmt"
"strings"
"time"
@@ -86,7 +87,9 @@ func ArchiveLibraryCandidate(ctx context.Context, archive *librarysnapshot.Archi
}
reader, err := objects.Open(ctx, resource.Provider, resource.PhysicalPath)
if err != nil {
- return "", errors.New("read library resource")
+ // 只写"read library resource"会让整条封存停在无信息的失败上:带上行 id
+ // 与底层原因(不含凭据),才能判断是对象缺失、桶错还是端点解析不到。
+ return "", fmt.Errorf("read library resource %s: %w", resource.ID, err)
}
part, readErr := archive.Put(reader)
closeErr := reader.Close()
--
2.52.0
From 8d2ed8ebe61fcf5ef9a5e1b25923e6456c52c5c8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 14:02:09 +0800
Subject: [PATCH 36/45] =?UTF-8?q?fix(library):=20=E7=BB=B4=E6=8A=A4?=
=?UTF-8?q?=E9=87=8A=E6=94=BE=E4=B8=8E=E6=9C=8D=E5=8A=A1=E6=81=A2=E5=A4=8D?=
=?UTF-8?q?=E5=AE=8C=E6=88=90=E4=B9=8B=E5=90=8E=E6=89=8D=E6=9A=B4=E9=9C=B2?=
=?UTF-8?q?=E4=BD=9C=E4=B8=9A=E6=88=90=E5=8A=9F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
原本 execute 写完生效版本就写 succeeded,而服务恢复、入口开放与维护锁释放发生在
窗口返回之后。任一步失败时外部已看到成功,重启接管又只认非终态,于是目标永远
留在维护里(本轮真实现象:同步 succeeded 后立即恢复被 409)。
现在内容校验与版本登记完成后只记"待收尾":finishLibrarySuccess 先确认目标写入者
与入口健康,再按 scope → instance 顺序释放两把锁(每一步错误都上抛,不再 `_ =` 丢弃),
最后才写 succeeded;任一步失败即落失败并保持 needs_restore。释放与终态写入用
context.WithoutCancel 有界包住,停机不会留下半成品。接管的 finalize-only 判定改为
按证据(finalize 阶段成功或未顶掉的生效版本),只复核与登记,不重写生产。
测试覆盖:调用顺序(成功后两把锁必已释放)、健康失败不释放不报成功、三步释放失败
各自不报成功、终态写入失败提示等待接管、接管证据判定正负例。
---
CHANGELOG.md | 8 ++
cmd/worker/library_finish.go | 124 +++++++++++++++++++++++++
cmd/worker/library_finish_test.go | 149 ++++++++++++++++++++++++++++++
cmd/worker/library_handlers.go | 52 ++++++-----
4 files changed, 308 insertions(+), 25 deletions(-)
create mode 100644 cmd/worker/library_finish.go
create mode 100644 cmd/worker/library_finish_test.go
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8e99a7b..a976945 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -38,6 +38,14 @@
### Fixed
+- **作业成功暴露早于维护结束**:原来 `execute` 里写完生效版本就 `AdvanceLibraryJob(succeeded)`,
+ 而服务恢复、入口开放与维护锁释放要在窗口返回后才做。任何一步失败时外部已经看到
+ `succeeded`,重启接管又只认非终态,锁就永远挂着。现在内容校验/版本登记之后只记
+ "待收尾",`finishLibrarySuccess` 依次确认目标写入者与入口健康、按 **scope → instance**
+ 顺序释放两把锁(每一步错误都上抛,不再丢弃),最后才写 `succeeded`;任一步失败都把
+ 作业落成失败、维护保持 `needs_restore`。释放与终态写入用 `context.WithoutCancel`
+ 包住,停机不会留下半成品。接管判定改为按证据(finalize 阶段成功或存在未顶掉的生效
+ 版本)转 finalize-only,只复核与登记,不重写生产。
- **封存读资源失败只剩一句 `read library resource`**:对象缺失、桶错、端点解析不到
都会走到同一个字符串,真实封存直接卡在这里无法判断方向。现在带上资源行 id 与底层
原因(`read library resource : `),不含凭据。
diff --git a/cmd/worker/library_finish.go b/cmd/worker/library_finish.go
new file mode 100644
index 0000000..0b1628c
--- /dev/null
+++ b/cmd/worker/library_finish.go
@@ -0,0 +1,124 @@
+package main
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "time"
+
+ "knowledge-governance/internal/governance"
+ postgresstore "knowledge-governance/internal/platform/postgres"
+)
+
+// libraryMaintenanceStore 是"成功收尾"用到的存储能力。抽成接口是为了能在测试里
+// 让某一步失败,验证"没全部完成就不许暴露成功"。
+type libraryMaintenanceStore interface {
+ SetInstanceMaintenanceIngress(ctx context.Context, instance, ownerJobID, state, note string, now time.Time) error
+ SetLibraryMaintenanceIngress(ctx context.Context, scope, ownerJobID, state, note string, now time.Time) error
+ UpdateInstanceMaintenanceState(ctx context.Context, instance, ownerJobID, state, note string, now time.Time) error
+ UpdateLibraryMaintenanceState(ctx context.Context, scope, ownerJobID, state, note string, now time.Time) error
+ ReleaseInstanceMaintenance(ctx context.Context, instance, ownerJobID string, now time.Time) error
+ ReleaseLibraryMaintenance(ctx context.Context, scope, ownerJobID string, now time.Time) error
+ AdvanceLibraryJob(ctx context.Context, jobID string, state governance.LibraryJobState, stage, message, recovery, snapshotID, targetSnapshotID string, now time.Time) error
+}
+
+// releaseWindowLocks 是唯一释放路径。
+//
+// 顺序刻意是"scope 先、instance 后":instance 行是跨 scope 的互斥来源,最后放它
+// 才能保证任何新作业在全部记录落定之前都进不来。每一步的错误都必须向上暴露——
+// 只丢日志会让"锁其实没放"这件事变成页面上的成功。
+func releaseWindowLocks(ctx context.Context, store libraryMaintenanceStore, instance, scope, jobID, note string, now time.Time) error {
+ if err := store.SetLibraryMaintenanceIngress(ctx, scope, jobID, "open", note, now); err != nil {
+ return fmt.Errorf("记录入口已开放失败(scope):%w", err)
+ }
+ if err := store.SetInstanceMaintenanceIngress(ctx, instance, jobID, "open", note, now); err != nil {
+ return fmt.Errorf("记录入口已开放失败(instance):%w", err)
+ }
+ if err := store.UpdateLibraryMaintenanceState(ctx, scope, jobID, "verified", note, now); err != nil {
+ return fmt.Errorf("维护状态写入失败(scope):%w", err)
+ }
+ if err := store.ReleaseLibraryMaintenance(ctx, scope, jobID, now); err != nil {
+ return fmt.Errorf("维护占用释放失败(scope):%w", err)
+ }
+ if err := store.UpdateInstanceMaintenanceState(ctx, instance, jobID, "verified", note, now); err != nil {
+ return fmt.Errorf("维护状态写入失败(instance):%w", err)
+ }
+ if err := store.ReleaseInstanceMaintenance(ctx, instance, jobID, now); err != nil {
+ return fmt.Errorf("实例占用释放失败(instance):%w", err)
+ }
+ return nil
+}
+
+// healthChecker 是"目标写入者与入口是否真的恢复健康"的判定口(测试可注入失败)。
+type healthChecker interface {
+ VerifyRunning(ctx context.Context) error
+}
+
+// successBoundary 描述一次"内容已通过验证与版本登记,但还没到可以对外报成功"的作业。
+type successBoundary struct {
+ Ready bool
+ Backup string
+ Target string
+ FinishedAt time.Time
+}
+
+// finishLibrarySuccess 是唯一的成功收尾入口:只有以下全部成立才暴露 succeeded——
+// 目标服务健康、入口开放、scope 与 instance 两把维护锁都释放完成、终态写入成功。
+//
+// 为什么不能先标成功再释放:恢复/开入口/放锁都可能失败,先写 succeeded 会让外部
+// (页面、API、重启后的接管逻辑)看到一条"成功了但目标仍在维护"的作业;而
+// InterruptedLibraryJobs 只接管非终态,终态作业不会再被接管,锁就永远挂着。
+func finishLibrarySuccess(ctx context.Context, store libraryMaintenanceStore, health healthChecker,
+ instance, scope, jobID string, boundary successBoundary) error {
+ // 释放与终态写入必须能在 ctx 取消后继续:停机不该留下"锁放了但作业还在跑"或
+ // 反过来"作业成功了锁还挂着"的任一半成品。
+ bounded, cancel := context.WithTimeout(context.WithoutCancel(ctx), 60*time.Second)
+ defer cancel()
+
+ holdForRepair := func(reason string) error {
+ note := "内容已验证,但收尾未完成,目标保持维护:" + reason
+ _ = store.UpdateLibraryMaintenanceState(bounded, scope, jobID, "needs_restore", note, time.Now().UTC())
+ _ = store.UpdateInstanceMaintenanceState(bounded, instance, jobID, "needs_restore", note, time.Now().UTC())
+ _ = store.AdvanceLibraryJob(bounded, jobID, governance.LibraryJobFailed, "finalize", note,
+ "生产内容已写入并校验;维护保持,按预备份或人工核验后再开放", boundary.Backup, boundary.Target, time.Now().UTC())
+ return errors.New(note)
+ }
+
+ if err := health.VerifyRunning(bounded); err != nil {
+ return holdForRepair("目标服务或入口未恢复健康:" + err.Error())
+ }
+ if err := releaseWindowLocks(bounded, store, instance, scope, jobID,
+ "写入与校验完成,目标已按原运行状态恢复", time.Now().UTC()); err != nil {
+ return holdForRepair(err.Error())
+ }
+ finishedAt := time.Now().UTC()
+ if err := store.AdvanceLibraryJob(bounded, jobID, governance.LibraryJobSucceeded, "finalize", "", "",
+ boundary.Backup, boundary.Target, finishedAt); err != nil {
+ // 锁已释放但终态没写下去:作业保持非终态,重启后会被接管(接管走
+ // finalize-only,只复核与登记,不重写生产)。
+ return fmt.Errorf("维护已释放但作业终态写入失败(等待接管):%w", err)
+ }
+ return nil
+}
+
+// needsFinalizeOnly 判断一个被接管的作业是否"内容与版本都已落定、只差收尾"。
+// 判据只认真实证据:终态版本记录存在且未被顶掉,或 finalize 阶段已成功。
+func needsFinalizeOnly(job governance.LibraryJob, versions []governance.LibraryVersion) bool {
+ if job.TargetSnapshotID == "" {
+ return false
+ }
+ for _, stage := range job.Stages {
+ if stage.Stage == "finalize" && stage.State == "succeeded" {
+ return true
+ }
+ }
+ for _, version := range versions {
+ if version.Kind == governance.LibraryVersionProductionEffective && version.SupersededAt == nil &&
+ version.SnapshotID == job.TargetSnapshotID {
+ return true
+ }
+ }
+ return false
+}
+
+var _ libraryMaintenanceStore = (*postgresstore.Store)(nil)
diff --git a/cmd/worker/library_finish_test.go b/cmd/worker/library_finish_test.go
new file mode 100644
index 0000000..29d797c
--- /dev/null
+++ b/cmd/worker/library_finish_test.go
@@ -0,0 +1,149 @@
+package main
+
+import (
+ "context"
+ "errors"
+ "strings"
+ "testing"
+ "time"
+
+ "knowledge-governance/internal/governance"
+)
+
+type fakeFinishStore struct {
+ calls []string
+ failOn string
+ advanced []governance.LibraryJobState
+}
+
+func (f *fakeFinishStore) record(name string) error {
+ f.calls = append(f.calls, name)
+ if f.failOn == name {
+ return errors.New("injected " + name + " failure")
+ }
+ return nil
+}
+
+func (f *fakeFinishStore) SetInstanceMaintenanceIngress(context.Context, string, string, string, string, time.Time) error {
+ return f.record("instance_ingress")
+}
+func (f *fakeFinishStore) SetLibraryMaintenanceIngress(context.Context, string, string, string, string, time.Time) error {
+ return f.record("scope_ingress")
+}
+func (f *fakeFinishStore) UpdateInstanceMaintenanceState(context.Context, string, string, string, string, time.Time) error {
+ return f.record("instance_state")
+}
+func (f *fakeFinishStore) UpdateLibraryMaintenanceState(context.Context, string, string, string, string, time.Time) error {
+ return f.record("scope_state")
+}
+func (f *fakeFinishStore) ReleaseInstanceMaintenance(context.Context, string, string, time.Time) error {
+ return f.record("instance_release")
+}
+func (f *fakeFinishStore) ReleaseLibraryMaintenance(context.Context, string, string, time.Time) error {
+ return f.record("scope_release")
+}
+func (f *fakeFinishStore) AdvanceLibraryJob(_ context.Context, _ string, state governance.LibraryJobState,
+ _, _, _, _, _ string, _ time.Time) error {
+ f.advanced = append(f.advanced, state)
+ return f.record("advance_" + string(state))
+}
+
+type fakeHealth struct{ err error }
+
+func (h fakeHealth) VerifyRunning(context.Context) error { return h.err }
+
+func boundary() successBoundary {
+ return successBoundary{Ready: true, Backup: "backup-1", Target: "snap-1", FinishedAt: time.Now().UTC()}
+}
+
+// 首次观察到成功时,两把维护锁必须已经释放,且终态写入排在最后。
+func TestFinishLibrarySuccessReleasesEveryLockBeforeSucceeded(t *testing.T) {
+ store := &fakeFinishStore{}
+ if err := finishLibrarySuccess(context.Background(), store, fakeHealth{}, "kgseal-weknora", "internal", "job-1", boundary()); err != nil {
+ t.Fatal(err)
+ }
+ want := []string{"scope_ingress", "instance_ingress", "scope_state", "scope_release",
+ "instance_state", "instance_release", "advance_succeeded"}
+ if strings.Join(store.calls, ",") != strings.Join(want, ",") {
+ t.Fatalf("call order = %v", store.calls)
+ }
+ if len(store.advanced) != 1 || store.advanced[0] != governance.LibraryJobSucceeded {
+ t.Fatalf("advanced = %v", store.advanced)
+ }
+}
+
+// 目标服务/入口没恢复健康:不许放锁,不许报成功,作业落成失败并保持维护。
+func TestFinishLibrarySuccessKeepsMaintenanceWhenTargetIsNotHealthy(t *testing.T) {
+ store := &fakeFinishStore{}
+ err := finishLibrarySuccess(context.Background(), store, fakeHealth{err: errors.New("app not healthy")},
+ "kgseal-weknora", "internal", "job-2", boundary())
+ if err == nil || !strings.Contains(err.Error(), "未恢复健康") {
+ t.Fatalf("err = %v", err)
+ }
+ for _, call := range store.calls {
+ if strings.HasSuffix(call, "_release") || call == "advance_succeeded" {
+ t.Fatalf("released or reported success despite unhealthy target: %v", store.calls)
+ }
+ }
+ if len(store.advanced) != 1 || store.advanced[0] != governance.LibraryJobFailed {
+ t.Fatalf("advanced = %v", store.advanced)
+ }
+}
+
+// 任一步释放失败:不报成功,作业失败,维护状态写 needs_restore(等人工/接管)。
+func TestFinishLibrarySuccessStopsOnReleaseFailure(t *testing.T) {
+ for _, step := range []string{"scope_release", "instance_state", "instance_release"} {
+ t.Run(step, func(t *testing.T) {
+ store := &fakeFinishStore{failOn: step}
+ err := finishLibrarySuccess(context.Background(), store, fakeHealth{}, "kgseal-weknora", "internal", "job-3", boundary())
+ if err == nil {
+ t.Fatalf("%s failure was swallowed", step)
+ }
+ for _, call := range store.calls {
+ if call == "advance_succeeded" {
+ t.Fatalf("reported success after %s failed: %v", step, store.calls)
+ }
+ }
+ if len(store.advanced) != 1 || store.advanced[0] != governance.LibraryJobFailed {
+ t.Fatalf("advanced = %v", store.advanced)
+ }
+ })
+ }
+}
+
+// 终态写入失败:锁已释放,但不能声称成功;作业保持非终态等接管。
+func TestFinishLibrarySuccessReportsTerminalWriteFailure(t *testing.T) {
+ store := &fakeFinishStore{failOn: "advance_succeeded"}
+ err := finishLibrarySuccess(context.Background(), store, fakeHealth{}, "kgseal-weknora", "internal", "job-4", boundary())
+ if err == nil || !strings.Contains(err.Error(), "等待接管") {
+ t.Fatalf("err = %v", err)
+ }
+}
+
+// 接管判定只认证据:finalize 阶段成功或存在未被顶掉的生效版本。
+func TestNeedsFinalizeOnlyUsesRealEvidence(t *testing.T) {
+ job := governance.LibraryJob{Scope: "internal", Kind: governance.LibraryJobSync, TargetSnapshotID: "snap-1"}
+ if needsFinalizeOnly(job, nil) {
+ t.Fatal("job without evidence treated as finalized")
+ }
+ withStage := job
+ withStage.Stages = []governance.LibraryStage{{Stage: "finalize", State: "succeeded"}}
+ if !needsFinalizeOnly(withStage, nil) {
+ t.Fatal("finalize stage ignored")
+ }
+ versions := []governance.LibraryVersion{{Kind: governance.LibraryVersionProductionEffective, SnapshotID: "snap-1"}}
+ if !needsFinalizeOnly(job, versions) {
+ t.Fatal("effective version ignored")
+ }
+ superseded := []governance.LibraryVersion{{Kind: governance.LibraryVersionProductionEffective,
+ SnapshotID: "snap-1", SupersededAt: ptrTime(time.Now())}}
+ if needsFinalizeOnly(job, superseded) {
+ t.Fatal("superseded version treated as evidence")
+ }
+ other := []governance.LibraryVersion{{Kind: governance.LibraryVersionProductionEffective, SnapshotID: "snap-2"}}
+ if needsFinalizeOnly(job, other) {
+ t.Fatal("version of another snapshot treated as evidence")
+ }
+}
+
+func ptrTime(value time.Time) *time.Time { return &value }
diff --git a/cmd/worker/library_handlers.go b/cmd/worker/library_handlers.go
index bdb3973..e256eae 100644
--- a/cmd/worker/library_handlers.go
+++ b/cmd/worker/library_handlers.go
@@ -117,6 +117,13 @@ func runLibraryRelease(ctx context.Context, store *postgresstore.Store, config a
// 绝不重新备份——重新备份会把"半写状态"当成新基线,覆盖真正可回滚的那份。
previous, err := store.LibraryJob(ctx, payload.LibraryJobID)
resumed := err == nil && previous.SnapshotID != ""
+ if resumed {
+ // 上次可能死在"锁已放、终态没写"之间:这种情况下只复核与登记,不重写生产。
+ if versions, versionErr := store.LibraryVersions(ctx, payload.Scope, 50); versionErr == nil &&
+ needsFinalizeOnly(previous, versions) {
+ payload.FinalizeOnly = true
+ }
+ }
if resumed {
recorder.Stage(ctx, "prebackup", "skipped", "接管失败前已创建的预备份 "+previous.SnapshotID)
}
@@ -257,6 +264,7 @@ func runLibraryRelease(ctx context.Context, store *postgresstore.Store, config a
if resumed {
contentState = contentHalfWritten
}
+ pending := successBoundary{}
tracked := &contentTrackedTarget{inner: target, onApply: func() { contentState = contentHalfWritten }}
allowRestore := func(error) bool {
return contentState == contentUntouched || contentState == contentSucceeded || contentState == contentRolledBack
@@ -291,8 +299,9 @@ func runLibraryRelease(ctx context.Context, store *postgresstore.Store, config a
return errors.New(message)
}
recorder.Stage(ctx, "finalize", "succeeded", "已登记生效版本(仅收尾,未重写生产)")
- _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobSucceeded, "finalize", "", "",
- previous.SnapshotID, payload.TargetSnapshotID, time.Now().UTC())
+ // 成功要等维护锁释放完才暴露:这里只记"待收尾"。
+ pending = successBoundary{Ready: true, Backup: previous.SnapshotID,
+ Target: payload.TargetSnapshotID, FinishedAt: time.Now().UTC()}
return nil
}
@@ -341,13 +350,10 @@ func runLibraryRelease(ctx context.Context, store *postgresstore.Store, config a
return errors.New(message)
}
recorder.Stage(ctx, "finalize", "succeeded", "已登记生效版本")
- if advanceErr := store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobSucceeded, "finalize", "", "",
- outcome.Backup.SnapshotID, payload.TargetSnapshotID, finishedAt); advanceErr != nil {
- // 状态落不下去时不要把队列作业报成功:让上层可见并等待接管。
- return fmt.Errorf("作业状态写入失败: %w", advanceErr)
- }
- log.Printf("library %s succeeded job=%s scope=%s snapshot=%s backup=%s", kind,
- payload.LibraryJobID, payload.Scope, payload.TargetSnapshotID, outcome.Backup.SnapshotID)
+ // 内容与版本都落定了,但还不能报成功:服务健康、入口开放、两把维护锁
+ // 释放完成才允许暴露 succeeded(见 finishLibrarySuccess)。
+ pending = successBoundary{Ready: true, Backup: outcome.Backup.SnapshotID,
+ Target: payload.TargetSnapshotID, FinishedAt: finishedAt}
return nil
case "rolled_back":
contentState = contentRolledBack
@@ -408,10 +414,19 @@ func runLibraryRelease(ctx context.Context, store *postgresstore.Store, config a
}
return windowErr
case contentState == contentSucceeded:
- if err := releaseWindowLocks(ctx, store, identity.Instance, payload.Scope, payload.LibraryJobID,
- "写入与校验完成,目标已按原运行状态恢复", now2); err != nil {
- return fmt.Errorf("目标已恢复但维护占用释放失败: %w", err)
+ if !pending.Ready {
+ // 内容状态说成功但没有收尾凭据(不可能两者都缺):按未收尾处理,保持维护。
+ note := "内容状态为已验证,但缺少收尾凭据,目标保持维护"
+ _ = store.UpdateLibraryMaintenanceState(ctx, payload.Scope, payload.LibraryJobID, "needs_restore", note, now2)
+ _ = store.UpdateInstanceMaintenanceState(ctx, identity.Instance, payload.LibraryJobID, "needs_restore", note, now2)
+ return errors.New(note)
}
+ if finishErr := finishLibrarySuccess(ctx, store, manager, identity.Instance, payload.Scope,
+ payload.LibraryJobID, pending); finishErr != nil {
+ return finishErr
+ }
+ log.Printf("library %s succeeded job=%s scope=%s snapshot=%s backup=%s", kind,
+ payload.LibraryJobID, payload.Scope, payload.TargetSnapshotID, pending.Backup)
return windowErr
case contentState == contentRolledBack:
if err := releaseWindowLocks(ctx, store, identity.Instance, payload.Scope, payload.LibraryJobID,
@@ -429,19 +444,6 @@ func runLibraryRelease(ctx context.Context, store *postgresstore.Store, config a
}
}
-// releaseWindowLocks 是唯一释放路径:先记录入口已恢复,再放 scope 行与实例锁。
-// 顺序反过来会出现"实例锁放了、scope 还挂着"的中间态,页面就会说正在维护。
-func releaseWindowLocks(ctx context.Context, store *postgresstore.Store, instance, scope, jobID, note string, now time.Time) error {
- _ = store.SetInstanceMaintenanceIngress(ctx, instance, jobID, "open", note, now)
- _ = store.SetLibraryMaintenanceIngress(ctx, scope, jobID, "open", note, now)
- _ = store.UpdateInstanceMaintenanceState(ctx, instance, jobID, "verified", note, now)
- _ = store.UpdateLibraryMaintenanceState(ctx, scope, jobID, "verified", note, now)
- if err := store.ReleaseInstanceMaintenance(ctx, instance, jobID, now); err != nil {
- return err
- }
- return store.ReleaseLibraryMaintenance(ctx, scope, jobID, now)
-}
-
// resumeInterruptedLibraryJobs 在 worker 启动时接管中断的写作业:
// 已经持久化预备份的重新排队(同一个业务作业 id,阶段与备份都接着用),
// 连预备份都没完成的才判失败——那种情况没有可回滚的基线,不能盲写。
--
2.52.0
From 691e4e0225b8b2b861be80a58a134158c81603ee Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 14:07:35 +0800
Subject: [PATCH 37/45] =?UTF-8?q?docs:=20=E5=8F=B0=E8=B4=A6=E8=A1=A5?=
=?UTF-8?q?=E8=AE=B0=200.1.195=E2=80=930.1.197?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
记录 R1 身份契约、封存资源诊断与 R4 成功边界三个提交的真实 SHA 与 CI run,
标明候选栈 clean 构建(vcs.modified=false)与真实验收覆盖范围。
---
docs/release-ledger.md | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/docs/release-ledger.md b/docs/release-ledger.md
index 3dddf55..4d628d8 100644
--- a/docs/release-ledger.md
+++ b/docs/release-ledger.md
@@ -93,6 +93,10 @@ run164 因 qawemail 依赖外网 DNS 失败,已修,不涂改。
| 0.1.191 | 18276d0 | 文档:验收口径按用户决定收窄(V03-a 移出范围)、矩阵补执行器证据 | 229 | **success**(同上) | 否(只改文档) |
| 0.1.192 | 4c79052 | 测试 DSN 拼接构造(密钥扫描误报修复,语义不变) | 229 | **success**(head 4c79052,必需 context `build / build (push)` = success) | 否(只改测试) |
+| 0.1.195 | 6ed0635 | 期望执行器身份随 capture 请求送达并在执行前核对(TOCTOU) | 233 | **success**(head c14dd01 之前的 run 232/233 连续绿;最终以 8d2ed8e/run234 为准) | 是(候选栈) |
+| 0.1.196 | c14dd01 | 封存读资源失败带资源行与底层原因 | 233 | **success**(run 233 / run_number 210,head c14dd01,必需 context success) | 是(候选栈,clean 构建 `vcs.modified=false`) |
+| 0.1.197 | 8d2ed8e | 维护释放与服务恢复完成后才暴露作业成功(R4) | 234 | **success**(run 234 / run_number 211,head 8d2ed8e,必需 context success) | 是(候选栈,clean 构建 `vcs.modified=false`;真实封存→同步→恢复与"成功后立即恢复 202"均在该构建上跑过) |
+
这批提交的候选栈验证:候选 api/worker/libraryagent/libraryctl 由该工作树重新构建(`vcs.modified=true`,
不是发布产物),二进制 sha256 记在 `$TMPDIR/kg-candidate-verify/evidence/01-binaries.json`;
旧二进制整目录备份在该目录下的 `bin-prev-*`,可一条命令回退。真实观测证据见
--
2.52.0
From 24d2546cbb99e2d5d1d8e126a1bf5d06af9ee457 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 14:24:12 +0800
Subject: [PATCH 38/45] =?UTF-8?q?fix(library):=20=E6=8E=A5=E7=AE=A1?=
=?UTF-8?q?=E4=B8=8D=E5=86=8D=E6=8A=8A=E7=89=88=E6=9C=AC=E6=9F=A5=E8=AF=A2?=
=?UTF-8?q?=E5=A4=B1=E8=B4=A5=E5=BD=93=E6=88=90=E6=B2=A1=E6=9C=89=E6=94=B6?=
=?UTF-8?q?=E5=B0=BE=E8=AF=81=E6=8D=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
resumed 分支里 LibraryVersions 的错误被忽略,FinalizeOnly 保持 false 后继续完整
apply:对"已登记版本并释放窗口、只差终态"的作业,这等于把同一份内容重写一遍目标,
与"最终只复核"的承诺相反。
现在接管先分类:finalize 阶段成功作为独立证据(不受版本查询影响)→ 只收尾;查询
失败且无阶段证据 → 未知,零写入、可重试;本快照被别的快照顶替 → 拒绝覆盖;其余才
按正常流程。
同时修释放幂等:Update*/Release* 对"已由本作业释放"的行返回 ErrMaintenanceReleased,
收尾重试视为已完成(部分释放后不会永久卡死),别的作业仍报未持有。真 PG 负例验证
两种情形。
---
CHANGELOG.md | 8 ++
cmd/worker/library_finish.go | 72 +++++++++---
cmd/worker/library_finish_test.go | 106 ++++++++++++++----
cmd/worker/library_handlers.go | 14 ++-
.../postgres/library_instance_maintenance.go | 9 ++
.../platform/postgres/library_maintenance.go | 22 ++++
6 files changed, 188 insertions(+), 43 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a976945..49dd5a6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -38,6 +38,14 @@
### Fixed
+- **接管在版本查询失败时 fail-open**:`resumed` 后版本查询出错被忽略、`FinalizeOnly` 仍为
+ false,于是"已成功登记并释放窗口、只差终态"的作业会被**重新写一遍目标**。现在接管先按
+ 证据分类:`finalize` 阶段成功是独立证据(不受版本查询影响);查询失败且无阶段证据 ⇒
+ **未知**,零写入、作业失败可重试;本快照的生效版本已被别的快照顶替 ⇒ **拒绝覆盖**;
+ 只有真正没有收尾证据时才按正常流程。
+- **维护释放部分成功后的重试不再永久卡死**:`Update*/Release*` 对"已由本作业释放"的行
+ 返回可判别的 `ErrMaintenanceReleased`,收尾重试视其为已完成;别的作业来释放仍是
+ "未持有"错误。真 PG 负例:同作业重复 Update/Release 得到已释放,跨作业得到未持有。
- **作业成功暴露早于维护结束**:原来 `execute` 里写完生效版本就 `AdvanceLibraryJob(succeeded)`,
而服务恢复、入口开放与维护锁释放要在窗口返回后才做。任何一步失败时外部已经看到
`succeeded`,重启接管又只认非终态,锁就永远挂着。现在内容校验/版本登记之后只记
diff --git a/cmd/worker/library_finish.go b/cmd/worker/library_finish.go
index 0b1628c..e8ba1eb 100644
--- a/cmd/worker/library_finish.go
+++ b/cmd/worker/library_finish.go
@@ -28,22 +28,22 @@ type libraryMaintenanceStore interface {
// 才能保证任何新作业在全部记录落定之前都进不来。每一步的错误都必须向上暴露——
// 只丢日志会让"锁其实没放"这件事变成页面上的成功。
func releaseWindowLocks(ctx context.Context, store libraryMaintenanceStore, instance, scope, jobID, note string, now time.Time) error {
- if err := store.SetLibraryMaintenanceIngress(ctx, scope, jobID, "open", note, now); err != nil {
+ if err := store.SetLibraryMaintenanceIngress(ctx, scope, jobID, "open", note, now); !releasedOrNil(err) {
return fmt.Errorf("记录入口已开放失败(scope):%w", err)
}
- if err := store.SetInstanceMaintenanceIngress(ctx, instance, jobID, "open", note, now); err != nil {
+ if err := store.SetInstanceMaintenanceIngress(ctx, instance, jobID, "open", note, now); !releasedOrNil(err) {
return fmt.Errorf("记录入口已开放失败(instance):%w", err)
}
- if err := store.UpdateLibraryMaintenanceState(ctx, scope, jobID, "verified", note, now); err != nil {
+ if err := store.UpdateLibraryMaintenanceState(ctx, scope, jobID, "verified", note, now); !releasedOrNil(err) {
return fmt.Errorf("维护状态写入失败(scope):%w", err)
}
- if err := store.ReleaseLibraryMaintenance(ctx, scope, jobID, now); err != nil {
+ if err := store.ReleaseLibraryMaintenance(ctx, scope, jobID, now); !releasedOrNil(err) {
return fmt.Errorf("维护占用释放失败(scope):%w", err)
}
- if err := store.UpdateInstanceMaintenanceState(ctx, instance, jobID, "verified", note, now); err != nil {
+ if err := store.UpdateInstanceMaintenanceState(ctx, instance, jobID, "verified", note, now); !releasedOrNil(err) {
return fmt.Errorf("维护状态写入失败(instance):%w", err)
}
- if err := store.ReleaseInstanceMaintenance(ctx, instance, jobID, now); err != nil {
+ if err := store.ReleaseInstanceMaintenance(ctx, instance, jobID, now); !releasedOrNil(err) {
return fmt.Errorf("实例占用释放失败(instance):%w", err)
}
return nil
@@ -101,24 +101,62 @@ func finishLibrarySuccess(ctx context.Context, store libraryMaintenanceStore, he
return nil
}
-// needsFinalizeOnly 判断一个被接管的作业是否"内容与版本都已落定、只差收尾"。
-// 判据只认真实证据:终态版本记录存在且未被顶掉,或 finalize 阶段已成功。
-func needsFinalizeOnly(job governance.LibraryJob, versions []governance.LibraryVersion) bool {
- if job.TargetSnapshotID == "" {
- return false
- }
+// takeoverKind 是接管时"这个作业走到哪一步"的分类。
+//
+// 四类必须分开:把"版本查不到"当成"没有收尾证据",就会把只差收尾的作业重新写一遍
+// 目标;把"曾被顶替"当成正常重放,就会用旧快照覆盖更新的生产版本。
+type takeoverKind string
+
+const (
+ // takeoverFresh:没有任何收尾证据,按正常流程(有预备份则复用,写前仍备份)。
+ takeoverFresh takeoverKind = "fresh"
+ // takeoverPendingFinal:内容与版本已落定,只差收尾(只复核与登记,不重写)。
+ takeoverPendingFinal takeoverKind = "pending_final"
+ // takeoverSuperseded:本快照曾经生效、后来被别的快照顶替,不得自动覆盖。
+ takeoverSuperseded takeoverKind = "superseded"
+ // takeoverUnknown:版本状态读不到且没有阶段证据,属"未知",不得写入。
+ takeoverUnknown takeoverKind = "unknown"
+)
+
+// classifyTakeover 只按证据分类:
+// - finalize 阶段成功是独立证据(来自作业自己的阶段行),不因版本查询失败而丢弃;
+// - 本快照存在 released/被顶替的版本 ⇒ superseded;
+// - 本快照存在未被顶掉的生效版本 ⇒ pending_final;
+// - 查询失败且无阶段证据 ⇒ unknown(可重试,不当成没有证据)。
+func classifyTakeover(job governance.LibraryJob, versions []governance.LibraryVersion, versionsErr error) takeoverKind {
+ finalized := false
for _, stage := range job.Stages {
if stage.Stage == "finalize" && stage.State == "succeeded" {
- return true
+ finalized = true
}
}
+ if versionsErr != nil && !finalized {
+ return takeoverUnknown
+ }
+ superseded, effective := false, false
for _, version := range versions {
- if version.Kind == governance.LibraryVersionProductionEffective && version.SupersededAt == nil &&
- version.SnapshotID == job.TargetSnapshotID {
- return true
+ if version.Kind != governance.LibraryVersionProductionEffective || version.SnapshotID != job.TargetSnapshotID {
+ continue
+ }
+ if version.SupersededAt != nil {
+ superseded = true
+ } else {
+ effective = true
}
}
- return false
+ if superseded && !effective {
+ return takeoverSuperseded
+ }
+ if effective || finalized {
+ return takeoverPendingFinal
+ }
+ return takeoverFresh
}
var _ libraryMaintenanceStore = (*postgresstore.Store)(nil)
+
+// releasedOrNil:这一行已经由本作业释放过,说明该步在上一次尝试里已经完成。
+// 部分成功后重试幂等靠它——否则"scope 放了、instance 没放"的作业永远重试不下去。
+func releasedOrNil(err error) bool {
+ return err == nil || errors.Is(err, postgresstore.ErrMaintenanceReleased)
+}
diff --git a/cmd/worker/library_finish_test.go b/cmd/worker/library_finish_test.go
index 29d797c..08eca3c 100644
--- a/cmd/worker/library_finish_test.go
+++ b/cmd/worker/library_finish_test.go
@@ -8,12 +8,22 @@ import (
"time"
"knowledge-governance/internal/governance"
+ postgresstore "knowledge-governance/internal/platform/postgres"
)
type fakeFinishStore struct {
- calls []string
- failOn string
- advanced []governance.LibraryJobState
+ calls []string
+ failOn string
+ alreadyReleased bool
+ advanced []governance.LibraryJobState
+}
+
+// 模拟"这一行已由同一个作业释放过"(真实 Store 返回 ErrMaintenanceReleased)。
+func (f *fakeFinishStore) releasedSentinel() error {
+ if f.alreadyReleased {
+ return postgresstore.ErrMaintenanceReleased
+ }
+ return nil
}
func (f *fakeFinishStore) record(name string) error {
@@ -25,21 +35,39 @@ func (f *fakeFinishStore) record(name string) error {
}
func (f *fakeFinishStore) SetInstanceMaintenanceIngress(context.Context, string, string, string, string, time.Time) error {
+ if err := f.releasedSentinel(); err != nil {
+ return err
+ }
return f.record("instance_ingress")
}
func (f *fakeFinishStore) SetLibraryMaintenanceIngress(context.Context, string, string, string, string, time.Time) error {
+ if err := f.releasedSentinel(); err != nil {
+ return err
+ }
return f.record("scope_ingress")
}
func (f *fakeFinishStore) UpdateInstanceMaintenanceState(context.Context, string, string, string, string, time.Time) error {
+ if err := f.releasedSentinel(); err != nil {
+ return err
+ }
return f.record("instance_state")
}
func (f *fakeFinishStore) UpdateLibraryMaintenanceState(context.Context, string, string, string, string, time.Time) error {
+ if err := f.releasedSentinel(); err != nil {
+ return err
+ }
return f.record("scope_state")
}
func (f *fakeFinishStore) ReleaseInstanceMaintenance(context.Context, string, string, time.Time) error {
+ if err := f.releasedSentinel(); err != nil {
+ return err
+ }
return f.record("instance_release")
}
func (f *fakeFinishStore) ReleaseLibraryMaintenance(context.Context, string, string, time.Time) error {
+ if err := f.releasedSentinel(); err != nil {
+ return err
+ }
return f.record("scope_release")
}
func (f *fakeFinishStore) AdvanceLibraryJob(_ context.Context, _ string, state governance.LibraryJobState,
@@ -120,29 +148,61 @@ func TestFinishLibrarySuccessReportsTerminalWriteFailure(t *testing.T) {
}
}
-// 接管判定只认证据:finalize 阶段成功或存在未被顶掉的生效版本。
-func TestNeedsFinalizeOnlyUsesRealEvidence(t *testing.T) {
+// 接管分类:阶段证据独立成立;查询失败=未知(不得写入);被顶替=不得覆盖。
+func TestClassifyTakeoverSeparatesUnknownPendingSupersededAndFresh(t *testing.T) {
job := governance.LibraryJob{Scope: "internal", Kind: governance.LibraryJobSync, TargetSnapshotID: "snap-1"}
- if needsFinalizeOnly(job, nil) {
- t.Fatal("job without evidence treated as finalized")
- }
- withStage := job
- withStage.Stages = []governance.LibraryStage{{Stage: "finalize", State: "succeeded"}}
- if !needsFinalizeOnly(withStage, nil) {
- t.Fatal("finalize stage ignored")
- }
- versions := []governance.LibraryVersion{{Kind: governance.LibraryVersionProductionEffective, SnapshotID: "snap-1"}}
- if !needsFinalizeOnly(job, versions) {
- t.Fatal("effective version ignored")
- }
- superseded := []governance.LibraryVersion{{Kind: governance.LibraryVersionProductionEffective,
+ finalized := job
+ finalized.Stages = []governance.LibraryStage{{Stage: "finalize", State: "succeeded"}}
+ effective := []governance.LibraryVersion{{Kind: governance.LibraryVersionProductionEffective, SnapshotID: "snap-1"}}
+ supersededVersion := []governance.LibraryVersion{{Kind: governance.LibraryVersionProductionEffective,
SnapshotID: "snap-1", SupersededAt: ptrTime(time.Now())}}
- if needsFinalizeOnly(job, superseded) {
- t.Fatal("superseded version treated as evidence")
+ unrelated := []governance.LibraryVersion{{Kind: governance.LibraryVersionProductionEffective, SnapshotID: "snap-9"}}
+ queryErr := errors.New("version storage temporarily unavailable")
+
+ cases := []struct {
+ name string
+ job governance.LibraryJob
+ versions []governance.LibraryVersion
+ err error
+ want takeoverKind
+ }{
+ // 关键回归:查询失败 + 没有阶段证据 ⇒ 未知,不能当成"没有收尾证据"继续写。
+ {"query fails without stage evidence", job, nil, queryErr, takeoverUnknown},
+ // 阶段证据先独立成立:查询失败不影响"只差收尾"的判定。
+ {"query fails but finalize stage succeeded", finalized, nil, queryErr, takeoverPendingFinal},
+ {"effective version for this snapshot", job, effective, nil, takeoverPendingFinal},
+ {"finalize stage succeeded", finalized, nil, nil, takeoverPendingFinal},
+ {"this snapshot was superseded", job, supersededVersion, nil, takeoverSuperseded},
+ {"no evidence at all", job, nil, nil, takeoverFresh},
+ {"another snapshot effective but this one has no row", job, unrelated, nil, takeoverFresh},
+ {"empty target snapshot", governance.LibraryJob{Scope: "internal"}, nil, nil, takeoverFresh},
}
- other := []governance.LibraryVersion{{Kind: governance.LibraryVersionProductionEffective, SnapshotID: "snap-2"}}
- if needsFinalizeOnly(job, other) {
- t.Fatal("version of another snapshot treated as evidence")
+ for _, test := range cases {
+ t.Run(test.name, func(t *testing.T) {
+ if got := classifyTakeover(test.job, test.versions, test.err); got != test.want {
+ t.Fatalf("classify = %q, want %q", got, test.want)
+ }
+ })
+ }
+}
+
+// 部分释放后重试必须幂等:已由本作业释放的行不能再算失败。
+func TestReleaseWindowLocksToleratesAlreadyReleasedRows(t *testing.T) {
+ store := &fakeFinishStore{}
+ if err := releaseWindowLocks(context.Background(), store, "kgseal-weknora", "internal", "job-1",
+ "verified", time.Now().UTC()); err != nil {
+ t.Fatal(err)
+ }
+ store = &fakeFinishStore{alreadyReleased: true}
+ if err := releaseWindowLocks(context.Background(), store, "kgseal-weknora", "internal", "job-1",
+ "verified", time.Now().UTC()); err != nil {
+ t.Fatalf("retry after a partial release must be idempotent: %v", err)
+ }
+ // 真正"不是本作业持有"的错误仍然要暴露。
+ store = &fakeFinishStore{failOn: "instance_release"}
+ if err := releaseWindowLocks(context.Background(), store, "kgseal-weknora", "internal", "job-1",
+ "verified", time.Now().UTC()); err == nil {
+ t.Fatal("a foreign owner error was swallowed")
}
}
diff --git a/cmd/worker/library_handlers.go b/cmd/worker/library_handlers.go
index e256eae..331c6eb 100644
--- a/cmd/worker/library_handlers.go
+++ b/cmd/worker/library_handlers.go
@@ -118,9 +118,17 @@ func runLibraryRelease(ctx context.Context, store *postgresstore.Store, config a
previous, err := store.LibraryJob(ctx, payload.LibraryJobID)
resumed := err == nil && previous.SnapshotID != ""
if resumed {
- // 上次可能死在"锁已放、终态没写"之间:这种情况下只复核与登记,不重写生产。
- if versions, versionErr := store.LibraryVersions(ctx, payload.Scope, 50); versionErr == nil &&
- needsFinalizeOnly(previous, versions) {
+ versions, versionErr := store.LibraryVersions(ctx, payload.Scope, 50)
+ switch classifyTakeover(previous, versions, versionErr) {
+ case takeoverUnknown:
+ // 版本状态读不到、又没有阶段证据:不能当成"没有收尾证据"继续写目标。
+ return failLibraryJob(ctx, store, recorder, payload.LibraryJobID,
+ "接管时读不到该目标的版本状态,无法判断是只差收尾还是要重做;未对目标执行任何写入,稍后重试", "prebackup")
+ case takeoverSuperseded:
+ return failLibraryJob(ctx, store, recorder, payload.LibraryJobID,
+ "本快照的生效版本已被别的快照顶替,拒绝用旧快照覆盖当前生产版本", "prebackup")
+ case takeoverPendingFinal:
+ // 上次可能死在"锁已放、终态没写"之间:只复核与登记,不重写生产。
payload.FinalizeOnly = true
}
}
diff --git a/internal/platform/postgres/library_instance_maintenance.go b/internal/platform/postgres/library_instance_maintenance.go
index 6a6b468..6223b44 100644
--- a/internal/platform/postgres/library_instance_maintenance.go
+++ b/internal/platform/postgres/library_instance_maintenance.go
@@ -92,6 +92,9 @@ WHERE instance=$1 AND owner_job_id=$2 AND released_at IS NULL`, instance, ownerJ
return fmt.Errorf("update instance maintenance: %w", err)
}
if tag.RowsAffected() == 0 {
+ if s.releasedByThisJob(ctx, "library_instance_maintenance", "instance", instance, ownerJobID) {
+ return ErrMaintenanceReleased
+ }
return errors.New("instance maintenance not held by this job")
}
return nil
@@ -108,6 +111,9 @@ WHERE instance=$1 AND owner_job_id=$2 AND released_at IS NULL`, instance, ownerJ
return fmt.Errorf("update instance maintenance ingress: %w", err)
}
if tag.RowsAffected() == 0 {
+ if s.releasedByThisJob(ctx, "library_instance_maintenance", "instance", instance, ownerJobID) {
+ return ErrMaintenanceReleased
+ }
return errors.New("instance maintenance not held by this job")
}
return nil
@@ -121,6 +127,9 @@ WHERE instance=$1 AND owner_job_id=$2 AND released_at IS NULL`, instance, ownerJ
return fmt.Errorf("release instance maintenance: %w", err)
}
if tag.RowsAffected() == 0 {
+ if s.releasedByThisJob(ctx, "library_instance_maintenance", "instance", instance, ownerJobID) {
+ return ErrMaintenanceReleased
+ }
return errors.New("instance maintenance not held by this job")
}
return nil
diff --git a/internal/platform/postgres/library_maintenance.go b/internal/platform/postgres/library_maintenance.go
index 27d6a34..62eca4a 100644
--- a/internal/platform/postgres/library_maintenance.go
+++ b/internal/platform/postgres/library_maintenance.go
@@ -10,6 +10,19 @@ import (
"github.com/jackc/pgx/v5"
)
+var ErrMaintenanceReleased = errors.New("maintenance already released by this job")
+
+// releasedByThisJob 判断"零行更新"是因为本作业已经释放过,还是根本没持有。
+func (s *Store) releasedByThisJob(ctx context.Context, table, keyColumn, key, ownerJobID string) bool {
+ var owner string
+ var released *time.Time
+ query := "SELECT owner_job_id, released_at FROM " + table + " WHERE " + keyColumn + "=$1"
+ if err := s.db.QueryRow(ctx, query, key).Scan(&owner, &released); err != nil {
+ return false
+ }
+ return owner == ownerJobID && released != nil
+}
+
// LibraryMaintenance 是目标维护窗口的持有记录:一个 scope 只能有一个持有者。
//
// Level 说明这次维护到底动了什么:
@@ -97,6 +110,9 @@ WHERE scope=$1 AND owner_job_id=$2 AND released_at IS NULL`, scope, ownerJobID,
return fmt.Errorf("update library maintenance: %w", err)
}
if tag.RowsAffected() == 0 {
+ if s.releasedByThisJob(ctx, "library_maintenance", "scope", scope, ownerJobID) {
+ return ErrMaintenanceReleased
+ }
return errors.New("library maintenance not held by this job")
}
return nil
@@ -114,6 +130,9 @@ WHERE scope=$1 AND owner_job_id=$2 AND released_at IS NULL`, scope, ownerJobID,
return fmt.Errorf("update library maintenance ingress: %w", err)
}
if tag.RowsAffected() == 0 {
+ if s.releasedByThisJob(ctx, "library_maintenance", "scope", scope, ownerJobID) {
+ return ErrMaintenanceReleased
+ }
return errors.New("library maintenance not held by this job")
}
return nil
@@ -127,6 +146,9 @@ WHERE scope=$1 AND owner_job_id=$2 AND released_at IS NULL`, scope, ownerJobID,
return fmt.Errorf("release library maintenance: %w", err)
}
if tag.RowsAffected() == 0 {
+ if s.releasedByThisJob(ctx, "library_maintenance", "scope", scope, ownerJobID) {
+ return ErrMaintenanceReleased
+ }
return errors.New("library maintenance not held by this job")
}
return nil
--
2.52.0
From 271f9f5f0992d03e409affe0f1fd91326fa33f5e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 14:27:53 +0800
Subject: [PATCH 39/45] =?UTF-8?q?docs:=20=E5=8F=B0=E8=B4=A6=E8=A1=A5?=
=?UTF-8?q?=E8=AE=B0=200.1.198=E2=80=930.1.199?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
记录接管分类与维护释放幂等的真实 SHA、CI run(236)与候选栈身份注入后
/api/v1/build-info 的读回结果。
---
docs/release-ledger.md | 2 ++
1 file changed, 2 insertions(+)
diff --git a/docs/release-ledger.md b/docs/release-ledger.md
index 4d628d8..10e2367 100644
--- a/docs/release-ledger.md
+++ b/docs/release-ledger.md
@@ -97,6 +97,8 @@ run164 因 qawemail 依赖外网 DNS 失败,已修,不涂改。
| 0.1.196 | c14dd01 | 封存读资源失败带资源行与底层原因 | 233 | **success**(run 233 / run_number 210,head c14dd01,必需 context success) | 是(候选栈,clean 构建 `vcs.modified=false`) |
| 0.1.197 | 8d2ed8e | 维护释放与服务恢复完成后才暴露作业成功(R4) | 234 | **success**(run 234 / run_number 211,head 8d2ed8e,必需 context success) | 是(候选栈,clean 构建 `vcs.modified=false`;真实封存→同步→恢复与"成功后立即恢复 202"均在该构建上跑过) |
+| 0.1.198 | 691e4e0 | 台账补记 0.1.195–0.1.197 | 235 | **success**(run 235,head 691e4e0) | 否(文档) |
+| 0.1.199 | 24d2546 | 接管分类(未知/待收尾/被顶替)+ 维护释放幂等 | 236 | **success**(run 236,head 24d2546,必需 context success) | 是(候选栈,`-ldflags` 注入身份;`build-info` 读回 0.1.199 / 24d2546…,进程 `vcs.modified=false`) |
这批提交的候选栈验证:候选 api/worker/libraryagent/libraryctl 由该工作树重新构建(`vcs.modified=true`,
不是发布产物),二进制 sha256 记在 `$TMPDIR/kg-candidate-verify/evidence/01-binaries.json`;
旧二进制整目录备份在该目录下的 `bin-prev-*`,可一条命令回退。真实观测证据见
--
2.52.0
From f9c15a8f14353865258fd1c4bba19c9df5f621df Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 15:24:30 +0800
Subject: [PATCH 40/45] =?UTF-8?q?fix(web):=20=E5=AD=98=E5=82=A8=E6=8F=90?=
=?UTF-8?q?=E7=A4=BA=E6=94=B9=E4=B8=BA=E5=AE=9E=E9=99=85=E8=83=BD=E5=8A=9B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
页面仍写"保留策略与清理在系统设置→存储管理,均未接线",但存储与备份已有只读
去重/保护范围/预览。改为说明可查看什么、什么尚未开放。
---
web/src/ReleaseTargets.tsx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/web/src/ReleaseTargets.tsx b/web/src/ReleaseTargets.tsx
index 32a2a0e..d663dcc 100644
--- a/web/src/ReleaseTargets.tsx
+++ b/web/src/ReleaseTargets.tsx
@@ -1103,7 +1103,7 @@ function Drawer({
归档占用(只读):被版本引用的去重内容 {formatBytes(page?.content_bytes ?? 0)} · 磁盘分配{' '}
{formatBytes(page?.blob_allocated_bytes ?? 0)} · 未被引用 {page?.unreferenced_blobs ?? 0}{' '}
- 个。保留策略与清理在系统设置 → 存储管理,均未接线。
+ 个。清理与保留策略在系统设置 → 存储管理:当前可查看去重与保护范围,删除与保留策略尚未开放。
--
2.52.0
From 517d5f862df92230c494ae3bdeddd06021810a9e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 18:16:21 +0800
Subject: [PATCH 41/45] =?UTF-8?q?feat(library):=20=E9=A6=96=E6=AC=A1?=
=?UTF-8?q?=E5=8F=91=E5=B8=83=E6=8E=A5=E4=B8=8A=E7=9B=AE=E6=A0=87=E6=9D=83?=
=?UTF-8?q?=E5=A8=81=E5=9F=BA=E7=BA=BF=E4=B8=8E=E6=95=B4=E5=BA=93=E7=A9=BA?=
=?UTF-8?q?=E5=88=A4=E5=AE=9A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
目标非空又没有生效版本时,首次发布以前只能停在"权威版本未知"。现在有了
真实入口:管理员发起 baseline 作业,worker 在维护隔离下把目标整库捕获成
归档快照,再用同一套 Verify 证明目标与快照逐类一致,最后登记
production_effective(证据写明 origin=target_baseline、快照 ID、逐表行数、
目标索引映射)。不写目标内容、不清空目标、不手写版本。
同时修两处会误导人的判定:
- productionScopeEmpty 原来只数 knowledges,"文档删了但分块/Wiki/资源还在"
的目标会被当成空库;改用适配层同一份表清单与范围过滤逐表计数。
- 概览里的"测试封存候选"原来取该 scope 最新一份归档,而归档里还有生产
预备份与目标基线快照;改为只认版本登记里 kind=test_sealed 的那一份。
迁移 075 放开 kind='baseline' 并把它并入 sync/restore 的写互斥索引;
worker 重启时用同一作业 id 接管未完成的基线窗口。维护接口补 capability,
页面才能区分"未运行维护"与"维护能力没接线"。
验证:go build ./... / go vet ./... 通过;新增用例覆盖管理员校验、已有生效
版本拒绝、目标读不到时零作业零版本、候选来自登记、缺项文案指向基线入口、
capability 逐项缺失;反向自检(把候选改回按最新归档取、把文案改回旧句、
去掉管理员判断)三项均按预期变红后复原。
---
api/openapi.yaml | 52 ++++
cmd/api/main.go | 6 +
cmd/worker/library_baseline.go | 227 ++++++++++++++++++
cmd/worker/library_handlers.go | 7 +-
cmd/worker/library_wiring.go | 107 +++++++--
cmd/worker/main.go | 7 +
internal/governance/library_flow.go | 10 +
internal/httpapi/library_baseline.go | 150 ++++++++++++
internal/httpapi/library_baseline_test.go | 162 +++++++++++++
internal/httpapi/library_flow.go | 121 ++++++++--
internal/httpapi/server.go | 15 ++
internal/platform/postgres/library_jobs.go | 2 +-
.../000075_library_baseline_kind.down.sql | 8 +
.../000075_library_baseline_kind.up.sql | 12 +
internal/platform/postgres/migrations_test.go | 28 ++-
.../v071/library_scope_probe.go | 46 ++++
16 files changed, 902 insertions(+), 58 deletions(-)
create mode 100644 cmd/worker/library_baseline.go
create mode 100644 internal/httpapi/library_baseline.go
create mode 100644 internal/httpapi/library_baseline_test.go
create mode 100644 internal/platform/postgres/migrations/000075_library_baseline_kind.down.sql
create mode 100644 internal/platform/postgres/migrations/000075_library_baseline_kind.up.sql
create mode 100644 internal/releaseadapter/v071/library_scope_probe.go
diff --git a/api/openapi.yaml b/api/openapi.yaml
index aecfad0..b5d9f3e 100644
--- a/api/openapi.yaml
+++ b/api/openapi.yaml
@@ -1547,6 +1547,58 @@
}
}
},
+ "/api/v1/library/baselines": {
+ "post": {
+ "tags": [
+ "Runtime"
+ ],
+ "operationId": "startLibraryBaseline",
+ "summary": "建立目标权威基线:管理员在维护隔离下把非空目标整库捕获成快照、逐类校验后登记为生效版本;不清空目标、不手写版本",
+ "responses": {
+ "202": {
+ "description": "已创建基线作业(worker 在维护窗口内捕获并校验)"
+ },
+ "400": {
+ "$ref": "#/components/responses/BadRequest"
+ },
+ "403": {
+ "description": "不是管理员"
+ },
+ "409": {
+ "description": "已有生效版本、目标为空、目标正在维护或已有在飞写作业"
+ },
+ "500": {
+ "$ref": "#/components/responses/InternalError"
+ },
+ "503": {
+ "description": "目标整库读不到,不能建立基线(不创建作业、不登记版本)"
+ }
+ },
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "scope"
+ ],
+ "properties": {
+ "scope": {
+ "type": "string",
+ "enum": [
+ "internal",
+ "external"
+ ]
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
"/api/v1/library/snapshots/{id}": {
"get": {
"tags": [
diff --git a/cmd/api/main.go b/cmd/api/main.go
index 0a652f3..163a637 100644
--- a/cmd/api/main.go
+++ b/cmd/api/main.go
@@ -203,6 +203,12 @@ func run(ctx context.Context, getenv func(string) string) error {
VersionHistoryRepo: versionHistoryRepo,
LibraryArchiveRoot: config.LibraryArchiveRoot,
LibraryTargetInstance: config.LibraryTargetInstance,
+ LibraryTargetProject: config.LibraryTargetProject,
+ LibraryTargetWriters: config.LibraryTargetWriters,
+ LibraryTargetIngressURL: config.LibraryTargetIngressURL,
+ LibraryTargetIngressService: config.LibraryTargetIngressService,
+ LibraryTargetDockerSocket: config.LibraryTargetDockerSocket,
+ LibraryTargetJournalRoot: config.LibraryTargetJournalRoot,
LibrarySourceInstance: config.SourceInstance(),
LibrarySourceProject: config.SourceProject(),
LibraryAgentSocket: config.LibraryAgentSocket,
diff --git a/cmd/worker/library_baseline.go b/cmd/worker/library_baseline.go
new file mode 100644
index 0000000..0dab748
--- /dev/null
+++ b/cmd/worker/library_baseline.go
@@ -0,0 +1,227 @@
+package main
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "log"
+ "time"
+
+ "knowledge-governance/internal/appconfig"
+ "knowledge-governance/internal/governance"
+ "knowledge-governance/internal/jobs"
+ "knowledge-governance/internal/libraryfreeze"
+ "knowledge-governance/internal/librarymaintenance"
+ "knowledge-governance/internal/libraryrelease"
+ postgresstore "knowledge-governance/internal/platform/postgres"
+)
+
+// libraryBaselinePayload 是"建立目标权威基线"的队列载荷。
+type libraryBaselinePayload struct {
+ LibraryJobID string `json:"library_job_id"`
+ Scope string `json:"scope"`
+}
+
+// runLibraryBaseline 给"非空但没有权威版本"的目标建立基线。
+//
+// 真实链路:维护隔离(关入口/停写入者/证明排空)→ 把目标整库捕获成归档快照
+// → 用同一套 Verify 证明目标与这份快照逐类一致 → 登记 production_effective。
+// 它不写目标内容、不清空目标、不猜版本:基线只是"目标现在是什么"的忠实记录,
+// 因此失败时重新开放目标永远是安全的(allowRestore 恒 true)。
+func runLibraryBaseline(ctx context.Context, store *postgresstore.Store, config appconfig.Config, job jobs.Job) error {
+ var payload libraryBaselinePayload
+ if err := json.Unmarshal(job.Payload, &payload); err != nil || payload.LibraryJobID == "" ||
+ (payload.Scope != "internal" && payload.Scope != "external") {
+ return errors.New("invalid library baseline payload")
+ }
+ now := time.Now().UTC()
+ recorder := libraryStageRecorder{store: store, jobID: payload.LibraryJobID, scope: payload.Scope}
+ fail := func(message, stage string) error {
+ return failLibraryJob(ctx, store, recorder, payload.LibraryJobID, message, stage)
+ }
+ _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobRunning, "capture", "", "", "", "", now)
+
+ // 已有生效版本时不再建基线:基线只解决"目标非空但无权威版本"的首次发布,
+ // 版本切换必须走同步/恢复(它们有预备份、回滚与授权)。
+ versions, versionErr := store.LibraryVersions(ctx, payload.Scope, 50)
+ if versionErr != nil {
+ return fail("读不到版本记录,无法确认是否需要建立基线;未对目标执行任何操作", "capture")
+ }
+ for _, item := range versions {
+ if item.Kind == governance.LibraryVersionProductionEffective && item.SupersededAt == nil {
+ return fail("该目标已有生效版本 "+item.SnapshotID+",不需要再建基线;换版本请走同步或恢复", "capture")
+ }
+ }
+
+ if !config.ProductionReleaseRequestsEnabled {
+ return fail("生产写入闸口关闭(PRODUCTION_RELEASE_REQUESTS_ENABLED=false):建立基线要动目标运行状态,闸口关闭时不执行", "capture")
+ }
+ target, backups, wireErr := buildLibraryBaselineStack(ctx, config, payload.Scope)
+ if wireErr != nil {
+ return fail(wireErr.Error(), "capture")
+ }
+ defer target.Close()
+
+ manager, managerErr := openLibraryMaintenance(config)
+ if managerErr != nil {
+ return fail("目标维护未接线,拒绝在挡不住入口/后台写入的情况下捕获目标:"+managerErr.Error(), "capture")
+ }
+ defer manager.Close()
+ if topoErr := manager.VerifyTopology(ctx); topoErr != nil {
+ return fail("目标拓扑不满足唯一入口约束,拒绝开维护窗口:"+topoErr.Error(), "capture")
+ }
+ originalState, stateErr := manager.OriginalState(ctx)
+ if stateErr != nil {
+ return fail("读不到目标写入者的原运行状态,不能开维护窗口:"+stateErr.Error(), "capture")
+ }
+ identity := manager.Target()
+ // 实例级占用:internal/external 动的是同一批容器,必须按实例互斥。
+ if _, instanceErr := store.AcquireInstanceMaintenance(ctx, postgresstore.LibraryInstanceMaintenance{
+ Instance: identity.Instance, OwnerJobID: payload.LibraryJobID, OwnerScope: payload.Scope,
+ TargetFingerprint: identity.Fingerprint, Level: librarymaintenance.LevelInstance,
+ Services: identity.Writers, IngressState: "unknown", State: "acquired",
+ OriginalServiceState: originalState,
+ Note: "实例级维护:为建立权威基线捕获目标整库,捕获并校验后按原状态恢复",
+ }, now); instanceErr != nil {
+ return fail("目标实例正在维护中(跨对内/对外互斥):"+instanceErr.Error(), "capture")
+ }
+ if _, acquireErr := store.AcquireLibraryMaintenance(ctx, postgresstore.LibraryMaintenance{
+ Scope: payload.Scope, OwnerJobID: payload.LibraryJobID,
+ TargetIdentity: identity.Fingerprint,
+ Level: "instance",
+ TargetFingerprint: identity.Fingerprint,
+ Services: identity.Writers,
+ IngressState: "unknown",
+ State: "acquired",
+ OriginalServiceState: originalState,
+ Note: "实例级维护:为建立权威基线捕获目标整库,捕获并校验后按原状态恢复",
+ }, now); acquireErr != nil {
+ _ = store.UpdateInstanceMaintenanceState(ctx, identity.Instance, payload.LibraryJobID, "needs_restore",
+ "scope 占用申请失败,实例状态未确认:"+acquireErr.Error(), now)
+ return fail("目标正在维护中:"+acquireErr.Error(), "capture")
+ }
+
+ coordinator, control, openErr := manager.Open(config.LibraryTargetJournalRoot)
+ if openErr != nil {
+ _ = releaseWindowLocks(ctx, store, identity.Instance, payload.Scope, payload.LibraryJobID,
+ "未进入维护窗口(协调器不可用),目标未被停用", time.Now().UTC())
+ return fail("维护协调器不可用:"+openErr.Error(), "capture")
+ }
+ defer control.Close()
+ defer coordinator.Close()
+
+ var baselineID string
+ var counts map[string]int64
+ verified := false
+ work := func(ctx context.Context, window *libraryfreeze.Window) (string, error) {
+ current, currentErr := target.Current(ctx)
+ if currentErr != nil {
+ return "", errors.New("读取目标当前整库状态失败:" + currentErr.Error())
+ }
+ counts = map[string]int64{}
+ for table, count := range current.Counts {
+ counts[table] = count
+ }
+ // 预备份存储在导出后用同一份指纹复核"导出期间内容没变",所以这里
+ // 必须把窗口内读到的 state 交进去,而不是事后再读一次。
+ backup, backupErr := backups.Prepare(ctx, "", current)
+ if backupErr != nil {
+ return "", errors.New("捕获目标整库失败:" + backupErr.Error())
+ }
+ baselineID = backup.SnapshotID
+ // 先把"这次窗口的基线快照"落盘:进程在这里被杀时,恢复器知道该回到哪一份,
+ // 而不是把目标留在停机状态且没有任何可核对的基线。
+ if markErr := window.SetBackupSnapshot(ctx, baselineID); markErr != nil {
+ return "", errors.New("记录基线快照身份失败:" + markErr.Error())
+ }
+ // 作业行也要立刻带上这份快照身份:worker 被杀后接管/按预备份恢复都靠它,
+ // 否则"目标停着、却不知道拿哪一份核对"会让目标一直卡在维护里。
+ if persistErr := store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobRunning, "",
+ "", "", baselineID, "", time.Now().UTC()); persistErr != nil {
+ return "", errors.New("持久化基线快照引用失败:" + persistErr.Error())
+ }
+ recorder.Stage(ctx, "capture", "succeeded", "已封存目标整库快照 "+baselineID)
+ recorder.Stage(ctx, "verify", "running", "逐表/索引/资源比对目标与刚封存的快照")
+ if verifyErr := target.Verify(ctx, libraryrelease.Expectation{SnapshotID: baselineID}); verifyErr != nil {
+ return "", errors.New("目标内容与刚封存的快照不一致,拒绝登记基线:" + verifyErr.Error())
+ }
+ verified = true
+ recorder.Stage(ctx, "verify", "succeeded", "行身份/逐行内容/索引文档/资源摘要与快照一致")
+ return baselineID, nil
+ }
+
+ actor := ""
+ if libJob, jobErr := store.LibraryJob(ctx, payload.LibraryJobID); jobErr == nil {
+ actor = libJob.Actor
+ }
+ window, windowErr := coordinator.RunWindow(ctx, payload.LibraryJobID,
+ func(ctx context.Context) error { return manager.VerifyRunning(ctx) }, work,
+ func(error) bool { return true })
+
+ now2 := time.Now().UTC()
+ if !verified || window.State != "succeeded" {
+ message := "未建立基线:维护窗口没有完成捕获与校验"
+ if windowErr != nil {
+ message += ":" + windowErr.Error()
+ }
+ if window.State == "held" {
+ // 目标仍被占用:内容状态未知只能按维护保持,等"按预备份恢复"收尾。
+ note := message + "(目标保持维护)"
+ _ = store.UpdateLibraryMaintenanceState(ctx, payload.Scope, payload.LibraryJobID, "needs_restore", note, now2)
+ _ = store.UpdateInstanceMaintenanceState(ctx, identity.Instance, payload.LibraryJobID, "needs_restore", note, now2)
+ recorder.Stage(ctx, "capture", "failed", note)
+ _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobFailed, "capture", note,
+ "按预备份恢复并校验后再重试", baselineID, "", now2)
+ return errors.New(note)
+ }
+ // 没有写过目标:重新开放占用是安全的,窗口也已按原状态恢复。
+ if releaseErr := releaseWindowLocks(ctx, store, identity.Instance, payload.Scope, payload.LibraryJobID,
+ "未建立基线,目标未被改动", now2); releaseErr != nil {
+ return fmt.Errorf("%s;维护占用释放失败: %w", message, releaseErr)
+ }
+ recorder.Stage(ctx, "capture", "failed", message)
+ _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobFailed, "capture", message,
+ "未对目标执行任何写入,可直接重试", baselineID, "", now2)
+ return errors.New(message)
+ }
+
+ // 校验通过 → 登记权威基线。证据里记的是这份快照本身、逐表行数与目标索引映射;
+ // created_by 用发起人(管理员),不是 worker 自封。
+ recorder.Stage(ctx, "finalize", "running", "登记目标权威基线")
+ mapping, _ := target.Search().MappingSHA256(ctx)
+ versionErr = store.RecordLibraryVersion(ctx, governance.LibraryVersion{
+ ID: governance.LibraryVersionID(governance.LibraryVersionProductionEffective, payload.Scope, baselineID),
+ Scope: payload.Scope, Kind: governance.LibraryVersionProductionEffective,
+ SnapshotID: baselineID, SourceJobID: payload.LibraryJobID, CreatedBy: actor,
+ Evidence: map[string]any{
+ "action": "target_baseline_init",
+ "origin": "target_baseline",
+ "baseline_snapshot": baselineID,
+ "index_mapping_sha256": mapping,
+ "scope_content_counts": counts,
+ "verification": "目标与快照逐表行身份/逐行内容/索引文档/资源摘要一致",
+ "note": "基线是目标在维护窗口内的真实整库捕获,不是手写版本;发布仍需独立 sync 授权",
+ },
+ CreatedAt: now2,
+ })
+ if versionErr != nil {
+ message := "目标已捕获并校验,但基线版本登记失败:" + versionErr.Error()
+ recorder.Stage(ctx, "finalize", "failed", message)
+ _ = store.UpdateLibraryMaintenanceState(ctx, payload.Scope, payload.LibraryJobID, "needs_restore", message, now2)
+ _ = store.UpdateInstanceMaintenanceState(ctx, identity.Instance, payload.LibraryJobID, "needs_restore", message, now2)
+ _ = store.AdvanceLibraryJob(ctx, payload.LibraryJobID, governance.LibraryJobFailed, "finalize", message,
+ "基线快照 "+baselineID+" 保留;修好治理库后可续作登记", baselineID, "", time.Now().UTC())
+ return errors.New(message)
+ }
+ recorder.Stage(ctx, "finalize", "succeeded", "已登记目标权威基线 "+baselineID)
+
+ // 成功要等目标服务、入口与两把维护锁都落定才暴露。
+ if finishErr := finishLibrarySuccess(ctx, store, manager, identity.Instance, payload.Scope,
+ payload.LibraryJobID, successBoundary{Ready: true, Backup: baselineID, FinishedAt: time.Now().UTC()}); finishErr != nil {
+ return finishErr
+ }
+ log.Printf("library baseline succeeded job=%s scope=%s snapshot=%s actor=%s",
+ payload.LibraryJobID, payload.Scope, baselineID, actor)
+ return nil
+}
diff --git a/cmd/worker/library_handlers.go b/cmd/worker/library_handlers.go
index 331c6eb..795817e 100644
--- a/cmd/worker/library_handlers.go
+++ b/cmd/worker/library_handlers.go
@@ -480,8 +480,13 @@ func resumeInterruptedLibraryJobs(ctx context.Context, store *postgresstore.Stor
continue
}
queueType := librarySyncJobType
- if job.Kind == governance.LibraryJobRestore {
+ switch job.Kind {
+ case governance.LibraryJobRestore:
queueType = libraryRestoreJobType
+ case governance.LibraryJobBaseline:
+ // 基线作业被杀时窗口可能还停着目标:用同一个作业 id 接管那个窗口,
+ // 继续捕获/校验,而不是留下一个 held 目标等人工处理。
+ queueType = libraryBaselineJobType
}
payload, _ := json.Marshal(map[string]string{"library_job_id": job.ID, "scope": job.Scope,
"target_snapshot_id": job.TargetSnapshotID})
diff --git a/cmd/worker/library_wiring.go b/cmd/worker/library_wiring.go
index b4a6dfc..74f4aa6 100644
--- a/cmd/worker/library_wiring.go
+++ b/cmd/worker/library_wiring.go
@@ -11,11 +11,15 @@ import (
v071 "knowledge-governance/internal/releaseadapter/v071"
)
-// buildLibraryProductionStack 用部署注入的配置装配生产整库目标与独立预备份存储。
-// 任何一项缺失都返回明确原因,调用方据此把作业失败并把缺项写进阶段,
-// 不用"未配置"的占位对象假装能跑。
-func buildLibraryProductionStack(ctx context.Context, config appconfig.Config, scope, snapshotID, knownMapping string) (
- *v071.ProductionLibraryTarget, *v071.ProductionBackupStore, error) {
+// productionScopeConfig 是"某个 scope 的生产整库目标"的部署注入配置。
+// 校验、错误措辞与 S3 参数只在这里有一份:同步、恢复与基线共用同一套装配,
+// 不允许任何一条路径自己拼一份(那会让"目标是谁"随路径漂移)。
+type productionScopeConfig struct {
+ target v071.ProductionScope
+ s3 v071.S3ObjectStoreConfig
+}
+
+func productionScopeOf(ctx context.Context, config appconfig.Config, scope string) (productionScopeConfig, error) {
missing := make([]string, 0, 4)
if config.LibraryProductionDatabaseURL == "" {
missing = append(missing, "LIBRARY_PRODUCTION_DATABASE_URL")
@@ -38,26 +42,53 @@ func buildLibraryProductionStack(ctx context.Context, config appconfig.Config, s
missing = append(missing, "LIBRARY_PRODUCTION_S3_ENDPOINT/BUCKET/ACCESS_KEY/SECRET_KEY")
}
if len(missing) > 0 {
- return nil, nil, fmt.Errorf("生产整库目标未配置:缺少 %s", strings.Join(missing, "、"))
+ return productionScopeConfig{}, fmt.Errorf("生产整库目标未配置:缺少 %s", strings.Join(missing, "、"))
}
- secure := strings.HasPrefix(config.LibraryProductionS3Endpoint, "https://")
- objects, err := v071.NewS3ObjectStore(v071.S3ObjectStoreConfig{
- Provider: config.LibraryProductionS3Provider, Endpoint: config.LibraryProductionS3Endpoint,
- Region: config.LibraryProductionS3Region, Bucket: config.LibraryProductionS3Bucket,
- AccessKeyID: config.LibraryProductionS3AccessKey, SecretAccessKey: config.LibraryProductionS3SecretKey,
- Secure: secure, ForcePathStyle: true, MaxObjectBytes: 256 * 1024 * 1024,
- })
+ return productionScopeConfig{
+ target: v071.ProductionScope{TenantID: config.LibraryProductionTenantID, KnowledgeBaseID: kb},
+ s3: v071.S3ObjectStoreConfig{
+ Provider: config.LibraryProductionS3Provider, Endpoint: config.LibraryProductionS3Endpoint,
+ Region: config.LibraryProductionS3Region, Bucket: config.LibraryProductionS3Bucket,
+ AccessKeyID: config.LibraryProductionS3AccessKey, SecretAccessKey: config.LibraryProductionS3SecretKey,
+ Secure: strings.HasPrefix(config.LibraryProductionS3Endpoint, "https://"),
+ ForcePathStyle: true, MaxObjectBytes: 256 * 1024 * 1024,
+ },
+ }, nil
+}
+
+func newProductionTarget(ctx context.Context, config appconfig.Config, scope productionScopeConfig) (*v071.ProductionLibraryTarget, error) {
+ objects, err := v071.NewS3ObjectStore(scope.s3)
if err != nil {
- return nil, nil, errors.New("生产对象存储配置无效")
+ return nil, errors.New("生产对象存储配置无效")
}
- identity := v071.ProductionScope{TenantID: config.LibraryProductionTenantID, KnowledgeBaseID: kb}
- target, err := v071.NewProductionLibraryTarget(ctx, v071.ProductionLibraryConfig{
+ return v071.NewProductionLibraryTarget(ctx, v071.ProductionLibraryConfig{
Postgres: config.LibraryProductionDatabaseURL, SearchURL: config.LibraryProductionElasticURL,
SearchIndex: config.LibraryProductionIndex, Objects: objects, ObjectsReader: objects,
ArchiveRoot: config.LibraryArchiveRoot,
ObjectsBucket: config.LibraryProductionS3Bucket,
MaxDocuments: 200000,
- }, identity)
+ }, scope.target)
+}
+
+func newProductionBackupStore(config appconfig.Config, scope string,
+ target *v071.ProductionLibraryTarget, contract librarysnapshot.Compatibility) (*v071.ProductionBackupStore, error) {
+ return v071.NewProductionBackupStore(v071.ProductionBackupConfig{
+ Pool: target.Pool(), Search: target.Search(), Objects: target.Objects(),
+ ArchiveRoot: config.LibraryArchiveRoot, Scope: scope, Identity: target.Identity(),
+ Compatibility: contract, MaxDocuments: 200000, MaxObjectByte: 256 * 1024 * 1024,
+ })
+}
+
+// buildLibraryProductionStack 用部署注入的配置装配生产整库目标与独立预备份存储。
+// 任何一项缺失都返回明确原因,调用方据此把作业失败并把缺项写进阶段,
+// 不用"未配置"的占位对象假装能跑。
+func buildLibraryProductionStack(ctx context.Context, config appconfig.Config, scope, snapshotID, knownMapping string) (
+ *v071.ProductionLibraryTarget, *v071.ProductionBackupStore, error) {
+ scopeConfig, err := productionScopeOf(ctx, config, scope)
+ if err != nil {
+ return nil, nil, err
+ }
+ target, err := newProductionTarget(ctx, config, scopeConfig)
if err != nil {
return nil, nil, err
}
@@ -105,11 +136,43 @@ func buildLibraryProductionStack(ctx context.Context, config appconfig.Config, s
if knownMapping != "" {
backupContract.IndexMappingSHA256 = knownMapping
}
- backups, err := v071.NewProductionBackupStore(v071.ProductionBackupConfig{
- Pool: target.Pool(), Search: target.Search(), Objects: target.Objects(),
- ArchiveRoot: config.LibraryArchiveRoot, Scope: scope, Identity: target.Identity(),
- Compatibility: backupContract, MaxDocuments: 200000, MaxObjectByte: 256 * 1024 * 1024,
- })
+ backups, err := newProductionBackupStore(config, scope, target, backupContract)
+ if err != nil {
+ target.Close()
+ return nil, nil, err
+ }
+ return target, backups, nil
+}
+
+// buildLibraryBaselineStack 装配"给目标自己建基线"所需的目标与捕获器。
+//
+// 与同步的差别只有契约来源:同步要拿**待发布快照**的兼容性做契约,而基线
+// 还没有快照——它要捕获的正是目标当前状态,所以契约取目标此刻的真实索引映射,
+// 绝不去借一份别人的快照来当契约(那会把基线登记成"与某份快照一致"的假象)。
+func buildLibraryBaselineStack(ctx context.Context, config appconfig.Config, scope string) (
+ *v071.ProductionLibraryTarget, *v071.ProductionBackupStore, error) {
+ scopeConfig, err := productionScopeOf(ctx, config, scope)
+ if err != nil {
+ return nil, nil, err
+ }
+ target, err := newProductionTarget(ctx, config, scopeConfig)
+ if err != nil {
+ return nil, nil, err
+ }
+ mapping, mapErr := target.Search().MappingSHA256(ctx)
+ if mapErr != nil {
+ target.Close()
+ return nil, nil, fmt.Errorf("读取目标索引映射失败,无法确定基线契约: %w", mapErr)
+ }
+ // 只写能证明的字段:embedding 配置来自部署声明(与目标实例同一份配置),
+ // 索引映射来自目标此刻的真实映射。目标实例的 WeKnora/schema 版本这里没有
+ // 可靠来源,就不填——空白比编一个数字诚实,迁移/兼容判断不会因此放行任何东西。
+ contract := librarysnapshot.Compatibility{
+ EmbeddingModel: config.LibraryEmbeddingModel,
+ EmbeddingDimension: config.LibraryEmbeddingDimension,
+ IndexMappingSHA256: mapping,
+ }
+ backups, err := newProductionBackupStore(config, scope, target, contract)
if err != nil {
target.Close()
return nil, nil, err
diff --git a/cmd/worker/main.go b/cmd/worker/main.go
index e72aaf2..acdefac 100644
--- a/cmd/worker/main.go
+++ b/cmd/worker/main.go
@@ -93,6 +93,9 @@ const libraryRecoverJobType = "library.recover"
// libraryRestoreJobType 是按指定整库版本恢复的队列类型;与同步分开、授权也分开。
const libraryRestoreJobType = "library.restore"
+// libraryBaselineJobType 是"建立目标权威基线"的队列类型(与 API 侧常量同值)。
+const libraryBaselineJobType = "library.baseline"
+
func main() {
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()
@@ -326,6 +329,10 @@ func workerHandlers(store *postgresstore.Store, config appconfig.Config) (map[st
handlers[libraryRestoreJobType] = func(ctx context.Context, job jobs.Job) error {
return runLibraryRelease(ctx, store, config, job, governance.LibraryJobRestore)
}
+ // 建立目标权威基线:目标非空又没有生效版本时的唯一入口(只读捕获 + 校验 + 登记)。
+ handlers[libraryBaselineJobType] = func(ctx context.Context, job jobs.Job) error {
+ return runLibraryBaseline(ctx, store, config, job)
+ }
// A crash can leave the source writer stopped: recover before taking work,
// and keep the failure visible instead of pretending the worker is ready.
go func() {
diff --git a/internal/governance/library_flow.go b/internal/governance/library_flow.go
index ed8bb7b..7e6b440 100644
--- a/internal/governance/library_flow.go
+++ b/internal/governance/library_flow.go
@@ -31,6 +31,10 @@ const (
LibraryJobSync LibraryJobKind = "sync"
// LibraryJobRestore 是按指定整库版本恢复:与同步分开,授权与阶段也独立。
LibraryJobRestore LibraryJobKind = "restore"
+ // LibraryJobBaseline 建立首次发布目标的权威基线:在维护隔离下把目标整库
+ // 读出来封存成快照并逐类校验,再登记成 production_effective。
+ // 它不写目标内容、不清空目标、不猜版本——基线只能来自真实捕获与校验。
+ LibraryJobBaseline LibraryJobKind = "baseline"
)
type LibraryJobState string
@@ -134,6 +138,12 @@ func SealStages() []string {
return []string{"export"}
}
+// BaselineStages 是"建立目标权威基线"的阶段:捕获目标整库 → 与快照逐类校验
+// → 登记生效版本。没有 rollback 阶段:基线过程不写目标内容。
+func BaselineStages() []string {
+ return []string{"capture", "verify", "finalize"}
+}
+
// LibraryReleaseAuthorization 是生产发布授权:绑定目标、快照、参数摘要与有效期。
type LibraryReleaseAuthorization struct {
ID string `json:"id"`
diff --git a/internal/httpapi/library_baseline.go b/internal/httpapi/library_baseline.go
new file mode 100644
index 0000000..a96e803
--- /dev/null
+++ b/internal/httpapi/library_baseline.go
@@ -0,0 +1,150 @@
+package httpapi
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "net/http"
+ "time"
+
+ "knowledge-governance/internal/governance"
+ "knowledge-governance/internal/jobs"
+ postgresstore "knowledge-governance/internal/platform/postgres"
+)
+
+// 建立目标权威基线:首次发布时目标已经有内容,却没有生效版本记录。
+//
+// 唯一诚实的解法是"维护隔离 + 真实整库捕获 + 逐类校验 + 登记版本":
+// - 不手写 production_effective,不伪造验收;
+// - 不清空目标换库绕过(那会把"非空但未知"变成"空");
+// - 页面只投递作业,停写入者、捕获、校验都在 worker 里执行。
+//
+// 这个入口只建作业,不签发发布授权:基线不等于发布,同步仍然要单独的 sync 授权。
+const libraryBaselineJobType = "library.baseline"
+
+type libraryBaselineRequest struct {
+ Scope string `json:"scope"`
+}
+
+func libraryBaselineEnqueue(w http.ResponseWriter, r *http.Request, config Config) {
+ if r.Method != http.MethodPost {
+ writeJSON(w, http.StatusMethodNotAllowed, map[string]string{"error": "method not allowed"})
+ return
+ }
+ identity, ok := sessionFrom(r.Context())
+ if !ok || roleRank(identity.Role) < roleRank(roleAdmin) {
+ writeJSON(w, http.StatusForbidden, map[string]any{"error": "建立目标权威基线仅管理员可发起"})
+ return
+ }
+ var request libraryBaselineRequest
+ if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 4096)).Decode(&request); err != nil {
+ writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid request body"})
+ return
+ }
+ if request.Scope != "internal" && request.Scope != "external" {
+ writeJSON(w, http.StatusBadRequest, map[string]string{"error": "scope must be internal or external"})
+ return
+ }
+ store, ok := libraryStore(config)
+ if !ok {
+ writeJSON(w, http.StatusServiceUnavailable, map[string]any{"code": "library_baseline_unavailable",
+ "error": "版本登记存储不可用"})
+ return
+ }
+ versions, err := store.LibraryVersions(r.Context(), request.Scope, 50)
+ if err != nil {
+ writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read library versions"})
+ return
+ }
+ for _, item := range versions {
+ if item.Kind == governance.LibraryVersionProductionEffective && item.SupersededAt == nil {
+ writeJSON(w, http.StatusConflict, map[string]any{"code": "library_baseline_exists",
+ "error": "该目标已有生效版本,不需要再建基线;换版本请走同步或恢复",
+ "snapshot_id": item.SnapshotID})
+ return
+ }
+ }
+ // 目标必须真的读得到:读不到就不是"非空无权威版本",而是另一个问题,
+ // 不允许用建基线去掩盖连接/配置故障。
+ empty, counts, probeErr := productionScopeState(r.Context(), config, request.Scope)
+ if probeErr != nil {
+ writeJSON(w, http.StatusServiceUnavailable, map[string]any{"code": "library_baseline_unprobeable",
+ "error": "无法读取目标整库状态,不能建立基线:" + probeErr.Error()})
+ return
+ }
+ if empty {
+ writeJSON(w, http.StatusConflict, map[string]any{"code": "library_baseline_target_empty",
+ "error": "目标整库为空,不需要基线:首次同步会在写入前生成完整预备份并登记生效版本",
+ "counts": counts})
+ return
+ }
+ // 维护互斥与同步一致:基线要在目标上开维护窗口,目标正在维护时直接拒绝。
+ if body, held := instanceMaintenanceGuard(r.Context(), config, request.Scope); held {
+ writeJSON(w, http.StatusConflict, body)
+ return
+ }
+ if maintenanceStore, ok := config.Store.(interface {
+ LibraryMaintenanceOf(ctx context.Context, scope string) (*postgresstore.LibraryMaintenance, error)
+ }); ok {
+ if held, err := maintenanceStore.LibraryMaintenanceOf(r.Context(), request.Scope); err == nil && held != nil && held.ReleasedAt == nil {
+ writeJSON(w, http.StatusConflict, map[string]any{"code": "library_target_in_maintenance",
+ "error": "目标正在维护中,验证完成前不接受新的写入请求",
+ "owner_job": held.OwnerJobID, "state": held.State})
+ return
+ }
+ }
+ digest, err := governance.LibraryRequestDigest(request.Scope, governance.LibraryJobBaseline,
+ map[string]any{"scope": request.Scope})
+ if err != nil {
+ writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot digest request"})
+ return
+ }
+ now := time.Now().UTC()
+ job, reused, err := store.CreateLibraryJob(r.Context(), governance.LibraryJob{
+ ID: fmt.Sprintf("libbase-%s-%d", request.Scope, now.UnixNano()), Scope: request.Scope,
+ Kind: governance.LibraryJobBaseline,
+ IdempotencyKey: "library.baseline:" + request.Scope + ":" + now.Format("20060102T150405.000000000"),
+ RequestDigest: digest, Actor: identity.Username,
+ }, governance.BaselineStages(), now)
+ if errors.Is(err, governance.ErrLibraryJobActive) {
+ writeJSON(w, http.StatusConflict, map[string]any{"code": "library_write_active",
+ "error": "该目标已有在飞的写作业(同步/恢复/基线互斥),等它结束再发起"})
+ return
+ }
+ if errors.Is(err, governance.ErrLibraryJobIdempotencyConflict) {
+ writeJSON(w, http.StatusConflict, map[string]any{"code": "library_baseline_conflict",
+ "error": "同一幂等键对应了不同的请求"})
+ return
+ }
+ if err != nil {
+ writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot create library baseline job"})
+ return
+ }
+ if reused {
+ writeJSON(w, http.StatusAccepted, map[string]any{"job": job, "reused": true})
+ return
+ }
+ payload, err := json.Marshal(map[string]string{"library_job_id": job.ID, "scope": request.Scope})
+ if err != nil {
+ writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot build baseline payload"})
+ return
+ }
+ queueJob, err := config.Store.Enqueue(r.Context(), jobs.EnqueueRequest{
+ ID: governance.QueueJobIDFor(job.ID), Type: libraryBaselineJobType, Payload: payload,
+ AvailableAt: now, MaxAttempts: 1, IdempotencyKey: "library.baseline.queue:" + job.ID,
+ }, now)
+ if err != nil || queueJob == nil {
+ // 作业先落库、队列投递失败就把作业取消:不留下"看起来在跑"的空作业,
+ // 否则它会一直占着该 scope 的写互斥。
+ _ = store.CancelLibraryJob(r.Context(), job.ID, "队列投递失败,未开始建立基线", now)
+ writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot enqueue baseline job"})
+ return
+ }
+ if attachErr := store.AttachLibraryQueueJob(r.Context(), job.ID, queueJob.ID, now); attachErr != nil {
+ writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot attach baseline job"})
+ return
+ }
+ writeJSON(w, http.StatusAccepted, map[string]any{"job": job, "reused": false,
+ "target_counts": counts})
+}
diff --git a/internal/httpapi/library_baseline_test.go b/internal/httpapi/library_baseline_test.go
new file mode 100644
index 0000000..ce83293
--- /dev/null
+++ b/internal/httpapi/library_baseline_test.go
@@ -0,0 +1,162 @@
+package httpapi
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+ "time"
+
+ "knowledge-governance/internal/governance"
+)
+
+// 建立目标权威基线的入口契约:
+// - 只有管理员能发起(它是生产侧维护动作);
+// - 已有生效版本时拒绝(基线只解决首次发布);
+// - 目标读不到时拒绝,且**不建作业、不登记版本**(不能用基线掩盖连接问题)。
+
+func baselineRequest(body, role, username string) *http.Request {
+ request := httptest.NewRequest(http.MethodPost, "/api/v1/library/baselines", strings.NewReader(body))
+ request.Header.Set("Content-Type", "application/json")
+ ctx := context.WithValue(request.Context(), sessionKey{}, sessionIdentity{Username: username, Role: role})
+ return request.WithContext(ctx)
+}
+
+func decodeBody(t *testing.T, recorder *httptest.ResponseRecorder) map[string]any {
+ t.Helper()
+ var payload map[string]any
+ if err := json.Unmarshal(recorder.Body.Bytes(), &payload); err != nil {
+ t.Fatalf("response is not JSON: %s", recorder.Body.String())
+ }
+ return payload
+}
+
+func TestLibraryBaselineRequiresAdmin(t *testing.T) {
+ store := &fakeLibraryStore{}
+ recorder := httptest.NewRecorder()
+ libraryBaselineEnqueue(recorder, baselineRequest(`{"scope":"internal"}`, roleEngineer, "eng"), Config{Store: store})
+ if recorder.Code != http.StatusForbidden {
+ t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
+ }
+ if store.createN != 0 {
+ t.Fatal("non-admin must not create a baseline job")
+ }
+}
+
+func TestLibraryBaselineRefusesWhenEffectiveVersionExists(t *testing.T) {
+ store := &fakeLibraryStore{versions: []governance.LibraryVersion{{
+ ID: "libver-1", Scope: "internal", Kind: governance.LibraryVersionProductionEffective,
+ SnapshotID: "snap-effective", CreatedAt: time.Now().UTC(),
+ }}}
+ recorder := httptest.NewRecorder()
+ libraryBaselineEnqueue(recorder, baselineRequest(`{"scope":"internal"}`, roleAdmin, "admin"), Config{Store: store})
+ if recorder.Code != http.StatusConflict {
+ t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
+ }
+ if body := decodeBody(t, recorder); body["code"] != "library_baseline_exists" || body["snapshot_id"] != "snap-effective" {
+ t.Fatalf("body=%v", body)
+ }
+ if store.createN != 0 {
+ t.Fatal("existing effective version must not create another baseline job")
+ }
+}
+
+// 目标读不到(这里用"没配置目标库"复现):必须 503 并说明原因,
+// 既不能建作业,也不能顺手写一条版本记录来"解决"未知状态。
+func TestLibraryBaselineRefusesWhenTargetUnreadable(t *testing.T) {
+ store := &fakeLibraryStore{}
+ recorder := httptest.NewRecorder()
+ libraryBaselineEnqueue(recorder, baselineRequest(`{"scope":"external"}`, roleAdmin, "admin"), Config{Store: store})
+ if recorder.Code != http.StatusServiceUnavailable {
+ t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String())
+ }
+ body := decodeBody(t, recorder)
+ if body["code"] != "library_baseline_unprobeable" || !strings.Contains(func() string {
+ text, _ := body["error"].(string)
+ return text
+ }(), "无法读取目标整库状态") {
+ t.Fatalf("body=%v", body)
+ }
+ if store.createN != 0 {
+ t.Fatal("unreadable target must not create a baseline job")
+ }
+ if len(store.versions) != 0 {
+ t.Fatal("unreadable target must not record any version")
+ }
+}
+
+// 测试候选只认登记过 test_sealed 的那份快照:归档里同时存在更新的目标基线/
+// 预备份快照时,绝不能把它们当成"拟发布的测试版本"。
+func TestTestSealedCandidateComesFromRegistryNotNewestArchiveEntry(t *testing.T) {
+ sealed := librarySnapshotView{SnapshotID: "snap-sealed", CreatedAt: time.Date(2026, 10, 29, 8, 54, 0, 0, time.UTC)}
+ prebackup := librarySnapshotView{SnapshotID: "snap-prebackup", CreatedAt: time.Date(2026, 10, 29, 9, 30, 0, 0, time.UTC)}
+ byID := map[string]librarySnapshotView{sealed.SnapshotID: sealed, prebackup.SnapshotID: prebackup}
+ versions := []governance.LibraryVersion{
+ {Kind: governance.LibraryVersionProductionPrebackup, SnapshotID: "snap-prebackup"},
+ {Kind: governance.LibraryVersionTestSealed, SnapshotID: "snap-sealed"},
+ }
+ candidate, reason := testSealedOf(versions, byID)
+ if reason != "" {
+ t.Fatalf("reason=%q", reason)
+ }
+ if candidate == nil || candidate.SnapshotID != "snap-sealed" {
+ t.Fatalf("candidate=%v, want the registered test seal", candidate)
+ }
+
+ // 没有任何 test_sealed 登记:宁可说"还没有测试封存",也不拿别的快照顶替。
+ none, reason := testSealedOf([]governance.LibraryVersion{
+ {Kind: governance.LibraryVersionProductionPrebackup, SnapshotID: "snap-prebackup"},
+ }, byID)
+ if none != nil || !strings.Contains(reason, "还没有该目标的测试封存") {
+ t.Fatalf("candidate=%v reason=%q", none, reason)
+ }
+
+ // 登记过但它已经不在本机归档:说清是归档问题,不给候选。
+ missing, reason := testSealedOf([]governance.LibraryVersion{
+ {Kind: governance.LibraryVersionTestSealed, SnapshotID: "snap-gone"},
+ }, byID)
+ if missing != nil || !strings.Contains(reason, "不在本机归档里") {
+ t.Fatalf("candidate=%v reason=%q", missing, reason)
+ }
+}
+
+// 非空但无权威版本时,缺项必须指向真实入口,而不是一句"未知"。
+func TestLibrarySyncGateNamesTheBaselineEntryForNonEmptyTarget(t *testing.T) {
+ gate := librarySyncGateWithGrant(Config{ProductionReleaseRequestsEnabled: true,
+ ProductionBackupRestoreVerified: true, LibraryProductionDatabaseURL: "postgres://prod.invalid/db",
+ LibraryProductionInternalKB: "kb-int", LibraryCapacityBudgetBytes: 1 << 30},
+ libraryKnownView{State: "unknown"}, libraryKnownView{State: "unknown"}, "snap-1", true)
+ if gate.SyncAllowed {
+ t.Fatal("unknown production version must block the sync")
+ }
+ joined := strings.Join(gate.Reasons, "|")
+ if !strings.Contains(joined, "目标非空且没有生效版本记录") || !strings.Contains(joined, "目标权威基线") {
+ t.Fatalf("reasons=%v", gate.Reasons)
+ }
+}
+
+// 维护能力是配置事实:配置齐全时必须说"已接线",缺项要列出缺哪个变量。
+func TestLibraryMaintenanceCapabilityReportsWiringInsteadOfOneVagueSentence(t *testing.T) {
+ wired := libraryMaintenanceCapability(Config{
+ LibraryTargetInstance: "kgseal-app", LibraryTargetProject: "kgseal-weknora",
+ LibraryTargetWriters: []string{"app"}, LibraryTargetIngressURL: "http://kgseal-ingress:18084/health",
+ LibraryTargetIngressService: "ingress", LibraryTargetJournalRoot: "/var/lib/knowledge-governance/journal",
+ LibraryTargetDockerSocket: "/var/run/docker.sock",
+ })
+ if wired["configured"] != true {
+ t.Fatalf("capability=%v", wired)
+ }
+ if wired["instance"] != "kgseal-app" {
+ t.Fatalf("instance=%v", wired["instance"])
+ }
+ broken := libraryMaintenanceCapability(Config{LibraryTargetInstance: "kgseal-app"})
+ if broken["configured"] != false {
+ t.Fatalf("capability=%v", broken)
+ }
+ missing, _ := broken["missing"].([]string)
+ if len(missing) == 0 || !strings.Contains(strings.Join(missing, ","), "LIBRARY_TARGET_WRITERS") {
+ t.Fatalf("missing=%v", broken["missing"])
+ }
+}
diff --git a/internal/httpapi/library_flow.go b/internal/httpapi/library_flow.go
index 19f355f..191b427 100644
--- a/internal/httpapi/library_flow.go
+++ b/internal/httpapi/library_flow.go
@@ -19,6 +19,7 @@ import (
"knowledge-governance/internal/librarydiff"
"knowledge-governance/internal/librarysnapshot"
postgresstore "knowledge-governance/internal/platform/postgres"
+ v071 "knowledge-governance/internal/releaseadapter/v071"
)
// 整库版本/状态/差异读取契约 + 生产同步的 fail-closed 入口。
@@ -56,30 +57,36 @@ type libraryKnownView struct {
EmptyBaseline bool `json:"empty_baseline,omitempty"`
}
-// productionScopeEmpty 只读探测生产目标:真正连库数一遍,不用缓存或推断。
-func productionScopeEmpty(ctx context.Context, config Config, scope string) (bool, error) {
+// productionScopeState 只读探测生产目标:真正连库数一遍,不用缓存或推断。
+//
+// "空"必须是整库意义的空:只数 knowledges 会把"文档已删、分块/Wiki/资源还在"
+// 的目标当成首次发布的空基线,从而绕过基线初始化。所以这里用适配层同一份
+// 表清单与范围过滤(v071.ScopeContentEmpty),并把逐表行数交回调用方作为证据。
+func productionScopeState(ctx context.Context, config Config, scope string) (bool, map[string]int64, error) {
if strings.TrimSpace(config.LibraryProductionDatabaseURL) == "" {
- return false, errors.New("生产整库目标未配置")
+ return false, nil, errors.New("生产整库目标未配置")
}
kb := config.LibraryProductionInternalKB
if scope == "external" {
kb = config.LibraryProductionExternalKB
}
if kb == "" {
- return false, errors.New("生产知识库未配置")
+ return false, nil, errors.New("该范围的目标知识库未配置")
}
pool, err := pgxpool.New(ctx, config.LibraryProductionDatabaseURL)
if err != nil {
- return false, err
+ return false, nil, err
}
defer pool.Close()
- var count int64
- err = pool.QueryRow(ctx, `SELECT count(*) FROM knowledges WHERE tenant_id=$1 AND knowledge_base_id=$2 AND deleted_at IS NULL`,
- config.LibraryProductionTenantID, kb).Scan(&count)
- if err != nil {
- return false, err
- }
- return count == 0, nil
+ return v071.ScopeContentEmpty(ctx, pool,
+ v071.ProductionScope{TenantID: config.LibraryProductionTenantID, KnowledgeBaseID: kb})
+}
+
+// productionScopeEmpty 保留"只问空不空"的调用形状;逐表行数在需要举证时用
+// productionScopeState 取。
+func productionScopeEmpty(ctx context.Context, config Config, scope string) (bool, error) {
+ empty, _, err := productionScopeState(ctx, config, scope)
+ return empty, err
}
type libraryDiffView struct {
@@ -508,6 +515,70 @@ func errString(err error) string {
return err.Error()
}
+// shortSnapshot 只用于给人看的提示:完整摘要留给快照详情,别在原因句里塞 64 位。
+func shortSnapshot(id string) string {
+ if len(id) <= 12 {
+ return id
+ }
+ return id[:12]
+}
+
+// testSealedOf 选"拟发布的测试封存":只有登记过 test_sealed 的那一份才算候选。
+//
+// 归档是共享的:生产预备份与目标基线快照同样带着 scope 写进同一个归档根,
+// 按"这个 scope 最新一份"挑会把目标自己的内容当成测试候选(页面会显示一份
+// 永远不该被发布的东西)。所以候选来自版本登记,再用归档确认它真的还在本地。
+func testSealedOf(versions []governance.LibraryVersion, byID map[string]librarySnapshotView) (*librarySnapshotView, string) {
+ for _, item := range versions {
+ if item.Kind != governance.LibraryVersionTestSealed {
+ continue
+ }
+ snapshot, ok := byID[item.SnapshotID]
+ if !ok {
+ return nil, "最近一次测试封存 " + shortSnapshot(item.SnapshotID) + " 不在本机归档里(归档被清理或换了归档根)"
+ }
+ return &snapshot, ""
+ }
+ return nil, "还没有该目标的测试封存"
+}
+
+// libraryMaintenanceCapability 用配置事实回答"这台机器上维护是否接线"。
+// 它刻意只说配置:能停写入者/关入口/证明排空的真实能力在 worker 侧(docker socket、
+// 闸门、排空文件),API 若声称"能力可用"就是拿配置字符串冒充执行证据。
+func libraryMaintenanceCapability(config Config) map[string]any {
+ missing := make([]string, 0, 6)
+ if config.LibraryTargetInstance == "" {
+ missing = append(missing, "LIBRARY_TARGET_INSTANCE")
+ }
+ if config.LibraryTargetProject == "" {
+ missing = append(missing, "LIBRARY_TARGET_PROJECT")
+ }
+ if len(config.LibraryTargetWriters) == 0 {
+ missing = append(missing, "LIBRARY_TARGET_WRITERS")
+ }
+ if config.LibraryTargetIngressURL == "" {
+ missing = append(missing, "LIBRARY_TARGET_INGRESS_URL")
+ }
+ if config.LibraryTargetIngressService == "" {
+ missing = append(missing, "LIBRARY_TARGET_INGRESS_SERVICE")
+ }
+ if config.LibraryTargetJournalRoot == "" {
+ missing = append(missing, "LIBRARY_TARGET_JOURNAL_ROOT")
+ }
+ if config.LibraryTargetDockerSocket == "" {
+ missing = append(missing, "LIBRARY_TARGET_DOCKER_SOCKET")
+ }
+ return map[string]any{
+ "configured": len(missing) == 0,
+ "missing": missing,
+ "instance": config.LibraryTargetInstance,
+ "project": config.LibraryTargetProject,
+ "writers": config.LibraryTargetWriters,
+ "ingress_service": config.LibraryTargetIngressService,
+ "note": "配置齐全只说明治理侧接线完整;停写入者、关入口与排空由 worker 在作业内校验并执行",
+ }
+}
+
func librarySyncGate(config Config, production libraryKnownView, prebackup libraryKnownView, target string) libraryGateView {
return librarySyncGateWithGrant(config, production, prebackup, target, false)
}
@@ -531,9 +602,11 @@ func librarySyncGateWithGrant(config Config, production libraryKnownView, prebac
gate.Reasons = append(gate.Reasons, "生产整库目标未配置(LIBRARY_PRODUCTION_DATABASE_URL),无法核验生产当前状态")
}
// 首次发布:生产还没有"生效版本"记录,但只要生产目标可读且是空的,
- // 这就是一个合法的"空基线",不应该被永久挡住。非空但无权威版本仍然阻断。
+ // 这就是一个合法的"空基线",不应该被永久挡住。非空但无权威版本仍然阻断,
+ // 指向真实可行的入口(在维护隔离下捕获目标整库并校验后登记基线),
+ // 而不是让人去手写版本或清空目标。
if production.State != "known" && !production.EmptyBaseline {
- gate.Reasons = append(gate.Reasons, "生产当前权威版本未知,不能启动写入")
+ gate.Reasons = append(gate.Reasons, "目标非空且没有生效版本记录:先建立目标权威基线(维护隔离下捕获整库并逐类校验),或确认目标确实是空库")
}
if target == "" {
gate.Reasons = append(gate.Reasons, "还没有可同步的测试封存版本")
@@ -569,21 +642,20 @@ func libraryOverviewHandler(w http.ResponseWriter, r *http.Request, config Confi
// 可发起封存 = worker 真实探测到执行器可用且指向本实例;原因逐条给全。
overview.CaptureAvailable, overview.CaptureReason, overview.Executor = libraryExecutorAvailability(r.Context(), config)
- // 测试封存来自归档:它只是测试侧事实。
+ // 测试封存来自归档 + 版本登记:归档里**不止**测试封存——生产预备份与目标基线
+ // 快照同样带 scope,如果只按"这个 scope 最新一份"挑,页面就会把目标自己的内容
+ // 当成拟发布的测试候选。所以候选只认登记过 kind=test_sealed 的那一份。
snapshots, snapErr := readLibrarySnapshots(r.Context(), config.LibraryArchiveRoot)
+ byID := map[string]librarySnapshotView{}
+ archiveReadable := false
if snapErr != nil {
_, overview.TestSealedReason = libraryArchiveErrorStatus(snapErr, "归档不可读")
} else if !snapshots.Available {
overview.TestSealedReason = snapshots.Reason
} else {
- for index := range snapshots.Snapshots {
- if snapshots.Snapshots[index].Scope == scope {
- overview.TestSealed = &snapshots.Snapshots[index]
- break
- }
- }
- if overview.TestSealed == nil {
- overview.TestSealedReason = "还没有该目标的测试封存"
+ archiveReadable = true
+ for _, snapshot := range snapshots.Snapshots {
+ byID[snapshot.SnapshotID] = snapshot
}
}
@@ -593,6 +665,9 @@ func libraryOverviewHandler(w http.ResponseWriter, r *http.Request, config Confi
writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "cannot read library versions"})
return
}
+ if archiveReadable {
+ overview.TestSealed, overview.TestSealedReason = testSealedOf(versions, byID)
+ }
overview.Production = libraryKnownView{State: "unknown", Reason: "还没有生产验证通过的生效版本记录"}
overview.Prebackup = libraryKnownView{State: "unknown", Reason: "本次目标快照还没有生产预备份"}
target := ""
diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go
index 1b1c4cf..bb53029 100644
--- a/internal/httpapi/server.go
+++ b/internal/httpapi/server.go
@@ -148,6 +148,15 @@ type Config struct {
// LibraryTargetInstance 是实例级维护的目标实例名;留空即"未接线",
// 页面不能发起按预备份恢复,接口返回原因而不是假装能恢复。
LibraryTargetInstance string
+ // 维护能力的其余配置项只用于如实展示"是否接线":未运行维护与没有维护能力
+ // 是两件事,页面不能混成一句"未接入"。真正停写入者/关入口的能力由 worker
+ // 在执行作业时校验(socket、入口、排空文件都在 worker 侧)。
+ LibraryTargetProject string
+ LibraryTargetWriters []string
+ LibraryTargetIngressURL string
+ LibraryTargetIngressService string
+ LibraryTargetDockerSocket string
+ LibraryTargetJournalRoot string
// LibrarySourceInstance 是死信解除记录的来源实例名(封存源),留空回落到目标实例名。
LibrarySourceInstance string
// LibraryAgentSocket 是主机侧封存 agent 的 unix socket;留空即页面不能发起封存。
@@ -479,6 +488,8 @@ func NewHandler(config Config) (http.Handler, error) {
return
}
response := map[string]any{"held": held != nil && held.ReleasedAt == nil, "maintenance": held}
+ // 有没有维护能力是配置事实,和"此刻没有窗口"必须分开回答。
+ response["capability"] = libraryMaintenanceCapability(config)
// 实例级占用才是真正的互斥来源:跨 scope 也在这里体现。
if instanceStore, ok := config.Store.(interface {
InstanceMaintenanceOf(ctx context.Context, instance string) (*postgresstore.LibraryInstanceMaintenance, error)
@@ -527,6 +538,10 @@ func NewHandler(config Config) (http.Handler, error) {
mux.HandleFunc("POST /api/v1/library/syncs", func(w http.ResponseWriter, r *http.Request) {
librarySyncEnqueue(w, r, config)
})
+ // 首次发布的目标权威基线:管理员在维护隔离下捕获目标整库并校验后登记版本。
+ mux.HandleFunc("POST /api/v1/library/baselines", func(w http.ResponseWriter, r *http.Request) {
+ libraryBaselineEnqueue(w, r, config)
+ })
// 全部 main 提交时间线(读本库缓存,不直接打 Gitea)
mux.HandleFunc("GET /api/v1/version-history", func(w http.ResponseWriter, r *http.Request) {
versionHistoryList(w, r, config)
diff --git a/internal/platform/postgres/library_jobs.go b/internal/platform/postgres/library_jobs.go
index 83c7b92..66ad5fb 100644
--- a/internal/platform/postgres/library_jobs.go
+++ b/internal/platform/postgres/library_jobs.go
@@ -261,7 +261,7 @@ func (s *Store) InterruptedLibraryJobs(ctx context.Context) ([]governance.Librar
rows, err := s.db.Query(ctx, `
SELECT lj.id FROM library_jobs lj
LEFT JOIN jobs j ON j.id=lj.queue_job_id
-WHERE lj.kind IN ('sync','restore')
+WHERE lj.kind IN ('sync','restore','baseline')
AND (
-- 业务作业在跑、队列已经没了/停了/租约过期
(lj.state='running' AND (j.id IS NULL OR j.state IN ('failed','completed','cancelled','dead')
diff --git a/internal/platform/postgres/migrations/000075_library_baseline_kind.down.sql b/internal/platform/postgres/migrations/000075_library_baseline_kind.down.sql
new file mode 100644
index 0000000..a863f58
--- /dev/null
+++ b/internal/platform/postgres/migrations/000075_library_baseline_kind.down.sql
@@ -0,0 +1,8 @@
+DELETE FROM library_jobs WHERE kind='baseline';
+ALTER TABLE library_jobs DROP CONSTRAINT IF EXISTS library_jobs_kind_check;
+ALTER TABLE library_jobs ADD CONSTRAINT library_jobs_kind_check
+ CHECK (kind IN ('seal','sync','restore'));
+DROP INDEX IF EXISTS library_jobs_write_target;
+CREATE UNIQUE INDEX library_jobs_write_target
+ ON library_jobs(scope)
+ WHERE state IN ('pending','running') AND kind IN ('sync','restore');
\ No newline at end of file
diff --git a/internal/platform/postgres/migrations/000075_library_baseline_kind.up.sql b/internal/platform/postgres/migrations/000075_library_baseline_kind.up.sql
new file mode 100644
index 0000000..741515e
--- /dev/null
+++ b/internal/platform/postgres/migrations/000075_library_baseline_kind.up.sql
@@ -0,0 +1,12 @@
+-- 允许"建立目标权威基线"作为一种独立业务作业:首次发布的目标非空又没有生效版本时,
+-- 只能通过真实捕获 + 校验登记基线,不能手写版本记录。
+-- 基线会在目标上开维护窗口(停写入者),所以它与 sync/restore 共用同一把写互斥:
+-- 同一 scope 不允许同时存在两种写作业。
+ALTER TABLE library_jobs DROP CONSTRAINT IF EXISTS library_jobs_kind_check;
+ALTER TABLE library_jobs ADD CONSTRAINT library_jobs_kind_check
+ CHECK (kind IN ('seal','sync','restore','baseline'));
+
+DROP INDEX IF EXISTS library_jobs_write_target;
+CREATE UNIQUE INDEX library_jobs_write_target
+ ON library_jobs(scope)
+ WHERE state IN ('pending','running') AND kind IN ('sync','restore','baseline');
\ No newline at end of file
diff --git a/internal/platform/postgres/migrations_test.go b/internal/platform/postgres/migrations_test.go
index e15f24e..e638bba 100644
--- a/internal/platform/postgres/migrations_test.go
+++ b/internal/platform/postgres/migrations_test.go
@@ -11,45 +11,51 @@ func TestEmbeddedMigrationsAreVersionSorted(t *testing.T) {
if err != nil {
t.Fatalf("loadMigrations() error = %v", err)
}
- if len(migrations) != 74 {
- t.Fatalf("migration count = %d, want 74", len(migrations))
+ if len(migrations) != 75 {
+ t.Fatalf("migration count = %d, want 75", len(migrations))
+ }
+ // 75 允许"建立目标权威基线"作为独立业务作业,并与 sync/restore 共用写互斥。
+ if baseline := migrations[len(migrations)-1]; baseline.Version != 75 ||
+ !strings.Contains(baseline.UpSQL, "library_jobs_write_target") ||
+ !strings.Contains(baseline.UpSQL, "'baseline'") {
+ t.Fatalf("migration 75 = %#v", baseline)
}
// 74 记录封存执行器的运行时状态:页面可用性来自真实观测,不来自配置字符串。
- if executor := migrations[len(migrations)-1]; executor.Version != 74 ||
+ if executor := migrations[len(migrations)-2]; executor.Version != 74 ||
!strings.Contains(executor.UpSQL, "library_executor_status") {
t.Fatalf("migration 74 = %#v", executor)
}
// 73 记录死信精确解除:保留上游行,只绑定指纹、重放引用与观测摘要。
- if release := migrations[len(migrations)-2]; release.Version != 73 ||
+ if release := migrations[len(migrations)-3]; release.Version != 73 ||
!strings.Contains(release.UpSQL, "library_dead_letter_releases") {
t.Fatalf("migration 73 = %#v", release)
}
// 72 让维护占用按实例互斥(internal/external 不再各有各的锁)。
- if instance := migrations[len(migrations)-3]; instance.Version != 72 ||
+ if instance := migrations[len(migrations)-4]; instance.Version != 72 ||
!strings.Contains(instance.UpSQL, "library_instance_maintenance") {
t.Fatalf("migration 72 = %#v", instance)
}
// 71 让维护记录能区分实例级维护与仅治理库互斥。
- if level := migrations[len(migrations)-4]; level.Version != 71 ||
+ if level := migrations[len(migrations)-5]; level.Version != 71 ||
!strings.Contains(level.UpSQL, "level") || !strings.Contains(level.UpSQL, "ingress_state") {
t.Fatalf("migration 71 = %#v", level)
}
- if maint := migrations[len(migrations)-5]; maint.Version != 70 || !strings.Contains(maint.UpSQL, "library_maintenance") {
+ if maint := migrations[len(migrations)-6]; maint.Version != 70 || !strings.Contains(maint.UpSQL, "library_maintenance") {
t.Fatalf("migration 70 = %#v", maint)
}
- if tail := migrations[len(migrations)-6]; tail.Version != 69 ||
+ if tail := migrations[len(migrations)-7]; tail.Version != 69 ||
!strings.Contains(tail.UpSQL, "library_jobs_write_target") {
t.Fatalf("migration 69 = %#v", tail)
}
- if restore := migrations[len(migrations)-7]; restore.Version != 68 || !strings.Contains(restore.UpSQL, "restore") {
+ if restore := migrations[len(migrations)-8]; restore.Version != 68 || !strings.Contains(restore.UpSQL, "restore") {
t.Fatalf("migration 68 = %#v", restore)
}
- if last := migrations[len(migrations)-8]; last.Version != 67 ||
+ if last := migrations[len(migrations)-9]; last.Version != 67 ||
!strings.Contains(last.UpSQL, "library_release_authorizations") ||
!strings.Contains(last.UpSQL, "params_digest") {
t.Fatalf("migration 67 = %#v", last)
}
- if flow := migrations[len(migrations)-9]; flow.Version != 66 ||
+ if flow := migrations[len(migrations)-10]; flow.Version != 66 ||
!strings.Contains(flow.UpSQL, "CREATE TABLE library_versions") ||
!strings.Contains(flow.UpSQL, "library_jobs_active") {
t.Fatalf("migration 66 = %#v", flow)
diff --git a/internal/releaseadapter/v071/library_scope_probe.go b/internal/releaseadapter/v071/library_scope_probe.go
new file mode 100644
index 0000000..d25ec8e
--- /dev/null
+++ b/internal/releaseadapter/v071/library_scope_probe.go
@@ -0,0 +1,46 @@
+package v071
+
+import (
+ "context"
+ "errors"
+ "fmt"
+
+ "github.com/jackc/pgx/v5/pgxpool"
+)
+
+// ScopeContentCounts 数一个知识库在各内容表里的行数(数据库侧事实)。
+//
+// 为什么不能只数 knowledges:文档被删掉、分块与 Wiki/资源还在的库并不为空。
+// 只数一张表会把这种目标判成"首次发布的空库",从而让一条本该走基线初始化的
+// 路径绕过去;这里用与整库读写完全相同的表清单与过滤条件,保证"空"的定义只有一份。
+func ScopeContentCounts(ctx context.Context, pool *pgxpool.Pool, identity ProductionScope) (map[string]int64, error) {
+ if pool == nil || identity.TenantID == 0 || !validSearchIdentifier(identity.KnowledgeBaseID) {
+ return nil, errors.New("invalid scope identity")
+ }
+ counts := make(map[string]int64, len(productionLibraryTables))
+ for _, table := range productionLibraryTables {
+ var count int64
+ if err := pool.QueryRow(ctx, fmt.Sprintf(`SELECT count(*) FROM %s WHERE %s`, table, scopeWhere(table)),
+ identity.TenantID, identity.KnowledgeBaseID).Scan(&count); err != nil {
+ return nil, fmt.Errorf("count %s: %w", table, err)
+ }
+ counts[table] = count
+ }
+ return counts, nil
+}
+
+// ScopeContentEmpty 只有每张内容表都是 0 才算空目标,并交回逐表行数作为证据。
+// 注意它**不**包含检索索引:索引由分块派生,分块为空而索引非空属于不一致,
+// 应在执行侧(预备份/基线捕获)报出来,不能在这里被当成"空"。
+func ScopeContentEmpty(ctx context.Context, pool *pgxpool.Pool, identity ProductionScope) (bool, map[string]int64, error) {
+ counts, err := ScopeContentCounts(ctx, pool, identity)
+ if err != nil {
+ return false, nil, err
+ }
+ for _, count := range counts {
+ if count != 0 {
+ return false, counts, nil
+ }
+ }
+ return true, counts, nil
+}
--
2.52.0
From 3284658eb1d5d64de8693f83732fb4ed3030293f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?=
Date: Thu, 29 Oct 2026 18:16:25 +0800
Subject: [PATCH 42/45] =?UTF-8?q?feat(web):=20=E5=8F=91=E5=B8=83=E9=A1=B5?=
=?UTF-8?q?=E6=8E=A5=E4=B8=8A=E7=AD=BE=E5=8F=91=E5=90=8C=E6=AD=A5=E6=8E=88?=
=?UTF-8?q?=E6=9D=83=E4=B8=8E=E5=BB=BA=E7=AB=8B=E5=9F=BA=E7=BA=BF=E5=85=A5?=
=?UTF-8?q?=E5=8F=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
发布页原来只有一个永远 disabled 的"启动同步",title 还写着"生产同步执行链
尚未接线"——执行链其实已经存在。现在:
- 管理员看到"签发同步授权(30 分钟)"(action=sync,绑定范围+目标快照),
签发与执行仍是两步,不会自动签发;
- 闸口全满足时"启动同步"真的按 POST /library/syncs 投递,被拒时逐条显示
接口返回的缺项;
- 目标非空又无生效版本时,管理员看到"建立目标权威基线(维护隔离)";
- 测试封存候选改用接口给的 test_sealed(来自版本登记),不再拿归档里最新
一份顶替;
- 维护卡片区分"未运行维护 / 维护能力未接线 / 能力未知",逐项列出缺的变量。
验证:vitest 99 个文件 469 个用例全绿,tsc --noEmit 无错;反向自检(把按钮
改回恒 disabled、把维护文案改回旧句)两处按预期变红后复原。
---
CHANGELOG.md | 42 ++++++++
web/src/ReleaseTargets.test.tsx | 92 ++++++++++++++++-
web/src/ReleaseTargets.tsx | 176 ++++++++++++++++++++++++++++++--
web/src/librarySnapshots.ts | 81 +++++++++++++++
web/src/librarySyncAuth.test.ts | 82 +++++++++++++++
5 files changed, 460 insertions(+), 13 deletions(-)
create mode 100644 web/src/librarySyncAuth.test.ts
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 49dd5a6..ccb29c7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,47 @@
# Changelog
+## 开发快照(首次发布入口:同步授权、目标权威基线与维护能力)
+
+### Added
+
+- **管理员在发布页签发同步授权(`POST /api/v1/library/authorizations`,`action=sync`)**:
+ 授权把「范围 + 目标快照 + 参数摘要 + 有效期」钉死,仍与执行分成两步 ——
+ 页面只提供入口,不会替你签发,也不会自动重试执行。工程师看得到缺项原因,
+ 但拿不到签发按钮(接口本来就只认管理员)。
+- **目标权威基线(迁移 075,作业类型 `baseline`)**:目标非空、又没有生效版本时,
+ 首次发布的真实解法是「维护隔离 → 整库捕获 → 逐类校验 → 登记基线」。
+ `POST /api/v1/library/baselines` 只建作业;worker 用与同步同一套维护窗口
+ (关入口、停写入者、证明排空)把目标整库捕获成归档快照,再用同一套 `Verify`
+ 证明目标与这份快照一致,最后登记 `production_effective`(证据写明
+ `origin=target_baseline`、快照 ID、逐表行数、目标索引映射)。
+ 它**不写目标内容、不清空目标、不手写版本**:没有捕获与校验证据就没有基线。
+ 基线作业与 sync/restore 共用同一把写互斥(同一 scope 只允许一个在飞写作业),
+ worker 被杀时同一作业 id 会接管那个窗口继续,而不是把目标留在停机状态。
+- **维护能力(`GET /api/v1/library/maintenance` 的 `capability`)**:页面区分
+ 「此刻没有维护窗口」与「维护能力没接线」,逐项列出缺少的
+ `LIBRARY_TARGET_*`;接口没给能力信息时显示"未知",不再用一句
+ "也没有维护能力配置"糊过去。
+
+### Changed
+
+- **`productionScopeEmpty` 改成整库口径**:原来只数 `knowledges`,"文档删了但
+ 分块/Wiki/资源还在"的目标会被判成空库,从而绕过基线初始化。现在用适配层
+ 同一份表清单与范围过滤(`v071.ScopeContentEmpty`)逐表计数,并把逐表行数
+ 交回接口,"空"只有一份定义。
+- **拟发布的测试封存只认版本登记(`kind=test_sealed`)**:归档里同时存在生产
+ 预备份与目标基线快照,按"这个 scope 最新一份"挑会把目标自己的内容显示成
+ 测试候选。现在候选来自登记、再用归档确认它还在本机;不在就说明原因。
+- **发布页不再说"生产同步执行链尚未接线"**:同步按钮按真实闸口启用,
+ 点击走 `POST /api/v1/library/syncs`;被拒时逐条显示接口返回的缺项。
+- 缺项文案从"生产当前权威版本未知,不能启动写入"改为指向真实入口:
+ 「目标非空且没有生效版本记录:先建立目标权威基线…或确认目标确实是空库」。
+
+### Fixed
+
+- 维护卡片把"没有窗口记录"错误地写成"没有维护能力配置",与实际接线不符。
+- 首次发布时 `POST /library/baselines` 在目标读不到时**不建作业、不登记版本**
+ (拒绝用建基线掩盖连接/配置故障)。
+
## 开发快照(发布执行器可用性、整库还原入口与诊断)
### Added
diff --git a/web/src/ReleaseTargets.test.tsx b/web/src/ReleaseTargets.test.tsx
index 6e18f6d..b5394eb 100644
--- a/web/src/ReleaseTargets.test.tsx
+++ b/web/src/ReleaseTargets.test.tsx
@@ -92,7 +92,7 @@ const overview: LibraryOverview = {
reasons: [
'生产写入闸口关闭(PRODUCTION_RELEASE_REQUESTS_ENABLED=false)',
'没有已核验的生产恢复演练证据(PRODUCTION_BACKUP_RESTORE_VERIFIED=false)',
- '生产当前权威版本未知,不能启动写入',
+ '目标非空且没有生效版本记录:先建立目标权威基线(维护隔离下捕获整库并逐类校验),或确认目标确实是空库',
'本次目标快照还没有生产预备份',
],
},
@@ -150,6 +150,8 @@ const base: ViewProps = {
canCapture: true,
canWrite: true,
canRestore: false,
+ sync: { canSign: false, pendingGrant: false, onGrant: vi.fn(), canStart: false, pending: false, onStart: vi.fn() },
+ baseline: { canStart: false, pending: false, onStart: vi.fn() },
restore: null,
restoreNotice: null,
pendingRestore: false,
@@ -173,7 +175,7 @@ describe('ReleaseTargetsView(确认稿布局)', () => {
expect(html).toContain('对外知识库')
expect(html).toContain('role="tab"')
// 只显示一个主作业卡:选中库标题出现一次,另一个库不渲染作业卡
- expect(html.match(/· 已封存,生产同步未接入/g)?.length).toBe(1)
+ expect(html.match(/· 已封存,同步按条件放行/g)?.length).toBe(1)
expect(html).not.toContain('对外知识库 · 尚无')
})
@@ -355,8 +357,92 @@ describe('ReleaseTargetsView(确认稿布局)', () => {
})
it('无封存时给出“尚无封存”而不是空表', () => {
- const html = render({ page: { ...page, snapshots: [] } })
+ // 归档没有快照时接口也不会给 test_sealed:两处必须一致,否则页面会把
+ // 一个不存在的封存显示成"已封存"。
+ const html = render({
+ page: { ...page, snapshots: [] },
+ overview: { ...overview, test_sealed: undefined, test_sealed_reason: '还没有该目标的测试封存' },
+ })
expect(html).toContain('尚无测试封存')
expect(html).toContain('还没有测试库封存')
})
+
+ it('管理员在缺同步授权时看到签发入口,工程师只看到“需管理员签发”', () => {
+ const admin = render({
+ sync: { canSign: true, pendingGrant: false, onGrant: vi.fn(), canStart: false, pending: false, onStart: vi.fn() },
+ })
+ expect(admin).toContain('签发同步授权(30 分钟)')
+ // 授权入口不能顺手把执行也放行:闸口条件仍然逐条可见
+ expect(admin).toContain('生产写入闸口关闭')
+ const engineer = render()
+ expect(engineer).not.toContain('签发同步授权')
+ expect(engineer).toContain('同步授权只能由管理员按目标+快照签发')
+ })
+
+ it('目标非空又没有权威版本时,管理员看到建立基线入口;有生效版本时不显示', () => {
+ const admin = render({
+ baseline: { canStart: true, pending: false, onStart: vi.fn() },
+ })
+ expect(admin).toContain('建立目标权威基线(维护隔离)')
+ expect(admin).toContain('目标非空且没有生效版本记录')
+ const known = render({
+ baseline: { canStart: true, pending: false, onStart: vi.fn() },
+ overview: {
+ ...overview,
+ production: {
+ state: 'known',
+ version: {
+ id: 'v1',
+ kind: 'production_effective',
+ snapshot_id: 'a'.repeat(64),
+ version_label: '基线 abc',
+ source_job_id: 'libbase-1',
+ evidence: {},
+ created_by: 'admin',
+ created_at: '2026-10-29T09:00:00Z',
+ },
+ },
+ },
+ })
+ // 有生效版本时不再提供基线入口(缺项说明文字里仍会提到它存在,所以只断言按钮)
+ expect(known).not.toMatch(/建立目标权威基线(维护隔离)<\/button>/)
+ })
+
+ it('闸口全满足时“启动同步”真的可点,并给出执行说明', () => {
+ const html = render({
+ sync: { canSign: false, pendingGrant: false, onGrant: vi.fn(), canStart: true, pending: false, onStart: vi.fn() },
+ overview: { ...overview, gate: { sync_allowed: true, reasons: [] } },
+ })
+ expect(html).toMatch(/]*class="rel-primary"[^>]*>▶ 启动同步/)
+ expect(html).not.toMatch(/class="rel-primary"[^>]*disabled/)
+ expect(html).toContain('先固定测试版本,再备份目标并写入')
+ })
+
+ it('维护卡片区分“未运行维护”与“没有维护能力”', () => {
+ const wired = render({
+ maintenance: {
+ held: false,
+ capability: {
+ configured: true,
+ missing: [],
+ instance: 'kgseal-app',
+ project: 'kgseal-weknora',
+ writers: ['app'],
+ ingress_service: 'ingress',
+ },
+ },
+ })
+ expect(wired).toContain('未运行维护')
+ expect(wired).toContain('维护能力已接线:实例 kgseal-app · 写入者 app')
+ expect(wired).not.toContain('也没有维护能力配置')
+ const broken = render({
+ maintenance: { held: false, capability: { configured: false, missing: ['LIBRARY_TARGET_WRITERS'] } },
+ })
+ expect(broken).toContain('能力未接线')
+ expect(broken).toContain('维护能力未接线:缺少 LIBRARY_TARGET_WRITERS')
+ // 接口没给能力信息时不能猜成"没有能力"
+ const unknown = render({ maintenance: { held: false } })
+ expect(unknown).toContain('维护能力状态未知')
+ expect(unknown).not.toContain('也没有维护能力配置')
+ })
})
diff --git a/web/src/ReleaseTargets.tsx b/web/src/ReleaseTargets.tsx
index d663dcc..0988204 100644
--- a/web/src/ReleaseTargets.tsx
+++ b/web/src/ReleaseTargets.tsx
@@ -1,9 +1,12 @@
import { useCallback, useEffect, useState } from 'react'
import {
createLibraryRestoreAuthorization,
+ createLibrarySyncAuthorization,
+ enqueueLibraryBaseline,
enqueueLibraryCapture,
enqueueLibraryRecovery,
enqueueLibraryRestore,
+ enqueueLibrarySync,
fetchLibraryCaptures,
fetchLibraryMaintenance,
fetchLibraryOverview,
@@ -62,6 +65,24 @@ const jobStateLabel: Record = {
type Scope = 'internal' | 'external'
+// 签发授权与执行是两步:页面只提供入口,不会替人签发,也不会自动重试执行。
+export interface ReleaseSyncActions {
+ // 管理员才能签发;工程师看得到条件但没有按钮。
+ canSign: boolean
+ pendingGrant: boolean
+ onGrant: () => void
+ // 闸口全部满足才能启动(接口用同一份判定,按钮只是提前说明)。
+ canStart: boolean
+ pending: boolean
+ onStart: () => void
+}
+
+export interface ReleaseBaselineActions {
+ canStart: boolean
+ pending: boolean
+ onStart: () => void
+}
+
interface ScopeView {
scope: Scope
snapshot?: LibrarySnapshot
@@ -89,6 +110,10 @@ interface ViewProps {
pendingCapture: boolean
canCapture: boolean
canWrite: boolean
+ // 发布动作:签发授权(管理员)与启动同步是两个独立步骤,页面绝不自动签发。
+ sync: ReleaseSyncActions
+ // 目标非空又没有生效版本时,唯一入口是"建立目标权威基线"(管理员)。
+ baseline: ReleaseBaselineActions
// 按版本恢复是管理员动作:工程师看得到条件,但拿不到恢复入口。
canRestore: boolean
restore: LibraryRestoreAvailability | null
@@ -118,7 +143,9 @@ function scopeView(
overview?.job ?? persisted.find((item) => item.state === 'pending' || item.state === 'running') ?? persisted[0]
return {
scope,
- snapshot: history[0],
+ // 候选只认接口给的 test_sealed(来自版本登记):归档里还有生产预备份与
+ // 目标基线快照,按"最新一份"挑会把目标自己的内容显示成测试封存。
+ snapshot: overview?.test_sealed,
history,
activeJob: scoped.find((job) => ACTIVE_STATES.includes(job.state)),
lastJob: scoped[0],
@@ -271,6 +298,14 @@ export function MaintenanceCard({
}) {
const summary = maintenanceSummary(maintenance, job)
const record = maintenance?.instance_maintenance ?? maintenance?.maintenance
+ // "没有窗口记录"不等于"没有维护能力":能力是配置事实,接口单独返回。
+ // 接口没给能力信息时也不能猜,明确写"未知"。
+ const capability = maintenance?.capability
+ const capabilityText = !capability
+ ? '维护能力状态未知:接口没有返回能力信息,无法区分"未运行维护"与"能力未接线"'
+ : capability.configured
+ ? `维护能力已接线:实例 ${capability.instance || '—'} · 写入者 ${(capability.writers ?? []).join('、') || '—'}`
+ : `维护能力未接线:缺少 ${(capability.missing ?? []).join('、') || '必要配置'}`
return (
-
- {summary.held ? `${summary.level} · 占用中` : summary.level === '未接入' ? '未接入' : '未占用'}
+
+ {summary.held
+ ? `${summary.level} · 占用中`
+ : record
+ ? '未占用'
+ : capability?.configured
+ ? '未运行维护'
+ : capability
+ ? '能力未接线'
+ : '能力未知'}
- {summary.level === '未接入' ? (
+ {!record ? (
- 暂无维护窗口记录,也没有维护能力配置;维护类操作保持 fail closed,不会在此状态下写目标。
+ 暂无维护窗口记录。{capabilityText}
+ {capability?.configured
+ ? ';窗口只在同步或建立基线时开启,页面不会单独开窗口。'
+ : ';维护类操作保持 fail closed,不会在此状态下写目标。'}
) : (
<>
@@ -534,15 +582,23 @@ function ProtectionCard({
prebackup,
gate,
authorization,
+ targetSealed,
+ sync,
+ baseline,
onOpen,
}: {
production: LibraryOverview['production']
prebackup: LibraryOverview['prebackup']
gate: LibraryOverview['gate']
authorization: LibraryOverview['authorization']
+ targetSealed: boolean
+ sync: ReleaseSyncActions
+ baseline: ReleaseBaselineActions
onOpen: () => void
}) {
const backupKnown = prebackup.state === 'known' && prebackup.version
+ // 基线入口只在"目标非空、却没有生效版本"时才是答案;空库走首次同步(预备份+登记)。
+ const baselineNeeded = production.state !== 'known' && targetSealed
return (