Trigger.dev 保姆级部署教程：TypeScript 原生 AI 工作流与长任务编排平台，Docker Compose 一键自托管

本文所有命令与配置均照搬 Trigger.dev 官方仓库 README（github.com/triggerdotdev/trigger.dev）与官方文档《Self-hosting → Docker compose》（trigger.dev/docs/self-hosting/docker），未作任何改动与发挥。信息核验日期：2026-11-01。

一、项目介绍

Trigger.dev 是一个开源的、面向 TypeScript 的 AI 工作流与后台任务编排平台（官方 README 副标题："Build and deploy fully-managed AI agents and workflows"）。它把"长时间运行、可重试、带队列、可观测、弹性伸缩"的任务（Task）作为一等公民，开发者在自己的代码库里用 task({...}) 定义任务，部署到 Trigger.dev 后即可获得持久化执行、自动重试、队列并发、断点续跑（checkpointing）、人工审批（waitpoints）、实时流式（Realtime / LLM streaming）等能力，解决了 AWS Lambda、Vercel Function 等 Serverless 平台"超时即失败"的痛点。

官方同时提供托管云（cloud.trigger.dev）与自托管两种形态；本文聚焦自托管。项目在 GitHub（triggerdotdev/trigger.dev）持续活跃维护（核验日期 2026-11-01），许可证为 Apache-2.0。

二、功能拆解

按官方 README「Key features」与官方文档，核心能力如下：

三、官方/GitHub 链接

• GitHub 仓库：https://github.com/triggerdotdev/trigger.dev
• 官方网站：https://trigger.dev
• 官方文档：https://trigger.dev/docs
• 自托管总览：https://trigger.dev/docs/self-hosting/overview
• Docker Compose 自托管：https://trigger.dev/docs/self-hosting/docker
• Kubernetes / Helm：https://trigger.dev/docs/self-hosting/kubernetes
• 云服务：https://cloud.trigger.dev
• Discord：https://trigger.dev/discord

四、环境要求

官方《Docker compose》文档「Requirements」一节明确给出：

• 前置依赖： Docker 20.10.0+、Docker Compose 2.20.0+。
• Webapp 机器（跑 webapp、postgres、redis 及相关服务）：3+ vCPU、6+ GB RAM。
• Worker 机器（跑 supervisor 与所有 run）：4+ vCPU、8+ GB RAM。
• Webapp 与 Worker 可同机（测试）或分机（生产，便于水平扩 worker）。
• 官方给出容量估算公式：并发数 × 单任务规格 = 所需 CPU/内存，例如 10 并发 × small-1x（0.5 vCPU / 0.5 GB）= 5 vCPU + 5 GB。
• 端口： Webapp 默认对外暴露 8030（官方原文："You should now be able to access the webapp at http://localhost:8030"）。

五、部署步骤

官方文档将部署分为 Webapp、Worker 两段，同机可合并。下面按官方原文逐步给出。

步骤 1：克隆仓库（含 hosting/docker 目录）

git clone --depth=1 https://github.com/triggerdotdev/trigger.dev
cd trigger.dev/hosting/docker

逐段解释：git clone --depth=1 浅克隆，只取最新一次提交以加快速度；https://github.com/triggerdotdev/trigger.dev 是官方仓库；cd trigger.dev/hosting/docker 进入官方自托管 Compose 配置目录。

预期输出参考： git 克隆进度，最后进入该目录、无报错。

步骤 2：生成 .env 并填充强随机密钥（官方原命令）

cp .env.example .env
./generate-secrets.sh

逐段解释：cp .env.example .env 把官方示例环境变量模板复制为实际配置文件；./generate-secrets.sh 是官方自带脚本，"Fills the required secrets in .env with strong, unique values. Safe to re-run - it never overwrites a secret you've already set"——它会把应用密钥与内置数据存储（postgres/redis 等）口令填成强随机值。官方警告：这把加密密钥与会话密钥一旦轮转，已加密数据与现有会话将失效，请妥善保管。

预期输出参考： 脚本运行后在 .env 中写入若干随机密钥；无报错即成功。

步骤 3（Webapp）：启动 webapp 栈

cd webapp
docker compose up -d

逐段解释：cd webapp 进入 webapp 子目录（内含官方 docker-compose.yml）；docker compose up -d 按官方 compose 定义后台拉起 webapp、postgres、redis、clickhouse、内置 registry 与对象存储等容器。

预期输出参考： 拉取镜像、创建容器的日志，最终回到命令行提示符。首次运行 webapp 会向控制台打印 Worker Token（只显示一次，官方原文："WARNING: This will only be shown once. Save it now!"），形如：

==========================
Trigger.dev Bootstrap - Worker Token

WARNING: This will only be shown once. Save it now!

Worker group:
bootstrap

Token:
tr_wgt_fgfAEjsTmvl4lowBLTbP7Xo563UlnVa206mr9uW6
...
==========================

步骤 4：查看 magic link 登录链接

docker compose logs -f webapp

逐段解释：官方原文："When logging in, check the container logs for the magic link"——默认未配置邮件服务时，magic link 不会真正发出邮件，而是打印在 webapp 容器日志里。-f 持续跟踪，Ctrl+C 退出（不停止容器）。

预期输出参考： 日志中出现形如 https://localhost:8030/magic?token=... 的登录链接。

步骤 5（可选，初始化新项目）：

npx trigger.dev@latest init -p <project-ref> -a http://localhost:8030

逐段解释：npx trigger.dev@latest 临时拉取官方 CLI；init 在该自托管实例上初始化一个项目；-p <project-ref> 指定项目引用名；-a http://localhost:8030 指定 API 地址指向本机 webapp。

步骤 6（Worker，分机部署时）：

在另一台机器上同样克隆仓库、cp .env.example .env（不要在 worker 上再跑 generate-secrets.sh，官方明确警告会导致 MANAGED_WORKER_SECRET 不一致），把 webapp 启动时打印的 Worker Token 填进 worker 侧 .env：

cd worker
docker compose up -d

逐段解释：worker 容器启动 supervisor，按 TRIGGER_WORKER_TOKEN 连到 webapp 领取任务。官方原文："For a split webapp/worker setup, set MANAGED_WORKER_SECRET on the worker to the same value as the webapp's"。

步骤 7（同机合并部署，官方原命令）：

若想 webapp 与 worker 跑在同一台机器，官方原文：

docker compose -f webapp/docker-compose.yml -f worker/docker-compose.yml up -d

逐段解释：用 -f 同时加载两份 compose 文件叠加；同机部署时 worker 引导会自动完成，无需手工从日志抄 token。

六、配置参数详解

官方 .env.example 中的关键变量（按官方文档「Authentication」「Registry setup」「Object storage」「Version locking」节摘录）：

内置 Registry 默认凭据（官方「Registry setup」节）：

官方警告："You should change these before deploying to production, especially the password"，改密码需编辑 ./hosting/docker/registry/auth.htpasswd。

内置对象存储默认凭据（官方「Object storage」节）：

默认 bucket 为 packets；官方建议生产环境建专用子用户而非使用 root 凭据。

七、启动与运维

• 启动： docker compose up -d（webapp 目录或合并目录）。
• 停止： docker compose down。
• 查看日志： docker compose logs -f webapp（看 magic link / 启动错误）；docker compose logs -f worker。
• 开机自启： 官方 compose 未在文档中单独声明 restart policy；如需容器随 Docker 守护进程自动拉起，可在 compose 服务中追加 restart: unless-stopped（属 Docker 平台通用机制，非 Trigger.dev 官方文档内容）。
• 修改对外端口： 官方默认 webapp 监听 8030；如需改端口，在 compose 中改 ports 映射（如 18030:8030），并相应调整 npx trigger.dev init -a ... 与 OAuth 回调 URL。
• 数据持久化： 官方 compose 内部使用命名卷保存 postgres、redis、clickhouse、registry、对象存储数据；升级前官方警告"keep data safe"，对应卷位于 docker volume ls 列出的 webapp/worker 项目卷中。
• 登录 registry（每台执行 deploy 的机器）：

docker login -u <username> <registry>

逐段解释：官方原文："You will have to login to the registry on every machine that runs the deploy command"。执行后按提示输入密码。
- 把现有用户提为 admin： 官方说明二选一——新用户设 ADMIN_EMAILS 环境变量后再注册；老用户直接在数据库 user 表把 admin 字段置为 true。
- 创建额外 worker group（需 admin PAT）：

curl -X POST \
  "$api_url/admin/api/v1/workers" \
  -H "Authorization: Bearer $admin_pat" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"$wg_name\"}"

八、实操验证

1. 浏览器访问 http://localhost:8030（官方原文："You should now be able to access the webapp at http://localhost:8030"）。
2. 在登录页输入邮箱，官方未配置邮件时，magic link 不会发出；执行 docker compose logs -f webapp 找到形如 https://localhost:8030/magic?token=... 的链接，在浏览器打开即登录成功。
3. 登录后进入 Dashboard，按 npx trigger.dev@latest init -p <project-ref> -a http://localhost:8030 初始化第一个项目。
4. 在自己的代码库里写一个最简单的任务并 npx trigger.dev@latest deploy 部署；回到 Dashboard 应能看到该 project 与一次 run，点进去能看到完整 trace 视图（对应 README 中的 trace-view 截图）。
5. 验证内置对象存储：浏览器打开 http://localhost:9001，用默认 admin / very-safe-password 登录，应能看到 packets bucket。

登录与安全（重要）

• 官方默认账号密码：无内置用户。 Trigger.dev 自托管没有出厂账号，第一个用户通过 magic link 或 GitHub OAuth 注册；注册的第一个邮箱若命中 ADMIN_EMAILS 正则则自动成为 admin。
• 登录地址： http://localhost:8030。
• magic link： 默认 EMAIL_TRANSPORT 未设置时，链接打印在 webapp 容器日志中；生产必须配置 EMAIL_TRANSPORT=resend/smtp/aws-ses 之一，否则任何人翻日志都能拿到登录链接。
• 修改密码： Trigger.dev 不设传统密码，登录态靠 magic link / OAuth；撤销会话可在 Dashboard 账户设置或数据库层面处理。
• 密码/密钥存放位置： 应用密钥与数据存储口令在 .env 文件中（generate-secrets.sh 写入）；JWT/session 加密密钥由 DAGU_* 风格的应用密钥管理。官方警告：.env 中的加密密钥一旦丢失或被轮转，已加密数据与现有会话将全部失效。
• 安全提醒：
  1. 部署后必须立即修改内置 registry 默认口令 registry-user / very-secure-indeed 与对象存储 root 口令 admin / very-safe-password；
  2. 生产环境必须配置真实邮件服务（resend/smtp/aws-ses），不要依赖日志里的 magic link；
  3. 用 WHITELISTED_EMAILS 限制可注册邮箱；
  4. 官方原文："This guide alone is unlikely to result in a production-ready deployment. Security, scaling, and reliability concerns are not fully addressed here"——公网部署前请自行加反向代理、TLS、访问控制。

九、故障排查

案例 1：Worker 启动后无法连到 webapp / 认证失败

• 报错原文（常见形式）：worker 容器日志出现 unauthorized / authentication failed / worker 反复重连。
• 报错原因：官方文档明确警告——在分机部署时，如果在 worker 上又跑了一次 generate-secrets.sh，worker 的 MANAGED_WORKER_SECRET 会与 webapp 不一致；或 webapp 首次启动打印的 Worker Token 没有正确填到 worker 的 .env。
• 分步解决：① 在 webapp 主机 cd trigger.dev/hosting/docker/webapp && docker compose logs webapp，找到 Trigger.dev Bootstrap - Worker Token 段；② 把 TRIGGER_WORKER_TOKEN=tr_wgt_... 填到 worker 主机 .env；③ 确认 worker 上不要再跑 ./generate-secrets.sh；④ cd worker && docker compose down && docker compose up -d 重启。

案例 2：访问 8030 看不到 magic link，登录页输入邮箱后无反应

• 报错原因：未配置 EMAIL_TRANSPORT，官方行为是把 magic link 打印到 webapp 日志而不真正发信。
• 分步解决：① docker compose logs -f webapp 翻日志找 https://.../magic?token=...；② 生产环境按官方「Authentication」节配置 EMAIL_TRANSPORT=smtp 及 SMTP_HOST/PORT/USER/PASSWORD 等；③ docker compose up -d 重启生效。

案例 3：deploy 任务时 docker login / push 到内置 registry 失败

• 报错原文（常见形式）：docker login: authentication required 或 denied: requested access to the resource is denied。
• 报错原因：官方「Logging in」节要求每台执行 deploy 的机器都要先 docker login -u <username> <registry>，且默认口令仍是 very-secure-indeed。
• 分步解决：① 确认 registry 地址（默认 localhost:5000，分机部署时改成 webapp 主机可达地址）；② docker login -u registry-user localhost:5000，密码输入 very-secure-indeed（或你改过的口令）；③ 生产环境务必编辑 ./hosting/docker/registry/auth.htpasswd 修改默认口令后再对外。

案例 4：自托管后 CLI 报 v3 任务不被支持

• 报错原文（官方文档原文）："4.5.1 and later reject v3 triggers and deploys with an upgrade message"。
• 报错原因：官方说明 Trigger.dev 4.5.0 是最后一个支持 v3 SDK 任务的版本；4.5.1+ 必须迁移到 v4 SDK。
• 分步解决：① 若仍有 v3 任务，在 .env 中把 TRIGGER_IMAGE_TAG 锁到 v4.5.0；② 或按官方迁移指南把 SDK 升到 v4 后再用 latest 镜像。

十、升级、回滚与卸载

升级： 官方「Version locking」节说明默认镜像走 latest tag；升级即：

git pull
cd webapp && docker compose pull && docker compose up -d
cd ../worker && docker compose pull && docker compose up -d

逐段解释：git pull 拉取新版 hosting/docker 配置；docker compose pull 拉新镜像；docker compose up -d 用新镜像重建容器。官方提醒："We patch the latest released version line only, so keep an eye on new releases to receive security fixes"。升级前务必确认 .env 中的数据卷已正确挂载，避免数据丢失。

回滚： 官方未提供一键回滚命令；可在 .env 中把 TRIGGER_IMAGE_TAG 改回旧版本号（如 v4.5.0），再 docker compose pull && docker compose up -d。由于 postgres/clickhouse 数据卷独立于镜像，回滚时需自行确认旧镜像与新 schema 是否兼容（官方建议生产升级前先备份数据卷）。

卸载：

cd trigger.dev/hosting/docker
docker compose down          # webapp 目录
docker compose down          # worker 目录

如需彻底清理数据（永久删除所有任务运行记录、用户、部署产物），再删除命名卷：

docker volume ls | grep -E "webapp|worker" | awk '{print $2}' | xargs -r docker volume rm

注意：官方未在文档中给出"卸载"专章，上述卷清理基于 Docker 平台通用机制，操作前请先备份 .env 与数据卷。

十一、商用许可合规说明

• 许可证：Apache License 2.0（官方 README 徽章与仓库 LICENSE 文件明确）。
• Apache-2.0 允许自由使用、修改、分发与商用；分发时须保留版权声明与许可文本，修改过的文件须标注变更，并附带 NOTICE（如有）。
• Trigger.dev 同时提供商业云（cloud.trigger.dev）作为可选托管；自托管 OSS 版本商用无需付费授权。但官方文档提示："As self-hosted deployments tend to have unique requirements and configurations, we don't provide specific advice for securing your deployment, scaling up, or improving reliability"——生产级安全、高可用、扩容需自行负责或转用其商业云。