Docs
文档目录

全栈部署

示例中的 <APPBASE_ENDPOINT_WITH_V1>、<APPBASE_CONSOLE_ORIGIN> 和 <APPBASE_CONSOLE_HOST> 均需按实际使用位置替换为目标环境信息;先确认环境再运行。

这是什么 / 何时用

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

三种典型架构:

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

前置(凭据门禁)

使用骨架

  1. 数据层:tablesDB.create({ databaseId, name }) → tablesDB.createTable({ databaseId, tableId, name, rowSecurity, columns, indexes })(列/索引内联,relationship 列除外)→ 建桶(storage.createBucket)。

  2. 函数层:functions.create(...) → 配 execute(谁可调)与 scopes(运行时动态 Key 权限,与 execute 是两回事)→ functions.createVariable(变量 variableId 必填)→ 打 tar.gz(排除 node_modules、构建产物、.env)→ functions.createDeployment({ functionId, code, activate: true }) → 轮询 deployment ready。

  3. 前端层:sites.create(...)(框架/adapter/构建命令,见 sites.md)→ sites.createVariable(VITE_* 非密变量 + secret: true 的服务端 Key)→ 打包上传 sites.createDeployment({ siteId, code, activate: true })(HTTP 202)→ 轮询 getDeployment 至 ready。

  4. 平台注册:Console Session 下 projects.createPlatform({ projectId, type: 'web', name, hostname })——hostname 不带 https://;注册 localhost、127.0.0.1 与 Sites 域名,未注册的域名页面能开但 API 报 CORS/Invalid URI。

  5. 解析 URL:用本次 deploymentId 经 Console SDK 的 proxy.listRules 匹配规则取站点 URL(禁止 rules[0] / 复用旧 URL);函数执行上下文现查。

  6. 回报:Project ID、Function ID、Site URL、deploymentId、Console URL({consoleOrigin}/console/project-{region}-{projectId}/overview/platforms,origin = endpoint 去掉 /v1,region 通常 default)。

关键参数与返回

错误与边界

SDK 类别差异

各语言调用示例

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

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

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

下面的 Node.js 示例使用 SDK 2.12,先为本页通过 prepareRequest 发出的请求禁用重定向;这不代表 SDK 的所有请求方法均受保护。更换 SDK 版本或调用其他方法时,需要重新验证凭据和重定向行为。

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
// SDK 2.12: reject redirects for the request paths used in this guide.
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 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, ID } from 'agentbase-node-sdk';
import { InputFile } from 'agentbase-node-sdk/file';
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 --exclude=.git --exclude='.env*' --exclude=.npmrc -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, ID } from 'agentbase-node-sdk';
import { InputFile } from 'agentbase-node-sdk/file';
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: '<APPBASE_ENDPOINT_WITH_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 专有)

在控制台登录目标环境,进入项目的 概览 → 集成 → 平台,按实际使用的域名添加 Web 平台。项目 API Key 没有 platforms.* 权限,不能替代控制台授权;仅填写主机名,不包含协议。参见项目概览。

验证与回报:确认本次部署 URL

在控制台查看本次 deploymentId 对应的站点域名规则,核对规则状态为 verified,并实际访问地址。使用 API 查询时应翻页查找本次部署的已验证规则;未找到时停止并检查域名配置,不要复用旧 URL 或发起重复部署。回报 Project ID、Function ID、Site URL 和本次 deploymentId。参见站点管理。

示例指引