AgentbaseDocs
文档目录

核心概念

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

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

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

功能概述

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

本章对上述核心概念进行系统性拆解,作为全书各功能模块的设计与排障基石。

核心概念与架构

Agentbase 的全局架构由三级资源容器(Account → Organization → Project)、双平面鉴权网关(Control Plane vs Data Plane)、双模存储引擎(JsonTable vs Shared V2)以及六大 AI 原生原语共同组成。

flowchart TB
    subgraph Hierarchy["三级资源与治理层级"]
        Account["开发者账号 (Console Account)<br/>MFA / 恢复码 / 全局会话 / 账号级 30 日用量"]
        Org["组织 (Organization: 69c6d1aa00062e6bb60)<br/>Agentbase 企业智能中台<br/>成员角色 (Owner/Admin/Developer/Editor/Billing/Analyst)"]
        Proj["项目 (Project: enterprise-ai-hub-210)<br/>企业智能客服与知识中台<br/>Region + OceanBase Shared V2 表模式 + Services 开关"]
        Account --> Org
        Org --> Proj
    end

    subgraph AuthPlanes["双平面四类鉴权凭证"]
        ConsoleAuth["1. Console Session<br/>开发者浏览器 Cookie + X-Appwrite-Mode: admin"]
        ServerKey["2. Server API Key (standard_...)<br/>后端微服务 X-Appwrite-Key (按 Scopes 授权)"]
        ClientSess["3. Client Session / JWT<br/>终端用户 (user_zhangwei_001) 会话或短期 JWT"]
        DevKey["4. Dev Key (仅开发环境)<br/>X-Appwrite-Dev-Key (豁免 CORS 与限流)"]
    end

    subgraph ProjectResources["项目内核心资源原语(天然按 Project 隔离)"]
        subgraph BuildPrimitives["应用后端原语 (Build)"]
            AuthUsers["Auth 终端用户与团队<br/>(Users / Teams / Targets)"]
            DBTables["Databases 数据库与表<br/>(enterprise_biz_db / customer_tickets)"]
            StorageBuckets["Storage 存储桶与文件<br/>(kb_enterprise_docs)"]
            Compute["Functions 云函数 & Sites 站点<br/>(ACS 受限身份沙箱)"]
        end

        subgraph AIPrimitives["AI 原生原语 (AI & AgentOps)"]
            Gateways["模型与 AI 网关<br/>(dashscope-prod / prod-enterprise-ai-gateway)"]
            KBLex["知识库与干预词库<br/>(kb_enterprise_support + GraphRAG/Wiki/Lexicon)"]
            MemoryEngine["Memory 长期记忆引擎<br/>(事实提取 / 画像 / Context Dreaming / 技能蒸馏)"]
            WorkbenchObs["智能体工作台 & AgentOps<br/>(对话联调 / OTLP Traces / 索引质量评估)"]
        end
    end

    Proj --> AuthPlanes
    AuthPlanes --> BuildPrimitives
    AuthPlanes --> AIPrimitives
    KBLex --> Gateways
    MemoryEngine --> Gateways
    WorkbenchObs --> Gateways
    WorkbenchObs --> KBLex
    WorkbenchObs --> MemoryEngine

1. 三级资源层级与项目存储模式(JsonTable vs Shared V2)

Agentbase 中的一切资源均挂载在明确的层级节点下,不存在游离于项目之外的业务数据或密钥:

存储模式维度共享表 / 独占表(传统模式 / 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);<br/>2. 目标服务在 Settings → Services 中必须开启;<br/>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. 组织级与项目级控制台导航入口

治理层级核心操作模块控制台路由路径最小所需组织角色
账号级(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 安全状态

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

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

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

安全默认值

领域默认行为
外部 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 条工单记录?

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

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)”或准备转换表模式时无法操作?

原因与排查步骤:

相关文档