AgentbaseDocs
文档目录

Schema 版本与回滚

功能概述

Schema 版本与回滚(Schema Versions)为 Agentbase 结构化数据库(Databases / TablesDB)提供生产级的数据库结构快照、差异比对(Schema Diff)、物理结构前置校验、并发变更互斥以及零数据破坏的秒级版本回滚能力。在企业级 AI 与业务系统(如示例项目 **企业智能客服与知识中台**,Project ID:enterprise-ai-hub-210 下的 **企业智能客服业务库** enterprise_biz_db)持续迭代过程中,如果研发人员在生产库上直接零散地手动加列、删列或改索引,极易出现多环境结构漂移、并发 DDL 冲突覆盖或发布中途失败导致服务中断。

通过引入数据库级 Schema 版本控制(Schema Versioning),每一次针对 enterprise_biz_db 内表(Tables)、列(Columns)、索引(Indexes)及业务注释(Comments)的结构变更都以不可变的版本快照(SchemaVersion)形式提交。系统在激活新版本前会自动比对并校验底层 OceanBase 物理结构(兼容 Shared V2 与 JsonTable 两种存储模式):**只有当物理表、列与索引完全物化且校验一致时才原子切换生效版本指针;若校验失败(含自动重试一次后仍失败),当前正在生效的 active 版本继续无缝对外提供服务**,彻底杜绝“半成品结构”上线引发的生产故障。


核心概念与架构

Schema 版本控制引擎围绕“基线采纳(Baseline)或增量迁移(Migration)→ 规范化与哈希幂等(Schema Hash)→ 数据库级单写者互斥锁 → 异步物化与物理对账 → CAS 原子激活 / 指针回滚”构建闭环。下图展示了 Schema 版本从提交、物理校验到状态转换与回滚的完整架构:

stateDiagram-v2
    [*] --> BaselineCheck : POST /v1/tablesdb/{dbId}/schema/versions
    state "提交模式分流 (mode)" as BaselineCheck {
        direction LR
        baseline : mode = baseline (首次接入)<br/>连续两次读取运行时结构对账<br/>零 DDL 直接激活为 v1
        migration : mode = migration (常规演进)<br/>计算与当前 active 版本的 Diff<br/>生成迁移执行计划 (migrationPlan)
    }

    BaselineCheck --> Pending : 存在需物化的 DDL 变更
    BaselineCheck --> Active : baseline 对账一致 / 仅注释等零 DDL 变更

    Pending --> Running : 后台 Schema Migration Worker 领用
    Running --> Applying : 执行建表 / 加列 / 建索引并启动物理结构对账

    state "物理结构前置校验 (Fail-Closed Gate)" as VerifyGate {
        CheckPhysical : 重新读取实际 Table / Column / Index<br/>与目标 schemaJson 逐项严格比对
    }

    Applying --> VerifyGate
    VerifyGate --> Active : 物理结构 100% 匹配<br/>(CAS 原子切换 active,原 active 转为 deprecated)
    VerifyGate --> Failed : 校验不匹配 (自动重投 1 次后仍失败)<br/>(释放迁移锁,原 active 版本继续服务!)

    Active --> Deprecated : 被更新的 Schema 版本替代<br/>或执行 Rollback 切走
    Deprecated --> Active : 执行 Rollback 回滚切回生效指针<br/>(零物理 DROP,不删历史数据)

核心对象(SchemaVersion)与状态机说明

在 enterprise_biz_db 的 Schema Versions 页签或通过 API 获取的每一个版本记录,均包含以下核心元数据与状态语义:

核心字段 / 状态取值与类型架构语义与生产行为说明
**schemaVersion**正整数(1, 2, 3...)数据库内单调递增的版本序号,列表按版本号倒序排列(最新提交的版本在最上方)。
**schemaHash**64 位十六进制哈希串对规范化后的目标表、列、索引结构计算的确定性摘要。若重复提交与现有非 failed 版本具有相同 schemaHash 的请求,接口按幂等语义直接返回 200 及已有版本对象。
**status = pending / running / applying**处理中中间态表示当前版本正在排队、执行底层结构变更或进行激活前物理对账。**当同库存在处于这三个状态之一的版本时,新的结构提交与回滚按钮均自动禁用(API 返回 409)**。
**status = active**当前生效态同一时刻一个数据库最多只有一个 active 版本。数据面读写请求以当前 active 版本的 schemaJson 作为可见表与列的权威投影基准。
**status = deprecated**历史已退役态曾经作为 active 生效、后被新版本替代(或因回滚切走)的历史版本。可随时作为 Rollback(回滚) 的目标版本。
**status = failed**失败关闭态迁移执行或激活前物理结构校验失败(系统对可重试错误最多自动重投 1 次,再次失败即定格为 failed)。此时**原 active 版本保持不变并继续正常服务**,errorMessage 字段记录详细原因供修正后重新提交。
**stepsTotal / stepsCompleted**整数进度指标展示当前版本迁移计划(migrationPlanJson)中的总步骤数与已完成步骤数,配合 lastHeartbeatAt 实时反映执行进度。

角色、入口与关联关系

控制台入口与权限要求

与其他模块的关联关系


功能详解与操作指南

1. 两种版本提交模式:首次基线(baseline)vs 增量演进(migration)

在将业务数据库(如 enterprise_biz_db)纳入 Schema 多版本治理时,Agentbase 提供两种提交模式:

提交模式适用时机底层执行与校验机制关键返回码与约束
**baseline(基线采纳模式)**数据库首次开启 Schema 版本控制(当前库尚无任何现存 SchemaVersion 记录),希望将线上已稳定运行的表结构(如 customer_tickets)原样采纳为第 1 个版本(v1)。服务端连续两次读取完整的运行时权威结构(Canonical Schema),并与请求提交的 schema 做严格一致性比对。对账完全一致时,不触发任何物理建表/加列/建索引 Worker,在单事务内直接写入 v1 并置为 active(stepsTotal=0)。若数据库已有版本记录,禁止使用 baseline;若对账发现提交结构与当前实际运行结构不符或导出期间发生并发漂移,返回 409 schema_baseline_stale。
**migration(常规迁移模式,默认)**日常迭代演进(如为 customer_tickets 表新增 satisfactionScore 评分列、resolvedAt 结单时间列或新增复合索引)。计算提交的目标 schema 与当前 active 版本快照的结构差异(Diff):若仅含注释等零 DDL 变更则直接激活;若包含新增表/列/索引等物理变更,则生成迁移计划并交由后台 Worker 执行,完成后经物理对账激活为新 active 版本。不允许直接修改已有列的物理类型(Type)或缩小字符串列长度(Size),此类破坏性变更会直接返回 400 拦截,建议采用“新增列 + 迁移数据 + 新版本隐藏旧列”的 Expand-Contract 模式。

2. 查看 Schema 版本列表、结构差异与状态诊断

在数据库详情页进入 Schema Versions 页签后:

3. 执行安全回滚(Rollback Schema Version)操作步骤

当新发布的 Schema 版本(例如 v3 新增了若干试验性字段)在业务联调中决定撤回,希望立即切回上一个稳定版本(如 v2)时,可按以下步骤执行回滚:

4. 通过 Server / Console SDK 编排 Schema 版本发布代码示例

在企业 CI/CD 发布流水线中,推荐使用 agentbase-node-sdk@2.10.0(或 agentbase-console-sdk@2.10.0)将数据库结构变更纳入代码仓库进行声明式版本管理:

// 使用版本固定为 @2.10.0 的 Agentbase SDK 执行声明式 Schema 版本发布与回滚
// 对应 REST 端点: POST /v1/tablesdb/{databaseId}/schema/versions

async function deployTicketSchemaVersion(tablesDB) {
    // 1. 提交增量 Schema 版本 (mode: "migration")
    const version = await tablesDB.createSchemaVersion({
        databaseId: 'enterprise_biz_db',
        mode: 'migration', // 首次接入无版本库时可传 'baseline'
        schema: {
            tables: [
                {
                    tableId: 'customer_tickets',
                    name: '客户工单表',
                    comment: '企业智能客服工单主表(含 SLA 与满意度评分)',
                    columns: [
                        { key: 'ticketNo', type: 'varchar', size: 64, required: true, comment: '工单唯一业务编号' },
                        { key: 'title', type: 'varchar', size: 256, required: true, comment: '工单问题摘要标题' },
                        { key: 'priority', type: 'enum', elements: ['P0', 'P1', 'P2'], required: true, comment: '紧急程度' },
                        { key: 'status', type: 'enum', elements: ['open', 'processing', 'resolved', 'closed'], required: true, comment: '处理状态' },
                        { key: 'creatorUserId', type: 'varchar', size: 36, required: true, comment: '提单终端用户 ID' },
                        { key: 'satisfactionScore', type: 'float', required: false, comment: '结单客户满意度评分 (1.0-5.0)' }
                    ],
                    indexes: [
                        { key: 'uk_ticket_no', type: 'unique', attributes: ['ticketNo'], orders: ['ASC'] },
                        { key: 'idx_status_priority', type: 'key', attributes: ['status', 'priority'], orders: ['ASC', 'ASC'] },
                        { key: 'ft_title', type: 'fulltext', attributes: ['title'] }
                    ]
                }
            ]
        }
    });

    console.log(`已提交 Schema 版本 v${version.schemaVersion},当前状态: ${version.status}`);

    // 2. 如需在发布异常时秒级回滚至指定历史版本 versionId:
    // const rolledBack = await tablesDB.rollbackSchemaVersion({
    //     databaseId: 'enterprise_biz_db',
    //     versionId: '<PREVIOUS_ACTIVE_VERSION_ID>'
    // });
}

常见问题与排障

Q1:提交新的 Schema 版本或单独调用建列接口时返回 409 Conflict,提示已有正在进行的迁移或已存在 active 版本,该如何处理?

原因分析:

解决步骤:

Q2:使用 mode: "baseline" 初始化第一个版本时,为什么返回 409 schema_baseline_stale?

原因分析: baseline 模式的设计初衷是“零 DDL 原样采纳当前线上结构为 v1”。服务端在受理 baseline 请求时,会连续读取两次数据库当前的真实运行态结构并与您请求体中传入的 schema 比对。如果请求体里多写了线上还不存在的列/表,或者少写了线上已有的列,又或者在采纳瞬间正好有其他人在修改表结构,服务端就会触发 Fail-Closed 保护并返回 409 schema_baseline_stale。

解决步骤: 请先确保没有其他并发 DDL 操作,如果您的目的是在采纳的同时新增列或修改结构,请先用与线上完全一致的结构执行 baseline 生成 v1,随后再使用默认的 mode: "migration" 提交包含新增列的 v2 版本。

Q3:执行了 Schema 版本回滚(例如从 v4 回滚到 v3),为什么之前在 v4 中误删的一条工单行记录没有恢复回来?

回答: Schema 版本回滚仅针对“表结构与字段可见性(Schema Projection)”,不回退业务行数据(Row Data)。回滚操作只将生效的 Schema 快照指针切回 v3(且不会执行物理 DROP),但不会恢复已经被 DML DELETE 或 UPDATE 修改的业务行记录。如果需要恢复被误删的业务行数据,请前往 备份与恢复(Backups) 选择误操作之前的 Complete 备份点执行恢复。


相关文档