Docs
文档目录

核心概念

Agentbase 构建在严谨的多租户资源隔离、双平面身份鉴权与 OceanBase 分布式存储引擎之上。无论是使用基础的认证、数据库、存储与云函数,还是编排企业级大模型网关、混合检索知识库、长期记忆与智能体工作台,所有资源均遵循统一的层级归属、ID 规范、权限表达式与安全默认边界。

组织成员页(沿用已登记截图)

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

功能概述

在企业多团队、多环境(开发 / 预发 / 生产)协同研发智能体应用时,架构师与开发者需要明确四个核心基础问题:

  1. 资源归属与物理隔离:团队成员、计费配额、业务数据库与 AI 知识资产如何按组织与项目分层隔离?底层 OceanBase 的 JsonTable 与 Shared V2 存储模式有何本质区别?

  2. 双平面身份与凭证边界:管理控制台的开发者会话(Console Session)、后端微服务的 API Key、前端终端用户的登录会话(Client Session / JWT)分别在什么场景下使用?权限如何校验?

  3. 资源标识与细粒度 ACL:业务文档、数据行、存储文件与知识库条目的 $id 如何生成?如何通过 read、create、update、delete、write 结合角色选择器实现行级与对象级访问控制?

  4. 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 中的一切资源均挂载在明确的层级节点下,不存在游离于项目之外的业务数据或密钥:

  1. 账号(Account):自然人开发者在 /console/login 登录的身份实体,维护个人邮箱、密码、外部关联身份(GitHub / 企业 SSO)、多因素认证(MFA 与一次性恢复码)及账号级最近 30 个 UTC 日聚合用量。

  2. 组织(Organization):团队协作与资源治理的顶层容器(如 Agentbase 企业智能中台,ID:69c6d1aa00062e6bb60)。组织下可创建多个 Project(如开发环境、预发环境、生产环境项目),并通过 6 种组织角色控制成员在 Console 中的读写权限,同时提供组织级不活跃项目批量清理(Project cleanup)能力。

  3. 项目(Project):应用后端与 AI 能力的强隔离资源边界(如 企业智能客服与知识中台,ID:enterprise-ai-hub-210)。每个项目在创建或设置时确定其底层 OceanBase 表存储模式:

存储模式维度共享表 / 独占表(传统模式 / JsonTable 兼容)OceanBase Shared V2 模式(企业级 AI 推荐基线)深度独占表模式(Deep Dedicated)
物理存储结构基于通用元数据集合与 JSON 属性列映射承载业务文档针对多租户高并发与向量/混合负载深度优化的共享 V2 表结构为单个超大吞吐表分配物理级深度隔离存储空间
在线表模式转换支持在项目 Settings → 项目表模式 中与独占表互转(含 relationship 集合时阻断)支持新建项目直接采用,或在满足约束条件下通过转换任务迁移不支持在线转换为其他表模式
AI Memory 长期记忆支持不支持(调用 Memory 初始化会返回 HTTP 412)原生支持(Memory 事实提取、画像、经验技能蒸馏的强制前提)视平台专门配置而定,通用项目推荐使用 Shared V2
适用业务场景轻量级传统 CRUD 原型或纯文档型存量应用企业级智能体应用、智能客服中台、RAG + Memory 一体化生产项目超大规模单表写入且无跨模式转换需求的特殊核心账务表

2. 双平面鉴权模型(Dual-Plane Auth)

Agentbase 严格区分控制面管理身份与数据面业务身份,并在数据面进一步细分为服务端特权调用与客户端受限调用:

鉴权凭证类型适用调用方核心请求头权限决定机制是否受行级/文件级 ACL 约束
Console Session(开发者会话)开发者在 /console/ 浏览器操作,或使用 Console SDKCookie 会话 + 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 浏览器、iOS/Android App、小程序等终端用户端(Web SDK)X-Appwrite-Project: <PROJECT_ID> + Session Cookie 或 X-Appwrite-JWT: <JWT>1. 请求来源必须命中已登记的 Platform(Hostname / Bundle ID);
2. 目标服务在 Settings → Services 中必须开启;
3. 严格受目标表/行/存储桶/文件的 Permissions ACL 校验
是(仅能访问被显式授予 any、users、user:{id} 或所属 team:{id} 权限的资源)
Dev Key(开发调试密钥)本地开发联调环境(如 localhost 调试前端 SDK)X-Appwrite-Project + X-Appwrite-Dev-Key: <DEV_KEY>仅用于开发环境临时绕过请求速率限制(Ratelimit)与浏览器 CORS 校验,并返回详细错误堆栈;有效期最长 30 天是(不提升数据访问权限,仍遵循当前客户端身份的 ACL 规则)

3. 资源标识($id)与权限表达式(Permissions & Roles)

在 Agentbase 中,无论是项目、数据库、数据表、数据行、存储桶、文件,还是知识库、词库、网关与评估集,均采用双层标识设计:

在数据表(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 内部有机协同:

  1. LLM Gateway(模型网关 /llm-gateway):管理模型供应商凭据(如阿里云百炼 dashscope-prod)与模型能力目录(Chat qwen-plus / qwen-turbo、Embedding text-embedding-v3 1024 维、Rerank qwen3.7-text-rerank、Vision qwen-vl-max),并签发支持月度 Token 预算与 RPM/TPM 限流的 Gateway Key。

  2. AI Gateway(统一 AI 网关 /ai-gateway):面向复杂生产流量的治理面(如 prod-enterprise-ai-gateway gw_7194685489feb1e169548619),提供逻辑模型路由(lm-enterprise-chat 主备容灾与权重分流)、输入输出安全护栏(gp-enterprise-safety)、语义缓存(cp-semantic-cache)与 MCP 工具/Agent 注册治理。

  3. Knowledge Base & Lexicon(知识库与词库 /knowledge-base):将 Storage 中的非结构化文档经解析分块、向量化(校验与知识库锁定的 1024 维一致)后存入 OceanBase 混合索引;通过绑定同义词词库(lex_enterprise_synonyms)与停用词词库(lex_support_stopwords)优化召回准确率,并支持构建 GraphRAG(实体-关系-社区报告)、RAPTOR(递归聚类摘要树)与 LLM Wiki(带引用溯源的编译态百科页)。

  4. Memory & PowerContext(长期记忆与托管上下文 /memory · /powercontext):在 Shared V2 项目中,从多轮对话、图片或 PDF 中异步提取用户事实记忆、生成用户画像(Profile)、聚合分层上下文(Context Dreaming),并从高频成功轨迹中蒸馏可复用的经验与技能(Experience/Skill Distillation,如 dst_3e5b09f456c5d5c332507ec1dbe3eb6d),支持四类 Pipeline 草稿验证发布与二次人工确认。

  5. Agent Runtime Workbench(智能体工作台 /agent-runtime):提供零代码/低代码的智能体装配与流式对话调试环境,支持将主对话模型、系统提示词、多个知识库与干预词库持久化为项目级配置(/v1/agent-runtime/project/config),并支持服务端通过项目 API Key 直接调用运行。

  6. 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)平台登记、API Key 管理、服务开关、表模式转换、业务与 AI 模块配置/console/project-{region}-{project}/*查看:任意成员;创建/修改资源:owner / admin / developer / editor

2. 平台级安全默认行为(Security by Default)

为防范企业生产环境常见的越权、注入与内网探测风险,Agentbase 在底层执行面内置了不可绕过的安全默认策略:

安全领域平台强制默认行为对开发与运维的实际影响
出站网络与 SSRF 防护拒绝访问本机回环(127.0.0.0/8)、RFC1918 私网地址、链路本地地址与云厂商元数据地址(169.254.169.254)Webhook 目标 URL、远程 OAuth2 端点、模型 Provider 自定义端点及函数/站点出站请求均受 SSRF 守卫保护。
云函数与站点受限身份Functions 与 Sites 容器始终以非特权受限系统身份(Restricted Identity)运行若部署脚本或启动命令不满足受限安全条件,系统直接失败并报错,绝不静默回退为 root 高权限运行。
函数调用凭据传输严禁通过 URL Query String 传递 Function API Key触发受保护函数时必须通过 HTTP Header(如 X-Appwrite-Key)或平台注入的运行时身份认证,防止凭据被代理或访问日志明文记录。
存储图片审核 Fail-Closed开启图片内容审核的私有存储桶采用“失败关闭”策略一旦图片被判定违规(block/review)、超出大小上限或审核服务调用异常,已上传对象会被立即物理清除,不留存未审副本。
数据库 Schema 激活校验激活新版本 Schema 前强制校验底层 OceanBase 物理表结构一致性若物理结构校验未通过,激活操作立即中止并保持当前线上生效版本继续服务,杜绝元数据与物理列失步。
分布式事务连接恢复非事务幂等读请求在连接闪断时支持自动重连恢复;显式事务请求绝不自动重放当事务执行期间发生网络中断,调用方必须先通过业务唯一键确认事务最终状态,再按幂等策略决定是否重试。
敏感凭据单向掩码OAuth2 Client Secret、模型 Provider API Key、审核 AK/SK、全局 Secret 变量只写不回显保存后服务端加密存储,Console 界面仅展示掩码;API Key Secret 仅对项目 owner、创建者及特权角色可见。

功能详解与操作指南

本节通过三个核心治理实操场景,演示如何在 Console 中查看并管理组织成员角色、核查项目存储模式与服务开关,以及为业务资源配置细粒度 ACL 权限。

1. 核查组织成员角色与 2FA 安全状态

  1. 登录 Console 后,在顶部组织切换器中选择 Agentbase 企业智能中台(69c6d1aa00062e6bb60),点击顶部页签栏的 Members(成员),进入 /console/organization-69c6d1aa00062e6bb60/members(如图 1 所示)。

  2. 在成员列表表格中,核对每位成员的 Name、Email、2FA(二步验证启用状态) 与 Roles(组织角色)。

  3. 点击右上角 Invite(邀请成员),在弹窗中依次填写受邀人邮箱、展示姓名,并在角色下拉框中按职责勾选角色(如为算法工程师分配 Developer,为知识运营分配 Editor,为财务人员分配 Billing)。

  4. 对已有成员,点击行末操作菜单 ⋮ → Edit role,可即时调整其角色范围;调整保存后立即作用于该成员后续的所有 Console 与管理面请求。

2. 检查与管理项目表存储模式及客户端服务开关

  1. 在组织项目列表中点击进入 企业智能客服与知识中台(enterprise-ai-hub-210),点击左侧导航栏底部的 Settings(设置)。

  2. 在 Overview 页签下找到 项目表模式(Table Mode) 卡片:

    • 确认当前项目运行于 Shared V2 模式(这是启用 AI Memory 长期记忆服务与高性能混合负载的标准底座)。

    • 如需将旧版共享表转换为独占表或 Shared V2,需先确保项目内不含 relationship 类型的集合;提交转换后可在 Account → Table mode conversions 页签追踪异步转换进度。

  3. 向下滚动至 Services 卡片:

    • 检查各服务面向客户端 SDK 的启停开关(如 Account、Databases、Storage、Functions、Memory、Knowledge Bases、AI Gateway)。

    • 若计划在项目中使用统一 AI 网关,请在此处将 AI Gateway 开关拨至开启状态,左侧边栏随即解锁 AI 网关 导航项。

3. 在数据表与存储桶上配置资源级与行级权限(ACL)

以业务数据库 enterprise_biz_db 下的客户工单表 customer_tickets 为例,实现“任何登录客户可提交工单,但仅工单创建者本人与二线客服团队可查看和修改该工单”:

  1. 进入左侧边栏 Databases → 点击数据库 enterprise_biz_db → 点击数据表 customer_tickets → 切换到 Settings 页签。

  2. 在 Permissions(表级权限) 区域:

    • 点击 Add role → 选择 All users (users),仅勾选 Create(允许任何已登录终端用户创建工单行,但不勾选表级 Read,从而防止普通用户列出全表他人工单)。

    • 再次点击 Add role → 选择 Team,输入客服团队 ID(如 support_team),勾选 Read 与 Update(允许客服团队成员读取并处理所有工单)。

  3. 开启 Row security(行级安全开关) 并点击 Update 保存。

  4. 当客户端或服务端插入具体工单行(如 TK-20261022-001,归属客户 user_zhangwei_001)时,在该行的权限数组中写入 read("user:user_zhangwei_001") 与 update("user:user_zhangwei_001"),即可实现精准的行级租户隔离。

安全默认值

领域默认行为
外部 URL拒绝本机、私网与云元数据地址(SSRF 防护)
Function / Site使用受限身份运行;不满足安全条件时直接失败,不回退为高权限执行
Console SQL不向浏览器展示 MySQL wire 直连信息
Schema 变更激活前校验物理结构,失败保留当前生效版本继续服务
SQL Proxy 事务不提供公开事务状态;事务控制命令会被拒绝,未确认的写入结果应先读回再按幂等策略处理
存储审核私有图片审核 fail closed,失败清理上传
登录 state一次性使用,绑定项目 / 浏览器 / callback / Client ID / state revision
测试会话OAuth 登录测试产生的会话与 Console 会话隔离,退出测试不退出 Console
Function API Key不再接受 query string 传递,使用受保护 header 或平台注入的运行时认证路径

常见问题与排障

Q1:为什么用前端 Web SDK 查询数据表返回空数组 [],但用后端 API Key 却能查出 4 条工单记录?

原因与排查步骤: 这是最典型的双平面权限差异表现,而非数据丢失:

  1. 后端请求携带 X-Appwrite-Key: standard_...(Server API Key),只要该 Key 具备 rows.read / databases.read Scope,即可绕过表级和行级 ACL 读取全量数据。

  2. 前端 Web SDK 携带的是终端用户 Session,严格受表级 Permissions 与行级 Row security 限制。若表级未授予该用户 read 权限,且单行数据上也未添加 read("user:{userId}")(或行级安全开关 rowSecurity 未开启),服务端对无权访问的行会静默过滤,最终返回空列表 []。请前往数据表 Settings → Permissions 及具体数据行详情页核对权限配置。

Q2:组织角色设为 Billing 或 Analyst 的成员为什么在控制台里点击保存或创建按钮时报错?

原因与排查步骤: 在 Agentbase 的 RBAC 模型中,Billing(账单财务)与 Analyst(数据分析师)属于严格只读角色。他们可以浏览项目概览、近 30 个 UTC 日用量聚合、观测轨迹(Traces)与评估报告,但底层管理面接口会拦截一切写操作(要求 owner、admin、developer 或 editor 角色)。若该成员需要创建知识库、修改 Prompt 或生成 API Key,请由组织 Owner 或 Admin 在 Organization → Members 页将其角色升级为 Editor 或 Developer。

Q3:为什么在项目 Settings 中开启了“列删除(Column deletion)”或准备转换表模式时无法操作?

原因与排查步骤:

相关文档