企业官网建设流程全解析

Teable Standalone 独立版 Docker 自托管部署指南：开箱即用的单机部署方案

【免费下载链接】teable✨ AI Spreadsheet for Business项目地址: https://gitcode.com/GitHub_Trending/te/teable

Teable 是一个构建在 PostgreSQL 之上的业务数据平台，其 Standalone（独立版）镜像专注于交付核心能力：表格、协作、API 与自动化。本篇基于仓库中的 docker-compose.yaml 与 .env 示例，完整讲解 Standalone 的架构边界、编排文件、环境变量、启动流程与数据持久化细节，帮助你在单机上用一条命令完成自托管，并理解其底层启动机制，为后续向完整版平滑演进做好准备。

Standalone 定位：能部署到什么程度

根据 dockers/examples/standalone/README.md 与 dockers/README.md 中的对比，Teable 的自托管分为两条路线：

Standalone 版本专门承载 Teable 的核心业务能力，不需要额外组件即可运行；AI 能力（对话、App Builder、沙箱）属于 full-featured 自托管部署。官方也明确了升级路径：如果已经运行 Standalone，升级到完整版时你的数据会原地保留——完整版部署是在现有应用旁边附加运行时平面，不会迁移或重建数据。这一设计让 Standalone 既可以作为正式轻量部署，也可以作为完整版的前置步骤。

部署前置与准备

部署前需要准备：

• Docker Engine 与 Docker Compose 插件（docker compose子命令可用）；
• 可访问ghcr.io容器镜像仓库；
• 宿主机可用端口：3000（Web/API）与42345（PostgreSQL 对外映射，用于本机直连数据库）。

部署目录位于仓库的 dockers/examples/standalone/，其中包含两个文件：docker-compose.yaml（编排定义）与.env（全部配置变量）。按 README 的说明，在执行docker compose up -d之前，必须查看并更新.env中的变量（尤其是各类密码）。

docker-compose.yaml 逐项解读

docker-compose.yaml 定义了三个服务、一个自定义网络与三个命名卷。

teable 应用服务

teable: image: ghcr.io/teableio/teable:latest restart: always ports: - '3000:3000' volumes: - teable-data:/app/.assets:rw # 也可以改用宿主目录挂载（bind mount）， # 这样更难误删卷导致数据丢失： # - ./docker/teable/data:/app/.assets:rw env_file: - .env environment: - TZ=${TIMEZONE} networks: - teable-standalone depends_on: teable-db: condition: service_healthy teable-cache: condition: service_healthy

关键点：

• 镜像：ghcr.io/teableio/teable:latest为官方构建的完整产品镜像，由仓库根目录 dockers/teable/Dockerfile 的多阶段构建产物封装，EXPOSE端口为 3000；
• 端口：3000:3000暴露 Web 界面与 API，访问地址即http://127.0.0.1:3000；
• 数据卷：teable-data:/app/.assets:rw保存应用本地资产（附件等）。compose 文件给出了可选的 bind mount 写法（如./docker/teable/data:/app/.assets:rw），官方注释建议用它替代命名卷，从而降低误删卷导致数据丢失的风险；
• 健康依赖：depends_on配合condition: service_healthy，保证只有在 PostgreSQL 与 Redis 都通过健康检查后才启动应用，避免启动竞态；
• 环境变量：通过env_file: .env整体注入，并将TZ透传给容器。

teable-db 数据库服务

teable-db: image: postgres:15.4 restart: always ports: - '42345:5432' volumes: - teable-db:/var/lib/postgresql/data:rw # 也可以使用 bind mount： # - ./docker/db/data:/var/lib/postgresql/data:rw environment: - TZ=${TIMEZONE} - POSTGRES_DB=${POSTGRES_DB} - POSTGRES_USER=${POSTGRES_USER} - POSTGRES_PASSWORD=${POSTGRES_PASSWORD} networks: - teable-standalone healthcheck: test: ['CMD-SHELL', "sh -c 'pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}'"] interval: 10s timeout: 3s retries: 3

• 镜像版本：postgres:15.4，即 Teable 元数据库（meta）与业务数据均存储于 PostgreSQL 15；
• 对外端口：42345:5432仅用于从宿主机直接连接数据库（调试、SQL 查询等场景），容器网络内部仍通过teable-db:5432访问，与.env中POSTGRES_HOST=teable-db、POSTGRES_PORT=5432对应；
• 健康检查：使用pg_isready每 10 秒探测一次，超时 3 秒，失败重试 3 次后才标记为 healthy；
• 持久化：数据落在teable-db命名卷的/var/lib/postgresql/data，同样提供了 bind mount 替代写法。

teable-cache 缓存服务

teable-cache: image: redis:7.2.4 restart: always expose: - '6379' volumes: - teable-cache:/data:rw networks: - teable-standalone command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD} healthcheck: test: ['CMD', 'redis-cli', '--raw', 'incr', 'ping'] interval: 10s timeout: 3s retries: 3

• 镜像版本：redis:7.2.4，仅通过expose在容器网络内暴露6379，不对外发布端口，避免未授权访问；
• 持久化与鉴权：启动参数--appendonly yes开启 AOF 持久化，--requirepass ${REDIS_PASSWORD}强制设置密码（即.env中的REDIS_PASSWORD）；
• 健康检查：用redis-cli incr ping验证读写可用性。

网络与卷

networks: teable-standalone: name: teable-standalone-network driver: bridge volumes: teable-data: {} teable-db: {} teable-cache: {}

三个服务共享 bridge 网络teable-standalone-network，通过服务名互访；三个命名卷分别承载应用资产、数据库文件与 Redis 数据。仓库根目录的 dockers/networks.yml、dockers/database-postgres.yml、dockers/cache-redis.yml 等文件展示了这些基础设施片段在更大部署中的复用方式。

.env 配置变量详解

.env 示例 是 Standalone 部署唯一的配置入口，以下逐组说明。

时区

TIMEZONE=UTC

注入teable与teable-db两个容器的TZ环境变量。注意：部署后如需修改时区，需同时重新创建容器与数据库容器（docker compose up -d --force-recreate），因为 PostgreSQL 的时区在进程启动时读取。

PostgreSQL 连接

POSTGRES_HOST=teable-db POSTGRES_PORT=5432 POSTGRES_DB=example POSTGRES_USER=example POSTGRES_PASSWORD=example2password

• POSTGRES_HOST/PORT指向 compose 网络内的数据库服务名，不应改为127.0.0.1，除非应用以 host 模式运行；
• POSTGRES_PASSWORD为示例值，正式部署前务必修改。

Redis 连接

REDIS_HOST=teable-cache REDIS_PORT=6379 REDIS_DB=0 REDIS_PASSWORD=replace_this_password

REDIS_PASSWORD同时用于 Redis 容器启动参数（--requirepass）与后端连接串，两处必须保持一致，同样需要在部署前替换。

应用地址与数据库 URL

PUBLIC_ORIGIN=http://127.0.0.1:3000 PRISMA_DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB} PUBLIC_DATABASE_PROXY=127.0.0.1:42345

• PUBLIC_ORIGIN：后端校验的外部访问地址。本地部署保持http://127.0.0.1:3000；若通过域名或反向代理暴露，需改为对应公网地址（后端环境校验中该变量为必填项，见 env.validation.schema.ts）；
• PRISMA_DATABASE_URL：后端通过 Prisma 连接 PostgreSQL 的 DSN，直接引用上面的 PostgreSQL 变量组合而成，无需单独修改；
• PUBLIC_DATABASE_PROXY=127.0.0.1:42345：对应 compose 中数据库对宿主机的映射端口，供宿主机侧 SQL 客户端直连。

事务超时（可选）

# 事务最长执行时间（毫秒），默认 5000 #PRISMA_TRANSACTION_TIMEOUT=60000 # 从连接池获取事务的最大等待时间（毫秒），默认 2000 #PRISMA_TRANSACTION_MAX_WAIT=5000

适用于大批量更新、大量关联链接写入等长事务场景，按需取消注释并调整。

邮件服务（可选）

#BACKEND_MAIL_HOST=smtp.teable.ai #BACKEND_MAIL_PORT=465 #BACKEND_MAIL_SECURE=true #BACKEND_MAIL_SENDER=noreply.teable.ai #BACKEND_MAIL_SENDER_NAME=Teable #BACKEND_MAIL_AUTH_USER=username #BACKEND_MAIL_AUTH_PASS=password

Standalone 默认不配置邮件。只有需要发送邮件（如邀请、通知）时才启用，且必须替换为实际 SMTP 配置，否则无法正确发信。

缓存后端

BACKEND_CACHE_PROVIDER=redis BACKEND_CACHE_REDIS_URI=redis://default:${REDIS_PASSWORD}@${REDIS_HOST}:${REDIS_PORT}/${REDIS_DB}

Standalone 编排默认使用 Redis 作为缓存。后端环境校验对BACKEND_CACHE_REDIS_URI要求必须匹配redis://或rediss://协议前缀（见 env.validation.schema.ts）。示例 URI 使用default作为 Redis 用户名，密码引用上面的REDIS_PASSWORD，端口与库号与 Redis 组保持一致。

此外，.env 示例 中还注释了一个可选的安全开关BACKEND_SESSION_ORIGIN_CHECK_ENABLED：用于对不安全的 API 请求启用浏览器 Session Origin 校验，仅在反向代理或 CDN 能保留Origin与Sec-Fetch-*请求头时才建议开启。

启动、验证与常用运维命令

前置步骤完成后，在dockers/examples/standalone/目录下执行：

docker compose up -d

首次启动会依次拉起teable-db→teable-cache→teable（由健康依赖保证顺序），随后浏览器访问：

http://127.0.0.1:3000

常用运维命令：

# 查看全部服务状态与健康检查结果 docker compose ps # 跟踪应用日志 docker compose logs -f teable # 修改 .env 后重建容器（保留数据卷） docker compose up -d --force-recreate # 停止服务（不删除数据卷） docker compose down # 彻底清理（会删除命名卷中的数据，谨慎执行） docker compose down -v

启动流程与数据库迁移的源码视角

Standalone 容器的启动过程并非简单的进程拉起，而是"先迁移、后启动"的两段式流程，可以从源码确认：

1. 镜像入口：镜像ENTRYPOINT指向scripts/start.sh（见 Dockerfile）；
2. 自动迁移：start.sh 默认在启动前执行node scripts/db-migrate.mjs，数据库迁移失败则整个容器启动失败并退出（exit 1）。也可通过参数覆盖：skip-migrate（跳过迁移）、migrate-only（仅迁移后退出）；
3. 迁移实现：db-migrate.mjs 解析PRISMA_DATABASE_URL（兼容PRISMA_META_DATABASE_URL），先对 meta 库执行prisma migrate deploy（schema 为packages/db-main-prisma/prisma/postgres/schema.prisma），再对 data 库执行同样的部署迁移（schema 为packages/db-data-prisma/prisma/schema.prisma），并带 5 次、每次间隔 3 秒的重试逻辑；同时通过wait-for等待数据库端口就绪；
4. 服务启动：迁移完成后，同时启动 NestJS 后端（apps/nestjs-backend/dist/index.js）与插件服务器（plugins/server.js），wait -n保证任一进程退出即终止容器（见 start.sh）。

这一设计意味着：首次启动时数据库表结构由容器自动完成初始化，无需手工执行 SQL；升级镜像后重启容器也会自动应用新的迁移。

数据持久化、遥测与安全注意事项

• 数据持久化位置：应用资产、PostgreSQL 数据、Redis 数据分别落在三个命名卷teable-data、teable-db、teable-cache。如需长期保留数据，建议按 compose 中注释改为 bind mount 目录，并做好定期备份（尤其是teable-db卷）；
• 遥测状态：按 dockers/examples/standalone/README.md 的说明，Standalone 镜像中Telemetry（遥测）是默认关闭的，无需额外配置即可保证自托管环境的隐私性；
• 默认密码必须修改：.env中的POSTGRES_PASSWORD与REDIS_PASSWORD均为占位示例值，正式部署务必替换为强密码，且修改后需同步更新PRISMA_DATABASE_URL与BACKEND_CACHE_REDIS_URI（它们引用这些变量）；
• 端口暴露面：PostgreSQL 的42345端口对外映射，建议仅对可信网络开放，或改用防火墙限制来源 IP；Redis 不对外发布端口；
• 反向代理：若通过域名访问，建议在反向代理层启用 HTTPS，并将PUBLIC_ORIGIN改为域名地址；
• 会话校验（可选）：仅当代理/CDN 能透传Origin与Sec-Fetch-*头时，才启用BACKEND_SESSION_ORIGIN_CHECK_ENABLED以增强 API 安全性。

后续演进：升级到完整版时数据不丢失

如果未来需要 AI Chat、App Builder 与沙箱能力，无需推倒重来。官方迁移路径（migration/2026-07-basic-to-full-featured）明确说明：完整版部署会在现有 Standalone 应用旁边附加运行时平面，已有数据原地保留，无需迁移或重建数据库。因此 Standalone 既可长期作为轻量级正式部署，也可作为完整版的稳健起点——这正是其"单机、一个 PostgreSQL、三服务"精简架构的价值所在。

通过本文，你已经掌握了 Standalone 版的能力边界、docker-compose.yaml三服务的职责划分、.env全部变量的含义与取值规则、容器启动时的自动迁移机制，以及数据持久化与安全加固要点。接下来即可直接修改.env中的密码并执行docker compose up -d完成你的第一次 Teable 自托管。

【免费下载链接】teable✨ AI Spreadsheet for Business项目地址: https://gitcode.com/GitHub_Trending/te/teable