Typebot 3.19 配置参数详解

Typebot v3.19 全部 60+ 环境变量按功能分类详解（核心/认证/Google/GitHub/S3/媒体），含最小配置、生产增强、企业私有三套 .env 模板。

TypebotTypebot聊天机器人TypeScript无代码Next.jsRESTRedis缓存2026/10/27

Typebot 3.19 配置参数详解

目标：本文档系统梳理 Typebot v3.19 的全部环境变量配置项，按功能分类详解每个参数的含义、默认值、取值范围与实测行为，并给出三种典型场景（最小配置 / 生产增强 / 企业私有）的完整 .env 模板。版本信息截至 2026-10-27。

一、环境信息

  • Typebot 版本：v3.19.0（Builder + Viewer 共用同一个 .env）
  • 配置形式：环境变量（.env 文件、export、或 Docker Compose environment: / env_file:）
  • Builder 与 Viewer：相同的 DATABASE_URL、ENCRYPTION_SECRET、NEXTAUTH_URL、NEXT_PUBLIC_VIEWER_URL 必须一致，否则会出现登录失败或对话中断
  • 官方权威文档：https://docs.typebot.com/self-hosting/configuration（本文按其 v3.19 版本整理，并补充实测验证项）

二、前置条件

修改环境变量后，Builder 和 Viewer 需要同时重启以生效（docker compose restart typebot-builder typebot-viewer 或 pm2 restart typebot-builder typebot-viewer）。数据库迁移相关的改动（如需 SUPERUSER 权限）会在 Builder 启动时自动执行。

三、参数查看与修改方式

部署方式查看当前配置修改方式
Docker Composedocker compose exec typebot-builder env | grep -E 'TYPEBOT|NEXTAUTH|DATABASE'编辑 .env → docker compose up -d
PM2 + 源码pm2 describe typebot-builder 或 cat /proc/$(pgrep -f 'nx start builder')/environ | tr '\0' '\n'编辑根目录 .env → pm2 restart typebot-builder typebot-viewer

四、参数总览

Typebot 配置项按功能可分为 9 大类，共 60+ 个环境变量：

类别数量是否必需典型项
通用核心73 必需DATABASE_URL, ENCRYPTION_SECRET, NEXTAUTH_URL
邮件认证与通知7至少配一种认证SMTP_HOST, SMTP_PORT, SMTP_USERNAME
Google 全家桶11可选GOOGLE_AUTH_CLIENT_ID, NEXT_PUBLIC_GOOGLE_SHEETS_API_KEY
GitHub/GitLab/Facebook6可选GITHUB_CLIENT_ID, GITLAB_BASE_URL
企业身份认证9可选AZURE_AD_CLIENT_ID, KEYCLOAK_REALM, CUSTOM_OAUTH_ISSUER
S3 对象存储8可选S3_ACCESS_KEY, S3_ENDPOINT, S3_BUCKET
外部媒体服务4可选NEXT_PUBLIC_GIPHY_API_KEY
WhatsApp 预览2可选WHATSAPP_PREVIEW_APP_SECRET
调试与安全3可选TYPEBOT_DEBUG, SSRF_ALLOWED_HOSTS

五、核心参数分类详解

5.1 通用核心参数（必需 + 基础）

这是 Typebot 启动的最低必需配置，缺任意一个 Builder 和 Viewer 都无法正常启动。

参数默认必需说明实测验证
DATABASE_URL—✅PostgreSQL 连接串，格式 postgresql://user:pass@host:5432/dbname。数据库用户需 SUPERUSER 角色（Prisma 迁移要求）可通过 docker compose exec typebot-db psql -U typebot -d typebot 验证连通
ENCRYPTION_SECRET—✅恰好 32 字符的加密密钥，用于加密敏感数据（凭证、API Token 等）。Builder 与 Viewer 必须相同openssl rand -hex 16 生成；短于 32 字符 Builder 直接启动失败
NEXTAUTH_URL—✅Builder 的公开访问 URL（含协议和域名）。NextAuth.js 以此为基准做 OAuth 回调和 Cookie 设置必须与实际浏览器访问 Builder 的 URL 完全匹配
NEXT_PUBLIC_VIEWER_URL—✅Viewer 的公开访问 URL。用于嵌入脚本生成和跨域 Cookie根域必须和 NEXTAUTH_URL 相同，但 host 不同（浏览器 Cookie 忽略端口）
ADMIN_EMAIL—建议首次用此邮箱注册的用户自动获得 UNLIMITED 套餐并可绕过数据库规则。支持逗号分隔多个邮箱注册后在 Builder Settings 可确认套餐状态
DEFAULT_WORKSPACE_PLANFREE可选新用户创建 Workspace 时的默认套餐。可选值：FREE、STARTER、PRO、LIFETIME、UNLIMITED商业场景可设为 STARTER 以限制免费用户额度
DISABLE_SIGNUPfalse可选设为 true 禁止新用户自助注册（仅允许通过邀请链接注册）企业私有部署强烈建议开启

5.2 运行时与调试参数

参数默认说明
TYPEBOT_DEBUGfalse设为 true 时 Builder 输出详细配置调试日志（.env 解析过程、环境变量校验结果）
CHAT_API_TIMEOUT—聊天 API 执行超时（毫秒）。避免无限循环卡住，但不作用于 OpenAI 等已知长耗时 block
NEXT_PUBLIC_BOT_FILE_UPLOAD_MAX_SIZE—限制 Bot 内单文件上传大小（MB）。如 10 表示最大 10MB
NEXT_PUBLIC_ONBOARDING_TYPEBOT_ID—指定 Onboarding 用的 Typebot ID，未设置则跳过引导页
SSRF_ALLOWED_HOSTS—逗号分隔的内部 IPv4 SMTP 中继主机名白名单（SMTP 配置测试用）

5.3 邮件认证与 SMTP 配置

Typebot 支持通过 Email Magic Link（无需密码）登录，也可用于发送通知邮件。至少需要配置一种认证方式，SMTP 是最简单的。

参数默认说明
SMTP_HOST—SMTP 服务器地址（如 smtp.gmail.com）
SMTP_PORT25SMTP 端口。常用：25（明文）、587（STARTTLS）、465（SSL）
SMTP_USERNAME—SMTP 认证用户名
SMTP_PASSWORD—SMTP 认证密码或 App Password
SMTP_SECUREfalse设为 true 则强制 TLS 连接。端口 465 时建议开启
SMTP_IGNORE_TLS—当 SMTP_SECURE=false 时，设为 true 可强制不使用 STARTTLS
SMTP_AUTH_DISABLEDfalse仅禁用 Email 认证（仍用 SMTP 发通知邮件）。适合只想用 GitHub/Google 登录的场景
NEXT_PUBLIC_SMTP_FROM—发件人显示名和邮箱，格式 'DisplayName' <email@domain.com>

5.4 Google 全家桶集成

参数默认说明
Google OAuth 登录
GOOGLE_AUTH_CLIENT_ID—Google Cloud Console OAuth 2.0 Client ID
GOOGLE_AUTH_CLIENT_SECRET—对应的 Client Secret
Google Sheets 集成
GOOGLE_SHEETS_CLIENT_ID—OAuth 2.0 Client ID
GOOGLE_SHEETS_CLIENT_SECRET—Client Secret
NEXT_PUBLIC_GOOGLE_SHEETS_API_KEY—Google Sheets API Key
Gmail 发送
GMAIL_CLIENT_ID—Gmail OAuth Client ID
GMAIL_CLIENT_SECRET—Gmail Client Secret
Google Fonts
NEXT_PUBLIC_GOOGLE_FONTS_API_KEY—Web Fonts Developer API Key

5.5 GitHub / GitLab / Facebook OAuth

参数默认说明
GITHUB_CLIENT_ID—GitHub OAuth App Client ID（callback: $NEXTAUTH_URL/api/auth/callback/github）
GITHUB_CLIENT_SECRET—GitHub OAuth App Client Secret
GITLAB_CLIENT_ID—GitLab OAuth App Client ID
GITLAB_CLIENT_SECRET—GitLab OAuth App Client Secret
GITLAB_BASE_URLhttps://gitlab.com自建 GitLab 实例的 Base URL
GITLAB_REQUIRED_GROUPS—逗号分隔的用户必须直接隶属的 GitLab 组（如 foo,bar）
GITLAB_NAMEGitLab登录按钮显示名称
FACEBOOK_CLIENT_ID—Facebook OAuth App Client ID
FACEBOOK_CLIENT_SECRET—Facebook OAuth App Client Secret

5.6 企业身份认证（Azure AD / Keycloak / Custom OAuth）

参数默认说明
Azure AD
AZURE_AD_CLIENT_ID—Azure AD 应用程序 Client ID
AZURE_AD_CLIENT_SECRET—Client Secret
AZURE_AD_TENANT_ID—Azure Tenant ID
Keycloak
KEYCLOAK_CLIENT_ID—Keycloak Client ID
KEYCLOAK_CLIENT_SECRET—Client Secret
KEYCLOAK_REALM—Keycloak Realm 名称
KEYCLOAK_BASE_URL—Keycloak 实例 Base URL
Custom OAuth（OIDC）
CUSTOM_OAUTH_CLIENT_ID✅必需自定义 OIDC Provider 的 Client ID
CUSTOM_OAUTH_CLIENT_SECRET✅必需Client Secret
CUSTOM_OAUTH_ISSUER✅必需OIDC Issuer URL（如 https://auth.example.com/openid）
CUSTOM_OAUTH_NAMECustom OAuth登录按钮显示名称
CUSTOM_OAUTH_SCOPEopenid profile emailOAuth Scope
CUSTOM_OAUTH_USE_USERINFOfalse从 UserInfo Endpoint 而非 ID Token 取用户信息

5.7 S3 兼容对象存储（媒体上传）

Typebot 支持任意 S3 兼容对象存储（AWS S3、MinIO、DigitalOcean Spaces 等）。配置后 Builder 中的图片、视频、GIF 上传将存入 S3。

参数默认说明
S3_ACCESS_KEY—S3 Access Key（存在即表示启用上传功能）
S3_SECRET_KEY—S3 Secret Key
S3_BUCKETtypebotBucket 名称
S3_ENDPOINT—S3 Endpoint（如 MinIO minio:9000、AWS s3.<region>.amazonaws.com）
S3_PORT—S3 端口（非标准端口时显式指定）
S3_SSLtrue连接是否使用 SSL。MinIO 内网部署可设为 false
S3_REGION—S3 Region（AWS 必需，MinIO 可留空）
S3_PUBLIC_CUSTOM_DOMAIN—公开访问文件时的自定义域名（如 CDN 域名），不同于 S3_ENDPOINT

5.8 外部媒体搜索服务（GIPHY / Unsplash / Pexels）

参数默认说明
NEXT_PUBLIC_GIPHY_API_KEY—GIPHY API Key，启用 Builder 内 GIF 搜索
NEXT_PUBLIC_UNSPLASH_APP_NAME—Unsplash App 名称
NEXT_PUBLIC_UNSPLASH_ACCESS_KEY—Unsplash API Key
NEXT_PUBLIC_PEXELS_API_KEY—Pexels API Key（视频搜索）

5.9 WhatsApp Preview（本地测试 WhatsApp Bot）

仅用于 Builder Preview 抽屉内测试 WhatsApp Bot 功能，非生产必需：

参数默认说明
WHATSAPP_PREVIEW_APP_SECRET—WhatsApp Meta App 的 App Secret
META_SYSTEM_USER_TOKEN—Meta Business System User Token（权限：whatsapp_business_messaging, whatsapp_business_management）

六、生产配置模板

6.1 最小可用（单机 + SMTP 邮件登录）

适用于个人评估或小团队测试：

# ===== 必需 =====
DATABASE_URL=postgresql://typebot:your-pw@localhost:5432/typebot
ENCRYPTION_SECRET=$(openssl rand -hex 16)   # 32 字符
NEXTAUTH_URL=https://typebot.example.com
NEXT_PUBLIC_VIEWER_URL=https://bot.example.com

# ===== 基础安全 =====
ADMIN_EMAIL=admin@example.com
DISABLE_SIGNUP=true

# ===== 至少一种认证：SMTP Magic Link =====
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-gmail@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_SECURE=false
NEXT_PUBLIC_SMTP_FROM='Typebot' <your-gmail@gmail.com>

6.2 生产增强（SMTP + S3 + 调试禁用）

适用于生产环境的标准部署：

# ===== 必需 =====
DATABASE_URL=postgresql://typebot-prod:${DB_PASSWORD}@prod-db.internal:5432/typebot
ENCRYPTION_SECRET=${32-char-hex-secret}
NEXTAUTH_URL=https://typebot.yourcompany.com
NEXT_PUBLIC_VIEWER_URL=https://bot.yourcompany.com

# ===== 安全与管理 =====
ADMIN_EMAIL=admin@yourcompany.com,ops@yourcompany.com
DISABLE_SIGNUP=true
DEFAULT_WORKSPACE_PLAN=STARTER   # 新用户默认 Starter 套餐
TYPEBOT_DEBUG=false
CHAT_API_TIMEOUT=300000          # 5 分钟

# ===== SMTP（SendGrid / 企业内部 SMTP）=====
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USERNAME=apikey
SMTP_PASSWORD=${SENDGRID_API_KEY}
SMTP_SECURE=false
NEXT_PUBLIC_SMTP_FROM='Typebot NoReply' <noreply@yourcompany.com>
SSRF_ALLOWED_HOSTS=smtp.internal.yourcompany.com

# ===== S3（AWS S3）=====
S3_ACCESS_KEY=${AWS_S3_AK}
S3_SECRET_KEY=${AWS_S3_SK}
S3_BUCKET=typebot-prod
S3_ENDPOINT=s3.ap-northeast-1.amazonaws.com
S3_REGION=ap-northeast-1
S3_SSL=true

# ===== 外部媒体（可选）=====
NEXT_PUBLIC_GIPHY_API_KEY=${GIPHY_KEY}
NEXT_PUBLIC_PEXELS_API_KEY=${PEXELS_KEY}

6.3 企业私有（Keycloak + MinIO + 无外网服务）

适用于完全内网的企业部署：

# ===== 必需 =====
DATABASE_URL=postgresql://typebot-ent:${DB_PASSWORD}@10.0.0.10:5432/typebot
ENCRYPTION_SECRET=${32-char-hex-secret}
NEXTAUTH_URL=https://typebot.corp.local
NEXT_PUBLIC_VIEWER_URL=https://bot.corp.local

# ===== 安全与管理 =====
ADMIN_EMAIL=admin@corp.local
DISABLE_SIGNUP=true
DEFAULT_WORKSPACE_PLAN=PRO
TYPEBOT_DEBUG=false

# ===== 企业 Keycloak 认证 =====
KEYCLOAK_CLIENT_ID=typebot
KEYCLOAK_CLIENT_SECRET=${KEYCLOAK_SECRET}
KEYCLOAK_REALM=corp-realm
KEYCLOAK_BASE_URL=https://keycloak.corp.local

# ===== MinIO 内网 S3 =====
S3_ACCESS_KEY=typebot
S3_SECRET_KEY=${MINIO_SECRET}
S3_BUCKET=typebot
S3_ENDPOINT=minio.corp.local:9000
S3_PORT=9000
S3_SSL=false

# ===== 禁用外部媒体服务（内网不可达）=====
# 不设置 NEXT_PUBLIC_GIPHY_API_KEY 等，功能自动隐藏

七、常见问题

Q1：Builder 报 ENCRYPTION_SECRET Too small: expected string to have exactly 32 characters

原因：Typebot v3 强制 ENCRYPTION_SECRET 长度恰好 32（v2 版本允许更长）。

解决：

openssl rand -hex 16   # 输出 32 字符 hex
# 修改 .env 后重启
docker compose up -d --force-recreate

Q2：OAuth 回调报 redirect_uri_mismatch

原因：NEXTAUTH_URL 与 OAuth Provider 配置的回调 URL 不一致。

解决：在 Google / GitHub / GitLab / Azure OAuth 配置中将回调 URL 设为 $NEXTAUTH_URL/api/auth/callback/<provider>（如 https://typebot.example.com/api/auth/callback/google）。

Q3：S3 上传报 Access Denied

原因：S3 bucket 权限未正确设置（Typebot 需要 public read 权限读取公开文件）。

解决（MinIO）：

mc alias set minio http://minio:9000 minioadmin minioadmin
mc mb --ignore-existing minio/typebot
mc anonymous set public minio/typebot/public

Q4：Viewer 消息中无法显示上传的图片/视频

原因：S3 文件的公开访问 URL 不正确。

解决：

  • AWS S3：无需 S3_PUBLIC_CUSTOM_DOMAIN，默认用 https://<bucket>.s3.<region>.amazonaws.com/...
  • MinIO 内网：需要 S3_PUBLIC_CUSTOM_DOMAIN 指向 MinIO 的可访问地址（如 https://storage.example.com）
  • Cloudflare R2：S3_PUBLIC_CUSTOM_DOMAIN 设为 R2 公开域名

Q5：SSRF_ALLOWED_HOSTS 配置后 Builder SMTP 测试仍报错

原因：该参数只影响 Builder 内 Send Email block 的 SMTP 配置测试，不影响实际发送（实际发送仍走 SMTP 环境变量）。且 RFC1918 私有地址段默认已允许，不需要额外配置。

八、参考链接