站点
这是什么 / 何时用
Sites 在平台内构建并托管 Web 前端(静态站 static 或服务端渲染 ssr),每个 Site 拥有独立的预览域名。构建与运行由平台的执行器完成;Sites 只托管前端,页面里调用的认证、TablesDB、Storage、Functions 等仍走统一的 /v1 API 基址。
适用:给应用配一个可访问的 Web 入口(管理后台、用户门户、落地页);需要"提交源码 → 平台构建 → 拿到 URL"的免运维前端交付;SSR 框架(Next.js/Nuxt/SvelteKit/Astro)托管。
前置
- 能力白名单:实例以
_APP_SITES_WHITELIST_EMAILS控制谁能使用 Sites。名单为空时所有请求报Sites capability is disabled;名单非空时——项目级 API Key 要求项目 Team 中至少一名 confirmed Owner 的邮箱在名单内;用户 Session/JWT 按当前用户邮箱判定;账号级 Key 按 Key 所属用户邮箱判定。白名单报错应停止并联系实例运维,不要循环重试。 - API Key scopes:Site 增删改查与部署、变量需要
sites.write;读取与用量需要sites.read;域名规则(Proxy)需要rules.read/rules.write。 - 受限身份(2.6.0 安全默认值):Site 的安装/构建/启动命令在受限身份下运行,不满足安全条件时直接失败,不回退为高权限执行。
- 管理平台注册(把 Site 域名登记为应用 Platform)需要 Console Session,项目 API Key 无
platforms.*scope(见 deployment.md)。
使用骨架
listFrameworks()/listSpecifications()确认目标实例支持的框架、构建运行时与规格,不要硬编码默认值。- 创建 Site:指定
siteId、name、framework、buildRuntime(如node-22)、adapter(static或ssr)、构建命令(installCommand/buildCommand/startCommand)、outputDirectory;SPA 必须fallbackFile: 'index.html';SSR 设置请求超时timeout(秒)。 - 打包源码(含
package.json,排除node_modules、构建产物、.env)为 tar.gz,createDeployment({ siteId, code, activate: true })上传——响应为 HTTP 202,构建是异步的。 - 轮询
getDeployment({ siteId, deploymentId })直到状态机waiting → processing → building → ready | failed | canceled;failed时读构建日志(listLogs/ deployment 的 buildLogs)。 - 用本次
deploymentId经 Proxy 规则解析预览域名(Console SDK 的proxy.listRules();Server SDK 无 Proxy 服务)按deploymentResourceId+deploymentResourceType: 'site'过滤后匹配rule.deploymentId;禁止取rules[0]或复用旧 URL。 - (可选)自定义域名:
proxy.createSiteRule({ domain, siteId });VCS 部署用createVcsDeployment,模板部署用createTemplateDeployment,回滚用updateSiteDeployment切换活跃部署。 - 构建期变量用
createVariable({ siteId, variableId, key, value, secret })管理;修改变量后必须重新 createDeployment 才会进入构建/运行时。
关键参数与返回
sites.create:siteId(≤36 字符,字母数字与.、-、_)、name(≤128 字符)、framework/buildRuntime/adapter必填语义上缺一不可(adapter 与 framework 不匹配直接报Adapter not supported for the selected framework);enabled关闭后用户不可访问但 Server/Console SDK 仍可管理;logging关闭可加快响应;timeout为单请求最大秒数。sites.createDeployment:code为源码包(SDK 侧用InputFile.fromPath()),activate: true表示构建成功后自动设为活跃部署;可覆盖installCommand/buildCommand/outputDirectory。- 返回的 deployment 对象携带
status、构建日志入口与$createdAt;Site 对象携带enabled、live、框架与运行时规格。 - 构建资源与时长为实例配置:构建内存下限约 2048MB,构建超时默认 900 秒(自托管
_APP_COMPUTE_BUILD_TIMEOUT)。
错误与边界
- 白名单未放行:
Sites capability is disabled,或项目 Key 不满足 confirmed Owner 条件——停止流程而不是重试。 - 上传的是源码而非本地
dist;平台在构建期执行安装与构建。 - SPA 使用 browser router 时缺
fallbackFile会导致子路径刷新 404。 - 域名只在首次部署自动生成;此后 URL 解析优先级为实例公开地址 > 绑定本次 deploymentId 的规则 > 最新
$createdAt的规则。 - 预览域可能带 Console 登录门(SIT 环境):访客先被引导登录 Console 属预期行为。
- SSR Cookie 限制:Sites 代理转发请求到 SSR 运行时的 Header 白名单**不包含
Cookie/Set-Cookie**(两个方向都不通)。服务端"写 Session Cookie → Server Component 读 Cookie"的方案不可行(重定向循环或 404)。可行拆分:Server 侧用注入的 API Key(Site Variablesecret: true)做受控读写;浏览器侧用 Client SDK + 用户/匿名 Session 直连/v1。Next.js 配套output: 'standalone',并信任转发 Host 头。
SDK 类别差异
- Server SDK(server-sdk/nodejs.md):
Sites服务全集(创建/部署/变量/框架规格/日志),适合自动化部署脚本。 - Console SDK(console-sdk/nodejs.md):同样提供
Sites全集,另有Proxy(域名规则)、Domains(域名资产)与平台注册相关调用。 - 客户端 SDK(client-sdk/web.md):不暴露 Sites 管理面;浏览器只访问已部署站点的页面与
/v1数据面。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
枚举框架与规格
创建前先确认实例支持的框架、构建运行时与规格,不要硬编码默认值。(客户端 SDK 不暴露 Sites 管理,无 web 页签。)
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const frameworks = await sites.listFrameworks();
const specs = await sites.listSpecifications();import io.agentbase.services.Sites;
Sites sites = new Sites(client); // client 初始化见 server-sdk/java.md
var frameworks = sites.listFrameworks(); // 支持的框架清单
var specs = sites.listSpecifications(); // 构建运行时与规格;create 的规格取值以此为准frameworks = sites.list_frameworks()
specs = sites.list_specifications()sites := agentbase.NewSites(cl) // facade 构造器;cl 为已装载 API Key 的 Client
frameworks, err := sites.ListFrameworks() // 支持的框架清单
specs, err := sites.ListSpecifications() // 构建运行时与规格;create 的规格取值以此为准curl -sS "$APPBASE_ENDPOINT/sites/frameworks" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 构建规格:GET /sites/specifications;执行计划:GET /sites/execution-plans?framework=react创建站点
create 的 framework / buildRuntime / adapter 语义上缺一不可(不匹配直接报 Adapter not supported for the selected framework);SPA 必须 fallbackFile: 'index.html'。(客户端 SDK 不暴露 Sites 管理,无 web 页签。)
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
import { Client, Sites } from 'agentbase-node-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // 必须包含 /v1
.setProject(process.env.APPBASE_PROJECT_ID!)
.setKey(process.env.APPBASE_API_KEY!); // sites.write 最小 scope
const sites = new Sites(client);
await sites.create({
siteId: 'portal',
name: '用户门户',
framework: 'react', // 全量以 sites.listFrameworks() 为准,不要硬编码
buildRuntime: 'node-22',
adapter: 'static', // SSR 用 'ssr' 并设 timeout(秒)
installCommand: 'npm install',
buildCommand: 'npm run build',
outputDirectory: 'dist',
fallbackFile: 'index.html' // SPA(browser router)必备
});Sites sites = new Sites(client); // client 初始化见 server-sdk/java.md
// create 为位置参数全集(绝大多数可空),完整签名见 examples/java.md:
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()from agentbase.services.sites import Sites
sites = Sites(client) # 同步调用,返回 pydantic 模型
sites.create(site_id='portal', name='用户门户', framework='react',
build_runtime='node-22', adapter='static',
install_command='npm install', build_command='npm run build',
output_directory='dist', fallback_file='index.html')sites := agentbase.NewSites(cl) // facade 构造器;cl 为已装载 API Key 的 Client
_, err := sites.Create("portal", "用户门户", "react", "node-22", // framework / buildRuntime 必填位置参数
sites.WithCreateAdapter("static"), // SSR 用 "ssr" 并设 timeout(秒)
sites.WithCreateInstallCommand("npm install"),
sites.WithCreateBuildCommand("npm run build"),
sites.WithCreateOutputDirectory("dist"),
sites.WithCreateFallbackFile("index.html")) // SPA(browser router)必备
// framework 全量以 ListFrameworks() 为准,不要硬编码curl -sS -X POST "$APPBASE_ENDPOINT/sites" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"siteId":"portal","name":"用户门户","framework":"react","buildRuntime":"node-22","adapter":"static","installCommand":"npm install","buildCommand":"npm run build","outputDirectory":"dist","fallbackFile":"index.html"}'站点变量
变量以环境变量注入构建与 SSR 运行时;机密值传 secret: true(读取时掩码,不回显明文)。修改变量后必须重新 createDeployment 才会进入构建/运行时。(客户端 SDK 不暴露 Sites 管理,无 web 页签。)
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
import { ID } from 'agentbase-node-sdk';
await sites.createVariable({
siteId: 'portal',
variableId: ID.unique(),
key: 'VITE_API_BASE',
value: 'https://example.com/v1'
});// 与 Node 面差异:Java createVariable 无 variableId 参数(ID 由服务端生成)
sites.createVariable("portal", "VITE_API_BASE", "https://example.com/v1",
null); // secret:机密值传 true,读取时掩码;修改变量后需重新 createDeployment 才生效# 与 Node 面差异:Python create_variable 无 variable_id 参数(ID 由服务端生成)
sites.create_variable(site_id='portal', key='VITE_API_BASE', value='https://example.com/v1',
secret=None) # 机密值传 True,读取时掩码_, err := sites.CreateVariable("portal", "VITE_API_BASE", "https://example.com/v1") // 无 variableId,服务端生成
// 机密值经 WithCreateVariableSecret(true) 传入(读取时掩码);修改变量后需重新 CreateDeployment 才生效curl -sS -X POST "$APPBASE_ENDPOINT/sites/portal/variables" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"variableId":"v1","key":"VITE_API_BASE","value":"https://example.com/v1","secret":false}'
# 列表 GET /sites/portal/variables(机密不回显);更新 PUT /sites/portal/variables/{variableId};删除 DELETE 同路径上传源码部署
打包源码(含 package.json,排除 node_modules、构建产物、.env)为 tar.gz 上传;响应 HTTP 202、构建异步;activate: true 表示构建成功后自动设为活跃部署。(客户端 SDK 不暴露 Sites 管理,无 web 页签。)
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
import { InputFile } from 'agentbase-node-sdk';
const dep = await sites.createDeployment({
siteId: 'portal',
code: InputFile.fromPath('./site.tar.gz'), // 源码包,不是本地 dist 构建产物
activate: true // 构建成功后自动设为活跃部署
}); // HTTP 202:构建异步进行import io.agentbase.models.InputFile;
var dep = sites.createDeployment("portal",
InputFile.fromPath(java.nio.file.Paths.get("./site.tar.gz")), // 源码包,不是本地 dist 构建产物
null, null, null, // installCommand / buildCommand / outputDirectory 覆盖项
true); // activate:构建成功后自动设为活跃部署;HTTP 202 构建异步
// dep.getId() 供「轮询构建状态」卡使用from agentbase.input_file import InputFile
dep = sites.create_deployment(site_id='portal',
code=InputFile.from_path('./site.tar.gz'), # 源码包,不是本地 dist 构建产物
activate=True) # HTTP 202:构建异步dep, err := sites.CreateDeployment("portal",
file.NewInputFile("./site.tar.gz", "site.tar.gz"), // 源码包(agentbase-go-sdk/file),不是本地 dist 构建产物
sites.WithCreateDeploymentActivate(true)) // 构建成功后自动设为活跃部署;HTTP 202:构建异步curl -sS -X POST "$APPBASE_ENDPOINT/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"
# multipart/form-data;返回 202轮询构建状态
轮询 getDeployment 直至状态机 waiting → processing → building → ready | failed | canceled;failed 时读部署记录的 buildLogs。(客户端 SDK 不暴露 Sites 管理,无 web 页签。)
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
let d = await sites.getDeployment({ siteId: 'portal', deploymentId: dep.$id }); // 本次 createDeployment 返回的 ID
while (!['ready', 'failed', 'canceled'].includes(d.status)) {
await new Promise((r) => setTimeout(r, 5000)); // 构建异步:间隔轮询
d = await sites.getDeployment({ siteId: 'portal', deploymentId: dep.$id });
}
if (d.status === 'failed') {
console.log(d.buildLogs); // 构建日志,定位失败原因
}import io.agentbase.enums.DeploymentStatus;
var d = sites.getDeployment("portal", dep.getId()); // dep 为「上传源码部署」卡 createDeployment 返回值
while (d.getStatus() != DeploymentStatus.READY && d.getStatus() != DeploymentStatus.FAILED
&& d.getStatus() != DeploymentStatus.CANCELED) {
Thread.sleep(5000); // 构建异步:间隔轮询
d = sites.getDeployment("portal", dep.getId());
}
if (d.getStatus() == DeploymentStatus.FAILED) {
System.out.println(d.getBuildLogs()); // 构建日志,定位失败原因
}import time
# dep 为「上传源码部署」卡 create_deployment 的返回值
d = sites.get_deployment(site_id='portal', deployment_id=dep.id)
while d.status not in ('ready', 'failed', 'canceled'):
time.sleep(5) # 构建异步:间隔轮询
d = sites.get_deployment(site_id='portal', deployment_id=dep.id)
if d.status == 'failed':
... # 读部署记录的 buildLogs(构建日志)定位失败原因// dep 为「上传源码部署」卡 CreateDeployment 的返回值
d, err := sites.GetDeployment("portal", dep.Id)
for d.Status != "ready" && d.Status != "failed" && d.Status != "canceled" {
time.Sleep(5 * time.Second) // 构建异步:间隔轮询
d, err = sites.GetDeployment("portal", dep.Id)
}
// d.Status == "failed" 时读 d.BuildLogs 定位失败原因curl -sS "$APPBASE_ENDPOINT/sites/portal/deployments/$DEPLOYMENT_ID" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 轮询直至 status 为 ready | failed | canceled;failed 时读响应中的 buildLogs域名(解析预览地址与自定义域名)
域名只在首次部署自动生成;解析预览地址用 Console SDK 的 proxy.listRules() 按 deploymentResourceId + deploymentResourceType: 'site' 过滤,再匹配本次 rule.deploymentId,禁止取 rules[0] 或复用旧 URL;固定子域/自定义域名用 proxy.createSiteRule({ domain, siteId })。(Proxy 仅 Console SDK 提供:Server SDK 无 Proxy 服务、REST 无代理规则端点,故无其他页签。)
- Console(Node)
import { Client, Proxy, Query } from 'agentbase-console-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT)
.setProject(process.env.APPBASE_PROJECT_ID);
// Console Session 或项目 API Key(rules.read / rules.write)装载见 console-sdk/nodejs.md
const proxy = new Proxy(client);
// 解析本次部署的预览域名(dep.$id 为本次 createDeployment 返回值)
const rules = await proxy.listRules({
queries: [
Query.equal('deploymentResourceId', ['portal']),
Query.equal('deploymentResourceType', ['site'])
]
});
const bound = rules.rules.find((r) => r.domain && r.deploymentId === dep.$id);
console.log(bound.domain); // 预览地址;禁止取 rules[0]
// (可选)固定子域或自定义域名(生成 trigger=manual 公开规则)
await proxy.createSiteRule({
domain: 'app.example.com',
siteId: 'portal',
branch: 'main' // 可选:绑定 Git 分支
});VCS 与模板部署、回滚
已关联 VCS 的站点用 createVcsDeployment 按分支/提交/标签构建;模板部署用 createTemplateDeployment 指定仓库/属主/目录/引用;回滚用 updateSiteDeployment 把活跃部署切回目标 deploymentId(访客此后访问旧部署产物)。(客户端 SDK 不暴露 Sites 管理,无 web 页签。)
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
// VCS 部署:HTTP 202,构建异步
await sites.createVcsDeployment({
siteId: 'portal',
type: 'commit', // branch / commit / tag,随 reference 而定
reference: 'prod',
activate: true
});
// 模板部署:从模板仓库创建
await sites.createTemplateDeployment({
siteId: 'portal',
repository: 'agentbase/function-templates',
owner: 'agentbase',
rootDirectory: 'hello-world',
type: 'branch',
reference: 'main',
activate: true
});
// 回滚:切换活跃部署
await sites.updateSiteDeployment({ siteId: 'portal', deploymentId: '<previousDeploymentId>' });import io.agentbase.enums.TemplateReferenceType;
import io.agentbase.enums.VCSReferenceType;
// VCS 部署:HTTP 202,构建异步
sites.createVcsDeployment("portal", VCSReferenceType.COMMIT, "prod", true);
// 模板部署:从模板仓库创建
sites.createTemplateDeployment("portal", "agentbase/function-templates", "agentbase",
"hello-world", TemplateReferenceType.BRANCH, "main", true);
// 回滚:切换活跃部署
sites.updateSiteDeployment("portal", "<previousDeploymentId>");sites.create_vcs_deployment(site_id='portal', type='commit', reference='prod',
activate=True) # HTTP 202,构建异步;type: branch / commit / tag
sites.create_template_deployment(site_id='portal', repository='agentbase/function-templates',
owner='agentbase', root_directory='hello-world',
type='branch', reference='main', activate=True)
sites.update_site_deployment(site_id='portal', deployment_id='<previousDeploymentId>') # 回滚:切换活跃部署_, err := sites.CreateVcsDeployment("portal", "commit", "prod",
sites.WithCreateVcsDeploymentActivate(true)) // type: branch / commit / tag;HTTP 202,构建异步
_, err = sites.CreateTemplateDeployment("portal", "agentbase/function-templates", "agentbase",
"hello-world", "branch", "main",
sites.WithCreateTemplateDeploymentActivate(true))
_, err = sites.UpdateSiteDeployment("portal", "<previousDeploymentId>") // 回滚:切换活跃部署# VCS 部署(站点已关联仓库)
curl -sS -X POST "$APPBASE_ENDPOINT/sites/portal/deployments/vcs" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"type":"commit","reference":"prod","activate":true}'
# 模板部署
curl -sS -X POST "$APPBASE_ENDPOINT/sites/portal/deployments/template" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"repository":"agentbase/function-templates","owner":"agentbase","rootDirectory":"hello-world","type":"branch","reference":"main","activate":true}'
# 回滚:切换活跃部署
curl -sS -X PATCH "$APPBASE_ENDPOINT/sites/portal/deployment" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"deploymentId":"<previousDeploymentId>"}'示例指引
- JavaScript(Node 部署脚本 / Console 流程):examples/javascript.md
- Java(Server / Console SDK 调用写法):examples/java.md
事实源
skills/ob-agentbase/references/sites.mdskills/ob-agentbase/references/sites-ssr-guide.mdskills/ob-agentbase/references/full-stack-deploy.mdskills/ob-agentbase/references/agent-deploy-playbook.md- appbase v2.7.0(tag v2.7.0)
- agentbase-sdks v2.7.0 specs(
packages/sdks/*/src的 Sites / Proxy 方法面)