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使用 JSON 表模式;可用性和项目配额取决于实例配置。
独占表shared / Shared V2使用 Shared V2;本版 Memory 路由要求此模式。
深度独占表collection项目元数据表也独占;不是单个业务表的设置。

项目表模式转换目前面向 jsonTable 与 Shared V2,需满足实际预检条件;collection 不在这两个方向内。历史 sharedV1 以实例配置为准,选择或转换前应核对当前环境的可用选项与限制。

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、移动端等终端用户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 中,无论是项目、数据库、数据表、数据行、存储桶、文件,还是知识库、词库、网关与评估集,均采用双层标识设计:

在数据表(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 网关(/ai-gateway):用于管理网关实例、策略和工具接入。

  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)平台登记、密钥、服务开关和项目资源/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 安全状态

  1. 登录 Console 后,在顶部组织切换器中选择自己的组织,点击顶部页签栏的 成员(Members),进入 /console/organization-{organizationId}/members。

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

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

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

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

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

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

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

    • 如需转换表模式,请先检查可用目标池与预检结果。项目存在 Memory 数据或 PowerContext 配置时会阻止转换;请先评估数据保留和迁移方案。提交后可在 账号 → 表模式转换 页签追踪异步转换进度。

  3. 向下滚动至 服务 卡片:

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

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

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

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

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

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

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

    • 再次点击 添加角色 → 选择 团队,输入客服团队 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部分入口默认限制本机、私网和云元数据地址;覆盖范围及例外取决于部署配置
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 条工单记录?

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

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

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

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

原因与排查步骤: 组织 billing 和 analyst 默认没有 projects.read,因此在自托管配置下不能仅凭这两个角色进入项目;组织级账单或用量能力以实际部署及授权为准。项目资源操作还需对应权限。创建 API Key、开发密钥或登记平台需要相应管理权限,默认由组织 owner 或 admin 操作;请管理员按实际职责处理。

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

原因与排查步骤:

相关文档