站点
站点(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 资源边界内,提供四大核心能力:
- 三源接入与框架自适应构建:支持从精选模板库克隆(Clone template)、连接 GitHub 仓库(自动识别分支与提交)或手动拖拽上传
.tar.gz源码包,自动匹配 Next.js、SvelteKit 等框架的构建命令与产物目录。 - 零停机发布与一键回滚(Instant Rollback):每次构建生成独立的 Deployment 版本;支持在站点概览页通过 Instant rollback 一键切回任意曾激活且状态为
ready的历史稳定版本。 - 双层安全准入与受限身份运行:由实例级开关
_APP_SITES_ENABLED与能力白名单(邮箱白名单)双重门禁管控;底层构建与 SSR 运行容器强制采用非特权受限身份(Restricted Identity)并内置 SSRF 防护。 - 自有域名自动化与同源上下文注入:自动分配预览域名并支持绑定企业自定义域名(自动签发 SSL 证书);项目级全局变量(Global variables)与站点专属环境变量在构建和运行期自动注入。
| 核心管理维度 | 控制台页签位置 | 核心功能特性 | 风险与安全边界 |
|---|---|---|---|
| 站点概览与快速回滚 | 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 --> BuildCfg1. 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. 控制台导航路径与子页签结构
- 列表页入口:进入项目控制台后,在左侧导航栏点击 Sites(路径
/console/project-{region}-{project}/sites,如图 1 所示)。在列表页直接按键盘快捷键 **C或点击右上角 Create site** 即可启动站点创建向导(/sites/create-site)。 - 站点详情页六大页签(路径前缀
/console/project-{region}-{project}/sites/site-{site}): - Overview(
.../site-{site}):展示当前线上活动部署卡片、访问链接(Visit)、一键回滚按钮(Instant rollback)及实时构建状态提示。 - Deployments(
.../deployments):管理历史与进行中的全部部署版本,支持新建部署、取消构建、重新部署与删除部署。 - Logs(
.../logs):查看站点构建日志与运行时日志。 - Domains(
.../domains):管理站点自定义域名、预览域名与 SSL 证书签发状态。 - Usage(
.../usage):查看该站点的请求与带宽消耗趋势。 - Settings(
.../settings):维护站点名称、Git 仓库绑定、构建命令、运行时规格、站点级环境变量、超时时间、日志开关与删除站点(Danger zone)。
- Overview(
2. 与项目全局变量(Global Variables)及平台登记(Platforms)的关联
- 环境变量合并注入:项目 Settings → Overview → Global variables 中配置的全部变量会自动注入到每一个 Site 的构建与运行环境中;同时你还可以在站点的 Settings 页配置仅对该站点生效的站点作用域环境变量(构建时也可从关联的 Git 仓库自动预填环境变量)。
- 与前端 SDK 跨域协同:当托管在 Sites 上的前端页面通过浏览器调用同项目的 Agentbase Client API 时,请确保该站点的分配域名或自定义域名已登记在项目 Overview → Integrations → Platforms(Web 平台 Hostname)中。
功能详解与操作指南
1. 创建并部署第一个站点(三种接入方式详解)
在 Sites 列表页点击 Create site(或按快捷键 C),根据团队代码管理方式选择以下任一路径:
方式一:连接 Git 仓库(Connect Git Repository,生产推荐)
- 选择 Connect Git repository。若当前项目尚未关联 GitHub App,按界面引导先完成 GitHub 授权安装(也可在项目 Settings → Git 管理连接)。
- 从已授权列表中选择目标前端代码仓库与生产分支(如
main),点击进入 Deploy site(部署配置) 页面。
方式二:从官方模板克隆(Clone Template,快速体验)
- 选择 Clone template,在模板库中支持按 Use case(业务场景,如 AI Chat、Starter、Dashboard) 或 Framework(前端框架,如 Next.js、SvelteKit、Vue) 筛选。
- 选中模板后进入部署配置页,系统会自动填充该模板所需的全套构建命令与环境变量。
方式三:手动上传源码包(Manual Upload,离线/内网交付)
- 选择 Manual,将本地前端工程源码打包为 **
.tar.gz格式压缩包**(包大小受当前套餐与实例配置上限约束),拖拽或选择文件上传后进入部署配置页。
填写部署配置参数表(Deploy Site)
在部署配置向导中,按自上而下的 6 个区块核对参数并提交:
| 配置区块 | 核心字段名称 | 默认值 / 格式约束 | 填写说明与生产建议 |
|---|---|---|---|
| 1. Details(基本信息) | Name / **Site ID ($id) / Framework / 执行计划** | Framework 自动识别或手动下拉选择 | 例如填写名称 企业智能客服Web工作台,自定义 Site ID 为 enterprise-support-portal,框架选择 Next.js 或 SvelteKit。 |
| 2. Git configuration | Root directory(根目录) | 默认 ./ | 若前端工程位于 Monorepo 仓库的子目录中(例如 ./apps/web-portal),请在此处填入相对子目录路径。 |
| 3. Build configuration | Install 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)
- 触发新版本部署:
- 在站点详情页切换到 Deployments 页签,点击 Create deployment。
- 支持选择 Git(推荐,拉取最新分支提交构建)、CLI(通过命令行工具发布) 或 **Manual(上传新
.tar.gz包)**。
- 处理配置变更未生效提示:
- 当你在站点 Settings 页修改了构建命令、Output 目录、运行时规格或站点环境变量后,旧的活动部署不会自动改变;页面顶部会显示醒目的黄色警示横幅,直接点击横幅上的 Redeploy 按钮即可基于新配置重新构建并上线。
- 执行线上紧急回滚(两种方式):
- 方式 A(Overview 页 Instant rollback):当新上线的部署出现前端白屏或样式错乱时,进入站点 Overview 页签,在当前活动部署卡片上直接点击 Instant rollback(该按钮仅在存在状态为
ready且历史上曾被激活过的旧部署时可用),一键切回上一个稳定版本。 - 方式 B(Deployments 列表精准切换):进入 Deployments 页签,在历史列表中找到任意状态为
ready的目标部署版本,点击激活将其设为当前活动部署。
- 方式 A(Overview 页 Instant rollback):当新上线的部署出现前端白屏或样式错乱时,进入站点 Overview 页签,在当前活动部署卡片上直接点击 Instant rollback(该按钮仅在存在状态为
- 取消与删除部署:
- 对正在构建中的任务可点击 Cancel 终止;对不再需要的历史部署可点击 Delete 清理(删除操作不可恢复;若尝试删除当前正在服务的活动部署,系统会弹出额外的高危确认提示)。
3. 绑定站点自定义域名与管理站点设置
- 绑定自定义域名(Domains 页签):
- 进入站点详情 Domains 页签,点击添加自定义域名(如
chat.enterprise.example.com)。 - 按照界面提示在企业 DNS 中配置指向记录,并在域名列表中观察 SSL 证书状态;若证书生成失败(
Certificate generation failed),排查 DNS 生效后点击重试(Retry)即可。
- 进入站点详情 Domains 页签,点击添加自定义域名(如
- 调整运行时规格与危险区销毁(Settings 页签):
- 在 Settings 页签中,可随时更新站点名称、断开或重连 Git 仓库(Disconnect repository)、调整构建与运行时资源规格、修改执行超时(Timeout)及日志采集开关。
- 如需彻底下线某个测试站点,滚动至底部 Danger zone 点击 Delete site,完成二次确认后将永久删除该站点及其下属的全部历史部署产物(不可撤销),并自动返回 Sites 列表页。
常见问题与排障
Q1:项目左侧边栏显示了 Sites 入口,为什么我点击 Create site 提交时却直接报错失败,提示无权限使用 Sites?
原因与排查步骤: 这是因为 _APP_SITES_ENABLED=true 仅控制侧边栏显示 Sites 入口,而实际创建和部署站点还受实例级Sites 能力白名单(邮箱允许列表)的严格门禁校验:
- 若平台管理员尚未配置邮箱白名单(名单为空),Sites 功能对所有用户处于关闭状态。
- 若白名单非空,系统会检查你的当前登录账号邮箱(或使用项目/组织 API Key 调用时,该项目所属组织中已确认的 Owner 邮箱)是否在白名单内。请联系平台管理员将你的开发者邮箱及组织 Owner 邮箱加入实例的 Sites 允许名单中。
Q2:为什么站点 Overview 页面上的“Instant rollback(一键回滚)”按钮是置灰不可点的?
原因与排查步骤: Instant rollback 要求当前站点下至少存在一个除当前活动部署之外、**构建状态为 ready 且历史上曾经被激活上线过**的旧部署版本。如果该站点刚刚创建只有第 1 个部署版本,或者之前的部署全部为 failed(从未成功激活上线过),则没有合法的回滚目标,按钮会自动禁用。
Q3:站点构建日志报错权限拒绝(Permission denied)或无法访问内网地址是什么原因?
原因与排查步骤: 与 Functions 云函数完全一致,Sites 的构建容器与运行沙箱强制执行两项平台级安全基线:
- 受限身份运行(Restricted Identity):
Install command与Build command均以非 root 受限用户身份执行。请勿在package.json的postinstall或build脚本中执行sudo、写入系统全局目录(如/usr/local)或绑定<1024的特权端口;如不满足受限安全条件,构建会直接失败且绝不回退为高权限执行。 - 出站 SSRF 防护:构建或 SSR 运行期间发起的外部网络请求禁止访问本机回环、私网 IP 段与云元数据地址。