98294b9583
build / build (push) Failing after 24s
why:审计 19 项(12 P1 / 7 P2)来自同一批根因,逐点试错会把协议撕成十几份:
· 意图与执行混为一谈(F01/F15):`library.sync:<scope>:<快照>` 是终身幂等键,
A→B→A 的第三次发布拿到第一次的历史成功作业,什么都不做;
· 版本行既是实体又是事件(F02/F09):主键只由 (kind,scope,快照) 决定、写入是
upsert,第二个作业覆盖 `source_job_id`/`evidence`/`created_at`;
· 接管没有代次(F13):两个 worker 都能认领同一 pending 作业,失租的旧执行还能
写业务状态、释放别人的维护锁;
· 早退与终态没有统一政策(F03/F04/F05/F06):半写窗口的前置检查失败会重新开门、
服务起不来也照样开入口、journal 终态后收尾不可重建、恢复成功不回写 current;
· 数据身份与准入各写一套(F07/F08/F14/F17):接管丢了复用语义、全库搬运不改
location_hash、通用入口可造 library.* 作业、目标模型从没被问过;
· 存储/容量/UI/CI 判据各自为政(F10/F11/F12/F16/F18/F19)。
what:按批准的一套协议集中实施(详见 handoffs/release-consolidated-implementation/
current-contract.md):
· operation(一次明确意图)/ attempt(epoch 代次)/ 不可变版本事件 / current 指针;
治理库迁移 76,只动治理库,不碰 WeKnora Schema/源码/镜像;
· 所有业务状态、阶段、版本事件、维护锁写入带 epoch 守卫(失租代次写不进去);
心跳失租立刻取消 handler;
· 半写窗口早退保持关闭;服务未全部健康绝不开入口;journal 终态可从持久事实重建
收尾;恢复成功登记 recovery 事件并推进 current;
· worker 在动维护前核对业务行/kind/scope/队列关联;通用入口拒绝 library.*;
· 全库搬运重算 location_hash 并与文档级导入共用实现;接管消费写集合的复用决定;
发布前核目标实时模型契约、容量门禁前置;
· 存储保护闭包改为全量依赖、类型只认显式登记、保护未知则不出可删候选;
· 页面核 HTTP 状态与结构、恢复纳入轮询、Wiki 差异覆盖标题/摘要/父级。
how:`make verify` rc=0(16 项必需检查全绿,含 go test 全量与前端 485 例);
`go vet ./...` rc=0;`npx tsc -p tsconfig.json --noEmit` rc=0;逐项负例见各包测试
(F03/F04/F08/F12/F13/F14/F16/F18/F19 都有先红后绿记录)。
未执行:治理库迁移到任何已有库、真实 PG/ES/S3/WeKnora 集成、故障注入、部署。
285 lines
11 KiB
Go
285 lines
11 KiB
Go
package v071
|
||
|
||
import (
|
||
"context"
|
||
"crypto/sha256"
|
||
"encoding/hex"
|
||
"encoding/json"
|
||
"errors"
|
||
"fmt"
|
||
"strconv"
|
||
"strings"
|
||
)
|
||
|
||
// 整库同步是"把来源知识库的内容搬到目标的租户/知识库",但归档行带着来源身份
|
||
// (tenant_id / knowledge_base_id)。原样插入会让行落在来源范围里:目标范围的
|
||
// 删除、校验、预备份与恢复全都看不见它们(真实事故:同步失败后"已恢复到预备份",
|
||
// 目标却多出 4 文件 / 38 分块 / 21 资源 / 4 绑定,行所属租户还是来源租户)。
|
||
//
|
||
// 因此写入与校验必须共用这一个改写入口,并且对不上就失败——宁可不写,也不写
|
||
// 一行目标范围外的数据。
|
||
|
||
// tablesWithKB 是真实 WeKnora v0.7.1 里带 knowledge_base_id 的知识域表。
|
||
// resources / resource_bindings 是多知识库共享表,只有 tenant_id;
|
||
// knowledge_tag_relations 两列都没有,归属完全由父表 knowledges 决定。
|
||
var tablesWithKB = map[string]bool{
|
||
"knowledges": true, "chunks": true, "knowledge_tags": true,
|
||
"wiki_folders": true, "wiki_pages": true, "wiki_page_issues": true, "wiki_log_entries": true,
|
||
}
|
||
|
||
// tableHasTenant 报告这张表是否自带租户列。
|
||
func tableHasTenant(table string) bool { return table != "knowledge_tag_relations" }
|
||
|
||
// bindSnapshotScope 记下快照的来源身份。没有来源身份就无法判断"这行要搬到哪个
|
||
// 范围",宁可失败也不要按行内容猜。
|
||
func (t *ProductionLibraryTarget) bindSnapshotScope(manifest manifestScope) error {
|
||
if manifest.tenantID == 0 || !validSearchIdentifier(manifest.knowledgeBaseID) {
|
||
return errors.New("快照缺少来源范围身份(tenant_id / knowledge_base_id),无法确定目标范围映射")
|
||
}
|
||
t.snapshotTenant = manifest.tenantID
|
||
t.snapshotKB = manifest.knowledgeBaseID
|
||
return nil
|
||
}
|
||
|
||
// manifestScope 只是把快照的两个范围字段抽出来,避免调用点重复解构。
|
||
type manifestScope struct {
|
||
tenantID uint64
|
||
knowledgeBaseID string
|
||
}
|
||
|
||
// retargetRow 把一行归档数据改写成目标范围的数据:tenant_id / knowledge_base_id
|
||
// 换成目标身份,资源行还要把定位符、存储后端、提供方换成目标实例自己的值。
|
||
func (t *ProductionLibraryTarget) retargetRow(table string, row map[string]json.RawMessage) error {
|
||
if !tableHasTenant(table) {
|
||
return nil
|
||
}
|
||
if err := t.retargetTenantField(row); err != nil {
|
||
return fmt.Errorf("%s:%w", table, err)
|
||
}
|
||
if tablesWithKB[table] {
|
||
if err := t.retargetKnowledgeBaseField(row); err != nil {
|
||
return fmt.Errorf("%s:%w", table, err)
|
||
}
|
||
}
|
||
if table == "resources" {
|
||
return t.rewriteResourceIdentity(row)
|
||
}
|
||
if table == "knowledges" {
|
||
return t.retargetEmbeddingModelField(row)
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// retargetEmbeddingModelField 把文档的 embedding 模型换成目标知识库绑定的那一个。
|
||
// 来源模型 id 在目标实例里通常不存在(目标 models 表可能是空的),留着它等于让
|
||
// 应用拿一个解析不到的模型去查——库里的向量与查询向量就不是同一套了。
|
||
func (t *ProductionLibraryTarget) retargetEmbeddingModelField(row map[string]json.RawMessage) error {
|
||
if t.targetEmbeddingModel == "" {
|
||
return nil
|
||
}
|
||
if _, ok := row["embedding_model_id"]; !ok {
|
||
return nil
|
||
}
|
||
encoded, err := json.Marshal(t.targetEmbeddingModel)
|
||
if err != nil {
|
||
return errors.New("编码目标 embedding 模型失败")
|
||
}
|
||
row["embedding_model_id"] = encoded
|
||
return nil
|
||
}
|
||
|
||
// resolveEmbeddingModel 读目标知识库自己的 embedding 模型 id。读不到不算错误
|
||
// (目标可能确实没绑模型),此时保持来源值不动,由契约校验去发现不一致。
|
||
func (t *ProductionLibraryTarget) resolveEmbeddingModel(ctx context.Context) {
|
||
var model string
|
||
if err := t.pool.QueryRow(ctx,
|
||
`SELECT coalesce(embedding_model_id,'') FROM knowledge_bases WHERE id=$1 AND tenant_id=$2`,
|
||
t.scope.KnowledgeBaseID, t.scope.TenantID).Scan(&model); err == nil {
|
||
t.targetEmbeddingModel = model
|
||
}
|
||
}
|
||
|
||
func (t *ProductionLibraryTarget) retargetTenantField(row map[string]json.RawMessage) error {
|
||
raw, ok := row["tenant_id"]
|
||
if !ok {
|
||
return errors.New("行缺少 tenant_id,无法确定要写入哪个范围")
|
||
}
|
||
var current uint64
|
||
if err := json.Unmarshal(raw, ¤t); err != nil {
|
||
return errors.New("行 tenant_id 不可解析")
|
||
}
|
||
if t.snapshotTenant == 0 {
|
||
return errors.New("快照来源租户未知,拒绝猜测目标租户")
|
||
}
|
||
if current != t.snapshotTenant {
|
||
return fmt.Errorf("行 tenant_id=%d 不属于快照来源租户 %d", current, t.snapshotTenant)
|
||
}
|
||
encoded, err := json.Marshal(t.scope.TenantID)
|
||
if err != nil {
|
||
return errors.New("编码目标租户失败")
|
||
}
|
||
row["tenant_id"] = encoded
|
||
return nil
|
||
}
|
||
|
||
func (t *ProductionLibraryTarget) retargetKnowledgeBaseField(row map[string]json.RawMessage) error {
|
||
raw, ok := row["knowledge_base_id"]
|
||
if !ok {
|
||
return errors.New("行缺少 knowledge_base_id,无法确定要写入哪个知识库")
|
||
}
|
||
var current string
|
||
if err := json.Unmarshal(raw, ¤t); err != nil || current == "" {
|
||
return errors.New("行 knowledge_base_id 不可解析")
|
||
}
|
||
if t.snapshotKB == "" {
|
||
return errors.New("快照来源知识库未知,拒绝猜测目标知识库")
|
||
}
|
||
if current != t.snapshotKB {
|
||
return fmt.Errorf("行 knowledge_base_id=%s 不属于快照来源知识库 %s", current, t.snapshotKB)
|
||
}
|
||
encoded, err := json.Marshal(t.scope.KnowledgeBaseID)
|
||
if err != nil {
|
||
return errors.New("编码目标知识库失败")
|
||
}
|
||
row["knowledge_base_id"] = encoded
|
||
return nil
|
||
}
|
||
|
||
// rewriteResourceIdentity 把资源行的定位符与提供方换成目标实例的值。
|
||
//
|
||
// 只换桶不够:来源行的 scheme(oss/minio…)与对象键里的租户段也是来源实例的,
|
||
// 目标实例按它取文件会落到别的提供方或别的租户前缀上(真跑:storage backend
|
||
// not found → invalid path → 500 code1007)。
|
||
func (t *ProductionLibraryTarget) rewriteResourceIdentity(row map[string]json.RawMessage) error {
|
||
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, err := retargetLocator(locator, t.storageBackend, t.storageProvider, t.config.ObjectsBucket,
|
||
t.snapshotTenant, t.scope.TenantID)
|
||
if err != nil {
|
||
return err
|
||
}
|
||
if rewritten != locator {
|
||
encoded, err := json.Marshal(rewritten)
|
||
if err != nil {
|
||
return errors.New("编码目标定位符失败")
|
||
}
|
||
row["physical_path"] = encoded
|
||
}
|
||
// location_hash 的契约是 sha256(最终 physical_path),不是"来源路径的哈希"。
|
||
// 旧实现只换路径不重算哈希:目标行声明的是一个不存在的定位符,去重/按路径定位
|
||
// 都会失效;而写入与校验复用同一个转换函数,内部自比根本发现不了(F08)。
|
||
// 这里在同一个转换里重算,校验侧另有独立 oracle(测试里直接用 crypto/sha256 复算)。
|
||
if _, ok := row["location_hash"]; ok {
|
||
encoded, err := json.Marshal(resourceLocationHash(rewritten))
|
||
if err != nil {
|
||
return errors.New("编码目标定位符哈希失败")
|
||
}
|
||
row["location_hash"] = encoded
|
||
}
|
||
if t.storageBackend != "" {
|
||
if _, ok := row["storage_backend_id"]; ok {
|
||
encoded, err := json.Marshal(t.storageBackend)
|
||
if err != nil {
|
||
return errors.New("编码目标存储后端失败")
|
||
}
|
||
row["storage_backend_id"] = encoded
|
||
}
|
||
}
|
||
if t.storageProvider != "" {
|
||
if _, ok := row["provider"]; ok {
|
||
encoded, err := json.Marshal(t.storageProvider)
|
||
if err != nil {
|
||
return errors.New("编码目标提供方失败")
|
||
}
|
||
row["provider"] = encoded
|
||
}
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// resourceLocationHash 是 `location_hash` 契约的**唯一实现**:sha256(最终 physical_path)。
|
||
//
|
||
// 全库搬运(本文件)与文档级导入(postgres_import.go)必须用同一个函数:
|
||
// 两条路径各写一份,迟早只改一边,而目标实例正是按这个哈希去重/定位资源的。
|
||
func resourceLocationHash(physicalPath string) string {
|
||
sum := sha256.Sum256([]byte(physicalPath))
|
||
return hex.EncodeToString(sum[:])
|
||
}
|
||
|
||
// retargetLocator 把 "storage://<backend>/<scheme>://<bucket>/<key>" 整体换成目标
|
||
// 实例的真实取值:后端 id、scheme/提供方、桶名,以及对象键里的租户段。
|
||
// 桶名为空表示目标没有配置对象存储(测试夹具),此时不动定位符。
|
||
func retargetLocator(locator, backendID, provider, bucket string, sourceTenant, targetTenant uint64) (string, error) {
|
||
if bucket == "" || locator == "" {
|
||
return locator, nil
|
||
}
|
||
if locator != strings.TrimSpace(locator) {
|
||
return "", errors.New("资源定位符带首尾空白")
|
||
}
|
||
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]) || parts[1] == "" {
|
||
return "", errors.New("资源定位符结构不可解析")
|
||
}
|
||
if backendID != "" {
|
||
if !validSearchIdentifier(backendID) {
|
||
return "", errors.New("目标存储后端 id 形状不合法")
|
||
}
|
||
parts[0] = backendID
|
||
}
|
||
prefix, rest = "storage://"+parts[0]+"/", parts[1]
|
||
}
|
||
separator := strings.Index(rest, "://")
|
||
if separator < 0 {
|
||
// 裸对象键没有桶与租户段:落盘按配置桶,改写无意义。
|
||
return locator, nil
|
||
}
|
||
scheme := rest[:separator]
|
||
if !validSearchIdentifier(scheme) {
|
||
return "", errors.New("资源定位符的提供方不可解析")
|
||
}
|
||
schemeless := rest[separator+3:]
|
||
boundary := strings.Index(schemeless, "/")
|
||
if boundary <= 0 || boundary == len(schemeless)-1 {
|
||
return "", errors.New("资源定位符缺少对象键")
|
||
}
|
||
key := schemeless[boundary+1:]
|
||
if provider != "" {
|
||
if !validSearchIdentifier(provider) {
|
||
return "", errors.New("目标提供方形状不合法")
|
||
}
|
||
scheme = provider
|
||
}
|
||
return prefix + scheme + "://" + bucket + "/" + retargetKeyTenant(key, sourceTenant, targetTenant), nil
|
||
}
|
||
|
||
// retargetKeyTenant 把对象键里的来源租户段换成目标租户,并丢掉来源实例自己的
|
||
// 路径前缀(例如 MINIO_PATH_PREFIX=weknora/),让键与目标实例的写法一致。
|
||
// 找不到来源租户段时原样返回:此时键本身不含跨租户引用。
|
||
func retargetKeyTenant(key string, sourceTenant, targetTenant uint64) string {
|
||
if sourceTenant == 0 || targetTenant == 0 || sourceTenant == targetTenant {
|
||
return key
|
||
}
|
||
source, target := strconv.FormatUint(sourceTenant, 10), strconv.FormatUint(targetTenant, 10)
|
||
segments := strings.Split(key, "/")
|
||
for index := 0; index < len(segments) && index < 2; index++ {
|
||
// 只有"后面还有内容"的段才是路径前缀;整键就是租户号时不该动它。
|
||
if index >= len(segments)-1 || segments[index] != source {
|
||
continue
|
||
}
|
||
kept := segments[index:]
|
||
kept[0] = target
|
||
return strings.Join(kept, "/")
|
||
}
|
||
return key
|
||
}
|