AgentbaseDocs
文档目录

项目总览

项目(Project)是 Agentbase 2.10.0 中所有应用后端资源与 AI 原生能力的独立隔离边界。业务数据库、对象存储桶、云函数、消息通道、内容审核策略,以及大模型供应商凭据、AI 网关、企业知识库、干预词库、长期记忆与智能体工作台配置,均严格归属于某个具体的 Project。本章全面阐述项目的创建与上下文边界、客户端平台登记(Platforms,支持 15 种客户端类型)以及服务端接入密钥(API Keys 与 Dev Keys)的全生命周期管理。

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

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

功能概述

以企业生产样板“企业智能客服与知识中台”(项目 ID:enterprise-ai-hub-210,归属组织:Agentbase 企业智能中台 69c6d1aa00062e6bb60)为例,当团队进入一个项目控制台时,首屏即为 Overview(项目总览) 页面。该模块承担三大核心职责:

子模块名称控制台路由后缀适用调用面所需写权限 Scope / 角色
Overview 实时大盘/overview控制面可视化监控任意项目成员可读(含 billing / analyst)
Platforms(平台登记)/overview/platforms客户端访问面(Web SDK / 移动端 SDK)platforms.write(组织角色 owner / admin / developer / editor)
API keys(生产密钥)/overview/api-keys · .../api-keys/{keyId}服务端访问面(Server SDK / REST API / Agent Runtime)keys.write(Secret 读取受服务端可见性边界强制保护)
Dev keys(开发密钥)/overview/dev-keys · .../dev-keys/{keyId}本地开发调试环境(绕过 CORS 与限流)keys.write(有效期强制限制为 1 / 7 / 30 天)
Getting started(入门引导)/get-started新项目初始化与 AI 编程工具(Agent Skill)接入任意项目成员可读

核心概念与架构

在项目 enterprise-ai-hub-210 内部,项目上下文(区域、表模式、服务开关)与 Integrations 区域的三大接入配置(Platforms、API Keys、Dev Keys)共同构成了数据面流量的准入控制网关:

flowchart TB
    subgraph ProjectContext["项目容器上下文 (Project: enterprise-ai-hub-210)"]
        Region["物理区域 (Region: default)"]
        TableMode["存储底座 (OceanBase Shared V2 表模式)"]
        ServiceToggle["服务开关 (Settings -> Services)<br/>Auth / DB / Storage / Functions / Memory / KB / AI Gateway"]
    end

    subgraph Integrations["Overview -> Integrations 准入凭证中心"]
        Platforms["1. Platforms 平台白名单 (15 种类型)<br/>Web Hostname / Android Package / Apple Bundle ID"]
        APIKeys["2. Production API Keys (standard_...)<br/>12 大分类 Scopes 最小权限 + 过期时间策略"]
        DevKeys["3. Development Dev Keys (1/7/30 天)<br/>仅开发环境豁免 CORS 与 Ratelimit"]
    end

    subgraph Callers["外部应用与服务接入请求"]
        Frontend["浏览器 / App 终端客户端<br/>(X-Appwrite-Project + Origin/Package)"]
        DevLocal["本地开发前端调试<br/>(+ X-Appwrite-Dev-Key)"]
        Backend["企业生产后端微服务 / Agent<br/>(X-Appwrite-Project + X-Appwrite-Key)"]
    end

    Frontend -- "校验已登记 Platform + Services 开关 + 资源 ACL" --> Platforms
    DevLocal -- "命中有效 Dev Key 豁免 CORS 与限流" --> DevKeys
    Backend -- "校验 API Key 有效期 + 勾选的 Scopes" --> APIKeys
    Platforms --> ProjectContext
    DevKeys --> ProjectContext
    APIKeys --> ProjectContext

项目四大核心上下文属性表

上下文属性配置时机与修改位置对项目内资源的全局影响
**项目 ID($id)与名称**创建项目时指定 $id(如 enterprise-ai-hub-210);名称可在 Settings 修改$id 一旦创建不可更改,所有 SDK 初始化与 REST 请求均需通过 X-Appwrite-Project: enterprise-ai-hub-210 携带该标识。
物理区域(Region)创建项目时选择决定该项目下数据库、存储桶、云函数与知识库索引的物理计算与存储集群位置。
项目表模式(Table Mode)创建时初始化,可在 Settings → 项目表模式 中转换决定业务数据采用共享表、独占表、深度独占表还是 OceanBase **Shared V2 模式;其中 AI Memory 长期记忆服务强制要求 Shared V2 模式**。
服务开关(Services)Settings → Overview → Services逐项控制客户端 SDK 对各服务的访问可达性;注意统一 AI 网关(AI Gateway)默认关闭,需在此开启后左侧边栏才会显示入口。

角色、入口与关联关系

1. 控制台导航入口与权限要求

2. API Key 与 Dev Key 的核心定位对比

对比维度生产环境 API Key(API keys)开发调试密钥(Dev keys)
设计定位生产与预发服务端专用:供后端服务、云函数、外部 Agent 安全调用项目 API仅限本地开发环境:帮助前端开发者在本地调试时绕过平台限流与浏览器 CORS 报错
请求头名称X-Appwrite-Key: standard_<secret>X-Appwrite-Dev-Key: <secret>
权限范围(Scopes)细粒度受控:创建时从 12 大分类中按需勾选 Scope,绕过行级 ACL无 Scope 概念:不授予任何额外数据读写权限,仅豁免 CORS/Ratelimit 并开启详细错误日志
可选有效期Never(永不过期)/ 7 Days / 30 days / 90 days / 1 Year / Custom Date强制短期:**仅限 1 Day / 7 Days / 30 Days**(绝不允许创建永久有效的 Dev Key)
生产环境红线严禁硬编码到前端浏览器/移动端代码中严禁在生产环境使用(否则将失去速率限制与跨域防护)

功能详解与操作指南

1. 登记与管理客户端平台(Platforms)

当你的企业智能客服前端(Web 门户、iOS/Android 客户端或 Flutter 跨端应用)直接通过客户端 SDK 访问 Agentbase 时,网关会根据请求的 Origin(Web)或应用包名校验是否已在 Platforms 中登记。

步骤 1:打开平台创建向导

步骤 2:按平台类型填写标识字段

平台大类细分平台类型标识(type 白名单)必填字段与服务端校验约束生产配置示例与获取方式
Web 应用webName(≤128 字符)+ Hostname(合法主机名或通配域名)Name:企业客服 Web 门户;Hostname:support.enterprise.example.com(本地开发填 localhost)。向导支持选择 React / Next.js / Vue / Nuxt / Svelte / Angular 生成初始化代码。
Android 原生androidName(≤128 字符)+ Package name(key ≤256 字符)+ 可选 storePackage name 必须与 Android 工程 app/build.gradle 中的 applicationId 完全一致(如 com.enterprise.aihub)。
Apple 原生apple-ios · apple-macos · apple-watchos · apple-tvosName(≤128 字符)+ Bundle ID(key ≤256 字符)+ 可选 store按目标苹果设备系统分别登记;Bundle ID 取自 Xcode 主 Target → General → Identity → Bundle Identifier。
Flutter 跨端flutter-web · flutter-android · flutter-ios · flutter-linux · flutter-macos · flutter-windows按目标编译平台分别登记:Web 填 Hostname,其余填 Package name / Bundle ID若一套 Flutter 代码同时发布 Web、iOS 与 Android,需在 Platforms 下分别添加 3 条对应类型的平台记录。
React Nativereact-native-android · react-native-iosAndroid 填 Package name;iOS 填 Bundle ID分别对应 android/app/build.gradle 与 ios/*.xcodeproj 中的包标识。
Unity 引擎unityName + 目标平台的 Package name / Bundle ID用于 3D 数字人客服或交互式终端应用的客户端接入。

步骤 3:修改与删除已登记平台

2. 创建与管理服务端 API Keys(含 12 大分类 Scope 详解)

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

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

步骤 1:创建 API Key 并配置有效期

步骤 2:按最小权限原则勾选 12 大分类 Scopes

创建向导的 Scopes 区域将全平台权限划分为 12 个折叠分类面板,支持一键 Select all / Deselect all 或按分类精细勾选:

序号Scope 分类面板名称涵盖的核心权限标识示例典型适用业务场景
1Authusers.read · users.write · teams.read · teams.write · sessions.write后端同步企业员工账号、管理客服坐席团队、强制注销异常用户会话
2Databasedatabases.read/write · tables.read/write · columns.read/write · indexes.read/write · rows.read/write(及云端备份 policies.* / archives.* / restorations.*)后端微服务读写 enterprise_biz_db 数据库与 customer_tickets 工单表(勾选新式 tables/columns/rows Scope 时系统自动附带旧式 collections/attributes/documents 兼容变体)
3Functionsfunctions.read · functions.write · execution.read · execution.write触发异步云函数、上传 Java 17 JAR 部署包、按路径查询函数执行记录
4Memory记忆服务读写、用户画像、经验技能蒸馏与 Pipeline 管理相关 Scope后端 Agent 编排器写入多轮对话记忆、检索用户画像与执行上下文压缩
5Storagebuckets.read · buckets.write · files.read · files.write管理 kb_enterprise_docs 与 agent_multimedia_bucket 存储桶及上传/下载文件
6Messagingmessages.read/write · topics.read/write · subscribers.read/write · providers.read/write后端工单流转时自动触发邮件、短信或 App Push 通知
7Sitessites.read · sites.write · deployments.read/writeCI/CD 流水线自动触发前端站点构建部署与一键回滚
8AI Gateway统一 AI 网关、逻辑模型路由、安全护栏与缓存策略管理 Scope自动化配置与调用 prod-enterprise-ai-gateway 网关面
9Knowledge Base知识库、文档摄取、词库(Lexicon)、混合检索与高阶索引构建 Scope自动化同步企业 Wiki 文档至 kb_enterprise_support 并执行检索增强
10ObservabilityTrace/Observation 查询、评估任务(含知识索引质量评估)、Prompt 解析与数据集 ScopeCI 质量门禁自动触发 RAG 解析评估与 GraphRAG/Wiki 索引质量评测
11Trace Logs项目级追踪日志查询 Scope运维自动化脚本拉取异常请求追踪日志
12Otherhealth.read · locale.read · avatars.read 等通用辅助权限监控系统调用健康检查、区域字典与头像服务

步骤 3:复制、查看与平滑轮换 API Key

3. 创建与使用开发环境 Dev Keys

常见问题与排障

Q1:为什么我在控制台点开同事创建的 API Key 详情页,Secret 字段显示为空或无法复制?

原因与排查步骤: 这是 Agentbase 服务端强制执行的密钥可见性安全边界:为了防止普通协作成员导出非本人负责的生产凭据,服务端规定仅**项目所属组织的 Owner、该 API Key 的创建者本人以及平台特权管理员**能够读取 secret 明文;其他成员查询时,服务端会在响应层将 secret 置空。若你需要接入某项服务,请使用自己的账号(需具备 keys.write 权限)新建一枚专属的最小权限 API Key,切勿多人共用同一枚密钥。

Q2:前端 Web 应用部署到新域名后,调用接口报 CORS 跨域错误或 401,但本地 localhost 却是正常的?

原因与排查步骤: 这是因为之前仅在 Overview → Integrations → Platforms 中登记了 localhost(或本地使用了 Dev Key 绕过了 CORS 校验),而尚未登记生产/预发新域名。请前往 Platforms 页签点击 Add platform → Web app,将新上线的完整业务域名(Hostname,不含 https:// 协议头和路径后缀,例如 chat.enterprise.example.com)添加进白名单,保存后前端跨域请求即刻放行。

Q3:旧代码中使用了 collections.read 或 documents.write 等旧版权限概念,在新建 API Key 的 Scopes 面板里怎么找不到?

原因与排查步骤: Agentbase 2.10.0 控制台统一采用关系与表格化术语(tables.*、columns.*、rows.*),旧式前缀(collections.*、attributes.*、documents.*)不在 UI 选择器中单独重复列出。**你只需在 Database 分类下勾选对应的 tables.read、columns.read、rows.write 等新式 Scope**,控制台在向服务端提交保存时会自动在底层附带对应的旧式兼容 Scope 变体,旧版 SDK 与 REST 接口调用完全不受影响。

相关文档