agentbase-docs

站点

这是什么 / 何时用

Sites 在平台内构建并托管 Web 前端(静态站 static 或服务端渲染 ssr),每个 Site 拥有独立的预览域名。构建与运行由平台的执行器完成;Sites 只托管前端,页面里调用的认证、TablesDB、Storage、Functions 等仍走统一的 /v1 API 基址。

适用:给应用配一个可访问的 Web 入口(管理后台、用户门户、落地页);需要"提交源码 → 平台构建 → 拿到 URL"的免运维前端交付;SSR 框架(Next.js/Nuxt/SvelteKit/Astro)托管。

前置

使用骨架

关键参数与返回

错误与边界

SDK 类别差异

各语言调用示例

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

枚举框架与规格

创建前先确认实例支持的框架、构建运行时与规格,不要硬编码默认值。(客户端 SDK 不暴露 Sites 管理,无 web 页签。)

const frameworks = await sites.listFrameworks();
const specs = await sites.listSpecifications();

创建站点

create 的 framework / buildRuntime / adapter 语义上缺一不可(不匹配直接报 Adapter not supported for the selected framework);SPA 必须 fallbackFile: 'index.html'。(客户端 SDK 不暴露 Sites 管理,无 web 页签。)

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)必备
});

站点变量

变量以环境变量注入构建与 SSR 运行时;机密值传 secret: true(读取时掩码,不回显明文)。修改变量后必须重新 createDeployment 才会进入构建/运行时。(客户端 SDK 不暴露 Sites 管理,无 web 页签。)

import { ID } from 'agentbase-node-sdk';

await sites.createVariable({
    siteId: 'portal',
    variableId: ID.unique(),
    key: 'VITE_API_BASE',
    value: 'https://example.com/v1'
});

上传源码部署

打包源码(含 package.json,排除 node_modules、构建产物、.env)为 tar.gz 上传;响应 HTTP 202、构建异步;activate: true 表示构建成功后自动设为活跃部署。(客户端 SDK 不暴露 Sites 管理,无 web 页签。)

import { InputFile } from 'agentbase-node-sdk';

const dep = await sites.createDeployment({
    siteId: 'portal',
    code: InputFile.fromPath('./site.tar.gz'),   // 源码包,不是本地 dist 构建产物
    activate: true                               // 构建成功后自动设为活跃部署
});                                              // HTTP 202:构建异步进行

轮询构建状态

轮询 getDeployment 直至状态机 waiting → processing → building → ready | failed | canceled;failed 时读部署记录的 buildLogs。(客户端 SDK 不暴露 Sites 管理,无 web 页签。)

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);                        // 构建日志,定位失败原因
}

域名(解析预览地址与自定义域名)

域名只在首次部署自动生成;解析预览地址用 Console SDK 的 proxy.listRules() 按 deploymentResourceId + deploymentResourceType: 'site' 过滤,再匹配本次 rule.deploymentId,禁止取 rules[0] 或复用旧 URL;固定子域/自定义域名用 proxy.createSiteRule({ domain, siteId })。(Proxy 仅 Console SDK 提供:Server SDK 无 Proxy 服务、REST 无代理规则端点,故无其他页签。)

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 页签。)

// 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>' });

示例指引

事实源