Docs
文档目录

项目总览

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

项目概览页(沿用已登记截图)

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

功能概述

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

  1. 项目运行水位实时透视:在首屏仪表盘集中呈现当前项目在选定时间窗内的 Requests(API 请求吞吐)、Bandwidth(网络带宽消耗)、Databases(数据库文档/行数与读写趋势)、Storage(存储桶占用量)、Auth(注册终端用户数) 以及 Realtime connections(实时长连接并发数)。

  2. 客户端平台来源白名单治理(Platforms):为 Web 浏览器应用(React / Vue / Next.js / SvelteKit 等)、移动端原生应用(iOS / Android)以及跨平台框架(Flutter / React Native / Unity)登记合法的 Hostname、Android Package name 或 Apple Bundle ID。任何未登记来源的客户端 SDK 请求均会被网关层安全拦截。

  3. 服务端 API Keys 与开发环境 Dev Keys 签发治理:

    • API Key(standard_ 前缀):面向生产环境后端微服务、定时任务与外部 Agent 编排器,通过 12 大分类 Scope 权限选择器 实施最小权限授权,支持到期时间设定、Secret 掩码保护与平滑轮换。

    • Dev Key(X-Appwrite-Dev-Key):面向本地开发联调阶段,在最长 30 天的短期有效期内临时豁免请求速率限制(Ratelimit)与浏览器 CORS 跨域拦截,并返回详细诊断堆栈。

子模块名称控制台路由后缀适用调用面所需写权限 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 天)
旧入门引导路径/get-started重定向至 /overview/platforms,请在平台登记页继续操作任意项目成员可读

核心概念与架构

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

项目总览:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

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

上下文属性配置时机与修改位置对项目内资源的全局影响
项目 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. 控制台导航入口与权限要求

  1. 进入项目总览:在顶部导航选择组织 Agentbase 企业智能中台,点击项目 企业智能客服与知识中台,默认进入 /console/project-{region}-{project}/overview/platforms。实际区域与项目标识以当前项目为准;图 1 为历史界面参考。

  2. 切换 Integrations 三大页签:在项目总览页下半部分的 Integrations 区域,可直接点击 Platforms、API keys、Dev keys 三个页签切换管理视图。

  3. API Key Secret 的服务端读取安全边界:

    • 在 Console 或通过管理 API 读取某个 API Key 的 secret 明文时,服务端实施严格的身份边界校验:仅项目所属组织的 owner、该 API Key 的创建者本人以及平台特权成员可读取完整 secret。

    • 其他成员通过接口查询 Key 列表或详情时,服务端会自动将 secret 字段置空,防止横向越权窃取生产密钥。

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:打开平台创建向导

  1. 在项目 Overview → Integrations 区域保持在 Platforms 页签(路径 /overview/platforms)。

  2. 点击右侧 Add platform 按钮,从下拉菜单中选择客户端平台类型(后端接口对应 POST /v1/projects/{projectId}/platforms)。系统共支持 15 种细分平台类型白名单。

步骤 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 详解)

项目 API Keys 页(沿用已登记截图)

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

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

  1. 在 Overview → Integrations 区域点击切换到 API keys 页签(路径 /overview/api-keys,如图 2 所示),点击右上角 Create API key。

  2. 在 Configuration 区域填写:

    • Name(必填):输入清晰的用途标识(最长 128 字符,例如 cs-backend-prod-key 或 kb-ingestion-worker-key)。

    • Expiration(有效期):支持选择 Never、7 Days、30 days、90 days、1 Year 或 Custom Date(自定义日期最早为次日)。生产环境建议设置 90 days 或 1 Year 配合定期轮换策略。

步骤 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

  1. 点击 Create 完成后,页面自动跳转至该 Key 的详情页(/overview/api-keys/{keyId}),顶部弹出提示条并提供 Copy API key(复制 standard_ 开头的完整 Secret)与 Copy endpoint(复制当前区域 API 端点,如 https://appbuild.oceanbase.com/v1)。

  2. 日常巡检与状态监控:

    • 在 API keys 列表中,可查看每枚密钥的 Last accessed(最后访问时间,未调用过显示 never) 与 Expiration date。

    • 距离到期不足 14 天时,界面自动高亮显示 Expires soon 预警徽标;一旦过期则显示 Expired 并立即拒绝一切调用。

  3. 生产零停机轮换(Key Rotation)标准流程:

    • 第一步:在 API keys 页签点击 Create API key,勾选与旧 Key 完全一致的 Scopes,生成新 Key cs-backend-prod-key-v2。

    • 第二步:将新 Key Secret 更新至企业配置中心或 Kubernetes Secret,滚动重启应用服务。

    • 第三步:观察旧 Key 的 Last accessed 时间不再变化、新 Key 的 Last accessed 正常刷新后,进入旧 Key 详情页底部点击 Delete API key(或在列表页勾选批量删除)徹底吊销旧密钥。

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

  1. 在 Overview → Integrations 区域点击 Dev keys 页签(路径 /overview/dev-keys),点击 Create dev key。

  2. 在弹窗中输入 Name(如 local-frontend-debug),并在有效期下拉框中选择 1 Day、7 Days 或 30 Days,点击创建。

  3. 复制生成的 Dev Key Secret,在本地开发环境的请求中附加 HTTP 头 X-Appwrite-Dev-Key: <DEV_KEY>(或通过客户端 SDK 的 setDevKey() 方法传入),即可在本地调试期间免除频繁修改 CORS 域名白名单与触发限流的困扰。

常见问题与排障

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 接口调用完全不受影响。

相关文档