Files
knowledge-governance/docs/library-target-id-mapping.md
T
姚章浩 e0fc2c32b8
build / build (push) Successful in 2m11s
feat(library): 目标库隔离 ID 映射并保留旧库
同实例第二个目标 KB 与旧库共享源 UUID 时,计划/写入/校验/恢复按目标范围派生稳定身份;
计划持久化 target_id_mode,旧计划与写前镜像不二次映射;资源保持共享 ID。
2026-11-04 12:07:27 +08:00

2.9 KiB
Raw Blame History

目标库隔离 ID 映射

同一 WeKnora 实例里可以有多个知识库。同步把源快照写进目标库时,如果沿用源库的 UUID 主键, 第二个目标库会与实例里已有库的行撞主键(真实证据:2 knowledges / 2 chunks / 23 wiki_pages / 17 wiki_folders 已存在于旧库),写入前的跨范围检查会拒绝整次同步。关闭检查等于让两个库共享身份, 删除/恢复/校验会互相误伤,因此身份必须在目标侧派生。

映射规则

digest = sha256("knowledge-governance/target-identity/v1" || tenant || kb || table || source_id)
target_id = 前 16 字节按 8-4-4-4-12 十六进制格式化(置 RFC 4122 variant/version 位)

这是本产品自定义的稳定 ID 算法(target_id_mode=scoped-sha256-v1),只保证确定性与目标隔离; 它不是标准 RFC 4122 UUIDv5(UUIDv5 用 SHA-1 + 标准 namespace),不要按 UUIDv5 互操作。

  • 只绑定稳定目标身份(目标 tenant、目标 KB)与源身份,表名参与命名空间;
  • 不绑定 job、时间、快照版本等瞬态值:同一目标重复同步/重试/跨版本得到同一 ID;
  • 不同目标 KB、不同表得到不同 ID;
  • 源归档字节不变,映射只存在于目标侧派生视图(写集合、写入行、索引文档、校验预期);
  • 计划把策略持久化为 target_id_mode=scoped-sha256-v1:新进程按该字段重建映射,旧计划/写前镜像 没有该字段则按原 ID 回放,绝不二次映射。

参与映射的表与字段

表 身份 引用字段
knowledges id —
chunks id knowledge_id, tag_id, parent_chunk_id, pre_chunk_id, next_chunk_id, relation_chunks, indirect_relation_chunks, metadata(仅精确匹配)
knowledge_tags id —
knowledge_tag_relations (knowledge_id, tag_id) 两个分量分别映射
wiki_folders id parent_id
wiki_pages id folder_id, chunk_refs, source_refs(保留 `id
wiki_page_issues id page_id, knowledge_id, chunk_id
resource_bindings id owner_id(按 owner_type)
resources 不映射 resource_id 保持共享身份
索引文档 文档物理 ID chunk_id, knowledge_id, source_id, tag_id

正文、标题、摘要、向量、slug、in_links/out_links、pages_affected 不改写;本地自增列 (如 wiki_log_entries.id)仍由既有 LocalIDs 分配。引用指向未登记身份时拒绝(悬挂引用不静默放行)。

一致性边界

  • 写集合登记的是目标身份;verify 的身份摘要与内容摘要都按同一 rowTransform 计算;
  • 索引计划的目标文档 ID 与 _source 引用同步映射,before-image(目标写前镜像)保持原样;
  • 恢复重放写前镜像时映射关闭,避免把目标原始 ID 再映射一次;
  • 资源对象路径/location_hash 仍由既有资源改写逻辑处理,不因 ID 映射而变化。