全栈部署
示例中的 <APPBASE_ENDPOINT_WITH_V1>、<APPBASE_CONSOLE_ORIGIN> 和 <APPBASE_CONSOLE_HOST> 均需按实际使用位置替换为目标环境信息;先确认环境再运行。
这是什么 / 何时用
把一个完整应用(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-only 操作(创建项目、建 Team、
projects.createPlatform注册平台、组织查询);项目 API Key 做资源操作(库表/存储/函数/站点/部署)。platforms.read/write不在项目 Key 的可授予 scope 里——用项目 Key 调 createPlatform 会直接失败。控制台专有操作请先在目标环境登录并确认当前项目;自动化接入须先验证会话传递与重定向行为。
凭据只从项目
.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 示例使用 SDK 2.12,先为本页通过 prepareRequest 发出的请求禁用重定向;这不代表 SDK 的所有请求方法均受保护。更换 SDK 版本或调用其他方法时,需要重新验证凭据和重定向行为。
- 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
// 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 });Java SDK 2.12 的默认请求可能在跨主机重定向时携带项目 Key;安全配置尚未验证,暂不提供可执行资源操作代码。请使用本节 REST 步骤;安装信息见 Java Server SDK。
Python SDK 2.12 的默认请求可能在跨主机重定向时携带项目 Key;安全配置尚未验证,因此暂不提供可执行写入代码。请使用下方 REST 步骤;安装与客户端信息见 Python Server SDK。
创建数据库成功后再创建表;存储桶单独创建,并检查每次调用的错误。Go SDK 的重定向配置仍需按目标环境验证;可使用下方 REST 步骤,安装信息见 Go Server SDK。
设置 APPBASE_ENDPOINT 为目标环境含 /v1 的 API 地址,并在受控服务端配置 APPBASE_PROJECT_ID 和 APPBASE_API_KEY。每次仅执行一步,确认 HTTP 2xx 后继续;不要在终端日志或命令参数中暴露密钥。
创建数据库;成功后再创建表。
(
set +x
set -e -o pipefail
: "${APPBASE_ENDPOINT:?Set endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set project ID}"
: "${APPBASE_API_KEY:?Set project key}"
RESPONSE="$(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT%/}/tablesdb" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{"databaseId": "app-db", "name": "App", "enabled": true}')"
HTTP_STATUS="${RESPONSE##*$'\n'}"
builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)创建表。
(
set +x
set -e -o pipefail
: "${APPBASE_ENDPOINT:?Set endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set project ID}"
: "${APPBASE_API_KEY:?Set project key}"
RESPONSE="$(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT%/}/tablesdb/app-db/tables" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-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"]}]
}')"
HTTP_STATUS="${RESPONSE##*$'\n'}"
builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)存储桶是独立操作,按需创建。
(
set +x
set -e -o pipefail
: "${APPBASE_ENDPOINT:?Set endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set project ID}"
: "${APPBASE_API_KEY:?Set project key}"
RESPONSE="$(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT%/}/storage/buckets" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{"bucketId": "attachments", "name": "附件", "fileSecurity": true, "enabled": true}')"
HTTP_STATUS="${RESPONSE##*$'\n'}"
builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)函数层:创建、配置并部署函数
凭据:项目 API Key。execute 管「谁可调用」,scopes 管函数运行时动态 Key 的权限,两者是两回事;变量需重新 createDeployment 才对后续执行生效。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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'Java SDK 2.12 的默认请求可能在跨主机重定向时携带项目 Key;安全配置尚未验证,暂不提供可执行资源操作代码。请使用本节 REST 步骤;安装信息见 Java Server SDK。
Python Server SDK 2.12.0 的默认请求可能在跳转时转发项目 API Key,暂不提供本段的 SDK 调用代码。使用本节的 REST 页签。
functions := agentbase.NewFunctions(cl)
// 方法名同构(PascalCase):Create / CreateVariable / CreateDeployment /
// GetDeployment(轮询至 Status=ready);可选参数用 functions.With… 选项,
// 以模块源码为准设置 APPBASE_ENDPOINT 为目标环境含 /v1 的 API 地址,并在受控服务端配置 APPBASE_PROJECT_ID 和 APPBASE_API_KEY。每次仅执行一步,确认 HTTP 2xx 后继续;不要在终端日志或命令参数中暴露密钥。
创建函数;确认成功后继续。
(
set +x
set -e -o pipefail
: "${APPBASE_ENDPOINT:?Set endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set project ID}"
: "${APPBASE_API_KEY:?Set project key}"
RESPONSE="$(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT%/}/functions" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-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"
}')"
HTTP_STATUS="${RESPONSE##*$'\n'}"
builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)配置函数变量;确认成功后继续。
(
set +x
set -e -o pipefail
: "${APPBASE_ENDPOINT:?Set endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set project ID}"
: "${APPBASE_API_KEY:?Set project key}"
RESPONSE="$(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT%/}/functions/send-mailer/variables" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{"variableId": "var_database_id", "key": "DATABASE_ID", "value": "app-db"}')"
HTTP_STATUS="${RESPONSE##*$'\n'}"
builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)在项目目录执行以下打包命令,再上传。
tar -czf code.tar.gz --exclude=node_modules --exclude=.git --exclude='.env*' --exclude=.npmrc -C functions/send-mailer .上传源码包;
202后轮询部署状态直到ready。
(
set +x
set -e -o pipefail
: "${APPBASE_ENDPOINT:?Set endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set project ID}"
: "${APPBASE_API_KEY:?Set project key}"
RESPONSE="$(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT%/}/functions/send-mailer/deployments" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-F "code=@./code.tar.gz" \
-F "activate=true")"
HTTP_STATUS="${RESPONSE##*$'\n'}"
builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)前端层:创建站点、注入变量并部署
凭据:项目 API Key(sites.*)。VITE_* 非密变量加 secret: true 的服务端 Key;VITE_APPWRITE_ENDPOINT 必须带 /v1;改变量必须重新部署。框架与 adapter 细节见 sites.mdx。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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'Java SDK 2.12 的默认请求可能在跨主机重定向时携带项目 Key;安全配置尚未验证,暂不提供可执行资源操作代码。请使用本节 REST 步骤;安装信息见 Java Server SDK。
Python Server SDK 2.12.0 的默认请求可能在跳转时转发项目 API Key,暂不提供本段的 SDK 调用代码。使用本节的 REST 页签。
sites := agentbase.NewSites(cl)
// 方法名同构(PascalCase):Create / CreateVariable / CreateDeployment /
// GetDeployment(轮询至 Status=ready);可选参数用 sites.With… 选项,
// 以模块源码为准步骤 1: 创建站点;确认 HTTP 2xx 和返回内容。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -X POST "https://<your-endpoint>/v1/sites" -f -i \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-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"
}'
)步骤 2: 站点创建成功后,单独设置变量并确认 HTTP 2xx。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -X POST "https://<your-endpoint>/v1/sites/portal/variables" -f -i \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{"variableId": "var_endpoint", "key": "VITE_APPWRITE_ENDPOINT", "value": "<APPBASE_ENDPOINT_WITH_V1>"}'
)步骤 3: 变量设置成功后,单独提交部署。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -X POST "https://<your-endpoint>/v1/sites/portal/deployments" -f -i \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-F "code=@./site.tar.gz" \
-F "activate=true"
)部署受理返回 202 后,使用返回的 deployment ID 轮询 GET /v1/sites/portal/deployments/{deploymentId},直到状态为 ready。
平台注册(Console 专有)
在控制台登录目标环境,进入项目的 概览 → 集成 → 平台,按实际使用的域名添加 Web 平台。项目 API Key 没有 platforms.* 权限,不能替代控制台授权;仅填写主机名,不包含协议。参见项目概览。
验证与回报:确认本次部署 URL
在控制台查看本次 deploymentId 对应的站点域名规则,核对规则状态为 verified,并实际访问地址。使用 API 查询时应翻页查找本次部署的已验证规则;未找到时停止并检查域名配置,不要复用旧 URL 或发起重复部署。回报 Project ID、Function ID、Site URL 和本次 deploymentId。参见站点管理。
示例指引
JavaScript(Node 部署序列 + Console 注册平台):examples/javascript.md
Java:examples/java.md