Bunship任务队列
可插拔的任务队列，支持 Trigger.dev 和 BullMQ，通过环境变量自动切换。
Bunship 的 AI 生成流水线使用可插拔任务队列，当前支持两种后端。系统会根据你配置的环境变量自动选择后端。
后端对比
| Trigger.dev | BullMQ | |
|---|---|---|
| 任务运行位置 | Trigger.dev 云端 | 你的服务器 |
| Vercel Hobby (10s) | ✅ 可用 | ❌ 无持久进程 |
| Vercel Pro (300s) | ✅ 可用 | ❌ 无持久进程 |
| 自建服务器 (VPS) | ✅ 可用 | ✅ 可用 |
| 是否依赖 Redis | 否 | 是 |
| 卡住任务恢复 | 云端定时任务 | setInterval |
自动检测
系统按优先级检测环境变量：
TRIGGER_SECRET_KEY -> Trigger.dev（最高优先级）
（默认回退） -> BullMQ无需改代码，只需要配置正确环境变量。
方案 A：Trigger.dev（推荐 Vercel）
最适合 Vercel 部署。任务在 Trigger.dev 云端执行。
配置步骤
- 在 cloud.trigger.dev 创建项目
- 记录 Project ID 和 Secret Key
- 安装 SDK：
bun add @trigger.dev/sdk- 配置环境变量：
TRIGGER_SECRET_KEY=sk_dev_你的密钥
TRIGGER_PROJECT_ID=你的项目ID本地开发
# 终端 1：启动 Trigger.dev 本地 worker
cd apps/ship-api
npx trigger.dev@latest dev
# 终端 2：启动应用
bun run dev部署任务
手动部署：
cd apps/ship-api
npx trigger.dev@latest 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且修改了apps/ship-api/src/services/ai/queue/**或trigger.config.ts - 在 Actions 页面手动触发
需要配置的 GitHub Secrets：
| 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.dev）
部署后任务运行在 Trigger.dev 云端。请在 Trigger.dev 项目 prod 环境的 Environment Variables 中配置：
| 变量名 | 是否必填 | 用途 |
|---|---|---|
DATABASE_URL | 是 | 任务状态、计费、恢复的数据读写 |
TRIGGER_SECRET_KEY | 是 | Trigger 适配器与 SDK 鉴权 |
S3_ENDPOINT | 是 | 对象存储端点 |
S3_REGION | 是 | 对象存储地域 |
S3_ACCESS_KEY | 是 | 对象存储 Access Key |
S3_SECRET_KEY | 是 | 对象存储 Secret Key |
S3_BUCKET | 是 | 结果输出 Bucket |
NEXT_PUBLIC_S3_URL_BASE | 是 | 结果文件对外访问 URL 前缀 |
TRIGGER_PROJECT_ID | 否 | 项目路由（配置中有默认值） |
按 provider 启用的变量（按需配置）：
| 变量名 | 需要时机 |
|---|---|
FAL_API_KEY | 使用 fal provider 时 |
REPLICATE_API_TOKEN | 使用 replicate provider 时 |
KIE_API_KEY | 使用 kie provider 时 |
KIE_API_BASE_URL | 可选，覆盖 kie 默认 API 地址 |
可选调优变量：
| 变量名 | 默认值 | 说明 |
|---|---|---|
AI_STALE_QUEUE_FAILOVER_MS | 900000 | 陈旧任务判定基础阈值 |
AI_STALE_QUEUE_FAILOVER_GRACE_MS | 120000 | 队列超时后的额外宽限 |
AI_STALE_QUEUE_SCAN_LIMIT | 50 | 每次恢复扫描批量上限 |
方案 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.tsBullMQ 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 导出