Docs
文档目录

Console SDK(Node.js / JavaScript)

运行示例前,请将 <APPBASE_ENDPOINT_WITH_V1>、<APPBASE_CONSOLE_ORIGIN> 和 <APPBASE_CONSOLE_HOST> 等占位符按实际使用位置替换为目标环境信息,并核对项目及凭据属于同一环境。

Console SDK 面向管理面调用方:Console 面板能力、组织与项目治理、跨项目运维自动化,认证用管理身份——邮箱密码 Session 或 短期 JWT。npm 坐标 agentbase-console-sdk@2.12.0。Java / Python / Go 面见同目录 java.md / python.md / go.md;浏览器前端用 Client SDK;服务端数据面用 Server SDK。

安装与初始化

npm install agentbase-console-sdk@2.12.0 --save-exact

方式一:sdk 包装对象(推荐,自动管理端点与模式)

import { sdk, realtime } from 'agentbase-console-sdk';

sdk.forConsole.projects.list(/* 组织/控制台级调用 */);
sdk.forConsoleIn('default').health.get();      // 指定 region
sdk.forProject('default', '<projectId>').tablesDB.listRows(...); // 项目资源面,自动 setProject + setMode('admin')

方式二:裸 Client(需要精细控制认证时)

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

const client = new Client()
  .setEndpoint('<APPBASE_ENDPOINT_WITH_V1>')
  .setProject('<consoleOrProjectId>');   // X-Appwrite-Project 头

认证装载(三选一,互斥):

其他 setter:setMode('admin')、setLocale、setSelfSigned。

5 分钟上手(管理自动化)

const projects = sdk.forConsole.projects;

const project = await projects.create({
  projectId: 'unique()', name: 'My Project', teamId: '<teamId>', region: 'default',
});
const key = await projects.createKey(project.$id, 'server key', [
  'users.read', 'users.write', 'teams.read', 'teams.write',
]);
// key.secret 只在创建响应出现一次,立即交给服务端安全存储

服务端拿 Key 接入 Server SDK;域名规则、迁移、备份等治理面继续用本页服务。

Console 专有 service

服务覆盖
Organizations组织成员与账单等管理能力;作为导出类由 Console Client 单独实例化,不在 sdk.forConsole 包装对象上
Proxy站点/API/函数/重定向域名规则(createSiteRule / listRules / getRule / updateRuleVerification / deleteRule)
VcsGit 集成:installation、仓库发现、分支列表、仓库内容、外部部署状态回写
Migrations迁移任务(Appwrite/Firebase/Supabase/NHost/AppBase/CSV 导入导出):创建、报告、重试、删除;另有 SchemaMigration(基于 TablesDB 的表结构计划/执行助手)
Assistantassistant.chat() 管理侧 AI 助手
Console平台元数据:listRegions / listTags、计划与资源查询、列/索引建议(suggestColumns / suggestIndexes)、变量
Admin平台管理:池/标签列表、存储迁移、项目表模式转换、项目删除审计与恢复
Activities / Backups / Domains事件流、备份策略与档案、域名资产

创建项目、签发后端密钥并登记 Web 平台

下面使用 agentbase-console-sdk@2.12.0。开始前准备目标控制台的短期管理 JWT、允许登记的 Web 域名(放入 APPBASE_WEB_HOSTNAME),以及组织和项目的创建权限。创建项目时省略 region,由服务按环境配置选择默认区域。

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

function refuseAutomaticRedirects(client: Client) {
  const originalPrepareRequest = client.prepareRequest;
  if (typeof originalPrepareRequest !== 'function') throw new Error('Redirect control unavailable');
  client.prepareRequest = function (...args) {
    const request = originalPrepareRequest.apply(this, args);
    request.options.redirect = 'error';
    return request;
  };
}

const token = process.env.APPBASE_ADMIN_JWT;
if (!token) throw new Error('Set APPBASE_ADMIN_JWT for the target Console');
const webHostname = process.env.APPBASE_WEB_HOSTNAME;
if (!webHostname) throw new Error('Set APPBASE_WEB_HOSTNAME');

// 1. 初始化管理面 Client(先指向 console 项目完成组织与项目开通)
const consoleClient = new Client()
  .setEndpoint(process.env.APPBASE_ENDPOINT ?? '<APPBASE_ENDPOINT_WITH_V1>')
  .setProject(process.env.APPBASE_CONSOLE_PROJECT_ID ?? 'console')
  .setJWT(token);
refuseAutomaticRedirects(consoleClient);

const teams = new Teams(consoleClient);
const projects = new Projects(consoleClient);

// 2. 创建组织(Team)与 Shared V2 企业项目
const org = await teams.create({
  teamId: '69c6d1aa00062e6bb60',
  name: 'Agentbase 企业智能中台',
});

const project = await projects.create({
  projectId: '<APPBASE_PROJECT_ID>',
  name: '企业智能客服与知识中台',
  teamId: org.$id,
});

// 3. 为后端服务签发最小权限集合的 API Key(secret 仅在创建响应中返回一次)
const serverKey = await projects.createKey({
  projectId: project.$id,
  name: 'prod-backend-service-key',
  scopes: [
    Scopes.UsersRead,
    Scopes.UsersWrite,
    Scopes.TablesRead,
    Scopes.TablesWrite,
    Scopes.RowsRead,
    Scopes.RowsWrite,
  ],
});
// 将此次创建响应中的密钥直接保存到凭据管理系统。

// 4. 注册前端 Web 平台域名(开启浏览器 CORS 信任,仅 Console Session/JWT 可调)
await projects.createPlatform({
  projectId: project.$id,
  type: PlatformType.Web,
  name: 'Enterprise Support Portal',
  hostname: webHostname,
});

项目创建后,可配置数据库并按 SQL Proxy 接入指南 发起参数化查询。创建知识库后,可按词库管理新建和绑定词库。

Console SDK 与 Server SDK、Client Web SDK 选型对比

维度Console SDK(agentbase-console-sdk@2.12.0)Server SDK(agentbase-node-sdk@2.12.0)Client Web SDK(agentbase-web-sdk@2.12.0)
核心定位组织与项目生命周期治理、平台注册、域名规则、迁移、备份、SQL 终端业务后端数据面读写、用户管理、RAG 知识库、Memory、模型网关与可观测上报浏览器端用户登录会话、受 RLS 保护的数据读写与 Realtime 实时订阅
鉴权凭据管理员 Session Cookie / 短期 JWT(SQL 场景支持项目 API Key)项目 API Key(X-Appwrite-Key,跳过 RLS)终端用户 Session Cookie / JWT(严格执行 RLS 行级权限)
独占能力Organizations、Projects.create/createKey/createPlatform、Proxy、Vcs、Migrations、Admin、Backups、SqlUsers.createToken(Custom Token 签发)及全量项目级服务端批处理Account 浏览器 OAuth 跳转登录、Realtime WebSocket 订阅(与 Console 共享实时能力)

版本与 SDK 支持

功能面导航(治理域 → 服务)

域服务与方法要点功能文档
组织Organizations:成员、账单地址、发票、充值、组织 Key、listUsageAggregates({ organizationId });由 new Organizations(client) 实例化../organization.md、../usage.md
项目生命周期Projects.create({ projectId, name, teamId, region: 'default', poolTag }) / get / update / delete / list../overview.md
项目 Key 与平台projects.createKey(scope 小写点分串,secret 仅创建时可见)、createDevKey、createPlatform / listPlatforms(仅 Console Session)、updateOAuth2../overview.md
配额与限频项目 projects.getQuotaLimits / updateQuotaLimits;账号 account.getQuotaLimits / updateQuotaLimits / deleteQuotaLimits(无 listLimitsProjects);/limits 经 client.call../limits.md
三级用量sdk.forConsole.account / sdk.forConsole.projects 与独立 Organizations 服务的 listUsageAggregates()(最近 30 个 UTC 日)../usage.md
项目资源面TablesDB / Sql / Sites / Functions / Storage / Messaging / Memory(含项目配置与回滚)/ Users / Teams / Tokens / LLMGateway(含用量)/ Webhooks / Graphql / Avatars / Locale / Health各功能页(../misc/webhooks.md 等)
SQLSql.query / Sql.execute(JS Console SDK 独有;Java / Python / Go Console 面见各自页说明)../databases/sql-proxy.md
站点与域名Sites 全集 + Proxy 域名规则 + Domains../sites.md
实时realtime.forProject(region, channels, cb) / realtime.forConsole(...)../realtime.md
平台运维Admin / Backups / Activities / Health(含管理面队列检查)../misc/webhooks.md

错误与边界

示例指引