Files
knowledge-governance/internal/releasebundle/manifest.go
T
zheromiku dcdc8d1ddd 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 干净
2026-09-30 10:54:06 +08:00

188 lines
6.6 KiB
Go

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/?#\\")
}