站点
站点(Sites)是 Agentbase 提供的全托管前端与全栈 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 版本;支持在站点概览页通过 即时回滚 一键切回任意曾激活且状态为
ready的历史稳定版本。双层安全准入与受限身份运行:由实例级开关
_APP_SITES_ENABLED与能力白名单(邮箱白名单)双重门禁管控;构建与 SSR 的运行身份和网络限制取决于实际执行器及部署配置。自有域名自动化与同源上下文注入:自动分配预览域名并支持绑定企业自定义域名(自动签发 SSL 证书);项目级全局变量(Global variables)与站点专属环境变量在构建和运行期自动注入。
| 核心管理维度 | 控制台页签位置 | 核心功能特性 | 风险与安全边界 |
|---|---|---|---|
| 站点概览与快速回滚 | Overview | 查看当前活动部署(Active deployment)、点击 访问 访问线上站点、点击 即时回滚 一键回滚 | 仅已处于 ready 且历史上曾激活过的部署可作为一键回滚目标 |
| 部署版本流水(Deployments) | Deployments | 通过 Git(推荐)/ CLI / Manual 创建新部署;支持 Cancel / Redeploy / Delete 及查看构建指标 | 删除当前正在线上服务的活动部署时会弹出额外高危警示 |
| 构建与运行日志(Logs) | Logs | 查看构建输出与 SSR 运行日志 | 构建失败时可查看已记录的输出;日志可能被截断或因运行链路原因缺失 |
| 域名与证书(Domains) | Domains | 管理默认子域名、预览域名与企业自定义域名;查看 SSL 证书签发状态并支持失败重试 | 自定义域名需完成 DNS 记录指向后方可成功签发证书 |
| 站点配置与销毁(Settings) | Settings · Usage | 修改构建命令、Root/Output 目录、站点级环境变量、算力规格、Timeout 与 Danger zone 删除站点 | 删除站点 将永久销毁站点及其全部历史部署记录,不可撤销 |
核心概念与架构
1. Sites 能力启用条件与邮箱白名单校验规则(重点)
由于前端与全栈站点构建会消耗云端编译算力与公网出口资源,Agentbase 对 Sites 模块实施了严密的三级准入控制。只有同时满足以下三项条件,用户才能在项目中创建和部署站点:
| 准入层级 | 配置项或检验维度 | 详细判定规则与不满足时的系统行为 |
|---|---|---|
| 第一层:实例部署开关 | _APP_SITES_ENABLED | 应用代码将 enabled 视为开启,未配置时默认 enabled;disabled 等其他值不会开启。实际部署可能显式覆盖。Console 侧栏还结合当前用户的邮箱白名单判断。 |
| 第二层:能力邮箱白名单 | 实例级 Sites 允许名单(Email Allowlist) | • 若白名单配置为空:Sites 能力对所有用户关闭(Fail-Closed); • 若白名单非空:系统会严格校验请求方身份对应的邮箱是否在白名单内——包括:① 当前 Console 登录会话用户的邮箱;② 账号级 API Key 所属用户的邮箱;或 ③ 项目/组织 API Key 所属团队中已确认(Confirmed)的组织 Owner 邮箱。 • 若不满足白名单条件,请求将直接失败并返回明确权限报错。 |
| 第三层:项目写权限 | sites.write | 操作成员在当前项目所属组织中必须具备写角色(owner、admin、developer 或 editor);组织 billing、analyst 默认不含 projects.read,自托管时不能仅凭这些角色进入项目。 |
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.12.0 或 agentbase-web-sdk@2.12.0 直接调用同项目的 Auth、Databases、智能体接口与 Functions | 为站点前端提供受保护的后端定制业务逻辑、第三方 Webhook 回调处理与异步批处理 |
角色、入口与关联关系
1. 控制台导航路径与子页签结构
列表页入口:进入项目控制台后,在左侧导航栏点击 站点(路径
/console/project-{region}-{project}/sites)。在列表页直接按键盘快捷键C或点击右上角 创建站点 即可启动站点创建向导(/sites/create-site)。站点详情页六大页签(路径前缀
/console/project-{region}-{project}/sites/site-{site}):概览(
.../site-{site}):展示当前线上活动部署卡片、访问链接(访问)、一键回滚按钮(即时回滚)及实时构建状态提示。部署(
.../deployments):管理历史与进行中的全部部署版本,支持新建部署、取消构建、重新部署与删除部署。日志(
.../logs):查看站点构建日志与运行时日志。域名(
.../domains):管理站点自定义域名、预览域名与 SSL 证书签发状态。用量(
.../usage):查看该站点的请求与带宽消耗趋势。设置(
.../settings):维护站点名称、Git 仓库绑定、构建命令、运行时规格、站点级环境变量、超时时间、日志开关与删除站点(Danger zone)。
2. 与项目全局变量(Global Variables)及平台登记(Platforms)的关联
环境变量合并注入:项目 设置 → 概览 → 全局变量 中配置的全部变量会自动注入到每一个 Site 的构建与运行环境中;同时你还可以在站点的 设置 页配置仅对该站点生效的站点作用域环境变量(构建时也可从关联的 Git 仓库自动预填环境变量)。
与前端 SDK 跨域协同:当托管在 Sites 上的前端页面通过浏览器调用同项目的 Agentbase Client API 时,请确保该站点的分配域名或自定义域名已登记在项目 概览 → 集成 → 平台(Web 平台 Hostname)中。
功能详解与操作指南
1. 创建并部署第一个站点(三种接入方式详解)
在 Sites 列表页点击 创建站点(或按快捷键 C),根据团队代码管理方式选择以下任一路径:
方式一:连接 Git 仓库(Connect Git Repository,生产推荐)
选择 连接 Git 仓库。若当前项目尚未关联 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 自动识别或手动下拉选择 | 例如填写名称 企业智能客服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)。 |
| 构建命令 | 默认 npm run build | 生产构建命令;运行身份取决于执行器和部署配置。 | |
| 输出目录 | 默认 dist(随框架预设自动调整) | 构建产物输出目录(如 Vite/Vue 通常为 dist,Next.js/SvelteKit 按各自适配器目录设置)。 | |
| 4. Environment variables | 键值对列表(Key / Value) | 支持从仓库预填或手动添加 | 例如填入 PUBLIC_AGENTBASE_ENDPOINT=<APPBASE_ENDPOINT_WITH_V1> 与 PUBLIC_AGENTBASE_PROJECT_ID=<APPBASE_PROJECT_ID>。 |
| 5. Domain(站点域名) | Subdomain(站点子域名) | 全局唯一合法子域名前缀 | 系统为站点分配的默认访问子域名。 |
| 6. 提交构建 | 部署 按钮 | 提交后自动跳转构建等待页 | 构建完成前等待页会实时自动刷新进度,就绪后即可点击 访问 访问站点。 |
2. 日常发版、状态监控与一键秒级回滚(Instant Rollback)
触发新版本部署:
在站点详情页切换到 部署 页签,点击 Create deployment。
支持选择 Git(推荐,拉取最新分支提交构建)、CLI(通过命令行工具发布) 或 Manual(上传新
.tar.gz包)。
处理配置变更未生效提示:
当你在站点 设置 页修改了构建命令、Output 目录、运行时规格或站点环境变量后,旧的活动部署不会自动改变;页面顶部会显示醒目的黄色警示横幅,直接点击横幅上的 重新部署 按钮即可基于新配置重新构建并上线。
执行线上紧急回滚(两种方式):
方式 A(Overview 页 Instant rollback):当新上线的部署出现前端白屏或样式错乱时,进入站点 概览 页签,在当前活动部署卡片上直接点击 即时回滚(该按钮仅在存在状态为
ready且历史上曾被激活过的旧部署时可用),一键切回上一个稳定版本。方式 B(Deployments 列表精准切换):进入 部署 页签,在历史列表中找到任意状态为
ready的目标部署版本,点击激活将其设为当前活动部署。
取消与删除部署:
对正在构建中的任务可点击 取消 终止;对不再需要的历史部署可点击 删除 清理(删除操作不可恢复;若尝试删除当前正在服务的活动部署,系统会弹出额外的高危确认提示)。
3. 绑定站点自定义域名与管理站点设置
绑定自定义域名(Domains 页签):
进入站点详情 域名 页签,点击添加自定义域名(如
chat.enterprise.example.com)。按照界面提示在企业 DNS 中配置指向记录,并在域名列表中观察 SSL 证书状态;若证书生成失败(
Certificate generation failed),排查 DNS 生效后点击重试(Retry)即可。
调整运行时规格与危险区销毁(Settings 页签):
在 设置 页签中,可随时更新站点名称、断开或重连 Git 仓库(Disconnect repository)、调整构建与运行时资源规格、修改执行超时(Timeout)及日志采集开关。
如需彻底下线某个测试站点,滚动至底部 危险区域 点击 删除站点,完成二次确认后将永久删除该站点及其下属的全部历史部署产物(不可撤销),并自动返回 Sites 列表页。
常见问题与排障
Q1:项目左侧边栏显示了 Sites 入口,为什么我点击 Create site 提交时却直接报错失败,提示无权限使用 Sites?
原因与排查步骤: 侧栏入口取决于实例开关和当前登录用户的 Sites 邮箱白名单;提交请求时还会按实际调用身份、当前配置及权限重新校验。如果入口显示但操作失败,请检查以下条件:
若平台管理员尚未配置邮箱白名单(名单为空),Sites 功能对所有用户处于关闭状态。
若白名单非空,系统会检查你的当前登录账号邮箱(或使用项目/组织 API Key 调用时,该项目所属组织中已确认的 Owner 邮箱)是否在白名单内。请联系平台管理员将你的开发者邮箱及组织 Owner 邮箱加入实例的 Sites 允许名单中。
Q2:为什么站点 Overview 页面上的“Instant rollback(一键回滚)”按钮是置灰不可点的?
原因与排查步骤: 即时回滚 要求当前站点下至少存在一个除当前活动部署之外、构建状态为 ready 且历史上曾经被激活上线过的旧部署版本。如果该站点刚刚创建只有第 1 个部署版本,或者之前的部署全部为 failed(从未成功激活上线过),则没有合法的回滚目标,按钮会自动禁用。
Q3:站点构建日志报错权限拒绝(Permission denied)或无法访问内网地址是什么原因?
原因与排查步骤: 排查时区分执行器身份与网络配置:
运行身份与权限:ACS E2B 和 OpenSandbox 的受限执行路径会检查非 root 身份与权限,检查失败时拒绝该路径执行。其他执行器应核实实际运行身份。请检查
Install command、Build command和脚本对可写目录及权限的要求;具体命令失败后的行为取决于运行环境和脚本。构建与运行网络:构建或 SSR 运行期间的出站访问取决于执行环境与网络策略。请在目标环境核实回环、私网和云元数据地址的访问限制,不要假定所有请求均由同一 SSRF 守卫拦截。