项目总览
项目(Project)是 Agentbase 2.10.0 中所有应用后端资源与 AI 原生能力的独立隔离边界。业务数据库、对象存储桶、云函数、消息通道、内容审核策略,以及大模型供应商凭据、AI 网关、企业知识库、干预词库、长期记忆与智能体工作台配置,均严格归属于某个具体的 Project。本章全面阐述项目的创建与上下文边界、客户端平台登记(Platforms,支持 15 种客户端类型)以及服务端接入密钥(API Keys 与 Dev Keys)的全生命周期管理。
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
功能概述
以企业生产样板“企业智能客服与知识中台”(项目 ID:enterprise-ai-hub-210,归属组织:Agentbase 企业智能中台 69c6d1aa00062e6bb60)为例,当团队进入一个项目控制台时,首屏即为 Overview(项目总览) 页面。该模块承担三大核心职责:
- 项目运行水位实时透视:在首屏仪表盘集中呈现当前项目在选定时间窗内的 Requests(API 请求吞吐)、Bandwidth(网络带宽消耗)、Databases(数据库文档/行数与读写趋势)、Storage(存储桶占用量)、Auth(注册终端用户数) 以及 Realtime connections(实时长连接并发数)。
- 客户端平台来源白名单治理(Platforms):为 Web 浏览器应用(React / Vue / Next.js / SvelteKit 等)、移动端原生应用(iOS / Android)以及跨平台框架(Flutter / React Native / Unity)登记合法的
Hostname、AndroidPackage name或 AppleBundle ID。任何未登记来源的客户端 SDK 请求均会被网关层安全拦截。 - 服务端 API Keys 与开发环境 Dev Keys 签发治理:
- **API Key(
standard_前缀):面向生产环境后端微服务、定时任务与外部 Agent 编排器,通过 12 大分类 Scope 权限选择器** 实施最小权限授权,支持到期时间设定、Secret 掩码保护与平滑轮换。 - **Dev Key(
X-Appwrite-Dev-Key)**:面向本地开发联调阶段,在最长 30 天的短期有效期内临时豁免请求速率限制(Ratelimit)与浏览器 CORS 跨域拦截,并返回详细诊断堆栈。
- **API Key(
| 子模块名称 | 控制台路由后缀 | 适用调用面 | 所需写权限 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. 控制台导航入口与权限要求
- 进入项目总览:在顶部导航选择组织
Agentbase 企业智能中台,点击项目企业智能客服与知识中台,默认进入/console/project-default-enterprise-ai-hub-210/overview(如图 1 所示)。 - 切换 Integrations 三大页签:在项目总览页下半部分的 Integrations 区域,可直接点击 Platforms、API keys、Dev keys 三个页签切换管理视图。
- API Key Secret 的服务端读取安全边界:
- 在 Console 或通过管理 API 读取某个 API Key 的
secret明文时,服务端实施严格的身份边界校验:**仅项目所属组织的owner、该 API Key 的创建者本人以及平台特权成员可读取完整secret**。 - 其他成员通过接口查询 Key 列表或详情时,服务端会自动将
secret字段置空,防止横向越权窃取生产密钥。
- 在 Console 或通过管理 API 读取某个 API Key 的
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:打开平台创建向导
- 在项目 Overview → Integrations 区域保持在 Platforms 页签(路径
/overview/platforms)。 - 点击右侧 Add platform 按钮,从下拉菜单中选择客户端平台类型(后端接口对应
POST /v1/projects/{projectId}/platforms)。系统共支持 15 种细分平台类型白名单。
步骤 2:按平台类型填写标识字段
| 平台大类 | 细分平台类型标识(type 白名单) | 必填字段与服务端校验约束 | 生产配置示例与获取方式 |
|---|---|---|---|
| Web 应用 | web | Name(≤128 字符)+ Hostname(合法主机名或通配域名) | Name:企业客服 Web 门户;Hostname:support.enterprise.example.com(本地开发填 localhost)。向导支持选择 React / Next.js / Vue / Nuxt / Svelte / Angular 生成初始化代码。 |
| Android 原生 | android | Name(≤128 字符)+ Package name(key ≤256 字符)+ 可选 store | Package name 必须与 Android 工程 app/build.gradle 中的 applicationId 完全一致(如 com.enterprise.aihub)。 |
| Apple 原生 | apple-ios · apple-macos · apple-watchos · apple-tvos | Name(≤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 Native | react-native-android · react-native-ios | Android 填 Package name;iOS 填 Bundle ID | 分别对应 android/app/build.gradle 与 ios/*.xcodeproj 中的包标识。 |
| Unity 引擎 | unity | Name + 目标平台的 Package name / Bundle ID | 用于 3D 数字人客服或交互式终端应用的客户端接入。 |
步骤 3:修改与删除已登记平台
- 点击列表中任意已登记平台,进入详情页可随时修改 Name、Hostname / Package name / Bundle ID 及应用商店 ID(
store,≤256 字符)。 - 删除风险提示:在平台详情页底部点击删除并确认后,来自该域名或客户端包名的前端请求将立即无法通过来源校验,浏览器端会开始收到
401或 CORS 跨域拦截错误。
2. 创建与管理服务端 API Keys(含 12 大分类 Scope 详解)
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
步骤 1:创建 API Key 并配置有效期
- 在 Overview → Integrations 区域点击切换到 API keys 页签(路径
/overview/api-keys,如图 2 所示),点击右上角 Create API key。 - 在 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配合定期轮换策略。
- Name(必填):输入清晰的用途标识(最长 128 字符,例如
步骤 2:按最小权限原则勾选 12 大分类 Scopes
创建向导的 Scopes 区域将全平台权限划分为 12 个折叠分类面板,支持一键 Select all / Deselect all 或按分类精细勾选:
| 序号 | Scope 分类面板名称 | 涵盖的核心权限标识示例 | 典型适用业务场景 |
|---|---|---|---|
| 1 | Auth | users.read · users.write · teams.read · teams.write · sessions.write | 后端同步企业员工账号、管理客服坐席团队、强制注销异常用户会话 |
| 2 | Database | databases.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 兼容变体) |
| 3 | Functions | functions.read · functions.write · execution.read · execution.write | 触发异步云函数、上传 Java 17 JAR 部署包、按路径查询函数执行记录 |
| 4 | Memory | 记忆服务读写、用户画像、经验技能蒸馏与 Pipeline 管理相关 Scope | 后端 Agent 编排器写入多轮对话记忆、检索用户画像与执行上下文压缩 |
| 5 | Storage | buckets.read · buckets.write · files.read · files.write | 管理 kb_enterprise_docs 与 agent_multimedia_bucket 存储桶及上传/下载文件 |
| 6 | Messaging | messages.read/write · topics.read/write · subscribers.read/write · providers.read/write | 后端工单流转时自动触发邮件、短信或 App Push 通知 |
| 7 | Sites | sites.read · sites.write · deployments.read/write | CI/CD 流水线自动触发前端站点构建部署与一键回滚 |
| 8 | AI Gateway | 统一 AI 网关、逻辑模型路由、安全护栏与缓存策略管理 Scope | 自动化配置与调用 prod-enterprise-ai-gateway 网关面 |
| 9 | Knowledge Base | 知识库、文档摄取、词库(Lexicon)、混合检索与高阶索引构建 Scope | 自动化同步企业 Wiki 文档至 kb_enterprise_support 并执行检索增强 |
| 10 | Observability | Trace/Observation 查询、评估任务(含知识索引质量评估)、Prompt 解析与数据集 Scope | CI 质量门禁自动触发 RAG 解析评估与 GraphRAG/Wiki 索引质量评测 |
| 11 | Trace Logs | 项目级追踪日志查询 Scope | 运维自动化脚本拉取异常请求追踪日志 |
| 12 | Other | health.read · locale.read · avatars.read 等通用辅助权限 | 监控系统调用健康检查、区域字典与头像服务 |
步骤 3:复制、查看与平滑轮换 API Key
- 点击 Create 完成后,页面自动跳转至该 Key 的详情页(
/overview/api-keys/{keyId}),顶部弹出提示条并提供 Copy API key(复制standard_开头的完整 Secret)与 Copy endpoint(复制当前区域 API 端点,如https://appbuild.oceanbase.com/v1)。 - 日常巡检与状态监控:
- 在 API keys 列表中,可查看每枚密钥的 **Last accessed(最后访问时间,未调用过显示
never) 与 Expiration date**。 - 距离到期不足 14 天时,界面自动高亮显示
Expires soon预警徽标;一旦过期则显示Expired并立即拒绝一切调用。
- 在 API keys 列表中,可查看每枚密钥的 **Last accessed(最后访问时间,未调用过显示
- 生产零停机轮换(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(或在列表页勾选批量删除)徹底吊销旧密钥。
- 第一步:在 API keys 页签点击 Create API key,勾选与旧 Key 完全一致的 Scopes,生成新 Key
3. 创建与使用开发环境 Dev Keys
- 在 Overview → Integrations 区域点击 Dev keys 页签(路径
/overview/dev-keys),点击 Create dev key。 - 在弹窗中输入 Name(如
local-frontend-debug),并在有效期下拉框中选择1 Day、7 Days或30 Days,点击创建。 - 复制生成的 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 接口调用完全不受影响。