AgentbaseDocs
文档目录

数据库概览

功能概述

Agentbase 结构化数据库(Databases / TablesDB)构建于 OceanBase 原生分布式数据库引擎之上,为企业级 AI 智能体与业务系统提供强一致、高可用的结构化数据管理能力。在项目 **企业智能客服与知识中台**(Project ID:enterprise-ai-hub-210)中,企业可通过 Console 的 Databases 模块或客户端/服务端 SDK(agentbase-web-sdk@2.10.0、agentbase-node-sdk@2.10.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)的架构设计。下图展示了从上层 SDK / Console 接入、权限评估到 OceanBase 双存储模式(Shared V2 与 JsonTable)及模式转换的完整架构:

flowchart TB
    subgraph AccessLayer["接入与协议层 (Access & Protocols)"]
        SDK["Client / Server SDK<br/>(agentbase-web-sdk@2.10.0 / agentbase-node-sdk@2.10.0)"]
        ConsoleUI["Console 电子表格与管理视图<br/>(/console/project-{region}-{project}/databases)"]
        SQLProxy["SQL Proxy 受控 SQL 入口<br/>(HTTP /v1/sql & MySQL Wire)"]
    end

    subgraph LogicalModel["五层逻辑数据模型 (enterprise-ai-hub-210)"]
        DB["Database: 企业智能客服业务库<br/>(ID: enterprise_biz_db)"]
        Tbl["Table: 客户工单表<br/>(ID: customer_tickets, Row Security: Enabled)"]
        ColsIdx["Columns & Indexes<br/>(title, status, priority, creatorUserId + 索引)"]
        Rows["Rows (工单记录)<br/>(TK-20261022-001 .. TK-20261022-004)"]
        DB --> Tbl --> ColsIdx --> Rows
    end

    subgraph StorageModes["OceanBase 项目存储模式与双向转换 (PoolSelector)"]
        SharedV2["Shared V2 模式 (tableMode=shared)<br/>• 真实类型化物理列 + _tenant 行级租户隔离<br/>• 原生二级 / Unique / Fulltext / Spatial 索引<br/>• 支持 Memory / PowerContext / AI Gateway 全栈能力"]
        JsonTable["JsonTable 模式 (tableMode=jsonTable)<br/>• 固定 7 张 _jt_* 共享物理表 + _data JSON 存储<br/>• Catalog-only 零物理 DDL 秒级建表建列<br/>• _jt_index_values / _jt_unique_index_values 侧表索引"]
        Converter["双向存储模式转换器<br/>(ProjectTableModeConversion Worker)<br/>停写窗口 → 回填校验 → ID/序号重映射 → 缓存刷新 → 源数据清理"]
        SharedV2 <-->|在线受控转换| Converter
        Converter <-->|在线受控转换| JsonTable
    end

    SDK & ConsoleUI & SQLProxy --> LogicalModel
    LogicalModel --> SharedV2 & JsonTable

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)

当项目的业务形态演进(例如从轻量原型期迁移至开启 Memory 与高频检索的生产期,或从 Shared V2 归档收敛至 JsonTable)时,Agentbase 支持通过 **ProjectTableModeConversion** 执行项目级存储模式双向无损转换(Shared V2 $\leftrightarrow$ JsonTable):


角色、入口与关联关系

控制台入口与路由

角色与权限控制模型

Databases 采用“控制台管理权限(组织角色 / API Key Scopes)”与“终端用户数据访问权限(表级 / 行级 ACL)”双层鉴权机制:

权限层级管控范围授权主体与配置入口生效规则说明
管理面权限(Control Plane)创建/删除数据库、建表/建列/建索引、提交 Schema 版本、管理备份策略组织角色 owner、admin、developer、editor;或携带 databases.read / databases.write、tables.read / tables.write 的 Server API Keybilling 与 analyst 组织角色在 Console 中仅具只读权限,无法创建或修改库表结构。
表级数据权限(Table Permissions)终端用户对该表整体行的 create、read、update、delete 权限在表 Settings → Permissions 中添加 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. 浏览与检索数据库列表

进入项目 Databases 页面后,默认以表格视图展示当前项目下的所有数据库(如 enterprise_biz_db 企业智能客服业务库):

截图未公开:原图可能包含账号或资源标识。

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

2. 创建数据库(Create database)操作步骤

字段名称是否必填校验规则与示例值(enterprise-ai-hub-210)
Name必填数据库显示名称,最长 128 字符。示例:企业智能客服业务库
Database ID可选点击 Database ID 标签展开自定义输入框。仅允许 a-z、A-Z、0-9、句点(.)、连字符(-)、下划线(_),最长 36 字符,且首字符不能为特殊符号;留空时系统自动生成唯一 ID。示例:enterprise_biz_db
Backup policy(备份策略,云端套餐可见)可选创建数据库弹窗内嵌备份策略选择器,支持在建库同时勾选启用预设的每日/每小时备份策略或自定义备份策略;若当前套餐不含备份权益则展示升级提示。

3. 数据库启停(enabled)与设置管理

在数据库详情页的 Settings 页签(或通过 Server SDK 调用 databases.update(databaseId, name, enabled))中,管理员可维护数据库的基础属性:

4. 删除数据库(Delete database)与异步级联清理机制

当某个测试数据库不再需要时,可按以下安全确认流程将其删除:


常见问题与排障

Q1:新建项目或规划业务架构时,应该如何判断项目该使用 Shared V2 还是 JsonTable 存储模式?

决策指南:

Q2:为什么客户端查询 enterprise_biz_db 下的 customer_tickets 表时返回成功,但 documents / rows 数组为空(total: 0),而 Console 里明明能看到 4 条工单数据?

原因分析: Agentbase 数据库默认遵循默认拒绝(Default Deny)的零信任安全原则。Console 管理视图使用组织管理权限直接读取全表数据,而客户端 SDK 请求受表的 Permissions(表级权限) 和 Row security(行级安全) 严格过滤:如果既没有在表 Settings → Permissions 中为当前用户角色授予 Read 权限,也没有开启 Row security 并在单行上授予该用户 Read 权限,查询不会报错,但会自动过滤掉所有无权访问的行,返回空列表。

解决步骤:

Q3:执行删除数据库(或删除大表)后,为什么刷新页面该数据库还会短暂出现几秒钟?

原因分析: 为了避免同步 HTTP 请求在删除包含数百万行数据的数据库或大表时发生网关超时或长事务锁表,Agentbase 的数据库删除与表删除均采用异步级联清理架构。HTTP 接口在登记删除意图并锁定资源后立即返回,后台数据库 Worker 按有界批次安全删除底层行数据、侧表索引与备份文件,全部清理完毕后才移除顶层数据库元数据记录。只需等待数秒后再次刷新即可。


相关文档