Sites
Sites is a fully managed frontend and full-stack web application hosting service provided by Agentbase, supporting mainstream frameworks such as Next.js, SvelteKit, React, Vue, Nuxt, and Astro. With Sites, development teams can clone directly from official templates, connect GitHub repositories, or manually upload .tar.gz source packages to complete automated cloud builds and deployments, and within the same project context manage multi-version deployments, one-click rollback, build and runtime logs, custom domain SSL certificates, and site-level environment variables.
Feature Overview
When building enterprise customer service portals, internal knowledge base retrieval sites, or agent conversation web frontends (such as the frontend portal of project 企业智能客服与知识中台 enterprise-ai-hub-210), traditional approaches require separately purchasing static hosting or container clusters, individually configuring CI/CD build pipelines, manually applying for HTTPS certificates, and configuring cross-origin whitelists.
Agentbase Sites deeply integrates frontend/full-stack application hosting within the Project resource boundary, providing four core capabilities:
Three access sources with framework-adaptive builds: Supports cloning from a curated template library, connecting a GitHub repository (automatically detecting branches and commits), or manually dragging and uploading a
.tar.gzsource package, automatically matching build commands and output directories for frameworks such as Next.js and SvelteKit.Zero-downtime deployment and one-click Instant Rollback: Each build generates an independent Deployment version; from the site overview page, Instant rollback allows you to switch back with one click to any previously activated historical stable version whose status is
ready.Dual-layer security admission and restricted identity execution: Controlled by a dual gate consisting of the instance-level switch
_APP_SITES_ENABLEDand the capability email allowlist; build and SSR runtime identity and network restrictions depend on the executor and deployment configuration.Custom domain automation and same-origin context injection: Preview domains are automatically assigned and enterprise custom domains can be bound (with automatic SSL certificate issuance); project-level Global variables and site-specific environment variables are automatically injected at build and runtime.
| Core management dimension | Console tab location | Core feature characteristics | Risks and security boundaries |
|---|---|---|---|
| Site overview and quick rollback | Overview | View the current active deployment, click Visit to access the live site, click Instant rollback for one-click rollback | Only deployments already in ready status that were historically activated can serve as one-click rollback targets |
| Deployments pipeline | Deployments | Create new deployments via Git (recommended) / CLI / Manual; supports Cancel / Redeploy / Delete and viewing build metrics | An additional high-risk warning appears when deleting the active deployment currently serving live traffic |
| Build and runtime logs (Logs) | Logs | View build output and SSR runtime logs | On build failure, inspect recorded output; logs may be truncated or missing due to the execution path |
| Domains and certificates (Domains) | Domains | Manage default subdomains, preview domains, and enterprise custom domains; view SSL certificate issuance status and support retry on failure | Custom domains require DNS records to be pointed correctly before certificates can be successfully issued |
| Site settings and destruction (Settings) | Settings · Usage | Modify build commands, Root/Output directories, site-level environment variables, compute specs, Timeout, and Danger zone site deletion | Delete site permanently destroys the site and all its historical deployment records; this cannot be undone |
Core Concepts and Architecture
1. Sites capability enablement conditions and email allowlist validation rules (key points)
Because frontend and full-stack site builds consume cloud build compute and public network egress resources, Agentbase enforces strict three-level admission control on the Sites module. Only when all three of the following conditions are met can a user create and deploy sites in a project:
| Admission level | Configuration item or validation dimension | Detailed rules and system behavior when not satisfied |
|---|---|---|
| Level One: instance deployment switch | _APP_SITES_ENABLED | Application code treats enabled as on and defaults to enabled when unset; other values, including disabled, do not enable it. A deployment may explicitly override this. The Console sidebar also checks the current user's email allowlist. |
| Level Two: capability email allowlist | Instance-level Sites Email Allowlist | • If the allowlist is empty: the Sites capability is disabled for all users (Fail-Closed); • If the allowlist is non-empty: the system strictly verifies whether the email corresponding to the requester's identity is on the allowlist—including: ① the email of the user currently signed in to the Console session; ② the email of the user owning the account-level API Key; or ③ the confirmed (Confirmed) organization Owner email within the team owning the project/organization API Key. • If the allowlist condition is not met, the request will fail immediately and return an explicit permission error. |
| Level Three: project write permission | sites.write | The operating member must hold a write role (owner, admin, developer, or editor) in the organization the project belongs to; organization billing and analyst lack projects.read by default and cannot enter the project on those roles alone in self-hosted deployments. |
2. Architectural division of labor: Sites versus Functions
Within the same project (e.g. enterprise-ai-hub-210), Sites and Functions use their configured executors and project global variables, but each plays a distinct architectural role:
| Comparison dimension | Sites | Functions |
|---|---|---|
| Core positioning | Frontend/full-stack web site hosting and domain delivery for end-user browsers | Event-driven, scheduled task, and API microservice computing for backend logic |
| Typical technology stacks | Next.js, SvelteKit, React, Vue, Nuxt, static HTML/JS/CSS artifacts | Node.js, Python, java-17.0 (supports prebuilt JARs), Go, PHP, Deno |
| Access and trigger methods | Users directly access the site's subdomain or custom HTTPS domain via browser | Triggered via SDK executions endpoints, internal database/storage Events, or Cron schedules |
| How they work together | The site frontend directly calls the same project's Auth, Databases, agent endpoints, and Functions via @alipay/agentbase-web-sdk@2.12.0 or agentbase-web-sdk@2.12.0 | Provides the site frontend with protected custom backend business logic, third-party Webhook callback handling, and asynchronous batch processing |
Roles, Entry Points, and Relationships
1. Console navigation path and sub-tab structure
List page entry: After entering the project Console, click Sites in the left navigation bar (path
/console/project-{region}-{project}/sites). On the list page, press the keyboard shortcutCor click Create site in the top-right corner to launch the site creation wizard (/sites/create-site).Six tabs of the site details page (path prefix
/console/project-{region}-{project}/sites/site-{site}):Overview (
.../site-{site}): Displays the current live active deployment card, the access link (Visit), the one-click rollback button (Instant rollback), and real-time build status indicators.Deployments (
.../deployments): Manages all historical and in-progress deployment versions; supports creating deployments, canceling builds, redeploying, and deleting deployments.Logs (
.../logs): View site build logs and runtime logs.Domains (
.../domains): Manage site custom domains, preview domains, and SSL certificate issuance status.Usage (
.../usage): View request and bandwidth consumption trends for the site.Settings (
.../settings): Maintain the site name, Git repository binding, build commands, runtime specs, site-level environment variables, timeout, log toggles, and site deletion (Danger zone).
2. Relationship with project Global Variables and Platforms
Merged environment variable injection: All variables configured in the project's Settings → Overview → Global variables are automatically injected into every Site's build and runtime environment; additionally, you can configure site-scoped environment variables that apply only to that site on the site's Settings page (environment variables can also be auto-prefilled from the linked Git repository at build time).
Cross-origin coordination with the frontend SDK: When frontend pages hosted on Sites call the same project's Agentbase Client API from the browser, make sure the site's assigned domain or custom domain is registered under the project's Overview → Integrations → Platforms (Web platform Hostname).
Feature Details and Operation Guide
1. Creating and deploying your first site (three access methods explained)
On the Sites list page, click Create site (or press the shortcut C), then choose one of the following paths depending on how your team manages code:
Method One: Connect Git Repository (recommended for production)
Select Connect Git repository. If the current project is not yet linked to a GitHub App, follow the on-screen guidance to complete GitHub authorization and installation first (connections can also be managed in the project's Settings → Git).
Select the target frontend code repository and production branch (e.g.
main) from the authorized list, then click to enter the Deploy site (deployment configuration) page.
Method Two: Clone from Official Templates (Clone Template, quick start)
Select Clone template. The template library supports filtering by Use case (business scenario, e.g. AI Chat, Starter, Dashboard) or Framework (frontend framework, e.g. Next.js, SvelteKit, Vue).
After selecting a template, you enter the deployment configuration page, where the system automatically fills in the full set of build commands and environment variables required by the template.
Method Three: Manual Upload (Manual Upload, offline/intranet delivery)
Select Manual, package your local frontend project source code into a
.tar.gzformat archive (package size is constrained by the current plan and instance configuration limits), then drag and drop or select the file to upload and enter the deployment configuration page.
Filling In the Deployment Configuration Parameters Table (Deploy Site)
In the deployment configuration wizard, verify the parameters and submit according to the 6 sections from top to bottom:
| Configuration section | Core field name | Default value / format constraint | Filling instructions and production recommendations |
|---|---|---|---|
| 1. Details (basic information) | Name / Site ID ($id) / Framework / execution plan | Framework is auto-detected or selected manually from a dropdown | For example, enter the name 企业智能客服Web工作台, set a custom Site ID of enterprise-support-portal, and choose framework Next.js or SvelteKit. |
| 2. Git configuration | Root directory | Default ./ | If the frontend project is in a subdirectory of a Monorepo repository (e.g. ./apps/web-portal), enter the relative subdirectory path here. |
| 3. Build configuration | Install command | Default npm install | Dependency installation command (if using pnpm or yarn, change to pnpm install / yarn install). |
| Build command | Default npm run build | Production build command; runtime identity depends on the executor and deployment configuration. | |
| Output directory | Default dist (automatically adjusted per framework preset) | Build artifact output directory (e.g. typically dist for Vite/Vue; Next.js/SvelteKit follow their respective adapter directories). | |
| 4. Environment variables | Key-value pair list (Key / Value) | Supports pre-filling from the repository or manual addition | For example, enter PUBLIC_AGENTBASE_ENDPOINT=<APPBASE_ENDPOINT_WITH_V1> and PUBLIC_AGENTBASE_PROJECT_ID=<APPBASE_PROJECT_ID>. |
| 5. Domain (site domain) | Subdomain (site subdomain) | Globally unique valid subdomain prefix | The default access subdomain assigned to the site by the system. |
| 6. Submit build | Deploy button | After submission, automatically redirects to the build waiting page | The waiting page refreshes progress in real time until the build is complete; once ready, click Visit to access the site. |
2. Daily Releases, Status Monitoring, and One-Click Instant Rollback
Trigger a new version deployment:
Switch to the Deployments tab on the site details page and click Create deployment.
You can choose Git (recommended, pulls the latest branch commit for building), CLI (publish via command-line tool), or Manual (upload a new
.tar.gzpackage).
Handling the configuration-change-not-applied notice:
After you modify the build command, Output directory, runtime spec, or site environment variables on the site Settings page, the previous active deployment does not change automatically; a prominent yellow warning banner appears at the top of the page. Simply click the Redeploy button on the banner to rebuild and go live based on the new configuration.
Perform an emergency rollback in production (two methods):
Method A (Instant rollback on the Overview page): when a newly deployed version shows a frontend white screen or style issues, go to the site Overview tab and click Instant rollback directly on the current active deployment card (this button is only available when an old deployment with status
readyexists that has been activated before), switching back to the previous stable version in one click.Method B (precise switching in the Deployments list): go to the Deployments tab, find the target deployment version with status
readyin the history list, and click activate to set it as the current active deployment.
Canceling and deleting deployments:
For tasks currently building, click Cancel to terminate; for historical deployments no longer needed, click Delete to clean up (deletion is irreversible; if you attempt to delete the currently serving active deployment, an additional high-risk confirmation prompt appears).
3. Binding a Custom Domain and Managing Site Settings
Bind a custom domain (Domains tab):
Go to the site details Domains tab and click to add a custom domain (e.g.
chat.enterprise.example.com).Configure the pointing records in your enterprise DNS as prompted by the interface, and monitor the SSL certificate status in the domain list; if certificate generation fails (
Certificate generation failed), troubleshoot DNS propagation and click Retry.
Adjusting runtime spec and danger zone destruction (Settings tab):
In the Settings tab, you can update the site name at any time, disconnect or reconnect the Git repository (Disconnect repository), adjust build and runtime resource specs, and modify execution timeout (Timeout) and log collection toggles.
To fully take a test site offline, scroll to the bottom Danger zone and click Delete site; after completing the secondary confirmation, the site and all of its historical deployment artifacts are permanently deleted (irreversible), and you are automatically returned to the Sites list page.
FAQ and Troubleshooting
Q1: The project sidebar shows the Sites entry; why does clicking Create site to submit fail immediately with an error saying I have no permission to use Sites?
Cause and troubleshooting steps: The sidebar reflects the instance switch and current signed-in user's Sites email allowlist; a submitted request is also checked against its actual caller, current configuration, and permissions. If the entry is visible but an operation fails, check the following:
If the platform administrator has not configured an email allowlist (the list is empty), the Sites feature is disabled for all users.
If the allowlist is not empty, the system checks whether your current login account email (or, when called with a project/organization API Key, the confirmed Owner email of the organization the project belongs to) is on the allowlist. Please contact the platform administrator to add your developer email and organization Owner email to the instance's Sites allowlist.
Q2: Why is the "Instant rollback" button on the site Overview page grayed out and unclickable?
Cause and troubleshooting steps: Instant rollback requires that the current site has at least one old deployment version, besides the current active deployment, whose build status is ready and that has been activated and gone live before. If the site was just created and only has the 1st deployment version, or all previous deployments are failed (never successfully activated and gone live), there is no valid rollback target and the button is automatically disabled.
Q3: Why does the site build log report Permission denied or inability to access intranet addresses?
Cause and troubleshooting steps: Investigate executor identity and network configuration separately:
Runtime identity and permissions: the restricted execution paths for ACS E2B and OpenSandbox check non-root identity and privileges and reject that path if the check fails. Verify the actual identity for other executors. Check
Install command,Build command, and scripts for writable-directory and permission requirements; failure behavior depends on the runtime and script.Build and runtime networking: outbound access during build or SSR depends on the execution environment and network policy. Verify loopback, private-network, and cloud-metadata restrictions in the target deployment; do not assume a single SSRF guard covers all requests.