Docs
文档目录

知识库版本管理(Versions)

版本管理(Versions) 是 Agentbase v2.10.0 知识库面向生产环境零停机演进与变更审计打造的不可变快照治理体系。通过知识库详情页的 版本管理(Versions) 页签,团队可以将未启用版本化的存量知识库平滑迁移至版本化管理(版本采纳 Adoption),基于任意就绪快照创建隔离的可编辑工作副本(Working Copy / DRAFT),在副本内安全完成文档增删、分块调优与高级索引构建,通过严格的就绪门禁检查(Readiness Gate)后将其封存(Seal)为不可变只读版本(READY),并一键发布(Publish)切换为线上当前激活版本,或在出现业务异常时秒级回滚(Rollback)至上一保留版本。


功能概述与核心场景

在企业智能客服生产环境(如 kb_enterprise_support)中,如果知识运营人员直接在正在对外提供问答服务的线上知识库中大批量删除旧文档、上传尚未核验的新文档或触发漫长的全库重建(Reindex),会导致线上检索在变更窗口期内出现结果缺失、分块断层或回答前后矛盾。

Agentbase 的 知识库版本管理 借鉴了现代云原生数据库与软件发布工程的最佳实践,提供以下核心能力:

  1. 平滑的版本采纳(Version Adoption,POST /version-adoptions):

    • 对于尚未开启版本化管理的知识库,支持一键发起异步采纳操作,在不中断现有读取流量的前提下,将既有文档、分块、向量与派生索引完整封存为首个基准不可变版本(如 v1)。

  2. 写时复制(Copy-on-Write)隔离工作副本(Working Copy,POST /versions):

    • 基于任意 READY 状态的历史版本创建草稿副本(DRAFT)。后台异步完成行数、对象数、产物与字节级复制及完整性校验后,草稿副本才正式对外可见,复制与编辑全过程对线上当前激活版本(Current Version)零干扰。

  3. 四重严格就绪门禁(Readiness Gate,GET /versions/{versionId}/readiness)与封存(Seal):

    • 草稿副本要封存为 READY 快照,必须通过自动化的 Readiness 检查(确保无未完成任务、全部文档已 ready 且无需重建、已启用的 GraphRAG / RAPTOR / Wiki 索引已构建就绪、无未裁决的 Wiki 冲突)。

  4. 乐观锁保护的原子发布(Publish)与一键回滚(Rollback):

    • 发布操作将指定的 READY 版本原子切换为当前激活版本,并自动将先前的激活版本转为唯一的回滚目标(Rollback Target)。

    • 发布与回滚均强制校验预期绑定修订号(Expected Binding Revision),防范多人并发变更冲突。

  5. 自动保留策略(Retention Policy)与不可逆安全清理:

    • 支持配置自动保留的历史版本数量(默认保留 3 个),并支持对非当前、非回滚角色的冗余版本发起异步安全清理。

知识库版本列表与工作副本切换视图(沿用已登记截图)

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。


核心概念与架构

知识库不可变版本生命周期状态机

知识库版本管理(Versions):流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

版本状态、角色与核心概念表

概念类别标识名称详细含义与约束规则
版本状态DRAFT可编辑工作副本:后台复制与完整性校验通过后出现在版本列表中,允许增删改文档、分块与派生索引。
版本状态READY已封存只读快照:通过 Readiness 检查并执行 Seal 后的不可变版本。任何针对 READY 版本的写操作均被拒绝。
版本状态DELETING / CLEANED异步删除中 / 数据已清理:触发删除后立即不可访问,后台分批物理清除底层向量与分块数据,仅保留版本元数据作审计痕迹。
版本角色Current(当前版本)当客户端调用检索或问答接口且未显式指定版本时,默认路由命中的线上激活版本。
版本角色Rollback(回滚目标)每次执行 Publish 发布新版本时,系统自动将替换下来的前一个 Current 版本标记为唯一的回滚目标,支持秒级回退。
乐观锁修订号bindingRevision知识库版本指针绑定关系的递增修订号。调用 Publish 或 Rollback 时必须传入当前看到的修订号,防止并发覆盖。
保留策略retentionCount自动保留的历史 READY 版本数量上限(默认保留 3 个),超出保留数的旧版本按策略自动触发清理。

功能入口与权限矩阵

控制台入口、REST API、SDK 方法与权限矩阵

控制台入口 / 功能模块前端路由路径对应 REST API 端点Server SDK 方法(Node.js / Python)所需 RBAC 角色 / API Key Scope跨模块依赖关系
存量知识库版本化采纳(Adoption)/console/project-default-enterprise-ai-hub-210/knowledge-base/kb-kb_enterprise_support/versions(「启用版本化」引导)POST /v1/knowledgebases/{kbId}/version-adoptionsknowledgeBase.adoptVersioning()角色:owner、admin、developer
Scope:knowledgebases.write
将存量文档、分块、向量与派生索引封存为首个 READY 版本
基于 READY 版本创建 DRAFT 工作副本/console/.../kb-kb_enterprise_support/versions(点击「创建工作副本 Create working copy」)POST /v1/knowledgebases/{kbId}/versions
GET /v1/knowledgebases/{kbId}/versions
knowledgeBase.createVersion()
knowledgeBase.listVersions()
角色:owner、admin、developer
Scope:knowledgebases.write
写时复制隔离 文档、数据源、高级索引 与 Wiki 编辑
就绪门禁校验(Readiness Gate)与封存(Seal)版本列表展开「就绪状态(Readiness)」与「封存(Seal)」按钮GET /v1/knowledgebases/{kbId}/versions/{versionId}/readiness
POST .../versions/{versionId}/seal
knowledgeBase.getVersionReadiness()
knowledgeBase.sealVersion()
角色:owner、admin、developer
Scope:knowledgebases.write
强制核验无运行中任务、全部文档 ready、高级索引 已构建且无未裁决 Wiki 冲突
原子发布(Publish)与一键回滚(Rollback)版本列表「发布(Publish)」与顶部「一键回滚(Rollback)」POST /v1/knowledgebases/{kbId}/versions/{versionId}/publish
POST .../versions/{versionId}/rollback
knowledgeBase.publishVersion()
knowledgeBase.rollbackVersion()
角色:owner、admin(及授权发布人员)
Scope:knowledgebases.write
校验 expectedBindingRevision 乐观锁,原子切换线上 混合检索 默认命中版本
异步安全清理历史版本版本列表非 Current/Rollback 行操作「删除(Delete)」DELETE /v1/knowledgebases/{kbId}/versions/{versionId}knowledgeBase.deleteVersion()角色:owner、admin
Scope:knowledgebases.write
后台分批物理回收底层向量、分块与图谱存储,保留审计记录

功能详解与操作指南

一、存量知识库启用版本化:版本采纳(POST /version-adoptions)

如果知识库创建于早期版本或尚未开启版本化治理,首次进入 Versions 页签时会看到「启用版本化管理(Adopt Versioning)」引导卡片:

  1. 点击 启用版本化(Adopt Versioning) 按钮(或调用 POST /v1/knowledgebases/{knowledgeBaseId}/version-adoptions)。

  2. 系统启动异步采纳流水线,并在界面上实时展示五个收敛阶段:

    • 排队中(queued) -> 环境预检(precheck) -> 数据标记(marking) -> 完整性验证(verifying) -> 正式激活(activating)。

    • 取消窗口约束:在进入 marking(数据标记)阶段之前,管理员可随时点击 取消(Cancel) 中止采纳;一旦开始标记,系统将自动完成后续验证与激活,确保数据一致性。

  3. 采纳完成后,知识库既有全部内容自动成为首个不可变的 READY 且 Current 基准版本。


二、创建工作副本(POST /versions)并完成增量修订

当需要为 kb_enterprise_support 新增季度排障规范或调整分块策略时,标准操作流程如下:

  1. 在 Versions 页签的 工作副本(Working copies) 区域,点击 创建工作副本(Create working copy)。

  2. 填写工作副本创建表单:

    • 源版本(Source Version):选择当前处于 READY 状态的基准版本(如 v1.0-baseline)。

    • 版本标签(Label,必填且库内唯一):例如 v2.10.0-q4-support-upgrade。

    • 版本描述(Description,可选):例如 新增 AI 网关限流规范并完成 10 篇 Wiki 页面重编译。

  3. 点击 创建 后,后台开始异步复制源版本的文档、分块、向量与派生索引产物,界面实时展示行数、对象数、产物数与字节数的复制进度条:

    • 复制未完成前,该副本不会以半成品状态出现在正式版本列表中,且支持点击 取消(Cancel)(取消后私有半成品数据被自动彻底清除)。

    • 若复制因瞬时存储抖动失败或被取消,可直接点击 重试(Retry)(API 层自动关联 retryOf 指向原操作 ID)。

  4. 复制校验完成、副本状态变为 DRAFT 后,在顶部版本切换器中选中该 DRAFT 版本,前往 文档、知识索引 与 Wiki 页签完成新文档摄取与索引更新。


三、检查就绪门禁(Readiness Gate)并执行封存(POST /versions/{versionId}/seal)

在将 DRAFT 工作副本封存为 READY 快照之前,系统会强制执行四项就绪门禁检查。在 Versions 页签展开该 DRAFT 版本的 就绪状态(Readiness Summary),核对以下四项指标是否全部为绿色通过:

就绪检查项阻塞封存(Seal Blocked)的典型原因解决与修复方式
1. 活动任务检查 (activeOperations)当前版本仍有正在排队或运行中的文档摄取、数据源同步或索引构建任务等待异步任务执行完毕,或手动取消不需要的任务
2. 文档就绪与配置一致性 (documentsReadiness)存在处于 failed / processing 状态的文档,或修改了默认分块参数但尚未对存量文档执行重建修复失败文档并触发重新摄取(Re-ingest)或整库重建(Reindex),确保全部文档为 ready
3. 派生索引完整性 (indexCapabilitiesReadiness)已启用 GraphRAG、RAPTOR 或 Wiki 开关,但最新文档变更后尚未完成构建或构建失败前往 Indexes 页签点击 构建(Build) 直至状态变为 completed
4. Wiki 冲突清零 (wikiConflictsReadiness)当前版本存在尚未解决的跨文档 Wiki 知识冲突单前往 Wiki -> 冲突工作台(Conflicts) 逐条完成冲突裁决(Resolve)

当上述四项检查全部通过(readyToSeal = true)后,点击该版本右侧的 封存(Seal) 按钮。版本状态立即由 DRAFT 变为不可变的 READY(注意:封存仅冻结快照,不会自动将其发布为线上当前版本)。


四、执行原子发布(Publish)、一键回滚(Rollback)与 REST API 操作

  1. 发布新版本(Publish):

    • 在版本列表中找到已处于 READY 状态的 v2.10.0-q4-support-upgrade,点击 发布(Publish)。

    • 确认弹窗后,该版本立即成为新的 当前版本(Current),所有发往 kb_enterprise_support 的线上检索与智能体工作台问答无缝切换至新版本;同时原当前版本自动转为唯一的 回滚目标(Rollback Target)。

  2. 异常一键回滚(Rollback):

    • 若新版本上线后业务反馈检索效果不符合预期,在 Versions 页签顶部点击 一键回滚(Rollback),系统立即将保留的回滚目标恢复为当前激活版本,并将刚才撤下的版本互换为新的回滚目标。

  3. 完整的版本生命周期 REST API 调用示例:

# 1. 对存量知识库发起版本采纳 (POST /v1/knowledgebases/{knowledgeBaseId}/version-adoptions)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/version-adoptions" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

# 2. 基于指定 READY 源版本创建 DRAFT 工作副本 (POST /v1/knowledgebases/{knowledgeBaseId}/versions)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceVersionId": "ver_baseline_001",
    "label": "v2.10.0-q4-support-upgrade",
    "description": "Q4 客服排障手册与 Wiki 升级副本"
  }'

# 3. 查询 DRAFT 版本的就绪门禁检查报告 (GET /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/readiness)
curl -X GET "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions/ver_draft_002/readiness" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

# 4. 就绪检查通过后封存为 READY 快照 (POST /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/seal)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions/ver_draft_002/seal" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

# 5. 发布 READY 版本为线上当前激活版本 (POST /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/publish)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions/ver_draft_002/publish" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedBindingRevision": 1
  }'

# 6. 紧急回滚至保留的上一版本 (POST /v1/knowledgebases/{knowledgeBaseId}/versions/{versionId}/rollback)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/versions/ver_baseline_001/rollback" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedBindingRevision": 2
  }'

生命周期

一个版本在生命周期中依次经历:

阶段含义
DRAFT工作副本:可编辑的草稿版本,后台复制与校验通过后才出现在版本列表
READY已封存的只读快照:可被发布或作为回滚目标
当前版本(Current)新的版本解析请求默认使用该版本
回滚目标(Rollback)发布时自动保留的上一当前版本,用于一键回滚

DRAFT 经封存变为 READY;READY 经发布成为当前版本;回滚则把保留的回滚目标恢复为当前版本。

状态关系示意(非 Console 截图):

DRAFT ── Seal(Readiness 通过)──> READY ── Publish──> Current
                                           │                 │
                                           │                 └─ 下一个 READY 发布后
                                           │                    保留为 Rollback target
                                           └─ 仍是只读快照

Rollback target ── Rollback──> Current

需要安全发布新内容时,先从 READY 源版本创建工作副本,在 DRAFT 中完成编辑和就绪检查,再封存为 READY。封存不会自动改变线上使用的 Current;确认版本内容后再执行 Publish。

工作副本

在 Working copies 区点击创建工作副本,选择 READY 源版本并填写标签(必填)与描述(可选)。复制在后台进行,页签内展示行数、对象数、产物与字节的复制进度;校验成功后 DRAFT 才可见,不会影响当前激活版本。复制未完成前可取消(私有副本被清理,不会生成可见 DRAFT);失败或取消的操作可重试(retryOf 指向原操作)。

就绪封存(Seal)

DRAFT 需通过就绪检查才能置为 READY。页签展示各版本的 Readiness 摘要与阻塞原因:活动任务未完成、文档未就绪或需按当前配置重建、已启用索引能力待重建或构建失败、存在未解决的 Wiki 冲突,都会阻止封存。封存成功后版本变为只读快照,不会自动发布。

发布与回滚

版本删除

仅非当前、非回滚角色的版本可删除。删除为不可逆的异步操作:请求接受后版本立即不可访问,后台分批清理数据;页签内以删除操作展示状态(已排队、删除中、需关注、数据已清理),可查询进度。清理失败的版本保持不可访问,可重试删除。删除完成后版本记录保留为审计痕迹,数据已清除且无法恢复。

保留策略

自动保留设置控制保留的历史版本数(默认保留 3 个),可自定义或恢复默认;超出保留数的版本按策略清理。

使用边界

Versions 页面展示未启用状态和默认保留 3 个历史版本(沿用已登记截图)

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

常见问题与排障(FAQ)

Q1:点击「发布(Publish)」或「回滚(Rollback)」时提示修订号冲突(Revision Mismatch / 409 Conflict)怎么办?

Q2:为什么我无法直接选择列表里任意一个更早的历史版本点击「回滚」?

Q3:删除一个历史版本后,还能找回里面的文档分块数据吗?


相关文档