版本管理
这是什么 / 何时用
2.8.0 起知识库支持多版本:以 READY 版本为源创建工作副本(异步复制为隔离 DRAFT)→ 就绪检查通过后 Seal 为只读 READY → Publish 切换为当前激活版本,Rollback 则恢复保留的回滚目标;未启用版本化的库先走 Adoption 采纳。所有写路径携带预期修订号做并发保护,操作类变更为异步(幂等键 + 轮询)。产品语义与 Console 入口见版本管理(产品手册)。
使用骨架
列出与读取:
listVersions(knowledgeBaseId, limit, cursor, status, role)(limit、cursor、status、role均可选) 分页取版本(status过滤draft/ready,role过滤current/rollback/none),getVersion读单个版本;列表不包含仍在物化的工作副本。创建工作副本:
createVersion({ knowledgeBaseId, sourceVersionId, expectedSourceVersionRevision, expectedBindingRevision, label, description, retryOf })(description、retryOf均可选) 返回KnowledgeBaseWorkingCopyOperation——校验成功前 DRAFT 不可见,用listWorkingCopyOperations/getWorkingCopyOperation轮询,cancelWorkingCopyOperation请求取消。就绪检查与封存:
getVersionReadiness返回sealable与阻塞原因;sealVersion(携带expectedDefinitionRevision+expectedVersionRevision+ 幂等键)把 DRAFT 置为 READY,不自动发布。发布与回滚:
publishVersion/rollbackVersion(均携带expectedBindingRevision+expectedVersionRevision)原子切换currentVersionId/rollbackVersionId,返回KnowledgeBaseVersion。删除:
deleteVersion({ knowledgeBaseId, versionId, expectedVersionRevision })发起不可逆异步清理,返回KnowledgeBaseVersionDeleteOperation;getVersionDeleteOperation轮询至completed。CURRENT/ROLLBACK角色的版本不可删除。采纳:
createVersionAdoption({ knowledgeBaseId, expectedBindingRevision, retryOf })(retryOf可选) 为未版本化库启动采纳(返回 202 + operation);listVersionAdoptions/getVersionAdoption查询,cancelVersionAdoption(携带expectedOperationRevision)仅在版本标记开始前可取消。
关键参数与返回
createVersion必填sourceVersionId(READY 且deletionState=NONE)、expectedSourceVersionRevision、expectedBindingRevision与非空label;可选description、retryOf(指向失败/取消的原操作)。同一幂等键重放返回原操作;复用键提交不同输入失败。返回模型:版本读
KnowledgeBaseVersion(status:DRAFT/READY;role:CURRENT/ROLLBACK/NONE;deletionState;三个修订号versionRevision/definitionRevision/documentProcessingRevision)与列表KnowledgeBaseVersionList;操作KnowledgeBaseWorkingCopyOperation(status:queued → preflight → copying → validating → reconciling → succeeded | failed | cancelled)、KnowledgeBaseVersionDeleteOperation(queued/running/retryable_failed/completed)、采纳操作模型名以 spec 为准(KnowledgeBaseVersionAdoptionOperation口径);就绪KnowledgeBaseVersionReadiness(sealable+summary+blockers)。幂等键:工作副本创建、seal、delete、adoption 创建/取消等异步或不可逆调用要求稳定
Idempotency-Key(Server SDK 各语言方法面按平台约定装载;REST 直接传头)。publishVersion/rollbackVersion不创建任何摄取、同步或索引任务;发布后旧当前版本自动成为唯一回滚目标。
错误与边界
预期修订号不匹配(
expectedBindingRevision/expectedVersionRevision/expectedDefinitionRevision/expectedOperationRevision漂移)或并发状态变化返回version_concurrently_modified(409):刷新读取最新状态后决定是否重试。sealVersion要求就绪检查全部通过:活动任务、未就绪/待重建文档、stale/failed 的已启用索引能力与 Wiki 冲突都会拒绝转换。publishVersion仅接受 READY 且未删除的版本;rollbackVersion只能回滚到 Binding 保留的ROLLBACK目标,不能指定任意历史版本。deleteVersion不可逆:接受后访问立即被撤销且无法撤回;retryable_failed需换新幂等键重新提交 DELETE 重排队。仅role=NONE且deletionState=NONE的 DRAFT/READY 可删。adoption 仅适用于未版本化的 Shared V2 知识库;进入不可取消阶段后
cancelVersionAdoption失败。幂等键被不同输入复用返回
idempotency_key_reused(409);label重复返回version_label_already_exists。
各语言调用示例
主链:创建工作副本 → 轮询操作 → seal → publish。各卡 expectedBindingRevision 等修订号取自最近一次读取的库与版本对象。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
// 1) 创建工作副本(源版本与库的修订号取自最近一次读取)
const op = await kb.createVersion({
knowledgeBaseId: base.$id,
sourceVersionId: readyVersion.$id,
expectedSourceVersionRevision: readyVersion.versionRevision,
expectedBindingRevision: base.bindingRevision,
label: 'v2-改写稿',
});
// 2) 轮询操作直至终态 succeeded / failed / cancelled(DRAFT 校验成功后才可见)
let st = await kb.getWorkingCopyOperation({ knowledgeBaseId: base.$id, operationId: op.$id });
// 取消:await kb.cancelWorkingCopyOperation({ knowledgeBaseId: base.$id, operationId: op.$id, expectedOperationRevision: st.operationRevision });
const draft = await kb.getVersion({ knowledgeBaseId: base.$id, versionId: st.result.versionId });
// 3) 就绪检查通过后 seal 为 READY(幂等键按平台约定装载)
const readiness = await kb.getVersionReadiness({ knowledgeBaseId: base.$id, versionId: draft.$id });
if (readiness.sealable) {
await kb.sealVersion({
knowledgeBaseId: base.$id,
versionId: draft.$id,
expectedDefinitionRevision: readiness.definitionRevision,
expectedVersionRevision: readiness.versionRevision,
});
}
// 4) publish 切换当前激活版本(旧当前版本自动成为回滚目标)
await kb.publishVersion({
knowledgeBaseId: base.$id,
versionId: draft.$id,
expectedBindingRevision: base.bindingRevision,
expectedVersionRevision: draft.versionRevision,
});// 方法名与 Node 同名(camelCase),参数为位置参数;返回强类型模型
var op = kb.createVersion(base.getId(), ready.getId(),
ready.getVersionRevision(), base.getBindingRevision(), "v2-改写稿", null, null);
// 2) 轮询操作直至终态 succeeded / failed / cancelled
var st = kb.getWorkingCopyOperation(base.getId(), op.getId());
var draft = kb.getVersion(base.getId(),
((java.util.Map<?, ?>) st.getResult()).get("versionId").toString()); // result 为宽类型
var readiness = kb.getVersionReadiness(base.getId(), draft.getId());
if (readiness.getSealable()) {
kb.sealVersion(base.getId(), draft.getId(),
readiness.getDefinitionRevision(), readiness.getVersionRevision());
}
// 4) publish 切换当前激活版本
kb.publishVersion(base.getId(), draft.getId(),
base.getBindingRevision(), draft.getVersionRevision());# 方法名为 snake_case,关键字参数与 REST 字段一致
op = kb.create_version(
knowledge_base_id=base['$id'],
source_version_id=ready['$id'],
expected_source_version_revision=ready['versionRevision'],
expected_binding_revision=base['bindingRevision'],
label='v2-改写稿')
# 2) 轮询操作直至终态 succeeded / failed / cancelled
st = kb.get_working_copy_operation(knowledge_base_id=base['$id'], operation_id=op['$id'])
draft = kb.get_version(knowledge_base_id=base['$id'], version_id=st['result']['versionId'])
# 3) 就绪检查通过后 seal 为 READY
readiness = kb.get_version_readiness(knowledge_base_id=base['$id'], version_id=draft['$id'])
if readiness['sealable']:
kb.seal_version(knowledge_base_id=base['$id'], version_id=draft['$id'],
expected_definition_revision=readiness['definitionRevision'],
expected_version_revision=readiness['versionRevision'])
# 4) publish 切换当前激活版本
kb.publish_version(knowledge_base_id=base['$id'], version_id=draft['$id'],
expected_binding_revision=base['bindingRevision'],
expected_version_revision=draft['versionRevision'])// 方法名为 PascalCase;可选参数经 WithCreateVersion* 选项
op, err := kb.CreateVersion(base.Id, ready.Id,
ready.VersionRevision, base.BindingRevision, "v2-改写稿")
// 2) 轮询操作直至终态 succeeded / failed / cancelled
st, err := kb.GetWorkingCopyOperation(base.Id, op.Id)
draft, err := kb.GetVersion(base.Id, st.Result.(map[string]interface{})["versionId"].(string))
// 3) 就绪检查通过后 seal 为 READY
readiness, err := kb.GetVersionReadiness(base.Id, draft.Id)
if readiness.Sealable {
_, err = kb.SealVersion(base.Id, draft.Id,
readiness.DefinitionRevision, readiness.VersionRevision)
}
// 4) publish 切换当前激活版本
_, err = kb.PublishVersion(base.Id, draft.Id,
base.BindingRevision, draft.VersionRevision)# 1) 创建工作副本:稳定 Idempotency-Key,202 返回操作
curl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/$KB_ID/versions" \
-H 'Content-Type: application/json' -H "Idempotency-Key: wc-20260920-01" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"sourceVersionId":"<SOURCE_VERSION_ID>","expectedSourceVersionRevision":7,"expectedBindingRevision":3,"label":"v2-改写稿"}'
# 2) 轮询操作:GET .../working-copy-operations/{operationId};取消:POST .../working-copy-operations/{operationId}/cancel(body expectedOperationRevision)
# 校验成功后读 DRAFT:GET .../versions/{versionId}
# 3) 就绪检查:GET .../versions/{versionId}/readiness;seal 需幂等键
curl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/$KB_ID/versions/$VERSION_ID/seal" \
-H 'Content-Type: application/json' -H "Idempotency-Key: seal-20260920-01" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"expectedDefinitionRevision":5,"expectedVersionRevision":1}'
# 4) publish 切换当前激活版本
curl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/$KB_ID/versions/$VERSION_ID/publish" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"expectedBindingRevision":3,"expectedVersionRevision":2}'