Server SDK(Node.js)
Node 后端 / Worker / CLI / 自动化脚本以项目 API Key 调用 Server SDK(agentbase-node-sdk)。API Key 按最小 scope 授权,请求跳过行级权限检查(hasRole)——可管理全库数据,因此只存在于受控服务端,绝不进浏览器/客户端/Sites 前端。Java / Python / Go 面见同目录 java.md / python.md / go.md;浏览器前端用 Client SDK;治理自动化用 Console SDK。
安装与初始化
npm install agentbase-node-sdk@2.8.0 --save-exactimport { Client, TablesDB } from 'agentbase-node-sdk';
const client = new Client()
.setEndpoint('https://appbuild.oceanbase.com/v1') // SIT: https://appbuild-sit.oceanbase.com/v1
.setProject('<PROJECT_ID>')
.setKey('<API_KEY>'); // X-Appwrite-Key
const tablesDB = new TablesDB(client); // 服务逐个构造环境变量惯例:APPWRITE_ENDPOINT / APPWRITE_PROJECT_ID / APPWRITE_API_KEY(+ dotenv);自签名实例加 .setSelfSigned(true)。安全底线:行过滤条件在服务端生成,不信任前端传入的 queries。
5 分钟上手
- 初始化(上文);API Key 在项目 Overview → API keys 创建,按需选最小 scope。
- 建表并写入一行:
import { ID } from 'agentbase-node-sdk';
await tablesDB.createTable({
databaseId: 'app-db', tableId: 'tasks', name: 'Tasks',
rowSecurity: true,
columns: [{ key: 'title', type: 'varchar', size: 256, required: true }],
});
await tablesDB.createRow('app-db', 'tasks', ID.unique(), { title: '写周报' });- 为前端用户发登录令牌:
users.createToken('<userId>')→ 客户端account.createSession({ userId, secret })(见下节)。
Custom Token 签发入口
- 服务端:
users.createToken('<userId>')→ 返回{ secret, expire }。 - 客户端(client-sdk/web.md):
account.createSession({ userId, secret })完成 Custom Token 登录。
注意区分:Tokens 服务是 Storage 文件临时令牌(createFileToken),与用户令牌无关;users.createJWT / account.createJWT 是给用户签发短期 JWT(约 15 分钟),用于服务间带用户身份调用,不是 Session 通道。
功能面导航
| 服务 | 覆盖 | 功能文档 |
|---|---|---|
TablesDB | 库/表/列/索引/行 CRUD、事务、aggregateRows 行聚合、updateColumnComment | ../databases.md |
Databases / DocumentsDB | 旧文档面(新项目优先 TablesDB) | ../databases.md |
Storage | 桶与文件 CRUD、下载/预览/查看 | ../storage.md |
Functions | 创建/部署(tar 上传、VCS、模板、duplicate)、执行、变量、运行时与规格查询 | ../functions.md |
Sites | 站点与部署全集(构建/变量/框架规格/日志) | ../sites.md |
Users | 项目用户全生命周期 + **createToken** + Target/JWT/MFA | ../users.md |
Teams | 项目内团队与成员 | ../teams.md |
Messaging | Email/Push/SMS、Topic、Subscriber、Provider | ../messaging.md |
Account / Projects / Project | 账号级调用、项目 quota 与变量、组织治理查询 | ../limits.md |
Memory / KnowledgeBases | 记忆 / RAG 数据面全集 | ../memory.md、../knowledge-bases.md |
LlmGateway / AiGateway | 模型 Provider/Key + 执行;统一 AI 数据面控制面 | ../llm-gateway.md、../ai-gateway.md |
Observability / Moderation | 上报(≤100/批、207)与查询;审核配置与日志 | ../observability.md、../moderation.md |
Webhooks / Graphql / Avatars / Locale / Health / Tokens | 横切服务与文件临时令牌 | ../misc/webhooks.md |
| —— | **无 Sql 服务:SQL 走 HTTP 形态或 Console SDK(../databases/sql-proxy.md);无 Realtime**:实时推送是客户端能力(../realtime.md) |
与 Console SDK 并用
Server SDK 的服务面已覆盖全量项目功能,但以下场景需要 Console SDK 补位:
- Console-only 操作:创建项目/Team、
projects.createPlatform平台注册(项目 Key 无platforms.*scope)、组织与账单、Admin/Backups。 - **
Sql服务**:仅 Console SDK 提供(或走 HTTPPOST {endpoint}/sql)。 - **
/limits限频接口**:无 typed 封装时用 Console SDKclient.call或 REST。 - 组织级用量:
organizations.listUsageAggregates仅 Console SDK。
Node 同进程并用:npm i agentbase-node-sdk@2.8.0 agentbase-console-sdk@2.8.0 --save-exact,各自 new Client() 按需装载 Key/Session。
错误与边界
AgentbaseException:code为 HTTP 状态码、type为错误类型串;413(存储超限)、429(限频)、401/403(Key/scope)见各功能页。- 2.6.0 安全默认值:Function API Key 不接受 query string 传递;外部 URL 拒绝本机/私网/元数据地址。
- 用量/配额读取口径差异见 limits.md 与 usage.md。
示例指引
- Node 完整调用写法:../examples/javascript.md
事实源
skills/ob-agentbase/references/server-sdks/nodejs.md- appbase v2.7.0(tag v2.7.0)
- agentbase-sdks v2.7.0 specs(
packages/sdks/server-nodejs/src/{index.ts,client.ts,services/})