项目总览
Project 是 Agentbase 的工作与资源边界:数据库、存储、函数、消息、站点、模型凭据等资源都归属某个 Project。本章说明项目的创建、上下文、服务开关、平台登记与接入密钥(API Key / Dev Key)。
创建项目
- 登录 Console 后进入 Organization(首次使用先创建 Organization,见组织与账号中心)。
- 在 Organization 内创建 Project,创建时选择区域;区域决定资源放置位置。默认项目名为
Agentbase Project,可修改。 - 创建完成页提供 Agentbase Agent Skill 卡片,可复制当前环境的安装提示词,供 Cursor、Claude Code 等 Agent 工具使用。
项目上下文
Project 携带:
| 上下文 | 说明 |
|---|---|
| 区域 | 创建时选择,决定资源位置 |
| 服务开关 | 逐项目控制各服务可用性(见下) |
| 认证提供方 | 项目级 Auth 提供方配置(见 Auth 认证) |
| 配额 | 项目级用量与限制 |
服务开关
在项目 Settings 页的 Services 区逐项开关:
- Auth / Databases / Storage / Functions / Messaging / Realtime / Webhooks 等基础服务的项目级开关。
- Models(LLM Gateway,
llmGateway)与统一 AI 网关(AI Gateway,aiGateway,默认关闭,启用后侧栏出现 AI Gateway 页)是两个并存能力,名称、凭据与路径不可混用。 - Sites 依赖部署环境变量
_APP_SITES_ENABLED,实例未开启时不显示。 - Messaging 功能存在但侧栏入口默认隐藏,经直达 URL 访问(见界面与路由速查)。
平台登记(Platforms)
客户端(浏览器 / 移动端)SDK 的请求按已登记平台做来源校验:Web 校验 Hostname,Android / Apple 校验包名 / Bundle ID。未登记平台的客户端请求会被拒绝。
入口:项目 Overview → Integrations 的 Platforms 页签(/console/project-{region}-{project}/overview/platforms)。添加 / 修改平台需要 platforms.write 权限(组织角色 owner / admin / developer / editor 具备);新建项目后的 Get started 向导也包含平台登记一步。
添加流程:Platforms 页签 → Add platform 选择类型 → 进入创建向导按类型填写 → 提交(POST /v1/projects/{projectId}/platforms)。类型白名单共 15 种:web、android、unity、apple-ios / apple-macos / apple-watchos / apple-tvos、flutter-web / flutter-android / flutter-ios / flutter-linux / flutter-macos / flutter-windows、react-native-ios / react-native-android。
| 类型 | 必填字段 | 说明 |
|---|---|---|
| Web | Name + Hostname | 允许发起客户端请求的域名(本地开发可 localhost);向导可选框架(Svelte / React / Nuxt / Next.js / Vue / Angular 等)并生成接入代码 |
| Android | Name + Package name | 与应用 applicationId(app 级 build.gradle)一致 |
| Apple | Name + Bundle ID | iOS / macOS / watchOS / tvOS 四个子类型分别登记;Bundle ID 见 Xcode 主目标 General |
| Flutter | 按目标平台分别登记 | Android / iOS / Linux / macOS / Windows / Web 各一条;移动端填包名,Web 填 Hostname |
| React Native | Android / iOS 各一条 | Android 填包名,iOS 填 Bundle ID |
| Unity | Name + Package name / Bundle ID | 按目标平台填写对应标识 |
字段约束(服务端强制):name ≤ 128 字符;key(Android 包名 / Apple Bundle ID)≤ 256 字符;hostname 必须是合法主机名;可选 store(应用商店 / Google Play ID,≤ 256 字符)。提交成功后向导展示对应 SDK 的安装与初始化代码。
管理:平台详情页可修改 Name / 包名 / Bundle ID / Hostname / Store;删除需确认——删除后来自该平台的客户端请求不再通过来源校验,应用会开始报 401 / CORS 类错误。达到套餐平台数量上限时界面提示。
API Keys 与 Dev Keys
截图未公开:原图可能包含账号或资源标识。
项目的接入密钥在 Overview → Integrations 区域管理,页签:Platforms / API keys / Dev keys(/console/project-{region}-{project}/overview/api-keys 与 …/overview/dev-keys)。API keys 与 Dev keys 的创建入口都需要 keys.write 权限(组织角色 owner / admin / developer / editor 具备)。
两类密钥的定位
| API Key | Dev Key | |
|---|---|---|
| 用途 | 生产:服务端应用按 scope 访问项目 API | 仅开发环境:绕过限流与 CORS 报错、获得更详细的错误日志 |
| Scopes | 创建时按需勾选权限 | 无 scope 概念 |
| 有效期 | Never / 7 / 30 / 90 天 / 1 年 / 自定义日期 | 仅 1 / 7 / 30 天(不能永久) |
| Secret | standard_ 前缀 | 无前缀;请求头 X-Appwrite-Dev-Key |
| 说明 | 用于生产环境对线上数据与服务的安全访问 | "Bypass Agentbase rate limits and CORS errors in your development environment.";严格限开发用途 |
创建 API Key
- API keys 页签点击 Create API key,进入创建向导。
- Configuration 区:
- Name(必填,最长 128 字符)。
- Expiration:Never / 7 Days / 30 days / 90 days / 1 Year / Custom Date(自定义最早明天;保存后显示到期提示)。
- Scopes 区:勾选该 Key 被授权的权限。建议只授予达成项目目标所需的最小权限集合。选择器按 12 个分类折叠(Auth、Database、Functions、Memory、Storage、Messaging、Sites、AI Gateway、Knowledge Base、Observability、Trace Logs、Other),支持全选 / 全不选。
- 常用 scope 示例:
users.read/users.write、databases.read/databases.write(及 tables / columns / indexes / rows 细分)、files.read/files.write、buckets.read/buckets.write、messages.write、topics.write、providers.write、functions.read/execution.write、health.read等;云端备份能力另有 policies / archives / restorations 相关 scope。 - 旧式前缀(
collections.*、attributes.*、documents.*)不在选择器中显示;勾选对应新 scope 时会自动附带旧式兼容变体提交。
- 常用 scope 示例:
- 创建成功后跳到 Key 详情,成功提示带 Copy API key(复制 secret)与 Copy endpoint(复制区域端点)。
先保存再关页面:secret 应立即复制并存入密钥管理设施。详情页之后仍可再次查看(对 owner / 创建者 / 特权成员可见,见下),但不应把它当公开信息。
管理 API Key
Key 详情页(/overview/api-keys/{keyId}):
- 页头显示 API secret 复制标签与区域端点。
- Key details:Name、Last accessed(或 never)、Expiration date(或 never)、Secret(掩码展示,点击可见 / 复制)。
- 可见性边界(服务端强制):项目 owner、创建者与特权成员可读取 secret;其他成员通过 API 读取时 secret 被服务端置空。
- 可编辑:Name;Scopes(保存后提示已更新);Expiration date(到期前 14 天内显示 "Expires soon",过期显示 "Expired" 并拒绝使用)。
- 删除(吊销):详情页底部 Delete API key → 确认。列表页也支持勾选批量删除。删除立即生效,使用该 Key 的应用会开始收到 401。
创建与管理 Dev Key
- Dev keys 页签点击 Create dev key(弹窗):填 Name(必填)+ 有效期(1 / 7 / 30 天,到期自动失效)。
- 详情页同样展示掩码 Secret,可复制;可改有效期;删除走同一确认流。
- Dev Key 以请求头
X-Appwrite-Dev-Key发送:命中项目的有效 Dev Key 时,该请求绕过限流、绕过 CORS 校验并获得更详细的错误信息。严禁在生产使用——限流与 CORS 是生产防护。
安全保存与轮换建议
- Secret 只保存在服务端密钥管理设施(环境变量 / 密钥库),不入前端代码、不入库、不截图。
- 最小 scope 原则:按调用面勾选(例如只读同步只给
*.read)。 - 轮换:新建 Key → 应用切换 → 删除旧 Key;不要复用过期 Key。
- Key 泄露征兆(Last accessed 异常):立即删除并重建。
项目首页与导航
截图未公开:原图可能包含账号或资源标识。
项目内左侧边栏按成员角色与服务开关显示导航分组;全量路由与分组见界面与路由速查。
项目生命周期
- 重命名 / 标签 / 全局变量 / 更换组织等项目属性操作:项目 Settings 页(重命名、更换组织、删除项目等操作集中在该页)。
- 删除项目:项目 Settings 的删除入口,确认后永久删除;组织级不活跃项目批量清理与恢复见组织与账号中心。