版本管理
这是什么 / 何时用
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 / cancelling / succeeded / failed / cancelled)、KnowledgeBaseVersionDeleteOperation(queued/running/retryable_failed/completed)、采纳操作模型名以 spec 为准(KnowledgeBaseVersionAdoptionOperation口径);就绪KnowledgeBaseVersionReadiness(sealable+summary+blockers)。工作副本仅在
queued、preflight、copying、validating可请求取消;受理后进入cancelling,轮询终态并等待清理完成。幂等键:工作副本创建、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。
各语言调用示例
以下代码块是独立步骤:先初始化 client、kb,读取目标知识库 base 和源 READY 版本 ready(Node.js 中为 readyVersion)。REST 的 APPBASE_ENDPOINT 包含 /v1;替换所有占位符及修订号,确保项目和凭据属于目标环境。创建与封存使用不同的稳定幂等键;SDK 的客户端头对后续请求持续生效。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
创建工作副本。
client.addHeader('Idempotency-Key', '<CREATE_KEY>');
const op = await kb.createVersion({ knowledgeBaseId: base.$id,
sourceVersionId: readyVersion.$id, expectedSourceVersionRevision: readyVersion.versionRevision,
expectedBindingRevision: base.bindingRevision, label: 'draft-v2' });
console.log(op.$id);查询该操作;只有
succeeded才从结果的result.versionId取得versionId/version_id。failed、cancelled时停止;其他状态稍后再查询。
const st = await kb.getWorkingCopyOperation({ knowledgeBaseId: base.$id, operationId: op.$id });
if (st.status !== 'succeeded') throw new Error(`Working copy is ${st.status}; check again or inspect the failure`);
const result = st.result as { versionId?: unknown };
if (typeof result?.versionId !== 'string' || !result.versionId) throw new Error('Operation did not return a version ID');
const versionId = result.versionId;
console.log(versionId);先查询版本 readiness,确认
sealable为 true 后再执行封存。REST 先调用版本/readiness获取最新修订号,并用返回值替换下面的示例数字。
const readiness = await kb.getVersionReadiness({ knowledgeBaseId: base.$id, versionId });
if (!readiness.sealable) throw new Error('Version is not ready to seal');
client.addHeader('Idempotency-Key', '<SEAL_KEY>');
const sealed = await kb.sealVersion({ knowledgeBaseId: base.$id, versionId,
expectedDefinitionRevision: readiness.definitionRevision,
expectedVersionRevision: readiness.versionRevision });
console.log(sealed.$id, sealed.versionRevision);只有封存成功且确认需要切换时才执行发布;REST 先读取最新 binding 和封存结果修订号,替换示例数字。
const latest = await kb.get({ knowledgeBaseId: base.$id });
const published = await kb.publishVersion({ knowledgeBaseId: base.$id, versionId: sealed.$id,
expectedBindingRevision: latest.bindingRevision, expectedVersionRevision: sealed.versionRevision });
console.log(published.$id);创建工作副本。
client.addHeader("Idempotency-Key", "<CREATE_KEY>");
var op = kb.createVersion(base.getId(), ready.getId(), ready.getVersionRevision(),
base.getBindingRevision(), "draft-v2", null, null);
System.out.println(op.getId());查询该操作;只有
succeeded才从结果的result.versionId取得versionId/version_id。failed、cancelled时停止;其他状态稍后再查询。
var st = kb.getWorkingCopyOperation(base.getId(), op.getId());
if (!"succeeded".equals(st.getStatus().getValue()))
throw new IllegalStateException("Working copy is " + st.getStatus());
if (!(st.getResult() instanceof java.util.Map<?, ?>))
throw new IllegalStateException("Operation did not return a result");
var result = (java.util.Map<?, ?>) st.getResult();
var value = result.get("versionId");
if (!(value instanceof String) || ((String) value).isEmpty())
throw new IllegalStateException("Operation did not return a version ID");
var versionId = (String) value;
System.out.println(versionId);先查询版本 readiness,确认
sealable为 true 后再执行封存。REST 先调用版本/readiness获取最新修订号,并用返回值替换下面的示例数字。
var readiness = kb.getVersionReadiness(base.getId(), versionId);
if (!readiness.getSealable()) throw new IllegalStateException("Version is not ready to seal");
client.addHeader("Idempotency-Key", "<SEAL_KEY>");
var sealed = kb.sealVersion(base.getId(), versionId,
readiness.getDefinitionRevision(), readiness.getVersionRevision());
System.out.println(sealed.getId() + " " + sealed.getVersionRevision());只有封存成功且确认需要切换时才执行发布;REST 先读取最新 binding 和封存结果修订号,替换示例数字。
var latest = kb.get(base.getId(), null);
var published = kb.publishVersion(base.getId(), sealed.getId(),
latest.getBindingRevision(), sealed.getVersionRevision());
System.out.println(published.getId());创建工作副本。
client.add_header('Idempotency-Key', '<CREATE_KEY>')
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='draft-v2')
print(op.id)查询该操作;只有
succeeded才从结果的result.versionId取得versionId/version_id。failed、cancelled时停止;其他状态稍后再查询。
st = kb.get_working_copy_operation(knowledge_base_id=base.id, operation_id=op.id)
if st.status.value != 'succeeded':
raise RuntimeError(f'Working copy is {st.status.value}; check again or inspect the failure')
if not isinstance(st.result, dict) or not isinstance(st.result.get('versionId'), str) or not st.result['versionId']:
raise RuntimeError('Operation did not return a version ID')
version_id = st.result['versionId']
print(version_id)先查询版本 readiness,确认
sealable为 true 后再执行封存。REST 先调用版本/readiness获取最新修订号,并用返回值替换下面的示例数字。
readiness = kb.get_version_readiness(knowledge_base_id=base.id, version_id=version_id)
if not readiness.sealable:
raise RuntimeError('Version is not ready to seal')
client.add_header('Idempotency-Key', '<SEAL_KEY>')
sealed = kb.seal_version(knowledge_base_id=base.id, version_id=version_id,
expected_definition_revision=readiness.definitionrevision,
expected_version_revision=readiness.versionrevision)
print(sealed.id, sealed.versionrevision)只有封存成功且确认需要切换时才执行发布;REST 先读取最新 binding 和封存结果修订号,替换示例数字。
latest = kb.get(knowledge_base_id=base.id)
published = kb.publish_version(knowledge_base_id=base.id, version_id=sealed.id,
expected_binding_revision=latest.bindingrevision, expected_version_revision=sealed.versionrevision)
print(published.id)创建工作副本。
client.AddHeader("Idempotency-Key", "<CREATE_KEY>")
op, err := kb.CreateVersion(base.Id, ready.Id, ready.VersionRevision, base.BindingRevision, "draft-v2")
if err != nil { return err }
fmt.Println(op.Id)查询该操作;只有
succeeded才从结果的result.versionId取得versionId/version_id。failed、cancelled时停止;其他状态稍后再查询。
st, err := kb.GetWorkingCopyOperation(base.Id, op.Id)
if err != nil { return err }
if st.Status != "succeeded" { return fmt.Errorf("working copy is %s", st.Status) }
result, ok := st.Result.(map[string]interface{})
if !ok { return fmt.Errorf("operation did not return a result") }
versionId, ok := result["versionId"].(string)
if !ok || versionId == "" { return fmt.Errorf("operation did not return a version ID") }
fmt.Println(versionId)先查询版本 readiness,确认
sealable为 true 后再执行封存。REST 先调用版本/readiness获取最新修订号,并用返回值替换下面的示例数字。
readiness, err := kb.GetVersionReadiness(base.Id, versionId)
if err != nil { return err }
if !readiness.Sealable { return fmt.Errorf("version is not ready to seal") }
client.AddHeader("Idempotency-Key", "<SEAL_KEY>")
sealed, err := kb.SealVersion(base.Id, versionId, readiness.DefinitionRevision, readiness.VersionRevision)
if err != nil { return err }
fmt.Println(sealed.Id, sealed.VersionRevision)只有封存成功且确认需要切换时才执行发布;REST 先读取最新 binding 和封存结果修订号,替换示例数字。
latest, err := kb.Get(base.Id)
if err != nil { return err }
published, err := kb.PublishVersion(base.Id, sealed.Id, latest.BindingRevision, sealed.VersionRevision)
if err != nil { return err }
fmt.Println(published.Id)创建工作副本。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${KB_ID:?Set KB_ID}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT%/}/knowledgebases/${KB_ID}/versions" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H 'Content-Type: application/json' -H 'Idempotency-Key: <CREATE_KEY>' \
-d '{"sourceVersionId":"<SOURCE_VERSION_ID>","expectedSourceVersionRevision":7,"expectedBindingRevision":3,"label":"draft-v2"}'
)查询该操作;只有
succeeded才从结果的result.versionId取得versionId/version_id。failed、cancelled时停止;其他状态稍后再查询。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${KB_ID:?Set KB_ID}"
: "${OPERATION_ID:?Set OPERATION_ID from the create response}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS "${APPBASE_ENDPOINT%/}/knowledgebases/${KB_ID}/working-copy-operations/${OPERATION_ID}" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
)先查询版本 readiness,确认
sealable为 true 后再执行封存。REST 先调用版本/readiness获取最新修订号,并用返回值替换下面的示例数字。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${KB_ID:?Set KB_ID}"
: "${VERSION_ID:?Set VERSION_ID from the succeeded operation}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS "${APPBASE_ENDPOINT%/}/knowledgebases/${KB_ID}/versions/${VERSION_ID}/readiness" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
)确认就绪后,使用返回的修订号执行封存:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${KB_ID:?Set KB_ID}"
: "${VERSION_ID:?Set VERSION_ID from the succeeded operation}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT%/}/knowledgebases/${KB_ID}/versions/${VERSION_ID}/seal" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H 'Content-Type: application/json' -H 'Idempotency-Key: <SEAL_KEY>' \
-d '{"expectedDefinitionRevision":5,"expectedVersionRevision":1}'
)只有封存成功且确认需要切换时才执行发布;REST 先读取最新 binding 和封存结果修订号,替换示例数字。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${KB_ID:?Set KB_ID}"
: "${VERSION_ID:?Set VERSION_ID from the sealed version}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT%/}/knowledgebases/${KB_ID}/versions/${VERSION_ID}/publish" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H 'Content-Type: application/json' \
-d '{"expectedBindingRevision":3,"expectedVersionRevision":2}'
)