企业官网建设流程全解析

如何把 Mastra workflows 部署到 Inngest 获得步骤记忆化与自动重试

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

如果你在本地用 Mastra 内置 runner 跑 workflow，步骤结果依赖进程内存，进程一旦崩溃就要从头再来。把 workflow 部署到 Inngest 之后，编排、重试和状态记忆交给 Inngest 平台：每个 Mastra workflow 变成一个带唯一标识的 Inngest function，每个createStep映射为一个 Inngest step；事件触发后 Inngest 逐步执行 workflow 并记忆化（memoize）每个步骤的结果，重试或恢复时直接跳过已完成的步骤。前提条件：inngest@^4SDK、Inngest Dev Serverv1.18.0或更高版本。v4 的 SDK 已内置 Realtime，不再需要@inngest/realtime和realtimeMiddleware。

安装依赖

npm install @mastra/inngest@latest inngest

初始化 Inngest 客户端

开发环境（指向本地 Dev Server）：

import { Inngest } from 'inngest' export const inngest = new Inngest({ id: 'mastra', baseUrl: 'http://localhost:8288', isDev: true, })

生产环境去掉isDev和baseUrl：

import { Inngest } from 'inngest' export const inngest = new Inngest({ id: 'mastra', })

也可以不写死模式，用INNGEST_DEV环境变量让同一份客户端代码跨环境工作：

• INNGEST_DEV=1：强制 dev 模式，SDK 连接本地 Inngest Dev Server 并关闭签名校验；
• INNGEST_DEV=0：强制 cloud 模式，连接 Inngest Cloud，需要 event key 和 signing key；
• INNGEST_DEV=<url>：dev 模式并指定 Dev Server 地址，例如http://localhost:8288；
• 不设置：默认 cloud 模式（v4 SDK 默认 cloud 模式，需要INNGEST_EVENT_KEY和INNGEST_SIGNING_KEY）。

设置INNGEST_DEV后可以从客户端代码里删掉isDev和baseUrl。注意：生产环境不要设置INNGEST_DEV，它会关闭接收 Inngest Cloud 事件所必需的签名校验。若同时设置了isDev和INNGEST_DEV，isDev优先生效。

创建步骤与 workflow

init(inngest)返回与 Mastra 和 Inngest 双兼容的createWorkflow/createStep。以下示例是一个计数器 workflow，用于后续验证（与文档示例一致）：

import { z } from 'zod' import { inngest } from '../inngest' import { init } from '@mastra/inngest' // Initialize Inngest with Mastra, pointing to your local Inngest server const { createWorkflow, createStep } = init(inngest) // Step: Increment the counter value const incrementStep = createStep({ id: 'increment', inputSchema: z.object({ value: z.number(), }), outputSchema: z.object({ value: z.number(), }), execute: async ({ inputData }) => { return { value: inputData.value + 1 } }, }) // workflow that is registered as a function on inngest server const workflow = createWorkflow({ id: 'increment-workflow', inputSchema: z.object({ value: z.number(), }), outputSchema: z.object({ value: z.number(), }), }).then(incrementStep) workflow.commit() export { workflow as incrementWorkflow }

在 Mastra 实例上注册并暴露 serve 端点

serve()负责把 Mastra workflows 注册为 Inngest functions，并建立执行与监控所需的事件处理。自定义路由路径是/inngest/api，不是/api/inngest：Mastra 把/api前缀保留给内置路由（agents、workflows、memory），以默认apiPrefix（/api）开头的自定义apiRoutes路径会在启动时直接抛错。如果你必须保留/api/inngest（比如匹配 Inngest 的 auto-discover 约定），见文末"改用 /api/inngest"。

import { Mastra } from '@mastra/core' import { serve } from '@mastra/inngest' import { incrementWorkflow } from './workflows' import { inngest } from './inngest' import { PinoLogger } from '@mastra/loggers' export const mastra = new Mastra({ workflows: { incrementWorkflow }, server: { host: '0.0.0.0', apiRoutes: [ { path: '/inngest/api', method: 'ALL', createHandler: async ({ mastra }) => { return serve({ mastra, inngest }) }, }, ], }, logger: new PinoLogger({ name: 'Mastra', level: 'info' }), })

本地运行并验证记忆化与重试行为

1. 启动 Mastra 服务器，默认监听 4111 端口：

   npx mastra dev

2. 新开终端启动 Inngest Dev Server，-u参数告诉 Dev Server 到哪里找你的/inngest/api端点：

   npx inngest-cli@latest dev -u http://localhost:4111/inngest/api

3. 打开 Inngest Dashboard（http://localhost:8288），在侧边栏Apps区确认你的 Mastra workflow 已注册。

4. 在Functions里打开 workflow，选择Invoke，输入：

   { "data": { "inputData": { "value": 5 } } }

5. 在Runs页签监控执行，可以看到逐步骤的执行进度；每个步骤执行时的状态与输出都会被跟踪，必要时可以 resume。重试或恢复时，Inngest 依据已保存的 memoization 结果跳过已完成步骤——这就是部署到 Inngest 后 workflow 获得的 durable 行为。

部署到生产

文档给出的生产路径是部署到 Vercel。开始前的清单：

• Vercel 账号，并已安装 Vercel CLI（npm i -g vercel）；
• Inngest 账号；
• Vercel token。

1. 设置 Vercel token：

   export VERCEL_TOKEN=your_vercel_token

2. 在 Mastra 实例中添加VercelDeployer（your_team_slug、your_project_name替换为你自己的团队和项目）：

   import { VercelDeployer } from '@mastra/deployer-vercel' export const mastra = new Mastra({ deployer: new VercelDeployer({ teamSlug: 'your_team_slug', projectName: 'your_project_name', // you can get your vercel token from the vercel dashboard by clicking on the user icon in the top right corner // and then clicking on "Account Settings" and then clicking on "Tokens" on the left sidebar. token: process.env.VERCEL_TOKEN, }), })

3. 构建：

   npx mastra build

4. 部署：

   cd .mastra/output vercel login vercel --prod

5. 在 Inngest dashboard 中选择Sync new app with Vercel并按提示完成同步。这里有一个容易踩的坑：Inngest 的 auto-discover 约定假设路径是/api/inngest，而本指南用的是/inngest/api，所以必须把 Inngest app 的URL字段手动设为部署域名加/inngest/api（例如https://your-app.vercel.app/inngest/api）。保持默认值的话，dashboard 将找不到你的 app functions。

6. 在Functions中打开workflow.increment-workflow，选择All actions>Invoke，输入与本地相同的 JSON 载荷，然后在Runs页签确认步骤级执行进度。

备选：用 connect() 跑长驻 worker

如果你运行在无公网入口的私有网络（Kubernetes、Docker、ECS、Fly.io、Render 等长驻进程），不想暴露 HTTP 端点，可以用connect()建立 worker 到 Inngest 的出站长连接，Mastra server 在这种情况下不需要暴露/inngest/api。要求：inngest@^4、Node.js22.13.0及以上、一个长驻进程。注意 Inngest Connect 目前处于 public beta，Vercel、AWS Lambda 这类 serverless 运行时不支持 Connect worker，这类环境请继续用serve()：

import { connect } from '@mastra/inngest/connect' import { mastra } from './mastra' import { inngest } from './mastra/inngest' await connect({ mastra, inngest, instanceId: process.env.INNGEST_CONNECT_INSTANCE_ID, maxWorkerConcurrency: Number(process.env.INNGEST_CONNECT_MAX_WORKER_CONCURRENCY ?? 10), })

本地开发用INNGEST_DEV=1 node --import tsx src/worker.ts启动 worker，Dev Server 通过出向连接发现它，不需要-u参数。生产设置INNGEST_EVENT_KEY和INNGEST_SIGNING_KEY，并在Inngest客户端上把appVersion设为部署标识（commit SHA 或镜像 tag），便于 Inngest 管理滚动部署。从serve()迁移到connect()的存量生产应用，文档建议先用一个独立的 Inngest app 测试 worker，再切流量。

改用 /api/inngest：自定义 apiPrefix

如果一定要保留/api/inngest路径以匹配 Inngest 的 auto-discover 约定，就把server.apiPrefix改掉，把 Mastra 内置路由挪走：

import { Mastra } from '@mastra/core' import { serve } from '@mastra/inngest' import { inngest } from './inngest' export const mastra = new Mastra({ server: { apiPrefix: '/_mastra', apiRoutes: [ { path: '/api/inngest', method: 'ALL', createHandler: async ({ mastra }) => serve({ mastra, inngest }), }, ], }, })

改完后内置路由落在/_mastra/agents、/_mastra/workflows等处，/api/inngest空出来给自定义路由。注意默认 auth 配置保护的是/api/*并把/api、/api/auth/*视为公开，改apiPrefix后这些默认值不再匹配，需要同步更新server.auth.protected、server.auth.public，以及所有访问/api/*的客户端代码（包括MastraClient的apiPrefix）。

参考资料

• Inngest 部署指南全文（含 Express / Fastify / Koa / Next.js 适配器和 flow control 配置）：Inngest
• Workflow runners 总览（Inngest 与 Temporal 的取舍）：Workflow runners
• 完整示例（含 observability、cron、flow control、durable agents）：examples/inngest/README.md

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra