> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 后台任务

通过 JobRunner 契约与 Trigger.dev 的持久化工作。

## 安装与配置

在执行任何步骤之前，请阅读[开始之前](https://supastack.dev/zh/docs/web/before-you-start.md) 和[终端基础知识](https://supastack.dev/zh/docs/web/terminal-basics.md)。这些说明假设您在 VS Code 中打开了完整的 supastack monorepo；它的根 package.json 标记存储库根。在 pnpm 命令中，工作区包是应用程序或共享代码文件夹；在产品中，工作空间是团队的数据容器和安全边界。 corepack pnpm --filter ... 从 monorepo 选择一个包，同时从其根运行命令。如果您仅打开同步的移动或桌面文件夹，则它不包含 Web 后端、Docker 设置或根脚本：从此 monorepo 或可访问的托管服务器运行后端，并使用平台文件夹自己的脚本。环境变量是存储在本地 .env 文件或托管仪表板中的命名设置；更改后重新启动相关应用程序，并将服务器机密保留在 NEXT_PUBLIC_ 和 EXPO_PUBLIC_ 值之外。

1.在VS Code中打开apps/web/src/job-handlers.ts和apps/web/src/scheduler-runtime.ts。工作是后台工作；调度程序决定何时将其排队。

2. 对于本地tick，在apps/web/.env.local和repository-root .env中设置相同的SCHEDULER_TICK_SECRET； tick 脚本读取根 .env，而 Web 端点读取其应用程序设置。

3. 使用 corepack pnpm --filter @supastack/web dev 启动 Web，然后运行 corepack pnpm jobs:tick 从根开始。预期：终端显示 localhost:3000 的 POST 结果。 Trigger.dev 是一个独立的提供商，需要自己的帐户和服务器密钥。

为生产任务提交设置 JOB_PROVIDER=trigger，以及仅服务端的 TRIGGER_SECRET_KEY 与 TRIGGER_PROJECT_REF。配置目标项目前，先看 apps/web/trigger.config.ts 与 apps/web/trigger 中的 ai.generate 任务。

```
JOB_PROVIDER=trigger
TRIGGER_PROJECT_REF=your-project-reference
# Provide TRIGGER_SECRET_KEY through the server secret store.
# Local/self-hosted scheduler tick:
# SCHEDULER_TICK_SECRET=…
# SCHEDULER_TICK_URL=http://localhost:3000
```


## 要复制的命令

按照注释查看命令在哪个文件夹中运行。如果标记了两个终端，请打开两个终端窗口，并在使用第二个命令时保持第一个命令运行。

```
# Terminal 1 — start the Web app from the monorepo root:
corepack pnpm --filter @supastack/web dev

# Terminal 2 — run one scheduler tick from the monorepo root:
corepack pnpm jobs:tick
```


## 实现流程

共享的 JobRunner 契约承诺 enqueue、status 与 cancel。工作流专有语义归 Trigger.dev 所有；不要从通用接口推断调度、重试或持久性保证。

持久的应用任务 ID 把派发、worker 执行、用量记录与结果串起来。已确认入队后，供应商运行元数据挂载失败不得导致再次入队，也不得让已接受的工作失效。


## 验证与排障

如果勾选返回 404，请确认两个设置文件中都存在该密钥并且完全匹配，然后重新启动 Web。如果终端显示连接被拒绝，请先启动Web。如果没有作业运行，请检查计划是否已启用且到期；勾选一次不会立即运行未来的计划。

验证已部署的任务标识与项目同配置环境一致。把入队接受、工作流完成与邮件投递分开。手动重试之前，先读 docs/production-ai-runtime.md 中的恢复与安全诊断说明。


## 下一篇

[电子邮件](https://supastack.dev/zh/docs/web/email.md)