项目总览
示例中的 <APPBASE_ENDPOINT_WITH_V1>、<APPBASE_CONSOLE_ORIGIN> 和 <APPBASE_CONSOLE_HOST> 均需按实际使用位置替换为目标环境信息;先确认环境再运行。
这是什么 / 何时用
项目本身的创建与配置:创建(region / poolTag / 法务信息)、认证与会话策略、项目环境变量、Server API Key 与 Dev Key、平台注册(Platform)与 CORS、OAuth Provider 配置与回调 URL。这是接入任何业务功能前的第一站;项目内资源(库表、存储、函数等)见 project/ 下其余文档。
前置
具备建项权限的 Console 账号;组织(Team)已存在,见 organization.md。
Console SDK(
agentbase-console-sdk@2.8.0)初始化:setEndpoint+setProject('console')(或环境实际 Console project ID),邮箱密码 Session 或短期 JWT 认证。endpoint / region 环境事实见 environment.md。
使用骨架
创建项目:
Projects.create,组织内创建,得到项目 ID 与元数据;同一账号最多 100 个项目。切换上下文:
client.setProject(新项目 ID)后再调用依赖「当前项目」的接口(如Projectservice 的变量、usage)。认证与会话策略:
updateAuthDuration(Session 有效期,秒)、updateAuthLimit(登录尝试限流)、updateAuthSessionsLimit(单用户会话数)、updateAuthPasswordDictionary/updateAuthPasswordHistory(密码策略)、updateSessionAlerts/updateSessionInvalidation(会话提醒与失效)。项目变量:Console SDK
Projectservice 的createVariable/listVariables/updateVariable/deleteVariable;secret: true的变量加密存储,API 只读到空值,运行时(函数 / 站点)经环境变量读取。Server API Key:
Projects.createKey({ projectId, name, scopes, keyId, expire })(keyId、expire均可选);secret只在创建响应出现一次,立即妥善保存。按最小 scope 集合签发(如仅databases.read/write+users.read/write)。Dev Key:开发调试用 Key(
createDevKey/listDevKeys/getDevKey/updateDevKey/deleteDevKey),语义与 API Key 平行,但定位是开发期使用,不要进入生产配置。平台注册与 CORS:
createPlatform({ projectId, type: PlatformType.Web, name, hostname })注册浏览器来源;listPlatforms查重、deletePlatform下线。OAuth Provider:
updateOAuth2配置内建 Provider(provider、appId、secret、enabled);2.6.0 的通用customOauth2经同一 OAuth 管理入口保存配置 envelope(优先用 Console 页面,避免手工序列化 Secret/config)。项目用量(2.6.0):
projects.listUsageAggregates({ projectId })读取项目维度最近 30 个 UTC 日聚合。
关键参数与返回
创建项目
create({ projectId, name, teamId, region, poolTag, description, logo, url, legalName, legalCountry, legalState, legalCity, legalAddress, legalTaxId })(region、poolTag、description、logo、url、legalName、legalCountry、legalState、legalCity、legalAddress、legalTaxId 均可选)
| 参数 | 说明 |
|---|---|
projectId | ID.unique() 或自定义 ID |
teamId | 所属组织的 canonical Team ID |
region | 2.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 下。
错误与边界
建项超限:每账号 100 个项目上限;数量类 quota 超限有独立错误类型。
region传非default值直接 400(Value must be one of (default))。只
createEmailPasswordSession不setCookie时,createPlatform以 guests 身份报 missing scopes;项目 API Key 调平台接口同样失败。API Key
secret丢单不可再取,只能删除重建;轮换时先建新 Key 再撤旧 Key。OAuth Provider 变更(含 customOauth2 配置)后的语义与安全边界见 authentication.md。
quota / ratelimit(
updateQuotaLimits、综合/limits)属于限额治理,模型细节见skills/ob-agentbase/references/console-sdk.md,本页不展开。
SDK 类别差异
Console SDK(JS):本页主体(项目 CRUD、Key/Dev Key、平台、OAuth、认证策略、变量、usage 聚合)。
Console Java SDK:
Projects/Projectservice 与 JS 同形(create带 region/poolTag、createKey、createPlatform、updateAuth*、变量等);无 JS Console SDK 的部分专有 service(如Sql)。Server SDK:不含项目管理面(建项 / 平台注册 / OAuth 配置都不在 Server SDK scope 内);它消费这里签发的 API Key。
Client SDK:纯消费方;依赖本页的平台注册才可用,见 client-sdk/web.md。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
创建项目
组织内创建项目,得到项目 ID 与元数据;同一账号最多 100 个项目。region 2.6.0 只支持 default;poolTag 可选指定数据库池。
- Console(Node)
- Java
import { Client, Account, Projects, Teams, ID } from 'agentbase-console-sdk';
const client = new Client()
.setEndpoint('<APPBASE_ENDPOINT_WITH_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)
});import io.agentbase.console.ID;
import io.agentbase.console.services.Projects;
import java.util.List;
Projects projects = new Projects(client);
var list = projects.list(List.of(Query.limit(20)), null, null);
// 创建为位置参数(projectId, name, teamId, …),可空参数传 null;
// poolTag 指定数据库池(Agentbase 扩展)。全签名见 io.agentbase.console.services.Projects
var project = projects.create(
ID.unique(), // projectId
"billing-service", // name
null // teamId
);
projects.get(project.getId());
projects.delete(project.getId());切换项目上下文
创建/操作其他项目后,先切换「当前项目」再调用依赖它的接口(Project service 的变量、usage 等);这是 SDK 侧上下文切换,无 REST 对应。
- Console(Node)
client.setProject(project.$id); // 之后 X-Appwrite-Project 指向新项目认证与会话策略
项目级认证与会话治理,每个策略一个 update* 方法。
- Console(Node)
- Java
// 各方法的参数体按策略语义填写(数值/开关),形参见 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 }); // 会话失效// 会话有效期(秒)与登录限流(参数为 Long,注意字面量加 L)
projects.updateAuthDuration(project.getId(), 3600L);
projects.updateAuthLimit(project.getId(), 10L);
// 还有 updateAuthSessionsLimit / updateSessionAlerts / updateSessionInvalidation /
// updateAuthPasswordDictionary / updateAuthPasswordHistory 等一族 update* 方法项目变量
构建/运行期注入函数与站点的环境变量;secret: true 加密存储且不可反向切换,管理 API 读取一律掩码。
- Console(Node)
- Java
- REST(curl)
import { Project } from 'agentbase-console-sdk';
// Project service 作用于 setProject 的当前项目,不带 projectId 参数
const proj = new Project(client);
// createVariable / listVariables / updateVariable / deleteVariable;
// 形参见 agentbase-console-sdk 类型定义import io.agentbase.console.services.Project;
import io.agentbase.console.ID;
// 作用于 setProject 的当前项目
new Project(client).listVariables(null, null);
new Project(client).createVariable(ID.unique(), "SMTP_HOST", "smtp.example.com", false);curl -X POST "https://<your-endpoint>/v1/project/variables" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"variableId": "unique()",
"key": "SMTP_HOST",
"value": "smtp.example.com",
"secret": false
}'
curl "https://<your-endpoint>/v1/project/variables" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY"Server API Key
按最小 scope 集合签发;secret 只在创建响应出现一次,立即妥善保存。轮换时先建新 Key 再撤旧 Key。
- Console(Node)
- Java
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 仅创建时返回一次var key = projects.createKey(
project.getId(),
"ci-deploy",
List.of(Scopes.USERS_READ, Scopes.USERS_WRITE) // 按工具实际需要选最小集合
);
projects.listKeys(project.getId(), null, null);
projects.deleteKey(project.getId(), key.getId());Dev Key
开发调试用 Key,语义与 API Key 平行但定位是开发期使用,不要进入生产配置;方法族 createDevKey / listDevKeys / getDevKey / updateDevKey / deleteDevKey(Console SDK 专有,形参见 agentbase-console-sdk 类型定义)。
- Console(Node)
// 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。
- Console(Node)
- Java
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 }); // 下线projects.createPlatform(
project.getId(),
io.agentbase.console.enums.PlatformType.WEB,
"app-web",
"app.example.com" // hostname 白名单即 CORS/回调约束
);
projects.listPlatforms(project.getId(), null);OAuth Provider
配置内建 OAuth Provider(appId / secret / enabled);回调 URL {endpoint}/account/sessions/oauth2/callback/{provider}/{projectId} 中的 {provider} 小写,须填到上游 Provider 的应用配置。
- Console(Node)
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)。
- Console(Node)
- Java
const usage = await projects.listUsageAggregates({ projectId: project.$id });new Projects(client).getUsageAggregates(project.getId());示例指引
各语言写法集中在语言树
examples/;「Console 登录 → setCookie → 建 Team → 建项目 → 注册 Platform → 建 Key」的完整幂等脚本形态见skills/ob-agentbase/references/console-sdk.md与skills/ob-agentbase/references/platform-registration.md。