项目总览
项目(Project)是 Agentbase 中所有应用后端资源与 AI 原生能力的独立隔离边界。业务数据库、对象存储桶、云函数、消息通道、内容审核策略,以及大模型供应商凭据、AI 网关、企业知识库、干预词库、长期记忆与智能体工作台配置,均严格归属于某个具体的 Project。本章全面阐述项目的创建与上下文边界、客户端平台登记以及服务端接入密钥(API Keys 与 Dev Keys)的全生命周期管理。
功能概述
团队进入项目后,可通过侧栏访问概览页面;新项目也可能先显示接入引导。该模块承担三大核心职责:
项目运行水位实时透视:在首屏仪表盘集中呈现当前项目在选定时间窗内的 Requests(API 请求吞吐)、Bandwidth(网络带宽消耗)、Databases(数据库文档/行数与读写趋势)、Storage(存储桶占用量)、Auth(注册终端用户数) 以及 Realtime connections(实时长连接并发数)。
客户端平台登记(Platforms):为 Web 应用登记
Hostname,为移动应用登记Package name或Bundle ID。浏览器请求在适用条件下校验Origin;平台登记不能替代身份验证、服务开关和资源权限。服务端 API Keys 与开发环境 Dev Keys 签发治理:
API Key(
standard_前缀):面向生产环境后端微服务、定时任务与外部 Agent 编排器,通过 13 个分类 Scope 权限选择器 实施最小权限授权,支持到期时间设定、Secret 掩码保护与平滑轮换。Dev Key(
X-Appwrite-Dev-Key):供本地开发调试使用,可豁免请求速率限制和适用的浏览器来源检查,并提供详细诊断。控制台提供 1、7、30 天选项;管理接口不强制 30 天上限,应设置到期时间并及时吊销。
| 子模块名称 | 控制台路由后缀 | 适用调用面 | 所需写权限 Scope / 角色 |
|---|---|---|---|
| 概览实时大盘 | /overview | 控制面可视化监控 | 需要项目读取权限;组织 billing 和 analyst 角色默认不含 projects.read |
| 平台登记(Platforms) | /overview/platforms | 客户端平台配置 | platforms.write(默认组织角色中为 owner / admin) |
| API 密钥(生产密钥) | /overview/api-keys · .../api-keys/{keyId} | 服务端访问面(Server SDK / REST API / Agent Runtime) | keys.write(Secret 读取受服务端可见性边界强制保护) |
| 开发密钥 | /overview/dev-keys · .../dev-keys/{keyId} | 本地开发调试环境 | devKeys.write(默认组织角色为 owner / admin;控制台提供 1 / 7 / 30 天选项) |
| 项目引导 | /get-started | 展示项目创建、连接平台和构建应用的引导 | 需项目读取权限;配置操作还需相应权限 |
核心概念与架构
在项目 enterprise-ai-hub-210 内部,项目上下文(区域、表模式、服务开关)与 集成 区域的三大接入配置(Platforms、API Keys、Dev Keys)共同构成了数据面流量的准入控制网关:
流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。
项目四大核心上下文属性表
| 上下文属性 | 配置时机与修改位置 | 对项目内资源的全局影响 |
|---|---|---|
项目 ID($id)与名称 | 创建项目时指定 $id(如 enterprise-ai-hub-210);名称可在 设置 修改 | $id 一旦创建不可更改,所有 SDK 初始化与 REST 请求均需通过 X-Appwrite-Project: enterprise-ai-hub-210 携带该标识。 |
| 物理区域(Region) | 创建项目时选择 | 决定该项目下数据库、存储桶、云函数与知识库索引的物理计算与存储集群位置。 |
| 项目表模式(Table Mode) | 创建时初始化,可在 设置 → 项目表模式 中转换 | 决定业务数据采用共享表、独占表、深度独占表还是 OceanBase Shared V2 模式;其中 AI Memory 长期记忆服务强制要求 Shared V2 模式。 |
| 服务开关(Services) | 设置 → 概览 → 服务 | 逐项控制客户端 SDK 对各服务的访问可达性;注意统一 AI 网关(AI Gateway)默认关闭,需在此开启后左侧边栏才会显示入口。 |
角色、入口与关联关系
1. 控制台导航入口与权限要求
进入项目总览:在顶部导航选择自己的组织和项目,默认进入
/console/project-{region}-{project}/overview/platforms。实际区域与项目标识以当前项目为准。切换集成区域的三个页签:在项目总览页下半部分的 集成 区域,可直接点击 平台、API 密钥、开发密钥 三个页签切换管理视图。
API Key Secret 的服务端读取安全边界:
项目 API Key 列表与详情先检查接口权限;用户身份的明文读取还取决于项目创建账号、平台特权、服务端认定的所有者身份,或通过有效组织成员及项目绑定校验的
owner/admin。密钥的创建者身份本身不是读取条件。不满足明文读取条件的用户查询时,
secret会被置空;通过 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) | 细粒度受控:创建时从 13 个分类中按需勾选 Scope,绕过行级 ACL | 无 Scope 概念:不授予任何额外数据读写权限,仅豁免 CORS/Ratelimit 并开启详细错误日志 |
| 可选有效期 | Never / 7 Days / 30 days / 90 days / 1 Year / Custom Date | 控制台提供 1 Day / 7 Days / 30 Days;管理接口允许空到期时间且不强制 30 天上限。建议设定短有效期并在使用后吊销 |
| 生产环境红线 | 严禁硬编码到前端浏览器/移动端代码中 | 严禁在生产环境使用(否则将失去速率限制与跨域防护) |
功能详解与操作指南
1. 登记与管理客户端平台(Platforms)
Web 应用通过浏览器访问时,请在 平台 中登记前端域名。适用的来源检查会校验请求的 Origin;移动端包标识用于平台配置,不能据此假定每个移动请求都校验包名。访问仍需满足身份、服务开关和资源权限要求。
步骤 1:打开平台创建向导
在项目 概览 → 集成 区域保持在 平台 页签(路径
/overview/platforms)。点击创建平台,从下拉菜单中选择客户端平台类型(后端接口对应
POST /v1/projects/{projectId}/platforms)。系统共支持 15 种细分平台类型白名单。
步骤 2:按平台类型填写标识字段
| 平台大类 | 细分平台类型标识(type 白名单) | 必填字段与服务端校验约束 | 生产配置示例与获取方式 |
|---|---|---|---|
| Web 应用 | web | 名称(≤128 字符)+ 主机名(合法主机名或通配域名) | Name:企业客服 Web 门户;Hostname:support.enterprise.example.com(本地开发填 localhost)。向导支持选择 React / Next.js / Vue / Nuxt / Svelte / Angular 生成初始化代码。 |
| Android 原生 | android | 名称(≤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 | 名称(≤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 | 名称 + 目标平台的 Package name / Bundle ID | 用于 3D 数字人客服或交互式终端应用的客户端接入。 |
步骤 3:修改与删除已登记平台
点击列表中任意已登记平台,进入详情页可随时修改 名称、Hostname / Package name / Bundle ID 及应用商店 ID(
store,≤256 字符)。删除风险提示:删除 Web 域名登记可能影响该域名的浏览器来源检查或跳转地址校验。具体请求仍受路由与凭据条件影响;不要依赖删除平台注册来阻止所有客户端访问,应同时检查身份、服务开关和资源权限。
2. 创建与管理服务端 API Keys(含 13 个分类 Scope 详解)
图:2.12.0 测试项目的临时示例 API 密钥;截图后该密钥已删除。
步骤 1:创建 API Key 并配置有效期
在 概览 → 集成 区域点击切换到 API 密钥 页签(路径
/overview/api-keys),点击右上角 创建 API 密钥。在 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:按最小权限原则勾选 13 个分类 Scopes
创建向导的 Scopes 区域将全平台权限划分为 13 个折叠分类面板,支持一键 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 | Models | llm-gateway.providers.read/write · llm-gateway.keys.read/write · llm-gateway.execute | 管理模型提供商、模型密钥及调用模型 |
| 9 | Tool Gateway | aiGateway.read · aiGateway.write · aiGateway.execute | 管理及调用工具网关 |
| 10 | Knowledge Base | 知识库、文档摄取、词库(Lexicon)、混合检索与高阶索引构建 Scope | 自动化同步企业 Wiki 文档至 kb_enterprise_support 并执行检索增强 |
| 11 | Observability | Trace/Observation 查询、评估任务(含知识索引质量评估)、Prompt 解析与数据集 Scope | CI 质量门禁自动触发 RAG 解析评估与 GraphRAG/Wiki 索引质量评测 |
| 12 | Trace Logs | 项目级追踪日志查询 Scope | 运维自动化脚本拉取异常请求追踪日志 |
| 13 | 其他 | health.read · locale.read · avatars.read 等通用辅助权限 | 监控系统调用健康检查、区域字典与头像服务 |
步骤 3:复制、查看与平滑轮换 API Key
点击 创建 完成后,页面自动跳转至该 Key 的详情页(
/overview/api-keys/{keyId}),顶部弹出提示条并提供 复制 API 密钥(复制standard_开头的完整 Secret)与 复制端点(复制当前区域 API 端点,如https://appbuild.oceanbase.com/v1)。日常巡检与状态监控:
在 API keys 列表中,可查看每枚密钥的 Last accessed(最后访问时间,未调用过显示
never) 与 过期日期。距离到期不足 14 天时,界面自动高亮显示
Expires soon预警徽标;一旦过期则显示Expired并立即拒绝一切调用。
生产零停机轮换(Key Rotation)标准流程:
第一步:在 API 密钥 页签点击 创建 API 密钥,勾选与旧 Key 完全一致的 Scopes,生成新 Key
cs-backend-prod-key-v2。第二步:将新 Key Secret 更新至企业配置中心或 Kubernetes Secret,滚动重启应用服务。
第三步:观察旧 Key 的 上次访问 时间不再变化、新 Key 的 上次访问 正常刷新后,进入旧 Key 详情页底部点击 删除 API 密钥(或在列表页勾选批量删除)徹底吊销旧密钥。
3. 创建与使用开发环境 Dev Keys
在 概览 → 集成 区域点击 开发密钥 页签(路径
/overview/dev-keys),点击 创建开发密钥。在弹窗中输入 名称(如
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 字段显示为空或无法复制?
原因与排查步骤: 列表与详情接口先校验访问权限,再按项目创建账号、平台特权、服务端认定的所有者身份或有效组织成员及项目绑定条件判断是否返回明文;符合绑定条件的组织 owner / admin 可以读取,密钥创建者身份本身不是读取条件。使用 API Key 调用管理接口查询列表或详情时会脱敏。请由具备 keys.write 的管理员创建最小权限密钥,并保护有权读取密钥的账号。
Q2:前端 Web 应用部署到新域名后,调用接口报 CORS 跨域错误或 401,但本地 localhost 却是正常的?
原因与排查步骤: 可能是 概览 → 集成 → 平台 中只登记了 localhost,或本地使用了 Dev Key,但新域名未登记。请在 平台 页签添加 Web 平台主机名(不含协议和路径,例如 chat.enterprise.example.com),然后检查浏览器实际发送的 Origin、请求身份及其他权限后重试。
Q3:旧代码中使用了 collections.read 或 documents.write 等旧版权限概念,在新建 API Key 的 Scopes 面板里怎么找不到?
原因与排查步骤: Agentbase 控制台统一采用关系与表格化术语(tables.*、columns.*、rows.*),旧式前缀(collections.*、attributes.*、documents.*)不在 UI 选择器中单独重复列出。你只需在 Database 分类下勾选对应的 tables.read、columns.read、rows.write 等新式 Scope,控制台在向服务端提交保存时会自动在底层附带对应的旧式兼容 Scope 变体,旧版 SDK 与 REST 接口调用完全不受影响。

