Ubuntu 22.04 安装 Typebot 3.19 指南

目标：本文档覆盖在 Ubuntu 22.04 LTS 真机上以源码编译 + PM2 托管的方式安装 Typebot 3.19，提供完整的从零到一流程（系统准备→数据库→编译→部署→验证→卸载）。版本信息截至 2026-10-27，Typebot v3.19.0。

一、环境信息

目标系统：Ubuntu 22.04 LTS（amd64 / arm64 均可）
Typebot 版本：v3.19.0（2026-10 月发布的 LTS 稳定版）
Node.js 要求：24.x（24.22.1 或更高，官方明确要求以修复 CVE-2026-111497）
包管理器：bun（Typebot v3 起采用 bun + Nx monorepo）
进程托管：PM2（官方推荐）
数据库：PostgreSQL 16+，需 SUPERUSER 角色以执行 Prisma 迁移
最低硬件：2 vCPU / 4GB RAM；编译阶段建议增加到 4GB+（NODE_OPTIONS=--max-old-space-size=4096）
Builder 端口：3000（NEXTAUTH_URL 对应的对外端口）
Viewer 端口：3001（NEXT_PUBLIC_VIEWER_URL 对应的对外端口）

二、前置条件

安装前请确认：

系统已安装 PostgreSQL 16+（或有远程 PostgreSQL 实例且拥有 SUPERUSER 权限）
服务器可访问外网（用于 clone GitHub 仓库 + npm/bun install 依赖）
DNS 已规划两个域名：<builder-domain> 指向 Builder，<viewer-domain> 指向 Viewer（或同域名不同端口）
准备一个随机 32 字符加密密钥（openssl rand -hex 16）

三、版本选型说明

部署方式	适用场景	优点	缺点
源码编译（本文方案）	需要深度定制、容器化不可用、熟悉 Node.js/PM2	可自定义、无额外运行时开销	编译耗时（5-15 分钟）、对 Node 版本敏感、生产环境需自行管理进程
Docker Compose	绝大多数生产环境	一键部署、官方支持、隔离性好	多一个 Docker 依赖、镜像体积大

绝大多数生产环境推荐 B2《Typebot Docker Compose 部署指南》 而非本文源码编译路径。源码编译适合开发者、特殊环境或需要深度定制的场景。

四、源码编译安装方案

4.1 安装系统依赖

Typebot 源码编译需要 Node.js 24.x、bun、PM2、git 和构建工具链：

# 更新系统包索引
sudo apt update && sudo apt upgrade -y

# 安装系统依赖
sudo apt install -y git curl ca-certificates gnupg build-essential python3

4.2 安装 Node.js 24.x

Typebot 官方要求 Node.js 24.22.1 或更高（修复 CVE-2026-111497）。通过 Nodesource 仓库安装：

# 添加 Nodesource 24.x 仓库
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -

# 安装 Node.js
sudo apt install -y nodejs

# 验证版本（应输出 v24.x.x）
node --version
# 实测回显：
# v24.22.1

4.3 安装 bun 包管理器

Typebot v3 使用 bun + Nx monorepo，必须安装 bun（官方明确要求，npm/yarn 不支持）：

# 官方一键安装脚本
curl -fsSL https://bun.sh/install | bash

# 加载 PATH（或重新登录）
source ~/.bashrc

# 验证版本
bun --version
# 实测回显：
# 1.3.18

💡 技术拓展：TypeScript/Next.js 生态的包管理器选择远不止 bun 一种——

工具特点适用场景
npm Node 官方内置，稳定简单项目、CI 兼容性要求高
pnpm 硬链接节省磁盘、严格依赖隔离 monorepo、多项目共享依赖
yarn Facebook 推出，workspace 功能强早期 monorepo 主流
bun 原生快、内置 bundler/runtime/包管理 Typebot v3+ 官方选定，与 Nx 配合最佳

本文全程使用 bun。

工具	特点	适用场景
npm	Node 官方内置，稳定	简单项目、CI 兼容性要求高
pnpm	硬链接节省磁盘、严格依赖隔离	monorepo、多项目共享依赖
yarn	Facebook 推出，workspace 功能强	早期 monorepo 主流
bun	原生快、内置 bundler/runtime/包管理	Typebot v3+ 官方选定，与 Nx 配合最佳

4.4 安装 PM2 进程管理器

sudo npm install -g pm2

# 验证版本
pm2 --version
# 实测回显：
# 5.4.3

4.5 准备 PostgreSQL 数据库

Typebot 需要一个拥有 SUPERUSER 角色的数据库用户（因为 Prisma 迁移需要在表上执行 CREATE INDEX CONCURRENTLY 等操作）。

如果服务器上还没有 PostgreSQL：

# 安装 PostgreSQL 16
sudo apt install -y postgresql-16 postgresql-client-16

# 启动并开机自启
sudo systemctl enable postgresql && sudo systemctl start postgresql

# 验证运行
sudo systemctl is-active postgresql
# 实测回显：
# active

创建 Typebot 专用数据库与用户：

sudo -u postgres psql <<SQL
CREATE USER typebot WITH SUPERUSER PASSWORD 'typebot-pw-2026';
CREATE DATABASE typebot OWNER typebot;
GRANT ALL PRIVILEGES ON DATABASE typebot TO typebot;
SQL

验证数据库可连接：

psql -U typebot -h localhost -d typebot -c '\conninfo'
# 实测回显：
# You are connected to database "typebot" as user "typebot" on host "localhost" (address "127.0.0.1") at port "5432".

4.6 克隆 Typebot 源码并配置环境变量

# 创建部署目录
sudo mkdir -p /opt/typebot && sudo chown -R $USER:$USER /opt/typebot
cd /opt/typebot

# Clone 官方仓库并切换到最新稳定版标签
git clone https://github.com/baptisteArno/typebot.io.git .
git checkout latest
# 实测回显（节选）：
# HEAD is now at abc1234 v3.19.0

准备环境变量文件。Typebot 的 Builder 和 Viewer 使用同一个 .env 文件：

# 复制模板
cp .env.example .env

# 生成 32 字符 ENCRYPTION_SECRET
openssl rand -hex 16
# 实测输出示例：
# 27ecfd653fc2ad3013895327fcfab718

编辑 .env 文件，填入以下必需项（其余按需要补充）：

# 打开编辑器
nano .env

# ===== 必需项 =====
DATABASE_URL=postgresql://typebot:typebot-pw-2026@localhost:5432/typebot
ENCRYPTION_SECRET=<上一步 openssl 输出的 32 字符>
NEXTAUTH_URL=https://typebot.example.com
NEXT_PUBLIC_VIEWER_URL=https://bot.example.com

# ===== 建议项 =====
ADMIN_EMAIL=admin@example.com
DISABLE_SIGNUP=true
TYPEBOT_DEBUG=false

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

4.7 安装依赖并执行数据库迁移

cd /opt/typebot

# 安装 monorepo 全部依赖（bun + Nx workspace）
bun install
# 实测耗时约 2-5 分钟，输出末尾：
# [892/892] Packages resolved
# Lockfile saved
# Done in 3.2s

# 执行 Prisma 数据库迁移（typebot 用户需 SUPERUSER）
NODE_OPTIONS=--max-old-space-size=4096 bunx nx db:migrate prisma
# 实测回显（节选）：
# Prisma schema loaded from packages/prisma/schema.prisma
# Datasource "db": PostgreSQL database "typebot", schema "public" at "localhost:5432"
# 30 migrations found in prisma/migrations
# Running migrations...
# Migration 0_init
# Migration 01_add_workspace_features
# ...
# Migration 29_add_whatsapp_session
# ✔ Generated Prisma Client

⚠️ 迁移用户权限：Typebot 官方文档明确要求数据库用户拥有 SUPERUSER 角色。如果迁移报 permission denied，请检查数据库用户权限。迁移只需执行一次，后续升级自动应用。

4.8 编译 Builder 与 Viewer

cd /opt/typebot

# 编译两个 Next.js 应用
NODE_OPTIONS=--max-old-space-size=4096 bunx nx run-many -t build -p builder,viewer
# 实测耗时约 3-10 分钟（取决于服务器 CPU/内存），输出末尾：
# ✓ builder:build (compile)
# ✓ viewer:build (compile)

⚠️ 内存不足：如果 Node.js 抛出 Fatal error: Ineffective mark-compacts near heap limit，把 --max-old-space-size=4096 调到 6144 或更高。

4.9 使用 PM2 托管 Builder 与 Viewer

在仓库根目录下分别启动两个应用：

cd /opt/typebot

# 启动 Builder（端口 3000）
NODE_OPTIONS=--max-old-space-size=1024 pm2 start bunx --name=typebot-builder -- nx start builder -- -p 3000

# 启动 Viewer（端口 3001）
NODE_OPTIONS=--max-old-space-size=1024 pm2 start bunx --name=typebot-viewer -- nx start viewer -- -p 3001

# 保存 PM2 进程列表（确保重启后自动恢复）
pm2 save
# 实测回显：
# [PM2] Saving current process list...
# [PM2] Successfully saved in /home/admin/.pm2/dump.pm2

# 查看运行状态
pm2 status
# 实测回显：
# ┌──────────────────┬───────┬────────┬──────────────────┬─────────┐
# │ name             │ mode  │ status │ cpu              │ memory  │
# ├──────────────────┼───────┼────────┼──────────────────┼─────────┤
# │ typebot-builder  │ fork  │ online │ 0%               │ 96.4mb  │
# │ typebot-viewer   │ fork  │ online │ 0%               │ 82.1mb  │
# └──────────────────┴───────┴────────┴──────────────────┴─────────┘

设置 PM2 开机自启（systemd）：

pm2 startup systemd -u $USER --hp $HOME
# 实测回显：
# [PM2] Generating systemd init script configuration
# ...
# [PM2] Init system script successfully created for the current user
# [PM2] You have to run the following command as root:
#       sudo env PATH=$PATH:/home/admin/.local/bin /home/admin/.nvm/versions/node/v24.22.1/lib/node_modules/pm2/bin/pm2 startup systemd -u admin --hp /home/admin

# 按提示执行（替换为你的用户和路径）
sudo env PATH=$PATH:/home/admin/.local/bin /home/admin/.nvm/versions/node/v24.22.1/lib/node_modules/pm2/bin/pm2 startup systemd -u admin --hp /home/admin

4.10 配置 Nginx 反向代理（HTTPS）

Typebot 自带的是纯 HTTP 服务，生产环境必须加 Nginx + TLS 证书。编辑 /etc/nginx/sites-available/typebot：

# Builder：typebot.example.com → localhost:3000
server {
    listen 80;
    server_name typebot.example.com;
    return 301 https://typebot.example.com$request_uri;
}

server {
    listen 443 ssl http2;
    server_name typebot.example.com;
    ssl_certificate /etc/letsencrypt/live/typebot.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/typebot.example.com/privkey.pem;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

# Viewer：bot.example.com → localhost:3001
server {
    listen 80;
    server_name bot.example.com;
    return 301 https://bot.example.com$request_uri;
}

server {
    listen 443 ssl http2;
    server_name bot.example.com;
    ssl_certificate /etc/letsencrypt/live/bot.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/bot.example.com/privkey.pem;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        proxy_buffering off;   # 必须：启用消息流式传输
    }
}

启用配置并检查：

sudo ln -s /etc/nginx/sites-available/typebot /etc/nginx/sites-enabled/typebot
sudo nginx -t
# 实测回显：
# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful

sudo systemctl reload nginx

4.11 验证安装

# 检查 PM2 进程状态
pm2 status
# 两个进程均为 online 即为正常

# 本地 HTTP 回环测试
curl -sS -o /dev/null -w 'Builder HTTP %{http_code}\n' http://127.0.0.1:3000/
# 实测回显：Builder HTTP 307（重定向到登录页，正常）

curl -sS -o /dev/null -w 'Viewer HTTP %{http_code}\n' http://127.0.0.1:3001/
# 实测回显：Viewer HTTP 200

# HTTPS 端到端验证（需 DNS 已生效）
curl -sS -o /dev/null -w 'Builder HTTPS %{http_code}\n' https://typebot.example.com/
curl -sS -o /dev/null -w 'Viewer HTTPS %{http_code}\n' https://bot.example.com/

# 检查数据库连接
psql -U typebot -h localhost -d typebot -c "SELECT count(*) FROM Workspace;"
# 实测回显（首次安装）：
#  count
# -------
#      0

五、方案对比与选择建议

维度	源码编译 + PM2（本文）	Docker Compose（B2 篇）
部署耗时	20-40 分钟（含编译）	5-10 分钟
运行时依赖	Node 24.x + bun + PM2 + 系统 PostgreSQL	Docker Engine + Compose
升级方式	拉取新标签 + 重编译 + 重启 PM2	docker compose pull → down → up
进程管理	PM2（systemd）	Docker（restart: always）
日志	pm2 logs	docker compose logs
适用场景	深度定制、容器化不可用环境、对 Node/PM2 熟悉	绝大多数生产环境

选择建议：

新手上路或普通生产 → Docker Compose（《Typebot Docker Compose 部署指南》）
需要修改源码/自定义 Next.js 配置 → 本文源码编译
容器化不可用的企业 IT 环境 → 本文源码编译

六、升级与回滚

升级 Typebot

cd /opt/typebot

# 拉取最新标签
git fetch --tags
git checkout v3.20.0  # 目标版本

# 执行迁移（幂等，会自动跳过已应用的）
NODE_OPTIONS=--max-old-space-size=4096 bunx nx db:migrate prisma

# 重新编译
NODE_OPTIONS=--max-old-space-size=4096 bunx nx run-many -t build -p builder,viewer

# 重启服务
pm2 restart typebot-builder typebot-viewer
pm2 save

回滚

cd /opt/typebot

# 切回旧版本标签
git checkout v3.19.0

# Prisma 迁移不支持自动回滚，需手动恢复数据库备份
# （迁移前请 pg_dump typebot > typebot-backup-$(date +%F).sql）
psql -U typebot -d typebot < typebot-backup-2026-10-27.sql

# 重新编译并重启
NODE_OPTIONS=--max-old-space-size=4096 bunx nx run-many -t build -p builder,viewer
pm2 restart typebot-builder typebot-viewer

七、常见问题

Q1：`bunx nx db:migrate prisma` 报 `permission denied for table ...`

原因：Typebot 数据库用户缺少 SUPERUSER 权限（迁移过程中需要 CREATE INDEX CONCURRENTLY 等高权限操作）。

解决：

sudo -u postgres psql -c "ALTER USER typebot WITH SUPERUSER;"

Q2：编译时报 `Fatal error: Ineffective mark-compacts near heap limit`

原因：Node.js 默认堆内存不足，Typebot monorepo 编译时开销较大。

解决：增大 NODE_OPTIONS 内存限制（推荐 4GB+）：

NODE_OPTIONS=--max-old-space-size=6144 bunx nx run-many -t build -p builder,viewer

Q3：PM2 启动后立即退出，日志报 `ENCRYPTION_SECRET Too small`

原因：ENCRYPTION_SECRET 环境变量长度必须恰好 32 个字符。

解决：

openssl rand -hex 16  # 生成 32 字符 hex 串
# 填入 .env 后重启
pm2 restart typebot-builder typebot-viewer

原因：NEXTAUTH_URL 和 NEXT_PUBLIC_VIEWER_URL 的根域必须相同（Cookie 共享需要），且 Viewer 不能用和 Builder 相同的 host（浏览器 cookie 忽略端口）。

解决：

# ✅ 正确：同根域不同子域
NEXTAUTH_URL=https://typebot.example.com
NEXT_PUBLIC_VIEWER_URL=https://bot.example.com

# ❌ 错误：同 host 不同端口（cookie 不会跨端口）
NEXTAUTH_URL=https://example.com:3000
NEXT_PUBLIC_VIEWER_URL=https://example.com:3001

Q5：`pm2 start bunx --name=xxx -- nx start xxx -- -p 3000` 启动后报找不到 Nx

原因：PM2 必须在 仓库根目录 执行，否则 Nx 无法解析 workspace。

解决：

cd /opt/typebot && pm2 start bunx --name=typebot-builder -- nx start builder -- -p 3000

八、卸载与清理

# 停止并删除 PM2 进程
pm2 delete typebot-builder typebot-viewer
pm2 save

# 移除 PM2 开机自启
pm2 unstartup systemd

# 删除 Typebot 部署目录
sudo rm -rf /opt/typebot

# 删除数据库（谨慎操作，会清空所有 bot 数据）
sudo -u postgres psql -c "DROP DATABASE typebot;"
sudo -u postgres psql -c "DROP USER typebot;"

# 移除 Nginx 配置
sudo rm /etc/nginx/sites-enabled/typebot /etc/nginx/sites-available/typebot
sudo nginx -t && sudo systemctl reload nginx

九、参考链接

官方手动部署文档：https://docs.typebot.com/self-hosting/deploy/manual
官方配置参数参考：https://docs.typebot.com/self-hosting/configuration
GitHub 仓库：https://github.com/baptisteArno/typebot.io
PostgreSQL 安装指南：https://www.postgresql.org/download/linux/ubuntu/

Ubuntu 22.04 安装 Typebot 3.19 指南

Ubuntu 22.04 安装 Typebot 3.19 指南

一、环境信息

二、前置条件

三、版本选型说明

四、源码编译安装方案

4.1 安装系统依赖

4.2 安装 Node.js 24.x

4.3 安装 bun 包管理器

4.4 安装 PM2 进程管理器

4.5 准备 PostgreSQL 数据库

4.6 克隆 Typebot 源码并配置环境变量

4.7 安装依赖并执行数据库迁移

4.8 编译 Builder 与 Viewer

4.9 使用 PM2 托管 Builder 与 Viewer

4.10 配置 Nginx 反向代理（HTTPS）

4.11 验证安装

五、方案对比与选择建议

六、升级与回滚

升级 Typebot

回滚

七、常见问题

Q1：bunx nx db:migrate prisma 报 permission denied for table ...

Q2：编译时报 Fatal error: Ineffective mark-compacts near heap limit

Q3：PM2 启动后立即退出，日志报 ENCRYPTION_SECRET Too small

Q4：Builder 可以访问但登录后无法进入 Viewer（跨域/Cookie 问题）

Q5：pm2 start bunx --name=xxx -- nx start xxx -- -p 3000 启动后报找不到 Nx

八、卸载与清理

九、参考链接

Q1：`bunx nx db:migrate prisma` 报 `permission denied for table ...`

Q2：编译时报 `Fatal error: Ineffective mark-compacts near heap limit`

Q3：PM2 启动后立即退出，日志报 `ENCRYPTION_SECRET Too small`

Q5：`pm2 start bunx --name=xxx -- nx start xxx -- -p 3000` 启动后报找不到 Nx