任务队列 · Bunship 文档中心

可插拔的任务队列，支持 Trigger.dev 和 BullMQ，通过环境变量自动切换。

Bunship 的 AI 生成流水线使用可插拔任务队列，当前支持两种后端。系统会根据你配置的环境变量自动选择后端。

后端对比

	Trigger.dev	BullMQ
任务运行位置	Trigger.dev 云端	你的服务器
Vercel Hobby (10s)	✅ 可用	❌ 无持久进程
Vercel Pro (300s)	✅ 可用	❌ 无持久进程
自建服务器 (VPS)	✅ 可用	✅ 可用
是否依赖 Redis	否	是
卡住任务恢复	云端定时任务	setInterval

自动检测

系统按优先级检测环境变量：

TRIGGER_SECRET_KEY  ->  Web/API 运行时使用 Trigger.dev adapter（最高优先级）
REDIS_URL           ->  Web/API 或独立 API 运行时使用 BullMQ
（默认回退）          ->  BullMQ

无需改代码，只需要配置正确环境变量。

方案 A：Trigger.dev（推荐 Vercel）

最适合 Vercel 部署。任务在 Trigger.dev 云端执行。

配置步骤

在 cloud.trigger.dev 创建项目
记录 Project ID 和用于 Web/API 投递任务的 Secret Key
确认 SDK 版本与 CLI 一致。当前仓库在 apps/ship-api/package.json 中固定为 4.4.6：

@trigger.dev/sdk=4.4.6
@trigger.dev/build=4.4.6
trigger.dev CLI=4.4.6

在 Web/API 容器运行时配置投递变量：

TRIGGER_SECRET_KEY=sk_dev_你的密钥
TRIGGER_PROJECT_ID=你的项目ID

TRIGGER_SECRET_KEY 用于应用侧把任务投递到 Trigger.dev，不是 Docker build 变量，也不是 Trigger 云端 task runtime 必填变量。

本地开发

# 终端 1：启动 Trigger.dev 本地 worker
cd apps/ship-api
bun run trigger:dev

# 终端 2：启动应用
bun run dev

部署任务

手动部署：

cd apps/ship-api
bun run trigger:deploy

会注册 ai-generate 和 ai-stale-recovery（定时任务）。

如果你的本地 shell 存在 OTEL_* 环境变量（如 Shelltime 等监控工具注入），部署会报错 cannot merge resource due to conflicting Schema URL。请清除这些变量后再部署，或使用下方的 CI 工作流。

CI/CD 部署（GitHub Actions）

项目中 .github/workflows/deploy-trigger.yml 工作流会在推送到 main 时自动部署任务。

触发条件：

推送到 main 且修改了 Trigger 任务目录、apps/ship-api/package.json、trigger.config.ts 或 workflow
在 Actions 页面手动触发

需要配置的 GitHub Secrets / Variables：

Secret	说明
`TRIGGER_ACCESS_TOKEN`	Personal Access Token（`tr_pat_` 开头），在 cloud.trigger.dev/account/tokens 生成
`TRIGGER_PROJECT_ID`	你的 Trigger.dev 项目 ref（如 `proj_xxx`）。主仓库如果 `trigger.config.ts` 中默认值正确则可不设

Fork 仓库： Fork 用户在自己仓库的 Settings → Secrets 中配置自己的 TRIGGER_ACCESS_TOKEN 和 TRIGGER_PROJECT_ID，工作流会部署到各自的 Trigger.dev 项目，不会与上游仓库冲突。

三类 Trigger 相关变量不要混用

场景	变量	放在哪里
部署任务	`TRIGGER_ACCESS_TOKEN`, `TRIGGER_PROJECT_ID`	GitHub Secrets / Variables，供 `.github/workflows/deploy-trigger.yml` 使用
Web/API 投递任务	`TRIGGER_SECRET_KEY`, 可选 `TRIGGER_PROJECT_ID`	Web/API 容器 runtime env
Trigger 云端任务执行	`DATABASE_URL`, `S3_*`, `PUBLIC_S3_URL_BASE`, provider API keys, AI 调优变量	Trigger.dev 项目 Environment Variables，或由 `trigger.config.ts` 的 `syncEnvVars` 同步

生产环境变量（Trigger.dev 云端 task runtime）

部署后任务运行在 Trigger.dev 云端。请在 Trigger.dev 项目 prod 环境的 Environment Variables 中配置：

变量名	是否必填	用途
`DATABASE_URL`	是	任务状态、计费、恢复的数据读写
`S3_ENDPOINT`	是	对象存储端点
`S3_REGION`	是	对象存储地域
`S3_ACCESS_KEY`	是	对象存储 Access Key
`S3_SECRET_KEY`	是	对象存储 Secret Key
`S3_BUCKET`	是	结果输出 Bucket
`PUBLIC_S3_URL_BASE`	是	结果文件对外访问 URL 前缀；旧变量 `NEXT_PUBLIC_S3_URL_BASE` 仍兼容
`SITE_URL`	建议	生成绝对链接时使用
`PUBLIC_AUTH_PROVIDER`	建议	任务导入 auth 相关代码时保持 provider 一致
`AUTH_SECRET` / `BETTER_AUTH_SECRET`	Better Auth 时建议	任务导入 auth 相关代码时可能需要

按 provider 启用的变量（按需配置）：

变量名	需要时机
`FAL_API_KEY`	使用 fal provider 时
`REPLICATE_API_TOKEN`	使用 replicate provider 时
`KIE_API_KEY`	使用 kie provider 时
`KIE_API_BASE_URL`	可选，覆盖 kie 默认 API 地址
`OPENAI_API_KEY`	使用 CMS/管理端 AI copilot 时
`OPENAI_API_BASE`	可选，OpenAI-compatible base URL
`OPENAI_API_MODEL`	可选，默认模型覆盖

可选调优变量：

变量名	默认值	说明
`AI_TASK_RETRY_BASE_DELAY_MS`	`2000`	任务重试基础延迟
`AI_TASK_RETRY_MAX_DELAY_MS`	`60000`	任务重试最大延迟
`AI_TRIGGER_RUN_GUARD_TIMEOUT_MS`	`270000`	Trigger 任务执行保护超时
`AI_TRIGGER_RELEASE_TIMEOUT_MS`	`2000`	Trigger 释放并发槽超时
`AI_OUTBOX_WORKER_ENABLED`	`1`	设置 `0` 可禁用 outbox worker
`AI_TASK_HEARTBEAT_AUDIT`	`1`	设置 `0` 可关闭 heartbeat audit

方案 B：BullMQ

适合自建部署（Railway、Fly.io、VPS 等持久进程环境）。

前提条件

Redis（Upstash、Railway Redis 或自建）
持久运行进程（非 serverless）

配置步骤

配置 REDIS_URL，并确保没有 TRIGGER_SECRET_KEY：

REDIS_URL=redis://你的redis地址:6379

以独立服务部署 ship-api：

cd apps/ship-api
bun run src/index.ts

BullMQ worker 会自动启动（含准入、重试、卡住任务扫描）。

卡住任务恢复

无论使用哪种后端，Bunship 都内置自动恢复与退款机制。

后端	恢复机制
Trigger.dev	`ai-stale-recovery` 云端定时任务（每 5 分钟）
BullMQ	持久 worker 进程中的 `setInterval`

代码位置

apps/ship-api/src/services/ai/queue/
├── types.ts              # TaskQueueAdapter 接口
├── processor.ts          # 公共执行逻辑
├── adapter-bullmq.ts     # BullMQ 实现
├── adapter-trigger.ts    # Trigger.dev 实现
└── index.ts              # 自动检测 + adapter 导出

下一步

AI 图片工作流

从请求到交付的完整生成链路。

AI 供应商集成

配置模型目录、供应商接入和限流策略。

部署

部署到 Vercel、Railway 或你自己的服务器。