AgentbaseDocs
文档目录

项目总览

这是什么 / 何时用

项目本身的创建与配置:创建(region / poolTag / 法务信息)、认证与会话策略、项目环境变量、Server API Key 与 Dev Key、平台注册(Platform)与 CORS、OAuth Provider 配置与回调 URL。这是接入任何业务功能前的第一站;项目内资源(库表、存储、函数等)见 project/ 下其余文档。

前置

使用骨架

关键参数与返回

创建项目

create({ projectId, name, teamId, region?, poolTag?, description?, logo?, url?, legalName?, legalCountry?, legalState?, legalCity?, legalAddress?, legalTaxId? })

参数说明
projectIdID.unique() 或自定义 ID
teamId所属组织的 canonical Team ID
region2.6.0 只支持 default
poolTag可选;数据库池标签,不传时匹配 fallback(空 tag)池;可用 tag 经环境确认

返回 Models.Project(含 $id、teamId、region、authDatabasesStorageLimit 等元数据)。

平台注册(决定 CORS 与 OAuth 回调合法性)

规则说明
注册对象浏览器地址栏的 hostname(如 localhost、127.0.0.1、11.124.5.7、app.example.com),不是 API endpoint,不含协议 / 端口 / 路径
端口不参与匹配localhost:5173 与 localhost:3000 都只需注册 localhost
校验时机Client SDK 请求、OAuth success/failure URL、CORS 预检;Server SDK(API Key)不受限
平台类型web / flutter-web / apple-ios / android / react-native-*;移动端填 Bundle ID / Package name 到 key 字段
鉴权仅 Console SDK + 账号 Session(登录后 setCookie);项目 API Key 无 platforms.* scope,不能管理平台
未注册后果Invalid URI、OAuth 失败、CORS 403

OAuth 回调 URL

{endpoint}/account/sessions/oauth2/callback/{provider}/{projectId}

{provider} 小写;把该 URL 填到上游 Provider(GitHub / Google 等)的应用配置里。success/failure 必须落在已注册 Platform 的 origin 下。

错误与边界

SDK 类别差异

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。

创建项目

组织内创建项目,得到项目 ID 与元数据;同一账号最多 100 个项目。region 2.6.0 只支持 default;poolTag 可选指定数据库池。

import { Client, Account, Projects, Teams, ID } from 'agentbase-console-sdk';

const client = new Client()
  .setEndpoint('https://appbuild.oceanbase.com/v1')
  .setProject(process.env.APPWRITE_CONSOLE_PROJECT_ID);   // Console 自身的 project id
const account = new Account(client);
await account.createEmailPasswordSession({ email: '...', password: '...' });   // 或 client.setJWT(token)

const teams = new Teams(client);
const team = await teams.create({ teamId: ID.unique(), name: 'My Team' });

const projects = new Projects(client);
const project = await projects.create({
  projectId: ID.unique(),
  name: 'todo-app',
  teamId: team.$id,      // Console 页面的 Organization = Team
  region: 'default',
  // poolTag: 'pool-a',  // 可选:数据库池 tag(SDK >= 1.13.2)
});

切换项目上下文

创建/操作其他项目后,先切换「当前项目」再调用依赖它的接口(Project service 的变量、usage 等);这是 SDK 侧上下文切换,无 REST 对应。

client.setProject(project.$id);   // 之后 X-Appwrite-Project 指向新项目

认证与会话策略

项目级认证与会话治理,每个策略一个 update* 方法。

// 各方法的参数体按策略语义填写(数值/开关),形参见 agentbase-console-sdk 类型定义
await projects.updateAuthDuration({ projectId: project.$id });            // Session 有效期(秒)
await projects.updateAuthLimit({ projectId: project.$id });               // 登录尝试限流
await projects.updateAuthSessionsLimit({ projectId: project.$id });       // 单用户会话数
await projects.updateAuthPasswordDictionary({ projectId: project.$id });  // 密码字典校验
await projects.updateAuthPasswordHistory({ projectId: project.$id });     // 密码历史
await projects.updateSessionAlerts({ projectId: project.$id });           // 新设备登录提醒
await projects.updateSessionInvalidation({ projectId: project.$id });     // 会话失效

项目变量

构建/运行期注入函数与站点的环境变量;secret: true 加密存储且不可反向切换,管理 API 读取一律掩码。

import { Project } from 'agentbase-console-sdk';

// Project service 作用于 setProject 的当前项目,不带 projectId 参数
const proj = new Project(client);
// createVariable / listVariables / updateVariable / deleteVariable;
// 形参见 agentbase-console-sdk 类型定义

Server API Key

按最小 scope 集合签发;**secret 只在创建响应出现一次**,立即妥善保存。轮换时先建新 Key 再撤旧 Key。

import { Scopes } from 'agentbase-console-sdk';

const key = await projects.createKey({
  projectId: project.$id,
  name: 'setup-script',
  scopes: [
    Scopes.DatabasesRead,
    Scopes.DatabasesWrite,
    Scopes.UsersRead,
    Scopes.UsersWrite,
  ],
});
// key.secret 仅创建时返回一次

Dev Key

开发调试用 Key,语义与 API Key 平行但定位是开发期使用,不要进入生产配置;方法族 createDevKey / listDevKeys / getDevKey / updateDevKey / deleteDevKey(Console SDK 专有,形参见 agentbase-console-sdk 类型定义)。

// await projects.createDevKey({ projectId: project.$id, name: 'dev-sandbox' });
// await projects.listDevKeys(project.$id);

平台注册与 CORS

注册浏览器地址栏的 hostname(不含协议/端口/路径);未注册会导致 Invalid URI、OAuth 失败与 CORS 403。仅 Console SDK + 账号 Session(登录后 setCookie);项目 API Key 无 platforms.* scope。

import { PlatformType } from 'agentbase-console-sdk';

await projects.createPlatform({
  projectId: project.$id,
  type: PlatformType.Web,
  name: 'localhost',
  hostname: 'localhost',   // localhost:5173 与 localhost:3000 都只需注册 localhost
});
await projects.listPlatforms({ projectId: project.$id });   // 查重
// await projects.deletePlatform({ projectId: project.$id, platformId });  // 下线

OAuth Provider

配置内建 OAuth Provider(appId / secret / enabled);回调 URL {endpoint}/account/sessions/oauth2/callback/{provider}/{projectId} 中的 {provider} 小写,须填到上游 Provider 的应用配置。

import { OAuthProvider } from 'agentbase-console-sdk';

await projects.updateOAuth2({
  projectId: project.$id,
  provider: OAuthProvider.Github,
  appId: 'your_app_id',
  secret: 'your_app_secret',
  enabled: true,
});

项目用量

项目维度最近 30 个 UTC 日的用量聚合(2.6.0 扩展;quantity: null 表示缺失,不要默认成 0)。

const usage = await projects.listUsageAggregates({ projectId: project.$id });

示例指引

事实源