agentbase-docs

全栈部署

这是什么 / 何时用

把一个完整应用(TablesDB 数据模型 + Storage 资源 + Function 后端 + Sites 前端)从零部署到项目:建库表 → 部署函数 → 部署站点 → 注册平台 → 输出可访问 URL。适合 Agent 自动化交付、脚手架初始化与 CI 化的全栈发布。

三种典型架构:

依据:Sites/Functions/TablesDB 服务面在 v2.7.0 SDK 源码齐备,安全默认值(受限身份、Function API Key 不走 query string)自 2.6.0 起生效——本页按全流程写。

前置(凭据门禁)

使用骨架

关键参数与返回

错误与边界

SDK 类别差异

各语言调用示例

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

数据层:建库、建表与建桶

凭据:项目 API Key(databases.* / tables.* / columns.* / indexes.* / buckets.*)。列/索引在 createTable 内联提交(relationship 列走独立端点);Web SDK 不参与部署,无 Web 页签。

import { Client, TablesDB, Storage } from 'agentbase-node-sdk';

const client = new Client()
  .setEndpoint(process.env.APPBASE_ENDPOINT)     // 含 /v1,与账号 Console 同环境
  .setProject(process.env.APPWRITE_PROJECT_ID)
  .setKey(process.env.APPWRITE_API_KEY);         // 项目 API Key

const tablesDB = new TablesDB(client);
await tablesDB.create({ databaseId: 'app-db', name: 'App' });
await tablesDB.createTable({
  databaseId: 'app-db',
  tableId: 'tasks',
  name: 'Tasks',
  rowSecurity: true,
  columns: [/* 列定义内联;relationship 列除外 */],
  indexes: [],
});

const storage = new Storage(client);
await storage.createBucket({ bucketId: 'attachments', name: '附件', fileSecurity: true });

函数层:创建、配置并部署函数

凭据:项目 API Key。execute 管「谁可调用」,scopes 管函数运行时动态 Key 的权限,两者是两回事;变量需重新 createDeployment 才对后续执行生效。

import { Functions, InputFile, ID } from 'agentbase-node-sdk';
const functions = new Functions(client);

await functions.create({
  functionId: 'send-mailer',
  name: 'Send Mailer',
  runtime: 'node-22',
  execute: ['users'],                 // 谁可调用
  scopes: ['databases.read', 'tables.read', 'rows.read',
           'databases.write', 'tables.write', 'rows.write'],
  entrypoint: 'src/main.js',
  commands: 'npm install',
});
await functions.createVariable({
  functionId: 'send-mailer',
  variableId: ID.unique(),
  key: 'DATABASE_ID',
  value: 'app-db',
});

// tar -czf code.tar.gz --exclude=node_modules -C functions/send-mailer .
const dep = await functions.createDeployment({
  functionId: 'send-mailer',
  code: InputFile.fromPath('./code.tar.gz'),
  activate: true,
});
// 轮询 getDeployment(functionId + dep.$id)至 status === 'ready'

前端层:创建站点、注入变量并部署

凭据:项目 API Key(sites.*)。VITE_* 非密变量加 secret: true 的服务端 Key;VITE_APPWRITE_ENDPOINT 必须带 /v1;改变量必须重新部署。框架与 adapter 细节见 sites.mdx。

import { Sites, InputFile, ID } from 'agentbase-node-sdk';
const sites = new Sites(client);

await sites.create({
  siteId: 'portal',
  name: '用户门户',
  framework: 'react',            // 全量清单见 GET /sites/frameworks
  buildRuntime: 'node-22',
  adapter: 'static',
  fallbackFile: 'index.html',    // SPA 必备
  outputDirectory: 'dist',
  installCommand: 'npm install',
  buildCommand: 'npm run build',
});
await sites.createVariable({
  siteId: 'portal',
  variableId: ID.unique(),
  key: 'VITE_APPWRITE_ENDPOINT',
  value: 'https://appbuild.oceanbase.com/v1',
});

// 打包前端源码(排除 node_modules 与本地构建产物,远端 npm run build)
const dep = await sites.createDeployment({
  siteId: 'portal',
  code: InputFile.fromPath('./site.tar.gz'),
  activate: true,                // HTTP 202
});
// 轮询 sites.getDeployment(siteId + dep.$id)至 status === 'ready'

平台注册(Console 专有)

凭据:Console Session(邮箱密码登录 + setCookie)——项目 API Key 无 platforms.* scope,调 createPlatform 直接失败。hostname 不带 https://;REST 管理端点未在 apis 文档开放,故无 REST 页签。

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

const client = new Client()
  .setEndpoint(process.env.APPBASE_ENDPOINT)   // 含 /v1
  .setProject(process.env.APPBASE_CONSOLE_PROJECT_ID || 'console');  // Console 上下文

// 仅 createEmailPasswordSession 不够:拦截登录响应 set-cookie 拼接后
// client.setCookie(sessionCookie),否则后续调用以 guests 身份被拒
const account = new Account(client);
await account.createEmailPasswordSession({
  email: process.env.APPBASE_EMAIL,
  password: process.env.APPBASE_PASSWORD,
});

const projects = new Projects(client);
const list = await projects.listPlatforms({ projectId });   // projectId 为应用项目 ID
const registered = new Set(
  list.platforms.filter((p) => p.type === 'web').map((p) => p.hostname),
);

for (const hostname of ['localhost', '127.0.0.1', '<sites-preview-hostname>']) {
  if (!registered.has(hostname)) {
    await projects.createPlatform({
      projectId,                 // 应用项目 ID
      type: PlatformType.Web,
      name: hostname,
      hostname,                  // 不带 https://
    });
  }
}

验证与回报:解析本次部署 URL

凭据:项目 API Key(需 rules.read)调 proxy.listRules;Console SDK 同样导出 Proxy(Console Session 装载)。rules 的 REST 端点未在 apis 文档开放,故无 REST 页签。回报 Project ID、Function ID、Site URL、deploymentId、Console URL({consoleOrigin}/console/project-{region}-{projectId}/overview/platforms,origin = endpoint 去掉 /v1,region 通常 default)。

import { Proxy, Query } from 'agentbase-node-sdk';

const proxy = new Proxy(client);   // 项目 API Key(rules.read)

const rules = await proxy.listRules({
  queries: [
    Query.equal('deploymentResourceId', [siteId]),
    Query.equal('deploymentResourceType', ['site']),
  ],
});
const withDomain = rules.rules.filter((r) => r.domain);
// 只认绑定「本次 deploymentId」的规则;顺序不保证最新,禁止取 rules[0]
const bound = withDomain.find((r) => r.deploymentId === deploymentId);
const siteUrl = `https://${bound.domain}`;

示例指引

事实源