Docs
文档目录

站点

站点(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 资源边界内,提供四大核心能力:

  1. 三源接入与框架自适应构建:支持从精选模板库克隆(Clone template)、连接 GitHub 仓库(自动识别分支与提交)或手动拖拽上传 .tar.gz 源码包,自动匹配 Next.js、SvelteKit 等框架的构建命令与产物目录。

  2. 零停机发布与一键回滚(Instant Rollback):每次构建生成独立的 Deployment 版本;支持在站点概览页通过 即时回滚 一键切回任意曾激活且状态为 ready 的历史稳定版本。

  3. 双层安全准入与受限身份运行:由实例级开关 _APP_SITES_ENABLED 与能力白名单(邮箱白名单)双重门禁管控;构建与 SSR 的运行身份和网络限制取决于实际执行器及部署配置。

  4. 自有域名自动化与同源上下文注入:自动分配预览域名并支持绑定企业自定义域名(自动签发 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. 控制台导航路径与子页签结构

  1. 列表页入口:进入项目控制台后,在左侧导航栏点击 站点(路径 /console/project-{region}-{project}/sites)。在列表页直接按键盘快捷键 C 或点击右上角 创建站点 即可启动站点创建向导(/sites/create-site)。

  2. 站点详情页六大页签(路径前缀 /console/project-{region}-{project}/sites/site-{site}):

    • 概览(.../site-{site}):展示当前线上活动部署卡片、访问链接(访问)、一键回滚按钮(即时回滚)及实时构建状态提示。

    • 部署(.../deployments):管理历史与进行中的全部部署版本,支持新建部署、取消构建、重新部署与删除部署。

    • 日志(.../logs):查看站点构建日志与运行时日志。

    • 域名(.../domains):管理站点自定义域名、预览域名与 SSL 证书签发状态。

    • 用量(.../usage):查看该站点的请求与带宽消耗趋势。

    • 设置(.../settings):维护站点名称、Git 仓库绑定、构建命令、运行时规格、站点级环境变量、超时时间、日志开关与删除站点(Danger zone)。

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

功能详解与操作指南

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

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

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

  1. 选择 连接 Git 仓库。若当前项目尚未关联 GitHub App,按界面引导先完成 GitHub 授权安装(也可在项目 Settings → Git 管理连接)。

  2. 从已授权列表中选择目标前端代码仓库与生产分支(如 main),点击进入 Deploy site(部署配置) 页面。

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

  1. 选择 Clone template,在模板库中支持按 Use case(业务场景,如 AI Chat、Starter、Dashboard) 或 Framework(前端框架,如 Next.js、SvelteKit、Vue) 筛选。

  2. 选中模板后进入部署配置页,系统会自动填充该模板所需的全套构建命令与环境变量。

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

  1. 选择 Manual,将本地前端工程源码打包为 .tar.gz 格式压缩包(包大小受当前套餐与实例配置上限约束),拖拽或选择文件上传后进入部署配置页。

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

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

配置区块核心字段名称默认值 / 格式约束填写说明与生产建议
1. Details(基本信息)Name / Site ID ($id) / 框架 / 执行计划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)。
构建命令默认 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)

  1. 触发新版本部署:

    • 在站点详情页切换到 部署 页签,点击 Create deployment。

    • 支持选择 Git(推荐,拉取最新分支提交构建)、CLI(通过命令行工具发布) 或 Manual(上传新 .tar.gz 包)。

  2. 处理配置变更未生效提示:

    • 当你在站点 设置 页修改了构建命令、Output 目录、运行时规格或站点环境变量后,旧的活动部署不会自动改变;页面顶部会显示醒目的黄色警示横幅,直接点击横幅上的 重新部署 按钮即可基于新配置重新构建并上线。

  3. 执行线上紧急回滚(两种方式):

    • 方式 A(Overview 页 Instant rollback):当新上线的部署出现前端白屏或样式错乱时,进入站点 概览 页签,在当前活动部署卡片上直接点击 即时回滚(该按钮仅在存在状态为 ready 且历史上曾被激活过的旧部署时可用),一键切回上一个稳定版本。

    • 方式 B(Deployments 列表精准切换):进入 部署 页签,在历史列表中找到任意状态为 ready 的目标部署版本,点击激活将其设为当前活动部署。

  4. 取消与删除部署:

    • 对正在构建中的任务可点击 取消 终止;对不再需要的历史部署可点击 删除 清理(删除操作不可恢复;若尝试删除当前正在服务的活动部署,系统会弹出额外的高危确认提示)。

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

  1. 绑定自定义域名(Domains 页签):

    • 进入站点详情 域名 页签,点击添加自定义域名(如 chat.enterprise.example.com)。

    • 按照界面提示在企业 DNS 中配置指向记录,并在域名列表中观察 SSL 证书状态;若证书生成失败(Certificate generation failed),排查 DNS 生效后点击重试(Retry)即可。

  2. 调整运行时规格与危险区销毁(Settings 页签):

    • 在 设置 页签中,可随时更新站点名称、断开或重连 Git 仓库(Disconnect repository)、调整构建与运行时资源规格、修改执行超时(Timeout)及日志采集开关。

    • 如需彻底下线某个测试站点,滚动至底部 危险区域 点击 删除站点,完成二次确认后将永久删除该站点及其下属的全部历史部署产物(不可撤销),并自动返回 Sites 列表页。

常见问题与排障

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

原因与排查步骤: 侧栏入口取决于实例开关和当前登录用户的 Sites 邮箱白名单;提交请求时还会按实际调用身份、当前配置及权限重新校验。如果入口显示但操作失败,请检查以下条件:

  1. 若平台管理员尚未配置邮箱白名单(名单为空),Sites 功能对所有用户处于关闭状态。

  2. 若白名单非空,系统会检查你的当前登录账号邮箱(或使用项目/组织 API Key 调用时,该项目所属组织中已确认的 Owner 邮箱)是否在白名单内。请联系平台管理员将你的开发者邮箱及组织 Owner 邮箱加入实例的 Sites 允许名单中。

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

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

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

原因与排查步骤: 排查时区分执行器身份与网络配置:

  1. 运行身份与权限:ACS E2B 和 OpenSandbox 的受限执行路径会检查非 root 身份与权限,检查失败时拒绝该路径执行。其他执行器应核实实际运行身份。请检查 Install command、Build command 和脚本对可写目录及权限的要求;具体命令失败后的行为取决于运行环境和脚本。

  2. 构建与运行网络:构建或 SSR 运行期间的出站访问取决于执行环境与网络策略。请在目标环境核实回环、私网和云元数据地址的访问限制,不要假定所有请求均由同一 SSRF 守卫拦截。

相关文档