全栈部署
这是什么 / 何时用
把一个完整应用(TablesDB 数据模型 + Storage 资源 + Function 后端 + Sites 前端)从零部署到项目:建库表 → 部署函数 → 部署站点 → 注册平台 → 输出可访问 URL。适合 Agent 自动化交付、脚手架初始化与 CI 化的全栈发布。
三种典型架构:
- 模式 A:浏览器 → Sites → Client SDK 只调 Function → TablesDB(前端不直连数据面)。
- 模式 B:读直连 TablesDB/Storage/Realtime,敏感写经
functions.createExecution(如看板 demo)。 - 模式 C:Sites SSR——SSR 侧用 API Key 读库,用户 Session 走 Client SDK 浏览器直连
/v1(注意 sites.md 的 Cookie 不透传限制)。
依据:Sites/Functions/TablesDB 服务面在 v2.7.0 SDK 源码齐备,安全默认值(受限身份、Function API Key 不走 query string)自 2.6.0 起生效——本页按全流程写。
前置(凭据门禁)
- 两把钥匙分工:Console Session(邮箱密码登录后
setCookie)做 Console-only 操作(创建项目、建 Team、projects.createPlatform注册平台、组织查询);项目 API Key 做资源操作(库表/存储/函数/站点/部署)。platforms.read/write不在项目 Key 的可授予 scope 里——用项目 Key 调 createPlatform 会直接失败。 - Console 登录必须落 cookie:拦截登录响应的
set-cookie拼接后consoleClient.setCookie(...),否则后续teams.create/projects.createKey会以 guests 身份被拒。 - 凭据只从项目
.env读取(优先级:项目根.env>scripts/.env> 进程环境);禁止把密码/Key/JWT 打进日志,禁止把部署脚本落进用户仓库。 - API Key scopes 建议(17 项):databases / tables / columns / indexes / rows / buckets / functions / execution / sites 各 read+write,另加
rules.read。ConsolecreateKey的 scope 是小写点分字符串(如sites.write)。 - 2.6.0 安全默认值:Function/Site 的安装、构建、启动命令在受限身份下运行,不满足条件直接失败、不回退高权限;Function API Key 不再接受 query string 传递,用受保护 header 或平台注入的运行时认证。
使用骨架
- 数据层:
tablesDB.create({ databaseId, name })→tablesDB.createTable({ databaseId, tableId, name, rowSecurity, columns, indexes })(列/索引内联,relationship 列除外)→ 建桶(storage.createBucket)。 - 函数层:
functions.create(...)→ 配execute(谁可调)与scopes(运行时动态 Key 权限,与 execute 是两回事)→functions.createVariable(变量variableId必填)→ 打 tar.gz(排除node_modules、构建产物、.env)→functions.createDeployment({ functionId, code, activate: true })→ 轮询 deploymentready。 - 前端层:
sites.create(...)(框架/adapter/构建命令,见 sites.md)→sites.createVariable(VITE_*非密变量 +secret: true的服务端 Key)→ 打包上传sites.createDeployment({ siteId, code, activate: true })(HTTP 202)→ 轮询getDeployment至ready。 - 平台注册:Console Session 下
projects.createPlatform({ projectId, type: 'web', name, hostname })——hostname 不带https://;注册 localhost、127.0.0.1与 Sites 域名,未注册的域名页面能开但 API 报 CORS/Invalid URI。 - 解析 URL:用本次 deploymentId 经 Console SDK 的
proxy.listRules匹配规则取站点 URL(禁止rules[0]/ 复用旧 URL);函数执行上下文现查。 - 回报:Project ID、Function ID、Site URL、deploymentId、Console URL(
{consoleOrigin}/console/project-{region}-{projectId}/overview/platforms,origin = endpoint 去掉/v1,region 通常default)。
关键参数与返回
- 同步 Function 经负载均衡有约 30 秒上限(超时报 408):长任务改
async: true+getExecution轮询。 - Function 运行时注入变量:
APPWRITE_FUNCTION_API_ENDPOINT、APPWRITE_FUNCTION_PROJECT_ID与请求头x-appwrite-key/x-appwrite-user-id——不要自建同名变量。 - 幂等约定:Site/Function 用固定 ID(先 get 后 update/create);变量按 key upsert;deployment 每次用
ID.unique();Platform 按 hostname 查重。 - 构建超时建议按 900 秒评估;部署轮询示例 5 秒间隔、上限 10 分钟。
错误与边界
- Sites 能力白名单未放行 → 先过 sites.md 的门禁再继续,失败即停(可保留 checkpoint:Team/Project/Key 写回
.env后修复重跑)。 - 环境一致性:endpoint 必须与账号 Console 同环境(SIT
https://appbuild-sit.oceanbase.com/v1,生产https://appbuild.oceanbase.com/v1);无配置时询问,不要默认 SIT。 - 改过 Site 变量必须重新 createDeployment 才生效;前端
VITE_*endpoint 必须带/v1。 - 修改变量/回滚部署后,URL 仍以"绑定本次 deploymentId 的规则"为准。
SDK 类别差异
- Server SDK(server-sdk/nodejs.md):tablesDB / storage / functions / sites 资源操作全集——部署脚本的主力。
- Console SDK(console-sdk/nodejs.md):项目/团队/Key/平台注册等 Console-only 操作。
- 客户端 SDK(client-sdk/web.md):不参与部署,只访问已部署应用的
/v1数据面。 - 两者并用模式见 server-sdk/nodejs.md「与 Console SDK 并用」。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
数据层:建库、建表与建桶
凭据:项目 API Key(databases.* / tables.* / columns.* / indexes.* / buckets.*)。列/索引在 createTable 内联提交(relationship 列走独立端点);Web SDK 不参与部署,无 Web 页签。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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 });// io.agentbase 位置参数形态;逐参数签名以 SDK 源码为准
TablesDB tables = new TablesDB(client);
tables.create("app-db", "App", null, true, null, null, null, null, null, null, null, null);
tables.createTable(
"app-db", "tasks", "Tasks",
null, // permissions
true, // rowSecurity
true, // enabled
List.of(new DatabaseColumnDefinition()
.setKey("title").setType(DatabaseSchemaType.VARCHAR)
.setSize(256L).setRequired(true)),
List.of(new DatabaseIndexDefinition()
.setKey("title_idx").setType(DatabaseSchemaIndexType.KEY)),
null // comment
);
Storage storage = new Storage(client);
storage.createBucket("attachments", "附件", null, true, true,
26214400L, null, null, true, false, true);from agentbase.services.tables_db import TablesDB
from agentbase.services.storage import Storage
tables_db = TablesDB(client)
tables_db.create(database_id='app-db', name='App')
tables_db.create_table(
database_id='app-db', table_id='tasks', name='Tasks',
row_security=True,
columns=[{'key': 'title', 'type': 'string', 'size': 256, 'required': True}],
indexes=[{'key': 'idx_title', 'type': 'unique', 'attributes': ['title']}],
)
storage = Storage(client)
storage.create_bucket(bucket_id='attachments', name='附件', file_security=True, enabled=True)tables := agentbase.NewTablesDB(cl)
_, err := tables.Create("app-db", "App")
_, err = tables.CreateTable("app-db", "tasks", "Tasks",
tables.WithCreateTableRowSecurity(true),
tables.WithCreateTableColumns([]models.DatabaseColumnDefinition{
{Key: "title", Type: "string", Size: 256, Required: true},
}),
tables.WithCreateTableIndexes([]models.DatabaseIndexDefinition{
{Key: "idx_title", Type: "unique", Attributes: []string{"title"}},
}),
)
storage := agentbase.NewStorage(cl)
_, err = storage.CreateBucket("attachments", "附件",
storage.WithCreateBucketFileSecurity(true),
storage.WithCreateBucketEnabled(true))curl -X POST "https://<your-endpoint>/v1/tablesdb" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"databaseId": "app-db", "name": "App", "enabled": true}'
curl -X POST "https://<your-endpoint>/v1/tablesdb/app-db/tables" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tableId": "tasks",
"name": "Tasks",
"rowSecurity": true,
"columns": [{"key": "title", "type": "string", "size": 256, "required": true}],
"indexes": [{"key": "idx_title", "type": "fulltext", "attributes": ["title"]}]
}'
curl -X POST "https://<your-endpoint>/v1/storage/buckets" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"bucketId": "attachments", "name": "附件", "fileSecurity": true, "enabled": true}'函数层:创建、配置并部署函数
凭据:项目 API Key。execute 管「谁可调用」,scopes 管函数运行时动态 Key 的权限,两者是两回事;变量需重新 createDeployment 才对后续执行生效。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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'Functions functions = new Functions(client);
// 方法名同构(位置参数,逐参数签名以 SDK 源码为准):
// create(...):runtime、execute、scopes、entrypoint、commands 等
// createVariable(functionId, variableId, key, value)
// 打包:tar -czf code.tar.gz --exclude=node_modules -C functions/send-mailer .
// createDeployment(functionId, code, activate, ...) 返回 202;
// 随后 getDeployment(functionId, deploymentId) 轮询至 readyfrom agentbase.input_file import InputFile
from agentbase.services.functions import Functions
functions = Functions(client)
# 方法面与 Node SDK 同构(snake_case):create / create_variable /
# create_deployment(code=InputFile.from_path('./code.tar.gz'), activate=True)/
# get_deployment 轮询至 status == 'ready';逐参数签名以 agentbase.services.functions 源码为准functions := agentbase.NewFunctions(cl)
// 方法名同构(PascalCase):Create / CreateVariable / CreateDeployment /
// GetDeployment(轮询至 Status=ready);可选参数用 functions.With… 选项,
// 以模块源码为准curl -X POST "https://<your-endpoint>/v1/functions" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}'
curl -X POST "https://<your-endpoint>/v1/functions/send-mailer/variables" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"variableId": "var_database_id", "key": "DATABASE_ID", "value": "app-db"}'
# tar -czf code.tar.gz --exclude=node_modules -C functions/send-mailer .
curl -X POST "https://<your-endpoint>/v1/functions/send-mailer/deployments" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-F "code=@./code.tar.gz" \
-F "activate=true"
# 202:轮询 GET /v1/functions/send-mailer/deployments/{deploymentId} 至 status=ready前端层:创建站点、注入变量并部署
凭据:项目 API Key(sites.*)。VITE_* 非密变量加 secret: true 的服务端 Key;VITE_APPWRITE_ENDPOINT 必须带 /v1;改变量必须重新部署。框架与 adapter 细节见 sites.mdx。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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'Sites sites = new Sites(client);
sites.create("portal", "用户门户", Framework.REACT, BuildRuntime.NODE_22,
true, true, 30L,
"npm install", "npm run build", "", "dist",
Adapter.STATIC,
null, "index.html", // installationId, fallbackFile(SPA 必备)
null, null, false, null, // VCS 相关
null, null, null, null, null); // 规格/执行计划/保留期,见 listSpecifications()
// 部署:sites.createDeployment(siteId, code, activate, ...) 后轮询 getDeployment;
// createVariable(siteId, variableId, key, value) 注入 VITE_* 变量from agentbase.input_file import InputFile
from agentbase.services.sites import Sites
sites = Sites(client)
# 方法面与 Node SDK 同构(snake_case):create / create_variable /
# create_deployment(code=InputFile.from_path('./site.tar.gz'), activate=True)/
# get_deployment 轮询至 status == 'ready';逐参数签名以 agentbase.services.sites 源码为准sites := agentbase.NewSites(cl)
// 方法名同构(PascalCase):Create / CreateVariable / CreateDeployment /
// GetDeployment(轮询至 Status=ready);可选参数用 sites.With… 选项,
// 以模块源码为准curl -X POST "https://<your-endpoint>/v1/sites" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"siteId": "portal",
"name": "用户门户",
"framework": "react",
"buildRuntime": "node-22",
"adapter": "static",
"fallbackFile": "index.html",
"outputDirectory": "dist",
"installCommand": "npm install",
"buildCommand": "npm run build"
}'
curl -X POST "https://<your-endpoint>/v1/sites/portal/variables" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"variableId": "var_endpoint", "key": "VITE_APPWRITE_ENDPOINT", "value": "https://appbuild.oceanbase.com/v1"}'
curl -X POST "https://<your-endpoint>/v1/sites/portal/deployments" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-F "code=@./site.tar.gz" \
-F "activate=true"
# 202:轮询 GET /v1/sites/portal/deployments/{deploymentId} 至 status=ready平台注册(Console 专有)
凭据:Console Session(邮箱密码登录 + setCookie)——项目 API Key 无 platforms.* scope,调 createPlatform 直接失败。hostname 不带 https://;REST 管理端点未在 apis 文档开放,故无 REST 页签。
- Console(Node)
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)。
- Node.js(Server)
- Console(Node)
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}`;import { Proxy, Query } from 'agentbase-console-sdk';
const proxy = new Proxy(consoleClient); // Console Session 装载的 client
// listRules 与 Server SDK 同构:同一查询参数定位本次部署的站点规则
const rules = await proxy.listRules({
queries: [
Query.equal('deploymentResourceId', [siteId]),
Query.equal('deploymentResourceType', ['site']),
],
});示例指引
- JavaScript(Node 部署序列 + Console 注册平台):examples/javascript.md
- Java:examples/java.md
事实源
skills/ob-agentbase/references/full-stack-deploy.mdskills/ob-agentbase/references/agent-deploy-playbook.mdskills/ob-agentbase/references/team-kanban-demo.mdskills/ob-agentbase/references/agentbase-ssr-demo.mdskills/ob-agentbase/references/release-2.6.0.md(安全默认值)- appbase v2.7.0(tag v2.7.0)
- agentbase-sdks v2.7.0 specs(sites / functions / tables-db / projects 方法面)