AgentbaseDocs
文档目录

站点

站点(Sites)是 Agentbase 2.10.0 提供的全托管前端与全栈 Web 应用托管服务(支持 Next.js、SvelteKit、React、Vue、Nuxt、Astro 等主流框架)。通过 Sites,研发团队可以直接从官方模板克隆、连接 GitHub 代码仓库或手动上传 .tar.gz 源码包完成自动化云端构建与发布,并在同一项目上下文内管理多版本部署、一键秒级回滚(Instant rollback)、构建与运行日志、自定义域名 SSL 证书以及站点级环境变量。

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

功能概述

在企业构建智能客服门户、内部知识库检索站点或智能体对话 Web 前端(如项目 企业智能客服与知识中台 enterprise-ai-hub-210 的前端门户)时,传统方案需要额外采购静态托管或容器集群、单独配置 CI/CD 编译流水线、手动申请 HTTPS 证书并配置跨域白名单。

Agentbase Sites 将前端/全栈应用托管深度融入 Project 资源边界内,提供四大核心能力:

核心管理维度控制台页签位置核心功能特性风险与安全边界
站点概览与快速回滚Overview查看当前活动部署(Active deployment)、点击 Visit 访问线上站点、点击 Instant rollback 一键回滚仅已处于 ready 且历史上曾激活过的部署可作为一键回滚目标
部署版本流水(Deployments)Deployments通过 Git(推荐)/ CLI / Manual 创建新部署;支持 Cancel / Redeploy / Delete 及查看构建指标删除当前正在线上服务的活动部署时会弹出额外高危警示
构建与运行日志(Logs)Logs实时查看前端编译构建输出与 SSR 服务端渲染运行日志构建失败时保留完整错误输出供排查依赖或语法问题
域名与证书(Domains)Domains管理默认子域名、预览域名与企业自定义域名;查看 SSL 证书签发状态并支持失败重试自定义域名需完成 DNS 记录指向后方可成功签发证书
站点配置与销毁(Settings)Settings · Usage修改构建命令、Root/Output 目录、站点级环境变量、算力规格、Timeout 与 Danger zone 删除站点Delete site 将永久销毁站点及其全部历史部署记录,不可撤销

核心概念与架构

下图展示了 Sites 的三层准入校验门禁(部署开关 → 邮箱白名单 → 项目权限)、三种代码接入源、云端构建流水线以及线上活动部署与一键回滚的状态流转架构:

flowchart TB
    subgraph AccessGate["三层启用与安全准入门禁"]
        EnvFlag["1. 实例部署开关<br/>_APP_SITES_ENABLED=true<br/>(未开启则侧栏隐藏 Sites)"]
        AllowList["2. 能力邮箱白名单校验<br/>名单为空: 对所有人关闭<br/>名单非空: 校验会话用户邮箱 / 账号Key邮箱 / 团队已确认Owner邮箱"]
        ProjPerm["3. 项目级 RBAC 权限<br/>需具备 sites.write (owner/admin/developer/editor)"]
        EnvFlag --> AllowList --> ProjPerm
    end

    subgraph CreateSources["三种站点创建与部署来源 (快捷键 C)"]
        CloneTpl["方式 A: 克隆模板 (Clone template)<br/>按 Use case / Framework 筛选精选模板"]
        ConnGit["方式 B: 连接 Git 仓库 (Connect Git)<br/>GitHub App 授权 -> 选择仓库与分支"]
        UploadTar["方式 C: 手动上传 (Manual upload)<br/>拖拽上传 .tar.gz 源码包"]
    end

    subgraph BuildAndDeploy["Deploy site 构建与运行时沙箱 (Restricted Identity)"]
        BuildCfg["构建配置:<br/>Root directory (./) + Install (npm install)<br/>+ Build (npm run build) + Output (dist)<br/>+ 项目 Global variables & 站点环境变量"]
        HistoryDep["历史就绪部署 (ready & 曾激活)"]
        ActiveDep["当前活动部署 (Active Deployment)<br/>绑定站点域名对外提供 HTTPS 访问"]
        BuildCfg -- "构建成功激活" --> ActiveDep
        ActiveDep <-- "Instant rollback 一键秒级回滚" --> HistoryDep
    end

    ProjPerm --> CreateSources
    CloneTpl --> BuildCfg
    ConnGit --> BuildCfg
    UploadTar --> BuildCfg

1. Sites 能力启用条件与邮箱白名单校验规则(重点)

由于前端与全栈站点构建会消耗云端编译算力与公网出口资源,Agentbase 对 Sites 模块实施了严密的三级准入控制。只有同时满足以下三项条件,用户才能在项目中创建和部署站点:

准入层级配置项或检验维度详细判定规则与不满足时的系统行为
第一层:实例部署开关_APP_SITES_ENABLED实例环境变量必须设为 true,项目左侧边栏才会显示 Sites 入口;若设为 false 或未配置,侧栏自动隐藏该入口。
第二层:能力邮箱白名单实例级 Sites 允许名单(Email Allowlist)• 若白名单配置为空:Sites 能力对所有用户关闭(Fail-Closed);<br/>• 若白名单非空:系统会严格校验请求方身份对应的邮箱是否在白名单内——包括:① 当前 Console 登录会话用户的邮箱;② 账号级 API Key 所属用户的邮箱;或 ③ 项目/组织 API Key 所属团队中已确认(Confirmed)的组织 Owner 邮箱。<br/>• 若不满足白名单条件,请求将直接失败并返回明确权限报错。
第三层:项目写权限sites.write操作成员在当前项目所属组织中必须具备写角色(owner、admin、developer 或 editor);只读角色(billing、analyst)仅可浏览不可创建。

2. Sites(站点)与 Functions(云函数)的架构分工对比

在同一个项目(如 enterprise-ai-hub-210)中,Sites 与 Functions 共享底层受限身份沙箱技术与项目全局变量,但各自承担不同的架构角色:

对比维度站点(Sites)云函数(Functions)
核心定位面向终端用户浏览器的前端/全栈 Web 站点托管与域名分发面向后端逻辑的事件驱动、定时任务与 API 微服务计算
典型技术栈Next.js、SvelteKit、React、Vue、Nuxt、静态 HTML/JS/CSS 产物Node.js、Python、java-17.0(支持预构建 JAR)、Go、PHP、Deno
访问与触发方式用户通过浏览器直接访问站点子域名或自定义 HTTPS 域名通过 SDK executions 接口、内部数据库/存储事件(Events)或 Cron 定时触发
协同工作方式站点前端通过 @alipay/agentbase-web-sdk@2.10.0 或 agentbase-web-sdk@2.10.0 直接调用同项目的 Auth、Databases、智能体接口与 Functions为站点前端提供受保护的后端定制业务逻辑、第三方 Webhook 回调处理与异步批处理

角色、入口与关联关系

1. 控制台导航路径与子页签结构

2. 与项目全局变量(Global Variables)及平台登记(Platforms)的关联

功能详解与操作指南

1. 创建并部署第一个站点(三种接入方式详解)

在 Sites 列表页点击 Create site(或按快捷键 C),根据团队代码管理方式选择以下任一路径:

方式一:连接 Git 仓库(Connect Git Repository,生产推荐)

方式二:从官方模板克隆(Clone Template,快速体验)

方式三:手动上传源码包(Manual Upload,离线/内网交付)

填写部署配置参数表(Deploy Site)

在部署配置向导中,按自上而下的 6 个区块核对参数并提交:

配置区块核心字段名称默认值 / 格式约束填写说明与生产建议
1. Details(基本信息)Name / **Site ID ($id) / Framework / 执行计划**Framework 自动识别或手动下拉选择例如填写名称 企业智能客服Web工作台,自定义 Site ID 为 enterprise-support-portal,框架选择 Next.js 或 SvelteKit。
2. Git configurationRoot directory(根目录)默认 ./若前端工程位于 Monorepo 仓库的子目录中(例如 ./apps/web-portal),请在此处填入相对子目录路径。
3. Build configurationInstall command默认 npm install依赖安装命令(如使用 pnpm 或 yarn 可改为 pnpm install / yarn install)。
Build command默认 npm run build生产构建命令,容器内将以受限身份执行该命令。
Output directory默认 dist(随框架预设自动调整)构建产物输出目录(如 Vite/Vue 通常为 dist,Next.js/SvelteKit 按各自适配器目录设置)。
4. Environment variables键值对列表(Key / Value)支持从仓库预填或手动添加例如填入 PUBLIC_AGENTBASE_ENDPOINT=https://appbuild.oceanbase.com/v1 与 PUBLIC_AGENTBASE_PROJECT_ID=enterprise-ai-hub-210。
5. Domain(站点域名)Subdomain(站点子域名)全局唯一合法子域名前缀系统为站点分配的默认访问子域名。
6. 提交构建Deploy 按钮提交后自动跳转构建等待页构建完成前等待页会实时自动刷新进度,就绪后即可点击 Visit 访问站点。

2. 日常发版、状态监控与一键秒级回滚(Instant Rollback)

3. 绑定站点自定义域名与管理站点设置

常见问题与排障

Q1:项目左侧边栏显示了 Sites 入口,为什么我点击 Create site 提交时却直接报错失败,提示无权限使用 Sites?

原因与排查步骤: 这是因为 _APP_SITES_ENABLED=true 仅控制侧边栏显示 Sites 入口,而实际创建和部署站点还受实例级Sites 能力白名单(邮箱允许列表)的严格门禁校验:

Q2:为什么站点 Overview 页面上的“Instant rollback(一键回滚)”按钮是置灰不可点的?

原因与排查步骤: Instant rollback 要求当前站点下至少存在一个除当前活动部署之外、**构建状态为 ready 且历史上曾经被激活上线过**的旧部署版本。如果该站点刚刚创建只有第 1 个部署版本,或者之前的部署全部为 failed(从未成功激活上线过),则没有合法的回滚目标,按钮会自动禁用。

Q3:站点构建日志报错权限拒绝(Permission denied)或无法访问内网地址是什么原因?

原因与排查步骤: 与 Functions 云函数完全一致,Sites 的构建容器与运行沙箱强制执行两项平台级安全基线:

相关文档