核心概念
Agentbase 构建在严谨的多租户资源隔离、双平面身份鉴权与 OceanBase 分布式存储引擎之上。无论是使用基础的认证、数据库、存储与云函数,还是编排企业级大模型网关、混合检索知识库、长期记忆与智能体工作台,所有资源均遵循统一的层级归属、ID 规范、权限表达式与安全默认边界。
功能概述
在企业多团队、多环境(开发 / 预发 / 生产)协同研发智能体应用时,架构师与开发者需要明确四个核心基础问题:
资源归属与物理隔离:团队成员、计费配额、业务数据库与 AI 知识资产如何按组织与项目分层隔离?底层 OceanBase 的
JsonTable与Shared V2存储模式有何本质区别?双平面身份与凭证边界:管理控制台的开发者会话(Console Session)、后端微服务的 API Key、前端终端用户的登录会话(Client Session / JWT)分别在什么场景下使用?权限如何校验?
资源标识与细粒度 ACL:业务文档、数据行、存储文件与知识库条目的
$id如何生成?如何通过read、create、update、delete、write结合角色选择器实现行级与对象级访问控制?AI 原生原语协同:模型网关(LLM Gateway)、统一 AI 网关(AI Gateway)、知识库与词库(Knowledge Base & Lexicon)、长期记忆(Memory)、智能体工作台(Agent Runtime Workbench)与智能体运维(AgentOps)如何围绕 Project 上下文联动?
本章对上述核心概念进行系统性拆解,作为全书各功能模块的设计与排障基石。
核心概念与架构
Agentbase 的全局架构由三级资源容器(Account → Organization → Project)、双平面鉴权网关(Control Plane vs Data Plane)、双模存储引擎(JsonTable vs Shared V2)以及六大 AI 原生原语共同组成。
1. 三级资源层级与项目存储模式(JsonTable vs Shared V2)
Agentbase 中的一切资源均挂载在明确的层级节点下,不存在游离于项目之外的业务数据或密钥:
账号(Account):自然人开发者在
/console/login登录的身份实体,维护个人邮箱、密码、外部关联身份(GitHub / 企业 SSO)、多因素认证(MFA 与一次性恢复码)及账号级最近 30 个 UTC 日聚合用量。组织(Organization):团队协作与资源治理的顶层容器(如
Agentbase 企业智能中台,ID:69c6d1aa00062e6bb60)。组织下可创建多个 Project(如开发环境、预发环境、生产环境项目),并通过 6 种组织角色控制成员在 Console 中的读写权限,同时提供组织级不活跃项目批量清理(Project cleanup)能力。项目(Project):应用后端与 AI 能力的强隔离资源边界(如
企业智能客服与知识中台,ID:enterprise-ai-hub-210)。每个项目在创建或设置时确定其底层 OceanBase 表存储模式:
| 控制台名称 | 对应表模式 | 说明 |
|---|---|---|
| 共享表 | jsonTable | 使用 JSON 表模式;可用性和项目配额取决于实例配置。 |
| 独占表 | shared / Shared V2 | 使用 Shared V2;本版 Memory 路由要求此模式。 |
| 深度独占表 | collection | 项目元数据表也独占;不是单个业务表的设置。 |
项目表模式转换目前面向 jsonTable 与 Shared V2,需满足实际预检条件;collection 不在这两个方向内。历史 sharedV1 以实例配置为准,选择或转换前应核对当前环境的可用选项与限制。
2. 双平面鉴权模型(Dual-Plane Auth)
Agentbase 严格区分控制面管理身份与数据面业务身份,并在数据面进一步细分为服务端特权调用与客户端受限调用:
| 鉴权凭证类型 | 适用调用方 | 核心请求头 | 权限决定机制 | 是否受行级/文件级 ACL 约束 |
|---|---|---|---|---|
| Console Session(开发者会话) | 开发者在 /console/ 浏览器操作,或使用 Console SDK | Cookie 会话 + X-Appwrite-Mode: admin + X-Appwrite-Project | 由该开发者在项目所属 Organization 中的成员角色(owner / admin / developer / editor vs 只读 billing / analyst)决定 | 否(拥有管理视角,按组织角色放行) |
| Server API Key(服务端密钥) | 企业后端微服务、定时任务、外部 Agent 编排器、Function 内部调用 | X-Appwrite-Project: <PROJECT_ID> + X-Appwrite-Key: standard_... | 由创建 API Key 时勾选的 Scopes(权限范围,如 users.read、databases.write) 决定;且不受项目 Services 客户端开关关闭的影响 | 否(在授权 Scope 内可跨用户读写全项目资源,需在后端自行把控业务归属) |
| Client Session / JWT(终端用户凭证) | Web、移动端等终端用户 | X-Appwrite-Project + Session Cookie 或 X-Appwrite-JWT | 适用时检查浏览器 Origin;还需满足服务开关、身份及目标资源的权限要求。移动端包名登记不代表每次请求都会校验包名 | 是(数据访问按资源权限控制) |
| Dev Key(开发调试密钥) | 本地开发联调环境 | X-Appwrite-Project + X-Appwrite-Dev-Key: <DEV_KEY> | 可豁免速率限制和适用的浏览器来源检查;控制台提供 1、7、30 天选项,管理接口不强制最长 30 天。应设置到期时间并及时吊销 | 是(不提升数据访问权限,仍遵循客户端身份的权限规则) |
3. 资源标识($id)与权限表达式(Permissions & Roles)
在 Agentbase 中,无论是项目、数据库、数据表、数据行、存储桶、文件,还是知识库、词库、网关与评估集,均采用双层标识设计:
外部业务标识(
$id):对外暴露的唯一资源 ID(如知识库kb_enterprise_support、同义词库lex_enterprise_synonyms、AI 网关gw_7194685489feb1e169548619)。创建资源时支持传入自定义$id(允许字母、数字、连字符、下划线与句点,不可由特殊字符开头,最长 36 字符)或使用unique()由服务端自动生成高熵唯一 ID。内部物理序列号(
$sequence/ Internal ID):OceanBase 内部用于聚簇索引、外键关联与游标分页(cursorAfter/cursorBefore)的自增序列标识,调用方仅通过$id操作资源,无需关心底层物理序列。
在数据表(Table / Row)、存储桶(Bucket / File)、函数执行(Function Execute)与消息主题(Topic Subscribe)上,Agentbase 采用统一的 动作(Action) + 角色选择器(Role Selector) 权限模型,并且坚持默认拒绝(Deny by Default):若未配置任何权限条目,任何客户端终端用户均无权访问,仅服务端 API Key 与 Console 管理员可访问。
| 权限维度 | 语法格式 | 精确语义与适用范围 | 生产配置示例(智能客服工单场景) |
|---|---|---|---|
| 操作动作(Actions) | read("<role>") | 允许读取数据行、下载/预览文件或查看资源元数据 | read("user:user_zhangwei_001")(允许客户张伟查看自己的工单) |
create("<role>") | 允许在表中新增数据行或在存储桶中上传新文件(配置在表级或桶级) | create("users")(允许所有已登录客户提交新工单) | |
update("<role>") | 允许修改已有数据行或更新文件元数据(不含删除) | update("team:support_tier2/agent")(允许二线客服坐席更新工单状态) | |
delete("<role>") | 允许删除数据行或存储文件 | delete("team:support_tier2/owner")(仅客服主管可删除工单) | |
write("<role>") | create + update + delete 的组合简写别名 | write("team:kb_editors")(允许知识库编辑团队增删改文档) | |
| 角色选择器(Role Selectors) | any | 任何请求方(含未登录匿名访客与已登录用户) | 公开知识库附件桶配置 read("any") |
guests | 仅未登录的匿名会话访客 | 匿名意见反馈表配置 create("guests") | |
users / users/verified | 任何已登录的终端用户 / 仅已完成邮箱或手机验证的已登录用户 | 企业内部问答社区配置 read("users/verified") | |
user:{userId} | 指定唯一 $id 的单个终端用户(可选追加 /verified) | 工单行级权限 read("user:user_zhangwei_001") | |
team:{teamId} / team:{teamId}/{role} | 指定团队的全部成员 / 仅该团队内具备特定自定义角色(如 owner、agent)的成员 | 二线技术支持团队 read("team:ob_dba_team/specialist") | |
label:{label} | 带有指定用户标签(User Label,由服务端或管理员在 Auth 用户上打标,如 vip、internal)的全部用户 | VIP 专属服务通道配置 create("label:vip") |
4. 六大 AI 原生原语与协同机制
Agentbase 将构建生产级 Agent 所需的核心基础设施抽象为六大原语,它们在项目 enterprise-ai-hub-210 内部有机协同:
LLM Gateway(模型网关
/llm-gateway):管理模型供应商凭据(如阿里云百炼dashscope-prod)与模型能力目录(Chatqwen-plus/qwen-turbo、Embeddingtext-embedding-v31024 维、Rerankqwen3.7-text-rerank、Visionqwen-vl-max),并签发支持月度 Token 预算与 RPM/TPM 限流的 Gateway Key。AI 网关(
/ai-gateway):用于管理网关实例、策略和工具接入。Knowledge Base & Lexicon(知识库与词库
/knowledge-base):将 Storage 中的非结构化文档经解析分块、向量化(校验与知识库锁定的 1024 维一致)后存入 OceanBase 混合索引;通过绑定同义词词库(lex_enterprise_synonyms)与停用词词库(lex_support_stopwords)优化召回准确率,并支持构建 GraphRAG(实体-关系-社区报告)、RAPTOR(递归聚类摘要树)与 LLM Wiki(带引用溯源的编译态百科页)。Memory & PowerContext(长期记忆与托管上下文
/memory·/powercontext):在Shared V2项目中,从多轮对话、图片或 PDF 中异步提取用户事实记忆、生成用户画像(Profile)、聚合分层上下文(Context Dreaming),并从高频成功轨迹中蒸馏可复用的经验与技能(Experience/Skill Distillation,如dst_3e5b09f456c5d5c332507ec1dbe3eb6d),支持四类 Pipeline 草稿验证发布与二次人工确认。Agent Runtime Workbench(智能体工作台
/agent-runtime):提供零代码/低代码的智能体装配与流式对话调试环境,支持将主对话模型、系统提示词、多个知识库与干预词库持久化为项目级配置(/v1/agent-runtime/project/config),并支持服务端通过项目 API Key 直接调用运行。Observability / AgentOps(智能体运维
/observability):采集智能体每一次推理、工具调用、RAG 检索与记忆读写的全链路 Trace 与 Observation,提供通用评估、Memory 评估、知识库解析分块评估以及 GraphRAG / RAPTOR / LLM Wiki 知识索引质量评估。
角色、入口与关联关系
1. 组织级与项目级控制台导航入口
| 治理层级 | 核心操作模块 | 控制台路由路径 | 最小所需组织角色 |
|---|---|---|---|
| 账号级(Account) | 个人资料、MFA 与恢复码、全局会话、待清理项目恢复、表模式转换历史 | /console/account | 任何已注册登录的 Console 账号 |
| 组织级(Organization) | 项目列表、成员邀请与角色分配、30 日组织聚合用量、不活跃项目批量清理 | /console/organization-{organization}/members 等 | 查看:任意成员;邀请/管理:owner 或 admin;删组织/清理项目:owner |
| 项目级(Project) | 平台登记、密钥、服务开关和项目资源 | /console/project-{region}-{project}/* | 项目入口需要 projects.read;平台和密钥写操作分别需要 platforms.write、keys.write 或 devKeys.write,默认由 owner / admin 持有 |
2. 平台级安全默认行为(Security by Default)
为防范企业生产环境常见的越权、注入与内网探测风险,Agentbase 提供多项安全控制;具体覆盖范围和配置取决于入口与部署环境:
| 安全领域 | 平台强制默认行为 | 对开发与运维的实际影响 |
|---|---|---|
| 出站网络与 SSRF 防护 | 部分受保护的外部请求默认校验目标,限制回环、私网、链路本地与云元数据地址;相关防护可由部署配置影响 | 不同入口使用不同策略,AI Gateway 还有独立的私网配置。函数和站点的构建及运行出站应另行核实执行环境和网络策略,不能假定均经过同一守卫。 |
| 云函数与站点受限身份 | Functions 与 Sites 容器始终以非特权受限系统身份(Restricted Identity)运行 | 若部署脚本或启动命令不满足受限安全条件,系统直接失败并报错,绝不静默回退为 root 高权限运行。 |
| 函数调用凭据传输 | 严禁通过 URL Query String 传递 Function API Key | 触发受保护函数时必须通过 HTTP Header(如 X-Appwrite-Key)或平台注入的运行时身份认证,防止凭据被代理或访问日志明文记录。 |
| 存储图片审核 Fail-Closed | 开启图片内容审核的私有存储桶采用“失败关闭”策略 | 图片违规、超限或审核服务异常时上传失败;执行到清理步骤时尝试删除已上传对象,异常后须核查实际清理状态。 |
| 数据库 Schema 激活校验 | 激活新版本 Schema 前强制校验底层 OceanBase 物理表结构一致性 | 若物理结构校验未通过,激活操作立即中止并保持当前线上生效版本继续服务,杜绝元数据与物理列失步。 |
| 分布式事务连接恢复 | 非事务幂等读请求在连接闪断时支持自动重连恢复;显式事务请求绝不自动重放 | 当事务执行期间发生网络中断,调用方必须先通过业务唯一键确认事务最终状态,再按幂等策略决定是否重试。 |
| 敏感凭据单向掩码 | OAuth2 Client Secret、模型 Provider API Key、审核 AK/SK、全局 Secret 变量只写不回显 | 保存后服务端加密存储,Console 界面仅展示掩码;项目 API Key 列表和详情按项目身份与有效组织成员关系判断明文可见性,使用 API Key 查询时脱敏。 |
功能详解与操作指南
本节通过三个核心治理实操场景,演示如何在 Console 中查看并管理组织成员角色、核查项目存储模式与服务开关,以及为业务资源配置细粒度 ACL 权限。
1. 核查组织成员角色与 2FA 安全状态
登录 Console 后,在顶部组织切换器中选择自己的组织,点击顶部页签栏的 成员(Members),进入
/console/organization-{organizationId}/members。在成员列表表格中,核对每位成员的 Name、邮箱、2FA(二步验证启用状态) 与 Roles(组织角色)。
点击右上角 Invite(邀请成员),在弹窗中依次填写受邀人邮箱、展示姓名,并在角色下拉框中按职责勾选角色(如为算法工程师分配
Developer,为知识运营分配Editor,为财务人员分配Billing)。对已有成员,点击行末操作菜单
⋮→ 编辑角色,可即时调整其角色范围;调整保存后立即作用于该成员后续的所有 Console 与管理面请求。
2. 检查与管理项目表存储模式及客户端服务开关
在组织项目列表中点击进入
企业智能客服与知识中台(enterprise-ai-hub-210),点击左侧导航栏底部的 Settings(设置)。在 概览 页签下找到 项目表模式(Table Mode) 卡片:
确认当前项目运行于
Shared V2模式(这是启用 AI Memory 长期记忆服务与高性能混合负载的标准底座)。如需转换表模式,请先检查可用目标池与预检结果。项目存在 Memory 数据或 PowerContext 配置时会阻止转换;请先评估数据保留和迁移方案。提交后可在 账号 → 表模式转换 页签追踪异步转换进度。
向下滚动至 服务 卡片:
检查各服务面向客户端 SDK 的启停开关(如
Account、Databases、Storage、Functions、Memory、Knowledge Bases、AI Gateway)。若计划在项目中使用统一 AI 网关,请在此处将 AI Gateway 开关拨至开启状态,左侧边栏随即解锁 AI 网关 导航项。
3. 在数据表与存储桶上配置资源级与行级权限(ACL)
以业务数据库 enterprise_biz_db 下的客户工单表 customer_tickets 为例,实现“任何登录客户可提交工单,但仅工单创建者本人与二线客服团队可查看和修改该工单”:
进入左侧边栏 数据库 → 点击数据库
enterprise_biz_db→ 点击数据表customer_tickets→ 切换到 设置 页签。在 Permissions(表级权限) 区域:
点击 添加角色 → 选择 All users (
users),仅勾选Create(允许任何已登录终端用户创建工单行,但不勾选表级Read,从而防止普通用户列出全表他人工单)。再次点击 添加角色 → 选择 团队,输入客服团队 ID(如
support_team),勾选Read与Update(允许客服团队成员读取并处理所有工单)。
开启 Row security(行级安全开关) 并点击 Update 保存。
当客户端或服务端插入具体工单行(如
TK-20261022-001,归属客户user_zhangwei_001)时,在该行的权限数组中写入read("user:user_zhangwei_001")与update("user:user_zhangwei_001"),即可实现精准的行级租户隔离。
安全默认值
| 领域 | 默认行为 |
|---|---|
| 外部 URL | 部分入口默认限制本机、私网和云元数据地址;覆盖范围及例外取决于部署配置 |
| Function / Site | 使用受限身份运行;不满足安全条件时直接失败,不回退为高权限执行 |
| Console SQL | 不向浏览器展示 MySQL wire 直连信息 |
| Schema 变更 | 激活前校验物理结构,失败保留当前生效版本继续服务 |
| SQL Proxy 事务 | 不提供公开事务状态;事务控制命令会被拒绝,未确认的写入结果应先读回再按幂等策略处理 |
| 存储审核 | 图片审核失败时请求失败;清理到达及结果需核查 |
| 登录 state | 一次性使用,绑定项目 / 浏览器 / callback / Client ID / state revision |
| 测试会话 | OAuth 登录测试产生的会话与 Console 会话隔离,退出测试不退出 Console |
| Function API Key | 不再接受 query string 传递,使用受保护 header 或平台注入的运行时认证路径 |
常见问题与排障
Q1:为什么用前端 Web SDK 查询数据表返回空数组 [],但用后端 API Key 却能查出 4 条工单记录?
原因与排查步骤: 这是最典型的双平面权限差异表现,而非数据丢失:
后端请求携带
X-Appwrite-Key: standard_...(Server API Key),只要该 Key 具备rows.read/databases.readScope,即可绕过表级和行级 ACL 读取全量数据。前端 Web SDK 携带的是终端用户 Session,严格受表级 权限 与行级 行安全 限制。若表级未授予该用户
read权限,且单行数据上也未添加read("user:{userId}")(或行级安全开关rowSecurity未开启),服务端对无权访问的行会静默过滤,最终返回空列表[]。请前往数据表 设置 → 权限 及具体数据行详情页核对权限配置。
Q2:组织角色设为 Billing 或 Analyst 的成员为什么在控制台里点击保存或创建按钮时报错?
原因与排查步骤: 组织 billing 和 analyst 默认没有 projects.read,因此在自托管配置下不能仅凭这两个角色进入项目;组织级账单或用量能力以实际部署及授权为准。项目资源操作还需对应权限。创建 API Key、开发密钥或登记平台需要相应管理权限,默认由组织 owner 或 admin 操作;请管理员按实际职责处理。
Q3:为什么在项目 Settings 中开启了“列删除(Column deletion)”或准备转换表模式时无法操作?
原因与排查步骤:
列删除开关(Column deletion):由于删除物理列会不可逆地抹除该列全部历史业务数据,平台安全策略强制规定仅组织 Owner 与平台管理员有权开启该开关;普通
Admin、Developer或Editor无权切换。表模式转换受阻:
collection(深度独占表)不在当前项目表模式转换方向内。已有转换任务、Memory 数据或 PowerContext 配置等也可能阻止预检;请检查服务端提示并先评估数据保留和迁移方案。转换期间请勿并发执行 Schema 变更。