diff --git a/en/deploy/architecture.mdx b/en/deploy/architecture.mdx
index 5cb79e9..8699a3e 100644
--- a/en/deploy/architecture.mdx
+++ b/en/deploy/architecture.mdx
@@ -1,15 +1,26 @@
---
title: "Architecture"
-description: "What a self-hosted Teable deployment runs: the app, its data services, and the runtime plane behind AI sessions, App Builder, and deployed apps."
+description: "Deploying Teable gives you four platforms in one: a secure agent sandbox, a resource-efficient app deployment platform, an AI workflow engine, and a full-featured collaboration platform on PostgreSQL."
---
-Teable is an AI product: **AI Chat**, **App Builder**, and **app deployments**
-are part of the platform, not bolt-ons. A self-hosted deployment therefore
-runs the Teable app and its data services together with the **runtime plane**
-that powers those AI features. This page explains how the pieces fit
-together. The deployable assets (compose files, Helm chart, values) live in
-[teableio/teable-deployment](https://github.com/teableio/teable-deployment) and
-are the single source of truth — nothing on this page needs to be copied.
+Self-hosting Teable deploys four platforms in one:
+
+- **A secure, scalable agent sandbox** — every AI session runs in its own
+ isolated container, started on demand and gone when the session ends.
+- **A resource-efficient app deployment platform** — every app your team
+ builds and publishes runs as its own lightweight, long-lived container.
+- **An AI workflow engine** — automations triggered by record changes,
+ schedules, and webhooks, with AI steps, running right where your data lives.
+- **A full-featured database collaboration platform on PostgreSQL** — tables,
+ views, and API.
+
+Self-hosting Teable wraps your own compute into an **agent-ready, fully
+controlled productivity environment** — putting AI in the hands of everyone
+on your team.
+
+This page explains the services behind this and how they fit together. The
+deployable assets (compose files, Helm chart, values) live in
+[teableio/teable-deployment](https://github.com/teableio/teable-deployment).
AI features are available for self-hosted Business plan and above.
@@ -18,16 +29,16 @@ are the single source of truth — nothing on this page needs to be copied.
| Service | Purpose |
|---|---|
| **Teable app** | Web UI, API, automations, AI chat — a single image: `ghcr.io/teableio/teable` |
-| **PostgreSQL** | The system of record: tables, views, metadata |
+| **PostgreSQL** | The main database: all your tables, views, and metadata |
| **Redis** | Cache, queues, realtime collaboration |
-| **Object storage** | S3-compatible, three buckets: **public** (avatars and public assets), **private** (attachments), **build artifacts** (App Builder output) |
-| **Infra Service** | Console + API — the one door the Teable app talks to; orchestrates builds and app deployments |
-| **Sandbox engine** | Runs every AI session inside an isolated sandbox container |
-| **Git registry** | Source of truth for the apps you build (App Builder pushes here) |
-| **Preview gateway** | Serves sandbox previews and deployed apps in the browser |
+| **Object storage** | S3-compatible file storage with three buckets: **public** (avatars and other public assets), **private** (attachments), **build artifacts** (App Builder output) |
+| **Infra Service** | The single entry point the Teable app connects to; coordinates builds and app deployments, with its own console and API |
+| **Sandbox engine** | Runs every AI session in its own isolated container |
+| **Git registry** | Stores the source code of the apps you build (App Builder pushes here) |
+| **Preview gateway** | Routes browsers to sandbox previews and deployed apps |
-The last four services form the **runtime plane**; the deployment assets set
-all of this up as one platform.
+The last four make up the runtime plane. The deployment assets install all of
+this as one platform.
## How it fits together
@@ -66,62 +77,58 @@ graph LR
style A fill:#F59E0B,stroke:#b45309,color:#fff
```
-The Teable app reaches the runtime plane through **one connection**: the Infra
-Service (`TEABLE_INFRA_API_URL` / `TEABLE_INFRA_API_KEY`); everything behind it
-is internal. What the plane actually runs is two kinds of workload:
-
-- **Sandboxes** — every AI chat or App Builder session gets its own isolated
- container, started on demand and destroyed when the session ends. This is
- the dominant, bursty load: size your machine by **peak concurrent AI
- sessions**, not by user count (per-sandbox limits are configurable in the
- admin panel).
-- **Deployed apps** — every app someone ships runs as its own long-lived
- container behind `*.app.`. Sandboxes come and go; deployed apps
- accumulate and keep serving.
-
-The rest is plumbing: building happens inside the session's sandbox, the git
-registry and object storage persist what it produces (source and build
-artifacts), and the gateway routes browsers to the right sandbox or app.
+The Teable app talks to the runtime plane through **one connection**: the
+Infra Service (`TEABLE_INFRA_API_URL` / `TEABLE_INFRA_API_KEY`). Everything
+behind it is internal. Two kinds of workload do the real work — and they are
+what consume your machine:
+
+- **Sandboxes.** Every AI chat or App Builder session gets its own isolated
+ container, started when the session begins and removed when it ends. This
+ is the platform's main load, and it arrives in bursts: size your machine by
+ **peak concurrent AI sessions**, not by user count (per-sandbox resource
+ limits can be set in the admin panel).
+- **Deployed apps.** Every app someone publishes runs as its own long-lived
+ container, served at `*.app.`. Sandboxes come and go; deployed apps
+ add up and keep running.
+
+The other services play supporting roles: building happens inside the
+session's sandbox, the git registry and object storage keep what it produces
+(source code and build artifacts), and the gateway routes each browser
+request to the right sandbox or app.
## One domain, four DNS records
-Everything hangs off **one base domain** — typically a subdomain of yours, such
-as `teable.example.com`:
+Everything is served under **one base domain** — typically a subdomain of
+yours, such as `teable.example.com`:
| Record | Serves |
|---|---|
| `` | The Teable app |
-| `infra.` | Infra console + API — git (`/git`) and object storage (bucket paths) ride this host as paths |
+| `infra.` | The Infra Service console and API; git (`/git`) and object storage are also served from paths on this host |
| `*.app.` | Apps you built and deployed |
| `*.sandbox.` | Sandbox previews in the browser |
-Each name is only a default; every hostname can be overridden individually
+Each name is only a default, and every hostname can be overridden individually
(see the values example in the deployment repository).
-## How the agent stays in sync with the app
-
-The sandbox agent image is configured as a **prefix without a tag**. The Teable
-app appends **its own release tag** when launching AI sessions, so the agent
-always matches the app version — and the app preheats that exact image through
-the Infra Service, so the first session doesn't wait on a multi-gigabyte pull.
-You never pull or pin the agent manually.
-
## Versioning
The platform ships as **platform releases** (`v..`) of the
deployment repository:
-- A **tag** is a verified snapshot: `versions.yaml` pins every component image
- (with digests), and the repository's `CHANGELOG.md` says what changed and
- what, if anything, you must do.
-- The repository's `main` is the rolling latest.
-- The bundled **doctor** scripts compare what your deployment actually runs
- against the release manifest and report one of three states: compatible,
- upgrade the Teable app, or an unknown (unverified) combination.
+- A release **tag** is a verified snapshot: `versions.yaml` locks the exact
+ version of every component, and the repository's `CHANGELOG.md` says what
+ changed and what, if anything, you must do.
+- The repository's `main` branch is the rolling latest.
+- The bundled **doctor** script compares what your deployment actually runs
+ against the release and reports one of three results: compatible, upgrade
+ the Teable app, or an unknown (unverified) combination.
The Teable app has its own release line (date-based tags; `latest` is the
-stable channel) — see [Version Upgrade](/en/deploy/upgrade). Platform releases
-declare the app compatibility window; the doctor checks it for you.
+stable channel) — see [Version Upgrade](/en/deploy/upgrade). Each platform
+release states which app versions it has been verified with, and the doctor
+checks this for you. The sandbox agent behind AI sessions always follows the
+app's version on its own — there is nothing extra to upgrade or manage.
## Deploy it
@@ -133,26 +140,27 @@ deployment repository:
Everything on one machine — first full deployment, `local` or `server` mode.
- One umbrella chart on an existing cluster; only `global.baseDomain` is required.
+ A single Helm chart on an existing cluster; only `global.baseDomain` is required.
-Don't need AI? You can run just the app with PostgreSQL, Redis, and storage —
-a **standalone** deployment ([Docker Deployment](/en/deploy/docker)) — and
-attach the runtime plane later with your data in place.
+Don't need AI yet? You can run just the app with PostgreSQL, Redis, and
+storage — a **standalone** deployment ([Docker Deployment](/en/deploy/docker))
+— and attach the runtime plane later with your data in place.
Related topics, all maintained in the deployment repository:
-- **Already running standalone Teable?** Your data stays in place — the runtime
- plane attaches next to it: [migration guide](https://github.com/teableio/teable-deployment/blob/main/migration/2026-07-basic-to-full-featured.md)
-- **Private / corporate CA**: sandboxes must trust the CA your entry serves —
+- **Already running standalone Teable?** Your data stays in place — the
+ runtime plane installs next to it: [migration guide](https://github.com/teableio/teable-deployment/blob/main/migration/2026-07-basic-to-full-featured.md)
+- **Company-internal certificates?** If your domain uses a private or
+ corporate CA, sandboxes need to be told to trust it —
[private-ca.md](https://github.com/teableio/teable-deployment/blob/main/helm/private-ca.md)
- **Sizing, versions and mirrors**: [VERSIONS.md](https://github.com/teableio/teable-deployment/blob/main/VERSIONS.md) ·
[images/README.md](https://github.com/teableio/teable-deployment/blob/main/images/README.md)
- **When something fails**: run the doctor first, then
[TROUBLESHOOTING.md](https://github.com/teableio/teable-deployment/blob/main/TROUBLESHOOTING.md)
-After deploying, connect your Teable app to the runtime plane with
+After deploying, connect the Teable app to the runtime plane with
`TEABLE_INFRA_API_URL` / `TEABLE_INFRA_API_KEY` (the deployment guides cover
-this), then configure limits in
+this), then set resource limits in
[Admin Panel → Sandbox Agent](/en/basic/admin-panel/sandbox-agent).
diff --git a/zh/deploy/architecture.mdx b/zh/deploy/architecture.mdx
index 78953fb..c1ee868 100644
--- a/zh/deploy/architecture.mdx
+++ b/zh/deploy/architecture.mdx
@@ -1,31 +1,42 @@
---
title: "架构"
-description: "私有化部署的 Teable 由什么组成:应用与数据服务,以及支撑 AI 会话、App Builder 与应用部署的运行平面。"
+description: "部署一套 Teable = 同时得到四个平台:安全的 agent 沙箱、资源利用率极高的应用部署平台、AI 工作流引擎、基于 PostgreSQL 的全功能协作平台。"
---
-Teable 本身就是 AI 产品:**AI Chat**、**App Builder** 与**应用部署**是平台的
-一部分,不是外挂。因此一套私有化部署,除了 Teable 应用与它的数据服务,还包括
-支撑这些 AI 能力的**运行平面**。本页讲各部分如何协同;可部署资产(compose、
-Helm chart、values)全部在
+私有化部署一套 Teable,等于同时部署了四个平台:
+
+- **一套安全、可扩展的 agent 沙箱** —— 每个 AI 会话都在自己独立的容器中运行,
+ 按需启动,会话结束即回收;
+- **一套资源利用率极高的应用部署平台** —— 团队构建并发布的每个应用,都以
+ 自己的轻量长驻容器运行;
+- **一套 AI 工作流引擎** —— 由记录变更、定时与 webhook 触发的自动化,可编排
+ AI 步骤,就运行在你的数据旁边;
+- **一套基于 PostgreSQL 的全功能数据库协作平台** —— 表格、视图、API。
+
+通过 Teable 私有化部署,你的计算资源被封装成一个 **agent-ready、完全可控的
+生产力环境** —— 把 AI 能力交到团队每个人手里。
+
+本页讲清这背后的各个服务与它们如何协同。可部署资产(compose、Helm chart、
+values)全部在
[teableio/teable-deployment](https://github.com/teableio/teable-deployment)
-仓库中维护,那里是唯一事实源 —— 本页没有任何需要复制的内容。
+仓库中维护。
AI 能力面向私有化部署 Business 及以上套餐提供。
## 一套部署包含什么
-| 服务 | 职责 |
+| 服务 | 作用 |
|---|---|
| **Teable 应用** | Web 界面、API、自动化、AI 对话 —— 单一镜像:`ghcr.io/teableio/teable` |
-| **PostgreSQL** | 数据事实源:表、视图、元数据 |
+| **PostgreSQL** | 主数据库:你的所有表、视图与元数据都存在这里 |
| **Redis** | 缓存、队列、实时协作 |
-| **对象存储** | S3 兼容,三个桶:**public**(头像与公开资源)、**private**(附件)、**build artifacts**(App Builder 构建产物) |
-| **Infra Service** | 控制台与 API —— Teable 应用唯一的对接点;编排构建与应用部署 |
-| **沙箱引擎** | 每个 AI 会话都在独立的沙箱容器中运行 |
-| **Git 仓库服务** | 你构建的应用的源码事实源(App Builder 推送至此) |
-| **预览网关** | 在浏览器中提供沙箱预览与已部署应用的访问 |
+| **对象存储** | S3 兼容的文件存储,三个桶:**public**(头像等公开资源)、**private**(附件)、**build artifacts**(App Builder 的构建产物) |
+| **Infra Service** | Teable 应用唯一连接的入口;协调构建与应用部署,自带控制台与 API |
+| **沙箱引擎** | 让每个 AI 会话在自己独立的容器里运行 |
+| **Git 仓库服务** | 保存你构建的应用的源码(App Builder 推送至此) |
+| **预览网关** | 把浏览器请求转到沙箱预览或已部署应用 |
-后四个服务构成**运行平面**;部署资产会把以上全部作为一个平台一次装好。
+后四个组成运行平面。部署资产会把以上全部作为一个平台一次装好。
## 如何协同
@@ -64,51 +75,48 @@ graph LR
style A fill:#F59E0B,stroke:#b45309,color:#fff
```
-Teable 应用只通过**一个连接**触达运行平面:Infra Service
-(`TEABLE_INFRA_API_URL` / `TEABLE_INFRA_API_KEY`),其余全部是平面内部细节。
-平面上真正运行的,是两类负载:
+Teable 应用只通过**一个连接**接入运行平面:Infra Service
+(`TEABLE_INFRA_API_URL` / `TEABLE_INFRA_API_KEY`),其余交互都发生在运行平面
+内部,你无需关心。真正干活、也真正消耗机器资源的,是两类负载:
-- **沙箱** —— 每个 AI 对话、每次 App Builder 构建会话,都按需启动一个独立
- 容器,会话结束即销毁。这是平台最主要且突发性的负载:机器规格要按
- **AI 会话峰值并发**来估,而不是按用户数(单个沙箱的资源限额可在管理面板配置)。
-- **已部署应用** —— 每个被部署出去的应用都是一个长驻容器,经 `*.app.`
- 对外服务。沙箱来了又走,已部署应用则不断累积、持续运行。
+- **沙箱。** 每个 AI 对话、每次 App Builder 构建会话,都会得到一个自己独立的
+ 容器 —— 会话开始时启动,结束即回收。这是平台最主要的负载,而且一阵一阵来:
+ 机器规格按 **AI 会话的峰值并发**来估,而不是按用户数(单个沙箱的资源限额
+ 可在管理面板设置)。
+- **已部署应用。** 每个被发布出去的应用都是一个长期运行的容器,通过
+ `*.app.` 对外服务。沙箱来了又走,已部署应用则越攒越多、持续运行。
-其余都是配套管线:构建在会话的沙箱内完成,Git 仓库服务与对象存储负责沉淀
-它产出的源码与构建产物,网关把浏览器路由到对应的沙箱或应用。
+其余服务都是配角:构建在会话的沙箱里完成,Git 仓库服务与对象存储保存它产出的
+源码和构建产物,网关把每个浏览器请求转到对应的沙箱或应用。
## 一个域名,四条 DNS 记录
-一切派生自**一个基础域名** —— 通常是你组织域名的子域,例如 `teable.example.com`:
+所有服务都挂在**一个基础域名**下 —— 通常是你组织域名的子域,例如
+`teable.example.com`:
| 记录 | 用途 |
|---|---|
| `` | Teable 应用 |
-| `infra.` | Infra 控制台与 API —— git(`/git` 路径)与对象存储(桶路径)共用此主机 |
+| `infra.` | Infra Service 的控制台与 API;git(`/git`)与对象存储也从这个域名下的路径提供 |
| `*.app.` | 你构建并部署的应用 |
| `*.sandbox.` | 浏览器中的沙箱预览 |
每个名字都只是默认值,任何主机名均可单独覆盖(见部署仓库的 values 示例)。
-## Agent 如何与应用保持同步
-
-沙箱 agent 镜像配置为**不带 tag 的前缀**。Teable 应用启动 AI 会话时会拼上
-**自身的发布版本 tag**,因此 agent 永远与应用版本配对 —— 并且应用会经
-Infra Service 预热这个镜像,首次会话不必现场拉取数 GB 镜像。
-你永远不需要手动拉取或钉定 agent。
-
## 版本体系
平台以部署仓库的**平台版本**(`v<年>.<月>.<序号>`)形式发布:
-- **tag** 是已验证的快照:`versions.yaml` 钉定每个组件镜像(含 digest),
+- 版本 **tag** 是已验证的快照:`versions.yaml` 锁定每个组件的确切版本,
仓库的 `CHANGELOG.md` 写明每版变了什么、你需要做什么;
- 仓库 `main` 分支是滚动最新;
-- 自带的 **doctor** 脚本会把你实际运行的组合与版本清单比对,给出三态结论:
+- 自带的 **doctor** 脚本会把你实际运行的组合与版本清单比对,给出三种结论之一:
兼容 / 需升级 Teable 应用 / 未知(未经验证的)组合。
Teable 应用有自己独立的发版线(日期型 tag;`latest` 为稳定通道)——
-见[版本升级](/zh/deploy/upgrade)。平台版本会声明应用兼容窗口,doctor 替你检查。
+见[版本升级](/zh/deploy/upgrade)。每个平台版本都写明它验证过哪些应用版本,
+doctor 替你检查。支撑 AI 会话的沙箱 agent 会自动跟随应用自身的版本 ——
+没有任何需要你额外升级或管理的东西。
## 部署
@@ -119,25 +127,25 @@ Teable 应用有自己独立的发版线(日期型 tag;`latest` 为稳定通道)
一台机器装下一切 —— 首次全功能部署,支持 local / server 两种模式。
- 一个伞形 chart 装进现有集群;只需设置 global.baseDomain。
+ 一个 Helm chart 装进现有集群;只需设置 global.baseDomain。
暂时不需要 AI?也可以只运行应用与 PostgreSQL、Redis、存储 ——
即**基础版**部署([Docker 部署](/zh/deploy/docker)),之后随时把运行平面
-挂到旁边,数据原地不动。
+装到旁边,数据原地不动。
相关主题(均在部署仓库中维护):
-- **已在运行基础版 Teable?** 数据原地不动,运行平面挂在旁边即可:
+- **已在运行基础版 Teable?** 数据原地不动,运行平面装在旁边即可:
[迁移指南](https://github.com/teableio/teable-deployment/blob/main/migration/2026-07-basic-to-full-featured.md)
-- **私有/企业 CA**:沙箱必须信任你入口的证书 ——
+- **公司内部证书?** 如果你的域名用的是私有/企业 CA,需要让沙箱信任它 ——
[private-ca.md](https://github.com/teableio/teable-deployment/blob/main/helm/private-ca.md)
- **容量、版本与镜像加速**:[VERSIONS.md](https://github.com/teableio/teable-deployment/blob/main/VERSIONS.md) ·
[images/README.md](https://github.com/teableio/teable-deployment/blob/main/images/README.md)
- **出问题时**:先跑 doctor,再看
[TROUBLESHOOTING.md](https://github.com/teableio/teable-deployment/blob/main/TROUBLESHOOTING.md)
-部署完成后,用 `TEABLE_INFRA_API_URL` / `TEABLE_INFRA_API_KEY` 把 Teable 应用接到
-运行平面(部署指引中有说明),然后在
-[管理面板 → Sandbox Agent](/zh/basic/admin-panel/sandbox-agent) 配置运行限制。
+部署完成后,用 `TEABLE_INFRA_API_URL` / `TEABLE_INFRA_API_KEY` 把 Teable 应用
+接到运行平面(部署指引中有说明),然后在
+[管理面板 → Sandbox Agent](/zh/basic/admin-panel/sandbox-agent) 设置资源限额。