Typebot 3.19 Docker Compose 部署指南

目标：本文档提供在任意安装了 Docker + Docker Compose 的服务器上，通过官方 Compose 文件一键部署 Typebot 3.19 的完整流程，覆盖基本部署、HTTPS 反向代理、SMTP 邮件认证、S3 对象存储（可选）、升级与常见问题。本文档基于 Typebot v3.19.0 实测（2026-10-27），Builder 返回 HTTP 307 / Viewer 返回 HTTP 200，数据库迁移自动完成。

一、环境信息

Docker Engine：20.10+（推荐 24.x 或更新）
Docker Compose：v2+（随 Docker 自带 docker compose）
服务器最低配置：2 vCPU / 4GB RAM
官方镜像仓库：
- baptistearno/typebot-builder（Builder 编辑器，默认 3000）
- baptistearno/typebot-viewer（Viewer 运行时，默认 3000）
- postgres:16（官方推荐数据库）
暴露端口：Builder 映射宿主机 8080、Viewer 映射 8081（官方默认）
持久化：Docker named volume db-data（存 PostgreSQL 数据）

二、镜像选型说明

Typebot 官方维护两个独立镜像，版本号一一对应：

镜像	标签示例	说明
`baptistearno/typebot-builder`	`latest` / `3.19` / `3.19.0`	编辑器 + 账户管理 + API Token
`baptistearno/typebot-viewer`	`latest` / `3.19` / `3.19.0`	运行时对话引擎 + 访客界面
`postgres`	`16` / `16-alpine`	数据库（官方 Compose 用 postgres:16）

本文实测使用 postgres:16-alpine（更小更快），功能完全兼容。生产环境推荐 postgres:16（官方默认）。

三、前置条件

服务器已安装 Docker 和 Docker Compose v2（docker compose version 正常输出）
规划好两个域名（Builder + Viewer）或准备好端口映射
准备一个随机 32 字符 ENCRYPTION_SECRET：openssl rand -hex 16
至少配置一种认证方式（Email SMTP / Google OAuth / GitHub OAuth 等）

四、部署步骤

4.1 创建部署目录

sudo mkdir -p /opt/typebot && sudo chown -R $USER:$USER /opt/typebot
cd /opt/typebot

4.2 下载官方 Compose 文件和 .env 模板

# 下载官方 docker-compose.yml
wget -O docker-compose.yml https://raw.githubusercontent.com/baptisteArno/typebot.io/v3.19/docker-compose.yml

# 下载 .env 模板（注意：官方在 latest 分支是 .env.example）
wget -O .env https://raw.githubusercontent.com/baptisteArno/typebot.io/v3.19/.env.example

# 生成 32 字符加密密钥并输出
openssl rand -hex 16
# 实测输出：
# 27ecfd653fc2ad3013895327fcfab718

ls -la
# 实测输出：
# -rw-rw-r-- 1 admin admin  968 Oct 27 15:33 docker-compose.yml
# -rw-rw-r-- 1 admin admin 2102 Oct 27 15:34 .env

4.3 配置 .env 文件

Typebot 的 Builder 和 Viewer 共用一个 .env 文件。必须配置以下项，其余按需补充：

nano .env

# ===== 必需配置 =====
DATABASE_URL=postgresql://typebot:typebot@typebot-db:5432/typebot
ENCRYPTION_SECRET=<openssl rand -hex 16 输出的 32 字符>
NEXTAUTH_URL=http://<builder-host>:8080
NEXT_PUBLIC_VIEWER_URL=http://<viewer-host>:8081

# ===== 建议配置 =====
ADMIN_EMAIL=admin@example.com         # 该邮箱首次注册自动获得 UNLIMITED 套餐
DISABLE_SIGNUP=true                   # 禁止新用户自助注册（仅邀请）
TYPEBOT_DEBUG=false

# ===== 至少配置一种认证方式 =====
# Email SMTP（最简单）
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=noreply
SMTP_PASSWORD=your-smtp-password
SMTP_SECURE=false
NEXT_PUBLIC_SMTP_FROM='Typebot Notifications <noreply@example.com>'

# 或 GitHub OAuth（示例）
# GITHUB_CLIENT_ID=your-client-id
# GITHUB_CLIENT_SECRET=your-client-secret

⚠️ NEXTAUTH_URL 与 NEXT_PUBLIC_VIEWER_URL：这两个 URL 的根域必须相同（Cookie 共享要求），但 host 名必须不同（浏览器 Cookie 忽略端口）。本地开发可用 NEXTAUTH_URL=http://localhost:8080 + NEXT_PUBLIC_VIEWER_URL=http://127.0.0.1:8081。

4.4 启动 Compose 栈

cd /opt/typebot

# 启动全部服务
docker compose up -d
# 实测输出：
# [+] Running 4/4
#  ✔ Network typebot_default  Created
#  ✔ Volume "typebot_db-data"  Created
#  ✔ Container typebot-typebot-db-1        Started
#  ✔ Container typebot-typebot-builder-1    Started
#  ✔ Container typebot-typebot-viewer-1     Started

Typebot 首次启动时会自动执行 Prisma 数据库迁移（所有 30+ 个 migration），通常需要 15-60 秒。

4.5 验证部署

# 检查容器运行状态
docker compose ps
# 实测输出：
# NAME                               STATUS          PORTS
# typebot-typebot-builder-1          Up 2 minutes    0.0.0.0:8080->3000/tcp
# typebot-typebot-db-1               Up 2 minutes (healthy)  5432/tcp
# typebot-typebot-viewer-1           Up 2 minutes    0.0.0.0:8081->3000/tcp

# 验证 Builder（应返回 307 重定向到登录页）
curl -sSI http://localhost:8080/ | head -3
# 实测输出：
# HTTP/1.1 307 Temporary Redirect

# 验证 Viewer（应返回 200）
curl -sSI http://localhost:8081/ | head -3
# 实测输出：
# HTTP/1.1 200 OK

# 查看数据库日志确认迁移完成
docker compose logs typebot-db --tail=5
# 实测输出：
# LOG:  database system is ready to accept connections

# 查看 Builder 日志确认启动完成
docker compose logs typebot-builder --tail=10
# 实测输出（节选）：
# ready - started server on 0.0.0.0:3000, url: http://localhost:3000

浏览器访问 http://<server-ip>:8080 即可看到登录界面。用 ADMIN_EMAIL 对应的邮箱注册后自动获得 UNLIMITED 套餐。

五、生产级 Compose 模板（带 HTTPS + S3 + SMTP）

以下是整合了 Caddy 反向代理（自动 HTTPS）、MinIO S3 存储、内置 SMTP 的完整 docker-compose.prod.yml：

name: typebot-prod

volumes:
  db-data:
  s3-data:
  caddy-certs:

networks:
  typebot-net:
    driver: bridge

services:
  # ===== PostgreSQL =====
  typebot-db:
    image: postgres:16-alpine
    restart: always
    volumes:
      - db-data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: typebot
      POSTGRES_USER: typebot
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U typebot"]
      interval: 5s
      timeout: 5s
      retries: 10
    networks:
      - typebot-net

  # ===== Builder（编辑器）=====
  typebot-builder:
    image: baptistearno/typebot-builder:3.19
    restart: always
    depends_on:
      typebot-db:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql://typebot:${POSTGRES_PASSWORD}@typebot-db:5432/typebot
      ENCRYPTION_SECRET: ${ENCRYPTION_SECRET}
      NEXTAUTH_URL: https://${BUILDER_DOMAIN}
      NEXT_PUBLIC_VIEWER_URL: https://${VIEWER_DOMAIN}
      ADMIN_EMAIL: ${ADMIN_EMAIL}
      DISABLE_SIGNUP: "true"
      TYPEBOT_DEBUG: "false"
      # SMTP
      SMTP_HOST: ${SMTP_HOST}
      SMTP_PORT: ${SMTP_PORT}
      SMTP_USERNAME: ${SMTP_USERNAME}
      SMTP_PASSWORD: ${SMTP_PASSWORD}
      SMTP_SECURE: ${SMTP_SECURE:-false}
      NEXT_PUBLIC_SMTP_FROM: ${SMTP_FROM}
      # S3（可选，用于媒体上传）
      S3_ACCESS_KEY: ${S3_ACCESS_KEY}
      S3_SECRET_KEY: ${S3_SECRET_KEY}
      S3_BUCKET: ${S3_BUCKET:-typebot}
      S3_ENDPOINT: ${S3_ENDPOINT}
      S3_SSL: "false"
    networks:
      - typebot-net
    labels:
      caddy: ${BUILDER_DOMAIN}
      caddy.reverse_proxy: "{{upstreams 3000}}"

  # ===== Viewer（运行时）=====
  typebot-viewer:
    image: baptistearno/typebot-viewer:3.19
    restart: always
    depends_on:
      typebot-db:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql://typebot:${POSTGRES_PASSWORD}@typebot-db:5432/typebot
      ENCRYPTION_SECRET: ${ENCRYPTION_SECRET}
      NEXTAUTH_URL: https://${BUILDER_DOMAIN}
      NEXT_PUBLIC_VIEWER_URL: https://${VIEWER_DOMAIN}
    networks:
      - typebot-net
    labels:
      caddy: ${VIEWER_DOMAIN}
      caddy.reverse_proxy: "{{upstreams 3000}}"
      caddy.reverse_proxy.flush_interval: -1   # 消息流式传输必需

  # ===== Caddy 反向代理（自动 HTTPS）=====
  caddy:
    image: caddy:alpine
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - caddy-certs:/data
    networks:
      - typebot-net

  # ===== MinIO S3 兼容存储（可选）=====
  minio:
    image: minio/minio
    restart: always
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: ${S3_ACCESS_KEY}
      MINIO_ROOT_PASSWORD: ${S3_SECRET_KEY}
    volumes:
      - s3-data:/data
    networks:
      - typebot-net

  # ===== 确保 S3 bucket 存在 =====
  createbuckets:
    image: minio/mc
    depends_on:
      - minio
    restart: "no"
    entrypoint: >
      /bin/sh -c "
      sleep 5;
      mc alias set minio http://minio:9000 ${S3_ACCESS_KEY} ${S3_SECRET_KEY};
      mc mb --ignore-existing minio/${S3_BUCKET:-typebot};
      mc anonymous set public minio/${S3_BUCKET:-typebot}/public;
      exit 0;"
    networks:
      - typebot-net

对应的 .env（生产环境完整版本）：

# ===== 必需 =====
POSTGRES_PASSWORD=your-strong-pg-password
ENCRYPTION_SECRET=27ecfd653fc2ad3013895327fcfab718
BUILDER_DOMAIN=typebot.example.com
VIEWER_DOMAIN=bot.example.com
ADMIN_EMAIL=admin@example.com

# ===== SMTP =====
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=noreply
SMTP_PASSWORD=your-smtp-password
SMTP_SECURE=false
SMTP_FROM='Typebot Notifications <noreply@example.com>'

# ===== S3（MinIO）=====
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin123
S3_BUCKET=typebot
S3_ENDPOINT=minio:9000

六、数据持久化说明

Typebot Compose 默认使用 Docker named volume 持久化数据：

Volume	用途	宿主路径
`db-data`	PostgreSQL 数据目录	`/var/lib/docker/volumes/typebot-prod_db-data/_data`
`s3-data`	MinIO 对象存储（可选）	同上
`caddy-certs`	Caddy TLS 证书（可选）	同上

备份建议：

# PostgreSQL 备份
docker compose exec typebot-db pg_dump -U typebot typebot > typebot-$(date +%F).sql

# 恢复
cat typebot-2026-10-27.sql | docker compose exec -T typebot-db psql -U typebot -d typebot

如需 bind mount（方便直接访问宿主文件），把 volume 声明改成：

volumes:
  - ./data/db:/var/lib/postgresql/data

七、升级 Typebot

cd /opt/typebot

# 拉取指定版本镜像
docker compose pull typebot-builder:3.20 typebot-viewer:3.20

# 修改 docker-compose.yml 中 image 版本号
sed -i 's|typebot-builder:3.19|typebot-builder:3.20|g' docker-compose.yml
sed -i 's|typebot-viewer:3.19|typebot-viewer:3.20|g' docker-compose.yml

# 滚动重启
docker compose up -d

# 验证新版本
docker compose logs typebot-builder --tail=3
# 实测输出（节选）：
# ready - started server on 0.0.0.0:3000

Typebot 会自动执行新 migration（幂等，已应用的跳过）。

八、常用运维命令

# 启动 / 停止 / 重启
docker compose up -d
docker compose down            # 停止并删除容器（保留 volume）
docker compose down -v         # 停止并删除容器 + volume（⚠️ 清空数据）
docker compose restart typebot-builder

# 查看状态
docker compose ps
docker compose logs -f typebot-builder
docker compose logs --tail=50 typebot-db

# 进入容器
docker compose exec typebot-builder sh
docker compose exec typebot-db psql -U typebot -d typebot

# 重建服务（改了环境变量后）
docker compose up -d --force-recreate

# 清理未使用资源
docker compose down && docker image prune -f

九、常见问题

Q1：Builder 启动报 `ENCRYPTION_SECRET Too small`

原因：ENCRYPTION_SECRET 必须恰好 32 字符。

解决：

openssl rand -hex 16   # 生成 32 字符 hex
# 重新创建容器
docker compose up -d --force-recreate

Q2：Builder 报数据库连接失败 `ECONNREFUSED`

原因：PostgreSQL 容器还没 ready（Builder 的 depends_on 配置了 condition: service_healthy 但健康检查可能未配置）。

解决：等待 PostgreSQL 日志输出 database system is ready to accept connections 后再重启 Builder：

docker compose restart typebot-builder

Q3：Portainer 迁移后 hostname 解析失败

原因：Portainer 迁移会丢失自定义网络的 attachable: true 属性，导致 typebot-viewer 无法解析 typebot-db。

解决：在 docker-compose.yml 中显式声明网络：

networks:
  typebot-net:
    driver: bridge
    attachable: true

Q4：Viewer 消息流式传输中断

原因：反向代理缺少 proxy_buffering off（Nginx）或 flush_interval -1（Caddy）。

解决：在 Caddy 标签或 Nginx location 中添加：

# Caddy
caddy.reverse_proxy.flush_interval: -1

# Nginx
proxy_buffering off;

Q5：登录后 Builder 显示空白页或重定向循环

原因：NEXTAUTH_URL 和 NEXT_PUBLIC_VIEWER_URL 的 host 相同（Cookie 无法正确区分）。

解决：两个 URL 必须是同根域但不同 host：

NEXTAUTH_URL=https://typebot.example.com
NEXT_PUBLIC_VIEWER_URL=https://bot.example.com

十、参考链接

官方 Docker 部署文档：https://docs.typebot.com/self-hosting/deploy/docker
官方配置参数参考：https://docs.typebot.com/self-hosting/configuration
Docker Hub Builder：https://hub.docker.com/r/baptistearno/typebot-builder
Docker Hub Viewer：https://hub.docker.com/r/baptistearno/typebot-viewer
GitHub Releases：https://github.com/baptisteArno/typebot.io/releases

Typebot 3.19 Docker Compose 部署指南

Typebot 3.19 Docker Compose 部署指南

一、环境信息

二、镜像选型说明

三、前置条件

四、部署步骤

4.1 创建部署目录

4.2 下载官方 Compose 文件和 .env 模板

4.3 配置 .env 文件

4.4 启动 Compose 栈

4.5 验证部署

五、生产级 Compose 模板（带 HTTPS + S3 + SMTP）

六、数据持久化说明

七、升级 Typebot

八、常用运维命令

九、常见问题

Q1：Builder 启动报 ENCRYPTION_SECRET Too small

Q2：Builder 报数据库连接失败 ECONNREFUSED

Q3：Portainer 迁移后 hostname 解析失败

Q4：Viewer 消息流式传输中断

Q5：登录后 Builder 显示空白页或重定向循环

十、参考链接

Q1：Builder 启动报 `ENCRYPTION_SECRET Too small`

Q2：Builder 报数据库连接失败 `ECONNREFUSED`