feat: 知识治理平台(含已验证发布/回滚契约)
全栈知识治理平台首次入库(P1-P10 + 发布链路模拟验证闭环): - 治理核心:源目录/变更集/人工审核/发布批次/发布执行(fail-closed 闸口) - 测试通道:WeKnora 测试 KB 上传/轮询/验收;poll 完成时写入 parser_generation/index_generation,修复 manual/seed 路径发布闸口永久拦截 - 发布适配器 v071(本地 source=测试角色 / 云端 target=生产角色 模拟验证通过): * ES 导出/导入 mapping 自适应(.keyword 子字段、可选 tenant_id) * OSS locator 支持嵌套 scheme;chunks.seq_id 由目标序列分配 * bundle 归档同身份重试原子替换;verifier 按 bundle chunk_type 计数 * 回滚 job payload 支持 prior_execution_id(strict 解码) - 三通道发布+回滚演练实测:publish 4/4 verified,检索命中, rollback 4/4 rolled_back,目标端 PG is_enabled=false、ES is_enabled=false - 前端 A·Data-console 风格全站统一,120 用例通过 - 门禁:go vet / go test 全包通过,gofmt 干净
This commit is contained in:
@@ -0,0 +1,187 @@
|
||||
package releasebundle
|
||||
|
||||
import (
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"sort"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
const (
|
||||
FormatVersionV1 = "weknora-release-bundle/v1"
|
||||
WeKnoraVersionV071 = "v0.7.1"
|
||||
WeKnoraMigrationV071 = 74
|
||||
EmbeddingDimensionV071 = 1024
|
||||
)
|
||||
|
||||
var allowedTables = map[string]bool{
|
||||
"knowledges": true,
|
||||
"chunks": true,
|
||||
"knowledge_tags": true,
|
||||
"knowledge_tag_relations": true,
|
||||
"resources": true,
|
||||
"resource_bindings": true,
|
||||
"wiki_pages": true,
|
||||
"wiki_folders": true,
|
||||
}
|
||||
|
||||
type Manifest struct {
|
||||
FormatVersion string `json:"format_version"`
|
||||
ExecutionID string `json:"execution_id"`
|
||||
PublicationID string `json:"publication_id"`
|
||||
SourceItemVersionID string `json:"source_item_version_id"`
|
||||
SourceRevision string `json:"source_revision"`
|
||||
ParseRevision string `json:"parse_revision"`
|
||||
ReleaseRevision string `json:"release_revision"`
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
Contract Contract `json:"contract"`
|
||||
Tables []TableDigest `json:"tables"`
|
||||
Search SearchDigest `json:"search"`
|
||||
Assets AssetDigest `json:"assets"`
|
||||
BundleSHA256 string `json:"bundle_sha256"`
|
||||
}
|
||||
|
||||
type Contract struct {
|
||||
WeKnoraVersion string `json:"weknora_version"`
|
||||
MigrationVersion int `json:"migration_version"`
|
||||
TenantID uint64 `json:"tenant_id"`
|
||||
KnowledgeBaseID string `json:"knowledge_base_id"`
|
||||
KnowledgeID string `json:"knowledge_id"`
|
||||
RetrieverEngine string `json:"retriever_engine"`
|
||||
EmbeddingModel string `json:"embedding_model"`
|
||||
EmbeddingDimension int `json:"embedding_dimension"`
|
||||
ElasticsearchMappingSHA256 string `json:"elasticsearch_mapping_sha256"`
|
||||
}
|
||||
|
||||
type TargetContract struct {
|
||||
WeKnoraVersion string
|
||||
MigrationVersion int
|
||||
TenantID uint64
|
||||
KnowledgeBaseID string
|
||||
RetrieverEngine string
|
||||
EmbeddingModel string
|
||||
EmbeddingDimension int
|
||||
ElasticsearchMappingSHA256 string
|
||||
}
|
||||
|
||||
type TableDigest struct {
|
||||
Name string `json:"name"`
|
||||
RowCount int `json:"row_count"`
|
||||
SHA256 string `json:"sha256"`
|
||||
}
|
||||
|
||||
type SearchDigest struct {
|
||||
DocumentCount int `json:"document_count"`
|
||||
SHA256 string `json:"sha256"`
|
||||
}
|
||||
|
||||
type AssetDigest struct {
|
||||
ObjectCount int `json:"object_count"`
|
||||
TotalBytes int64 `json:"total_bytes"`
|
||||
SHA256 string `json:"sha256"`
|
||||
}
|
||||
|
||||
func Seal(manifest Manifest) (Manifest, error) {
|
||||
manifest.BundleSHA256 = ""
|
||||
manifest.Tables = append([]TableDigest(nil), manifest.Tables...)
|
||||
sort.Slice(manifest.Tables, func(left, right int) bool { return manifest.Tables[left].Name < manifest.Tables[right].Name })
|
||||
if err := validateManifestFields(manifest); err != nil {
|
||||
return Manifest{}, err
|
||||
}
|
||||
digest, err := manifestDigest(manifest)
|
||||
if err != nil {
|
||||
return Manifest{}, err
|
||||
}
|
||||
manifest.BundleSHA256 = digest
|
||||
return manifest, nil
|
||||
}
|
||||
|
||||
func Validate(manifest Manifest, target TargetContract) error {
|
||||
if err := validateManifestFields(manifest); err != nil {
|
||||
return err
|
||||
}
|
||||
if !validSHA256(manifest.BundleSHA256) {
|
||||
return errors.New("invalid bundle digest")
|
||||
}
|
||||
expected, err := manifestDigest(manifest)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if expected != manifest.BundleSHA256 {
|
||||
return errors.New("bundle digest mismatch")
|
||||
}
|
||||
contract := manifest.Contract
|
||||
if target.WeKnoraVersion != WeKnoraVersionV071 || target.MigrationVersion != WeKnoraMigrationV071 ||
|
||||
contract.WeKnoraVersion != target.WeKnoraVersion || contract.MigrationVersion != target.MigrationVersion ||
|
||||
contract.TenantID != target.TenantID || contract.KnowledgeBaseID != target.KnowledgeBaseID ||
|
||||
contract.RetrieverEngine != target.RetrieverEngine || contract.EmbeddingModel != target.EmbeddingModel ||
|
||||
contract.EmbeddingDimension != target.EmbeddingDimension ||
|
||||
contract.ElasticsearchMappingSHA256 != target.ElasticsearchMappingSHA256 {
|
||||
return errors.New("target release contract mismatch")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func validateManifestFields(manifest Manifest) error {
|
||||
if manifest.FormatVersion != FormatVersionV1 || manifest.Contract.WeKnoraVersion != WeKnoraVersionV071 ||
|
||||
manifest.Contract.MigrationVersion != WeKnoraMigrationV071 || manifest.Contract.EmbeddingDimension != EmbeddingDimensionV071 ||
|
||||
manifest.Contract.RetrieverEngine != "elasticsearch_v8" || manifest.Contract.TenantID == 0 || manifest.CreatedAt.IsZero() {
|
||||
return errors.New("unsupported release contract")
|
||||
}
|
||||
for _, value := range []string{manifest.ExecutionID, manifest.PublicationID, manifest.SourceItemVersionID,
|
||||
manifest.SourceRevision, manifest.ParseRevision, manifest.ReleaseRevision, manifest.Contract.KnowledgeBaseID,
|
||||
manifest.Contract.KnowledgeID, manifest.Contract.EmbeddingModel} {
|
||||
if !validIdentifier(value) {
|
||||
return errors.New("invalid release identity")
|
||||
}
|
||||
}
|
||||
if !validSHA256(manifest.Contract.ElasticsearchMappingSHA256) || !validSHA256(manifest.Search.SHA256) || !validSHA256(manifest.Assets.SHA256) ||
|
||||
manifest.Search.DocumentCount < 0 || manifest.Assets.ObjectCount < 0 || manifest.Assets.TotalBytes < 0 {
|
||||
return errors.New("invalid release digest")
|
||||
}
|
||||
seen := make(map[string]bool, len(manifest.Tables))
|
||||
hasKnowledge, hasChunks := false, false
|
||||
for _, table := range manifest.Tables {
|
||||
if !allowedTables[table.Name] || seen[table.Name] || table.RowCount < 0 || !validSHA256(table.SHA256) {
|
||||
return errors.New("invalid release table")
|
||||
}
|
||||
seen[table.Name] = true
|
||||
hasKnowledge = hasKnowledge || table.Name == "knowledges" && table.RowCount == 1
|
||||
hasChunks = hasChunks || table.Name == "chunks" && table.RowCount > 0
|
||||
}
|
||||
if !hasKnowledge || !hasChunks {
|
||||
return errors.New("release manifest requires one knowledge and at least one chunk")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func manifestDigest(manifest Manifest) (string, error) {
|
||||
manifest.BundleSHA256 = ""
|
||||
manifest.Tables = append([]TableDigest(nil), manifest.Tables...)
|
||||
sort.Slice(manifest.Tables, func(left, right int) bool { return manifest.Tables[left].Name < manifest.Tables[right].Name })
|
||||
payload, err := json.Marshal(manifest)
|
||||
if err != nil {
|
||||
return "", errors.New("encode release manifest")
|
||||
}
|
||||
digest := sha256.Sum256(payload)
|
||||
return hex.EncodeToString(digest[:]), nil
|
||||
}
|
||||
|
||||
func validSHA256(value string) bool {
|
||||
if len(value) != 64 {
|
||||
return false
|
||||
}
|
||||
for _, char := range value {
|
||||
if (char < '0' || char > '9') && (char < 'a' || char > 'f') {
|
||||
return false
|
||||
}
|
||||
}
|
||||
return true
|
||||
}
|
||||
|
||||
func validIdentifier(value string) bool {
|
||||
return value == strings.TrimSpace(value) && value != "" && len(value) <= 128 && !strings.ContainsAny(value, "\x00\r\n\t/?#\\")
|
||||
}
|
||||
@@ -0,0 +1,119 @@
|
||||
package releasebundle
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
func TestSealAndValidateV071Manifest(t *testing.T) {
|
||||
manifest := Manifest{
|
||||
FormatVersion: "weknora-release-bundle/v1",
|
||||
ExecutionID: "rx-safe", PublicationID: "tp-safe", SourceItemVersionID: "sv-safe",
|
||||
SourceRevision: "source-v1", ParseRevision: "parser-v1@index-v1", ReleaseRevision: "release-v1",
|
||||
CreatedAt: time.Date(2026, 9, 6, 8, 0, 0, 0, time.UTC),
|
||||
Contract: Contract{
|
||||
WeKnoraVersion: "v0.7.1", MigrationVersion: 74, TenantID: 10000,
|
||||
KnowledgeBaseID: "kb-safe", KnowledgeID: "knowledge-safe",
|
||||
RetrieverEngine: "elasticsearch_v8", EmbeddingModel: "bge-m3", EmbeddingDimension: 1024,
|
||||
ElasticsearchMappingSHA256: strings.Repeat("a", 64),
|
||||
},
|
||||
Tables: []TableDigest{
|
||||
{Name: "chunks", RowCount: 2, SHA256: strings.Repeat("b", 64)},
|
||||
{Name: "knowledge_tags", RowCount: 1, SHA256: strings.Repeat("f", 64)},
|
||||
{Name: "knowledges", RowCount: 1, SHA256: strings.Repeat("c", 64)},
|
||||
},
|
||||
Search: SearchDigest{DocumentCount: 2, SHA256: strings.Repeat("d", 64)},
|
||||
Assets: AssetDigest{ObjectCount: 1, TotalBytes: 42, SHA256: strings.Repeat("e", 64)},
|
||||
}
|
||||
sealed, err := Seal(manifest)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if len(sealed.BundleSHA256) != 64 {
|
||||
t.Fatalf("bundle sha=%q", sealed.BundleSHA256)
|
||||
}
|
||||
target := TargetContract{
|
||||
WeKnoraVersion: "v0.7.1", MigrationVersion: 74, TenantID: 10000,
|
||||
KnowledgeBaseID: "kb-safe", RetrieverEngine: "elasticsearch_v8",
|
||||
EmbeddingModel: "bge-m3", EmbeddingDimension: 1024,
|
||||
ElasticsearchMappingSHA256: strings.Repeat("a", 64),
|
||||
}
|
||||
if err := Validate(sealed, target); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
encoded, err := json.Marshal(sealed)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for _, forbidden := range []string{"endpoint", "password", "secret", "api_key", "physical_path", "database_url"} {
|
||||
if strings.Contains(strings.ToLower(string(encoded)), forbidden) {
|
||||
t.Fatalf("manifest leaked forbidden field %q", forbidden)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestSealCanonicalizesTableOrder(t *testing.T) {
|
||||
base := validManifest()
|
||||
first, err := Seal(base)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
base.Tables[0], base.Tables[1] = base.Tables[1], base.Tables[0]
|
||||
second, err := Seal(base)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if first.BundleSHA256 != second.BundleSHA256 {
|
||||
t.Fatalf("digest differs: %s vs %s", first.BundleSHA256, second.BundleSHA256)
|
||||
}
|
||||
}
|
||||
|
||||
func TestValidateRejectsContractDriftAndUnknownTables(t *testing.T) {
|
||||
manifest, err := Seal(validManifest())
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
target := validTarget()
|
||||
tests := []struct {
|
||||
name string
|
||||
mutate func(*Manifest, *TargetContract)
|
||||
}{
|
||||
{name: "version", mutate: func(_ *Manifest, target *TargetContract) { target.WeKnoraVersion = "v0.7.2" }},
|
||||
{name: "migration", mutate: func(_ *Manifest, target *TargetContract) { target.MigrationVersion = 73 }},
|
||||
{name: "kb", mutate: func(_ *Manifest, target *TargetContract) { target.KnowledgeBaseID = "other" }},
|
||||
{name: "embedding", mutate: func(_ *Manifest, target *TargetContract) { target.EmbeddingDimension = 768 }},
|
||||
{name: "mapping", mutate: func(_ *Manifest, target *TargetContract) { target.ElasticsearchMappingSHA256 = strings.Repeat("f", 64) }},
|
||||
{name: "unknown table", mutate: func(manifest *Manifest, _ *TargetContract) {
|
||||
manifest.Tables = append(manifest.Tables, TableDigest{Name: "users", RowCount: 1, SHA256: strings.Repeat("1", 64)})
|
||||
}},
|
||||
{name: "tampered bundle", mutate: func(manifest *Manifest, _ *TargetContract) { manifest.Search.DocumentCount++ }},
|
||||
{name: "missing parse revision", mutate: func(manifest *Manifest, _ *TargetContract) { manifest.ParseRevision = "" }},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
candidate, contract := manifest, target
|
||||
candidate.Tables = append([]TableDigest(nil), manifest.Tables...)
|
||||
tt.mutate(&candidate, &contract)
|
||||
if err := Validate(candidate, contract); err == nil {
|
||||
t.Fatal("Validate() error=nil")
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func validManifest() Manifest {
|
||||
return Manifest{
|
||||
FormatVersion: "weknora-release-bundle/v1", ExecutionID: "rx-safe", PublicationID: "tp-safe",
|
||||
SourceItemVersionID: "sv-safe", SourceRevision: "source-v1", ParseRevision: "parser-v1@index-v1", ReleaseRevision: "release-v1",
|
||||
CreatedAt: time.Date(2026, 9, 6, 8, 0, 0, 0, time.UTC),
|
||||
Contract: Contract{WeKnoraVersion: "v0.7.1", MigrationVersion: 74, TenantID: 10000, KnowledgeBaseID: "kb-safe", KnowledgeID: "knowledge-safe", RetrieverEngine: "elasticsearch_v8", EmbeddingModel: "bge-m3", EmbeddingDimension: 1024, ElasticsearchMappingSHA256: strings.Repeat("a", 64)},
|
||||
Tables: []TableDigest{{Name: "knowledges", RowCount: 1, SHA256: strings.Repeat("b", 64)}, {Name: "chunks", RowCount: 1, SHA256: strings.Repeat("c", 64)}},
|
||||
Search: SearchDigest{DocumentCount: 1, SHA256: strings.Repeat("d", 64)}, Assets: AssetDigest{SHA256: strings.Repeat("e", 64)},
|
||||
}
|
||||
}
|
||||
|
||||
func validTarget() TargetContract {
|
||||
return TargetContract{WeKnoraVersion: "v0.7.1", MigrationVersion: 74, TenantID: 10000, KnowledgeBaseID: "kb-safe", RetrieverEngine: "elasticsearch_v8", EmbeddingModel: "bge-m3", EmbeddingDimension: 1024, ElasticsearchMappingSHA256: strings.Repeat("a", 64)}
|
||||
}
|
||||
Reference in New Issue
Block a user