数据库概览
功能概述
Agentbase 结构化数据库(Databases / TablesDB)构建于 OceanBase 原生分布式数据库引擎之上,为企业级 AI 智能体与业务系统提供强一致、高可用的结构化数据管理能力。在项目 企业智能客服与知识中台(Project ID:enterprise-ai-hub-210)中,企业可通过 Console 的 数据库 模块或客户端/服务端 SDK(agentbase-web-sdk@2.12.0、agentbase-node-sdk@2.12.0)创建业务数据库(如 企业智能客服业务库,Database ID:enterprise_biz_db),并在其下定义结构化业务表(如客户工单表 customer_tickets)、强类型列(Columns)、高性能二级/唯一/全文索引(Indexes)与行记录(Rows)。
围绕 OceanBase 的多租户与海量表承载特性,Agentbase 在底层提供了 Shared V2(tableMode=shared) 与 JsonTable(tableMode=jsonTable) 两大生产级项目存储模式,并支持通过 ProjectTableModeConversion 在两种存储模式之间执行带停写保护窗口、数据完整性校验与平台引用重映射的双向在线转换。在此之上,Databases 服务进一步集成了 Schema 多版本控制与回滚(Schema Versions)、受控 SQL 访问面(SQL Proxy)、表级与行级安全权限(Row Security)、服务端聚合计算(COUNT / SUM) 以及 云端备份与恢复(Backups),形成面向企业核心生产负载的一站式数据底座。
核心概念与架构
Agentbase Databases 采用“五层逻辑资源模型(Project → Database → Table → Column & Index → Row)”映射到底层 OceanBase 存储池(Storage Pools)的架构设计。
1. 五层逻辑资源层级说明
| 层级对象 | 示例(enterprise-ai-hub-210) | 关键属性与架构说明 |
|---|---|---|
| Database(数据库) | enterprise_biz_db(企业智能客服业务库) | 逻辑表的命名空间与备份/Schema 版本控制单元。单个项目下可创建多个 Database;支持通过 enabled 开关控制客户端可访问性。 |
| Table(数据表) | customer_tickets(客户工单表) | 同类结构化行记录的集合。支持配置高达 256 字符的业务注释(comment)、表级读写权限(Permissions)与行级安全开关(rowSecurity)。 |
| Column(列 / 字段) | title、status、priority、creatorUserId | 定义表中每列的数据类型(如 varchar、text、integer、float、boolean、datetime、enum、relationship)、必填约束(required)、默认值(default)、数组标记(array)及最大 256 字符的列注释(comment)。 |
| Index(索引) | idx_status_priority、ft_title | 加速查询过滤、排序与唯一性约束的数据结构。支持普通索引(key)、唯一索引(unique)、全文索引(fulltext)及空间索引(spatial)。 |
| Row(行记录) | TK-20261022-001 .. TK-20261022-004 | 具体的业务数据记录。除用户定义的业务列外,系统自动维护 $id、$sequence、$createdAt、$updatedAt、$permissions、$databaseId、$tableId 系统元数据列。 |
2. OceanBase 存储模式深度对比:Shared V2 vs JsonTable
Agentbase 针对不同规模与业务特征的项目,在 OceanBase 存储池上提供 Shared V2(tableMode=shared) 与 JsonTable(tableMode=jsonTable) 两种核心存储模式(历史 collection 独立表与 Shared V1 仅作兼容保留,不作为新项目目标模式):
| 对比维度 | Shared V2 模式(tableMode=shared) | JsonTable 模式(tableMode=jsonTable) | 选型与架构影响 |
|---|---|---|---|
| 物理存储结构 | 系统表跨租户共享;用户业务表把每个字段映射为 OceanBase 真实类型化物理列,并通过 _tenant 列实现多租户行级隔离。 | 所有项目的全部逻辑表统一收敛在 固定 7 张 _jt_* 物理表中(_jt_documents、_jt_permissions、_jt_index_values、_jt_unique_index_values、_jt_fulltext_index_values、_jt_table_catalog、_jt_table_sequences),用户字段存入 _data JSON 列,按 project_seq + catalog_id 隔离。 | 高并发核心业务 & AI 全家桶首选 Shared V2(如 enterprise-ai-hub-210);超大规模长尾项目 / 高频动态建表且需压平物理表总量时选用 JsonTable。 |
| 建表与加列 DDL 成本 | 执行真实 OceanBase 物理 CREATE TABLE / ALTER TABLE DDL,由后台数据库 Worker 异步物化。 | Catalog-only 纯元数据写入(仅更新 _jt_table_catalog),零物理 DDL,建表、加列、建索引瞬时完成且不锁物理大表。 | JsonTable 彻底消除了海量逻辑表膨胀带来的 OceanBase Schema 内存与 DDL 阻塞开销。 |
| 索引实现机制 | 直接使用 OceanBase 原生二级索引、UNIQUE 索引、原生 FULLTEXT 全文索引与 SPATIAL 空间索引,查询与 ORDER BY 直接下推存储层。 | 普通索引通过 _jt_index_values 类型化侧表 INNER JOIN 加速;唯一索引通过 _jt_unique_index_values 侧表 + SHA-256 复合唯一约束强校验;每次写操作同步维护侧表(存在一定写放大)。 | Shared V2 原生索引性能最优;JsonTable 保障了等值/范围/唯一索引语义,但 ORDER BY 走作用域内 JSON_EXTRACT 排序。 |
| 全文检索与复杂算子 | 原生 MATCH ... AGAINST 全文检索;原生支持数组多值索引(MVI)与空间几何算子。 | search / notSearch、数组 contains*、regex 等算子先通过 SQL 缩小候选集,再在内存对候选集(上限默认 1 MB)执行精确过滤;不支持 Spatial 空间类型与空间算子。 | 若业务重度依赖海量数据全文检索、大表复杂聚合或空间地理位置查询,必须选用 Shared V2。 |
| AI 模块兼容性 | 全量支持 Databases、Storage、Knowledge Base、Memory(长期记忆)、PowerContext 与 AI Gateway。 | 支持 Databases、Storage、Knowledge Base、Lexicons、Scenarios 等通用项目资源;但 Memory、PowerContext、AI Gateway 当前要求项目运行在 Shared V2 模式。 | 启用智能体记忆(Memory)或 AI 网关的项目必须使用或先转换至 Shared V2 模式。 |
3. 项目存储模式双向在线转换(ProjectTableModeConversion)
Agentbase 支持在满足预检条件时,通过 ProjectTableModeConversion 在 Shared V2 和 JsonTable 之间转换项目存储模式。提交前,服务会检查是否已有进行中的转换、项目的 Memory 数据和 PowerContext 配置等;存在 Memory 数据或 PowerContext 配置时会阻止转换。请先评估数据保留和迁移方案,切勿为通过预检直接删除业务数据。可用目标池及其他限制以实际预检结果为准。
探测可用目标池(Target Pools):调用
GET /v1/project/table-mode-conversions/targets(或通过控制台表模式转换页)查询当前项目源池(sourcePool/sourceTableMode)以及可转换的目标模式(targetModes[])与可用存储池标签(tags[])。创建并启动任务:创建任务后先进入
preflight,不会自动开始转换;确认条件后点击启动,系统开始停写、准备目标池及数据回填。检查校验结果并确认切流:观察任务状态及校验报告。校验通过后任务停留在
verify;需要操作人员确认并执行切流,不能只等待自动完成。请关注停写期间的业务影响;失败时查看错误并按界面允许的操作处理或回滚。确认结果和源数据保留:切流后检查业务读写和目标数据。源数据的删除不可逆,删除后无法回滚;仅在确认无需回滚且符合保留要求后执行。
角色、入口与关联关系
控制台入口与路由
主导航路径:登录 Agentbase Console → 进入项目
企业智能客服与知识中台(enterprise-ai-hub-210)→ 点击左侧导航栏 基础设施 → 数据库。路由地址:
数据库列表页:
/console/project-{region}-{project}/databases单个数据库详情页:
/console/project-{region}-{project}/databases/database-{databaseId}(内含 Tables、备份、Schema 版本、SQL、用量、设置 等子页签)。
角色与权限控制模型
Databases 采用“控制台管理权限(组织角色 / API Key Scopes)”与“终端用户数据访问权限(表级 / 行级 ACL)”双层鉴权机制:
| 权限层级 | 管控范围 | 授权主体与配置入口 | 生效规则说明 |
|---|---|---|---|
| 管理面权限(Control Plane) | 创建/删除数据库、建表/建列/建索引、提交 Schema 版本、管理备份策略 | 组织角色 owner、admin、developer、editor;或携带 databases.read / databases.write、tables.read / tables.write 的 Server API Key | 组织 billing 与 analyst 默认没有 projects.read;自托管时不能仅凭这两个角色进入项目,其他访问取决于部署及实际授权。 |
| 表级数据权限(Table Permissions) | 终端用户对该表整体行的 create、read、update、delete 权限 | 在表 设置 → 权限 中添加 Role.any()、Role.users()、Role.team('team_support_ops') 等角色 | 只要终端用户命中表级 read(或 update/delete)权限,即可读取(或修改/删除)该表内的所有行。 |
| 行级安全权限(Row Security) | 单行记录粒度的隔离访问(如客户张伟只能看自己的工单) | 在表 Settings → Row security 开启开关,并在创建/编辑行时配置该行的 $permissions | 开启 Row security 后,未命中表级权限的用户若命中单行上的 Permission.read(Role.user('user_zhangwei_001')),则仅能读取或操作该特定行。 |
功能详解与操作指南
1. 浏览与检索数据库列表
进入项目 数据库 页面后,默认以表格视图展示当前项目下的所有数据库(如 enterprise_biz_db 企业智能客服业务库):
图 1:2.12.0 环境中的数据库列表;示例数据库 ID 已遮盖。
表格列说明:
Database ID:数据库唯一标识符(如
enterprise_biz_db),支持一键复制。Name:数据库业务名称(如
企业智能客服业务库)。备份(仅云端开通备份套餐时展示):实时展示该数据库当前绑定的定时备份策略状态(如
Daily backup)或未备份警告。Created / Updated:数据库创建时间与最近一次结构或属性更新时间。
视图与检索工具栏:支持按数据库名称或 ID 实时搜索、在表格视图(Table view)与网格卡片视图(Grid view)之间切换、自定义显示列以及调整每页条数。
2. 创建数据库(Create database)操作步骤
在 数据库 列表页点击右上角的 创建数据库。若按钮不可用,请先检查当前账号的数据库写入权限。
在弹出的创建窗口中填写以下参数:
| 字段名称 | 是否必填 | 校验规则与示例值(enterprise-ai-hub-210) |
|---|---|---|
| Name | 必填 | 数据库显示名称,最长 128 字符。示例:企业智能客服业务库 |
| Database ID | 可选 | 在数据库 ID 输入框填写自定义标识。仅允许 a-z、A-Z、0-9、句点(.)、连字符(-)、下划线(_),最长 36 字符,且首字符不能为特殊符号;留空时系统自动生成唯一 ID。示例:enterprise_biz_db |
| Backup policy(备份策略,云端套餐可见) | 可选 | 支持备份的环境可在创建时启用备份策略并填写计划和保留时间;该选项是否显示取决于环境能力。 |
点击 确认 提交。创建成功后进入数据库详情页,可继续创建数据表。
3. 数据库启停(enabled)与设置管理
在数据库详情页的 设置 页签(或通过 Server SDK 调用 databases.update(databaseId, name, enabled))中,管理员可维护数据库的基础属性:
修改数据库名称(Name):随时调整显示名称,不影响
Database ID及业务代码中的 SDK 调用。启用 / 停用数据库(
enabled属性语义):通过 Console 创建的数据库默认
enabled = true。当通过 API 将数据库设为
enabled = false时,所有来自终端用户客户端(Client SDK / Session / JWT)对该数据库下任意表的读写请求都会被立即阻断拒绝;但持有有效 API Key 的服务端(Server SDK)仍可正常读写库内数据,底层业务数据完好保留。该机制非常适合在做业务割接或紧急止血维护时临时针对前端封网。
4. 删除数据库(Delete database)与异步级联清理机制
当某个测试数据库不再需要时,可按以下安全确认流程将其删除:
进入目标数据库的 设置 页签底部 危险区域,点击 删除数据库 打开删除确认弹窗。
核对受影响表清单:弹窗会明确列出该数据库下即将被一并销毁的业务表名称(最多展示前 25 张表),并警示该数据库关联的所有备份快照也将同步永久销毁且不可恢复。
勾选强确认复选框:必须手动勾选 "I understand and confirm"(我理解并确认)复选框,右下角的红色 删除 按钮才会解除禁用。
理解异步级联删除行为:点击确认删除后,服务端受理请求并返回成功,随后交由后台异步删除任务(Worker)逐张表清理全部行记录、索引与列元数据,最后移除数据库主文档与关联备份。对于包含海量行的数据库,异步清理期间列表页可能会短暂保留该库记录直至后台级联清理彻底完成。
常见问题与排障
Q1:新建项目或规划业务架构时,应该如何判断项目该使用 Shared V2 还是 JsonTable 存储模式?
决策指南:
优先选择
Shared V2(tableMode=shared)的场景:项目需要使用 智能体长期记忆(Memory)、PowerContext 或 AI 网关(AI Gateway)(如演示项目
enterprise-ai-hub-210)。业务表单表数据量较大,重度依赖 OceanBase 原生二级索引排序、原生
FULLTEXT全文检索相关性排序、数组多值索引(MVI)或Point/Line/Polygon空间地理位置查询。
选择
JsonTable(tableMode=jsonTable)的场景:租户需要动态高频创建成百上千张逻辑表,希望建表、加列、改索引具备 零物理 DDL(Catalog-only) 的秒级响应,且希望底层 OceanBase 物理表数量恒定收敛在 7 张
_jt_*共享表内。若后期需要原生列索引或启用 Memory,可在满足转换预检条件后,通过
ProjectTableModeConversion转换至Shared V2。
Q2:为什么客户端查询 enterprise_biz_db 下的 customer_tickets 表时返回成功,但 documents / rows 数组为空(total: 0),而 Console 里明明能看到 4 条工单数据?
原因分析: Agentbase 数据库默认遵循默认拒绝(Default Deny)的零信任安全原则。Console 管理视图使用组织管理权限直接读取全表数据,而客户端 SDK 请求受表的 Permissions(表级权限) 和 Row security(行级安全) 严格过滤:如果既没有在表 设置 → 权限 中为当前用户角色授予 Read 权限,也没有开启 Row security 并在单行上授予该用户 Read 权限,查询不会报错,但会自动过滤掉所有无权访问的行,返回空列表。
解决步骤:
进入
enterprise_biz_db→ 点开customer_tickets表 → 切换到 设置 页签。在 权限 卡片中添加适合业务的读取角色(例如添加
Role.users()允许所有登录用户读取,或添加Role.team('team_support_ops')允许技术支持团队读取);若需按行隔离,请开启 行安全 并在每行数据菜单的 管理权限 中添加Role.user('<USER_ID>')。
Q3:执行删除数据库(或删除大表)后,为什么刷新页面该数据库还会短暂出现几秒钟?
原因分析: 为了避免同步 HTTP 请求在删除包含数百万行数据的数据库或大表时发生网关超时或长事务锁表,Agentbase 的数据库删除与表删除均采用异步级联清理架构。HTTP 接口在登记删除意图并锁定资源后立即返回,后台数据库 Worker 按有界批次安全删除底层行数据、侧表索引与备份文件,全部清理完毕后才移除顶层数据库元数据记录。只需等待数秒后再次刷新即可。
相关文档
表、列、行与索引(Tables):深入学习字段类型、复合/全文索引构建、电子表格行编辑与
customer_tickets工单表实战操作。Schema 版本与回滚(Schema Versions):使用版本快照管理数据库结构变更、查看结构 Diff 与一键安全回滚。
SQL 访问面(SQL Proxy):通过 HTTP
/v1/sql、MySQL Wire 协议或 Console SQL 终端执行受控 SQL 查询与操作。备份与恢复(Backups):配置手动备份快照、定时备份保留策略与跨库/原库数据恢复。
认证概览(Auth Overview):了解用于控制数据库表级与行级安全的
Role与Permission表达式。
