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) 设置资源限额。