# macOS 上的自托管 Ingest 这项技能将 Inngest 设置为 Mac 上的自托管耐用工作流引擎。 Inngest 为您提供事件驱动的函数，其中每个步骤都会独立重试 - 如果第 3 步（共 5 步）失败，则仅重试第 3 步。 ## 开始之前 **必填：** * 带有 Docker 的 macOS（Docker Desktop、OrbStack 或 Colima） * 用于工作进程的 Bun 或 Node.js **可选：** * k8s集群（Talos on Colima等）用于持久部署 * Redis（用于功能之间的状态共享和网关集成） ## 意图对齐询问用户这些问题以确定范围。 ### 问题 1：您正在构建什么？ 1. **快速实验** — 我想尝试 Inngest，运行一个函数，查看仪表板 2. **持久设置** - 我希望它始终运行，在重新启动后仍然存在，并具有真实的工作流程 3. **完整的基础设施** — 我想要 k8s 部署的 Ingest 具有持久存储，并与代理网关集成 ### 问题 2：worker 的运行时间是多少？ 1. **Bun** — 快速、良好的 TypeScript 支持，joelclaw 使用的 2. **Node.js** — 标准、最广泛的兼容性 3. **现有框架** — 我已经有一个 Next.js/Express/Hono 应用程序 ### 问题3：什么样的工作？ 1. **人工智能代理任务** — 编码循环、内容处理、转录管道 2. **一般后台作业**——计划任务、webhooks、数据处理 3. **两者** — 混合工作负载 ## 设置等级 ### 签名密钥（必需）截至 2026 年 2 月，“inngest/inngest:latest”需要签名密钥。如果没有它们，容器就会崩溃并显示“错误：需要签名密钥”。 # 生成一次，跨层复用 INNGEST_SIGNING_KEY="signkey-dev-$(openssl rand -hex 16)" INNGEST_EVENT_KEY="evtkey-dev-$(openssl rand -hex 16)" echo "INNGEST_SIGNING_KEY=$INNGEST_SIGNING_KEY" >> .env.inngest echo "INNGEST_EVENT_KEY=$INNGEST_EVENT_KEY" >> .env.inngest ### 第 1 层：Docker One-Liner（实验）在 30 秒内让 Ingest 运行： docker run -d --name inngest \ -p 8288:8288 \ -e INNGEST_SIGNING_KEY="$INNGEST_SIGNING_KEY" \ -e INNGEST_EVENT_KEY="$INNGEST_EVENT_KEY" \ 摄取/摄取：最新\ 摄取开始--主机0.0.0.0 打开 — 您应该看到 Inngest 仪表板。 **限制：** 无持久状态。容器重启=历史记录丢失。很适合做实验。 ### 第 2 层：持久 Docker（每日驱动程序）为 SQLite 状态添加卷： docker run -d --name inngest \ -p 8288:8288 \ -v inngest-数据：/var/lib/inngest \ -e INNGEST_SIGNING_KEY="$INNGEST_SIGNING_KEY" \ -e INNGEST_EVENT_KEY="$INNGEST_EVENT_KEY" \ --restart 除非停止 \ 摄取/摄取：最新\ 摄取开始--主机0.0.0.0 现在，Inngest 状态在容器重新启动后仍然存在。 `--restart except-stopped` 在 Docker 重新启动后将其恢复。 ### 第 3 层：Kubernetes（生产级）为了完全坚持适当的健康检查。需要 k8s 集群（Colima 上的 Talos 等）。 # inngest.yaml api版本：apps/v1 种类：StatefulSet 元数据：名称：摄取命名空间：默认规格： serviceName: inngest-svc # NOT "inngest" — 避免环境变量冲突副本：1 选择器：匹配标签：应用程序：摄取模板：元数据：标签：应用程序：摄取规格：容器： - 名称：摄取图片：inngest/inngest：最新命令：[“inngest”，“开始”，“--host”，“0.0.0.0”] 端口： - 集装箱端口：8288 体积安装： - 名称：数据挂载路径：/var/lib/inngest 体积声明模板： - 元数据：名称：数据规格：访问模式：[“读写一次”] 资源：要求：存储：5Gi --- api版本：v1 种类：服务元数据： name: inngest-svc # CRITICAL: not "inngest" — k8s 创建冲突的 INNGEST_PORT 环境变量命名空间：默认规格：类型：节点端口选择器：应用程序：摄取端口： - 端口：8288 目标端口：8288 节点端口：8288 申请： kubectl apply -f inngest.yaml **⚠️ 注意事项：** 切勿将 k8s 服务命名为与其运行的二进制文件相同的名称。名为“inngest”的服务创建“INNGEST_PORT=tcp://10.43.x.x:8288”。 Inngest 二进制文件期望“INNGEST_PORT”是一个整数。将其命名为“inngest-svc”。 ## 构建一个 Worker ### 第 1 步：初始化 mkdir my-worker && cd my-worker 面包初始化-y 包子添加 inngest @inngest/ai hono ### 步骤 2：创建 Ingest 客户端 // src/inngest.ts 从“inngest”导入{Inngest}； // 输入事件以获得完整的类型安全类型事件 = { “任务/进程”：{ 数据：{ url：字符串；输出路径：字符串 } }; “任务/已完成”：{ 数据：{ url：字符串；结果：字符串 } }; }; 导出 const inngest = new Inngest({ id：“我的工人”，架构： new EventSchemas().fromRecord(), }); ### 第 3 步：编写您的第一个函数 // src/functions/process-task.ts 从“../inngest”导入{ inngest }；导出 const processTask = inngest.createFunction( { id: "进程任务", concurrency: { limit: 1 }, // 一次一个重试次数：3， }, { 事件：“任务/进程” }, 异步（{事件，步骤}）=> { // 第 1 步：下载 — 失败时独立重试 const localPath = wait step.run("下载", async () => { const 响应 = 等待 fetch(event.data.url); const buffer =等待response.arrayBuffer(); const 路径 = `/tmp/downloads/${crypto.randomUUID()}.bin`; 等待 Bun.write(路径, 缓冲区); 返回路径； // 仅路径存储在步骤状态中（声明检查模式） }); // 步骤 2：处理 — 如果失败，下载不会重新运行 const result = wait step.run("进程", async () => { const data = wait Bun.file(localPath).text(); // ...你的处理逻辑返回 { 已处理：true，大小：data.length }； }); // 步骤 3：发出完成事件 - 链接到其他函数等待步骤.sendEvent("通知完成", { name: "任务/已完成", 数据: { url: event.data.url, 结果: JSON.stringify(result) }, }); 返回 { 状态：“完成”，结果 }; } ）； ### 步骤 4：上菜 // src/serve.ts 从“hono”导入{Hono}；从“inngest/hono”导入{充当inngestServe}；从“./inngest”导入{ inngest }；从“./functions/process-task”导入{processTask}； const app = new Hono(); // 健康检查 app.get("/", (c) => c.json({ 状态: "正在运行", 函数: 1 })); // Ingest端点——向服务器注册函数应用程序.on( [“获取”，“发布”，“放置”]， “/api/inngest”， inngestServe({ 客户端: inngest, 函数: [processTask] }) ）；导出默认值{ 端口：3111，获取：app.fetch， }; ### 第 5 步：运行它 INNGEST_DEV=1 包运行 src/serve.ts 工作进程启动，在 localhost:8288 上向 Inngest 注册，您的函数将显示在仪表板中。 ### 第 6 步：测试通过仪表板（事件→发送事件）或curl发送事件：卷曲 -X POST http://localhost:8288/e/key \ -H“内容类型：application/json”\ -d '{"name": "任务/进程", "data": {"url": "https://example.com/file.txt", "outputPath": "/tmp/out"}}' 观看它在仪表板中逐步执行。 ## 模式 ### 事件链函数 A 发出一个事件来触发函数 B： // 在函数A中： wait step.sendEvent("chain", { name: "pipeline/step-two", data: { result } }); // 函数 B 触发该事件：导出 const stepTwo = inngest.createFunction( { id: "第二步" }, { 事件：“管道/第二步” }, async ({ 事件, 步骤 }) => { /* ... */ } ）； ### 并发键每个项目运行一个实例，但允许跨项目并行：并发：{ 键：“事件.数据.项目”，限制：1， } ### 定时任务函数导出 const heartbeat = inngest.createFunction( { id: "心跳" }, [{ cron: "*/15 * * * *" }], 异步（{步骤}）=> { 等待步骤.run（“检查健康”，async（）=> { // ...系统健康检查 }); } ）； ### 声明检查模式步骤之间的大数据：写入文件、传递路径。 // ❌不要：从步骤返回大数据 consttranscript=awaitstep.run(“转录”，async()=>{ 返回 { 文本：巨大的字符串 }; // 步骤输出有大小限制！ }); // ✅ DO：写入文件，返回路径 const scriptPath = wait step.run("转录", async () => { const 结果 = 等待转录（audioPath）；等待 Bun.write("/tmp/transcript.json", JSON.stringify(结果)); 返回“/tmp/transcript.json”； }); ## 使其在重启后仍能生存 ### Worker 通过 launchd <字典> 标签com.you.inngest-worker 程序参数 <数组> <字符串>/Users/you/.bun/bin/bun <字符串>运行 <字符串>/path/to/your/worker/src/serve.ts 环境变量 <字典> <键> INNGEST_DEV <字符串> 1 HOME/Users/you PATH/usr/local/bin:/usr/bin:/bin:/Users/you/.bun/bin RunAtLoad 保持活动 StandardOutPath/tmp/inngest-worker.log StandardErrorPath/tmp/inngest-worker.log 工作目录/path/to/your/worker 负载： launchctl 加载 ~/Library/LaunchAgents/com.you.inngest-worker.plist ### 重启后会发生什么 1. Docker启动→Inngest服务器出现持久状态（SQLite） 2. launchd启动→工作进程注册函数 3. 任何不完整的函数都会从最后完成的步骤继续运行 ## 陷阱 1. **`@inngest/ai` 是必需的对等部门。** 仅靠 `bun add inngest` 是不够的 — SDK 在启动时导入 `@inngest/ai`。工作线程因“找不到模块‘@inngest/ai’”而崩溃。始终安装两者。 2. **Docker 到主机网络。** 如果 Inngest 在 Docker 中运行并且工作线程在主机上运行，则服务器无法访问 `localhost:3111`。在 docker run 命令上传递 `--sdk-url http://host.docker.internal:3111/api/inngest` 。这是 Docker Desktop/OrbStack 特定的； Linux Docker 需要 `--add-host=host.docker.internal:host-gateway`。 3. **k8s 中的服务命名：** 切勿将服务命名为与二进制文件相同的名称。 `INNGEST_PORT` 环境变量冲突导致容器崩溃。 4. **步输出大小：** 保持步返回值较小。对大数据使用声明检查模式。 5. **Worker重新注册：** Inngest服务器重启后，Worker需要重新注册。重新启动工作程序或点击注册端点。 6. **触发器漂移：** 函数在启动时注册其触发器。如果您更改代码中的触发器但服务器处于陈旧状态，则旧触发器将保持活动状态。建立一个审计员或重新启动服务器和工作人员。 7. **`INNGEST_DEV=1`:** 本地开发所需。如果没有它，工作人员会尝试向 Inngest Cloud 注册。 8. **GPU 工作的并发 = 1：** 转录、推理 — 任何使 GPU 饱和的内容都需要“并发：{ limit: 1 }”。 ## 验证 * Ingest 仪表板可通过访问 * 工作人员在仪表板（“功能”选项卡）中显示为已注册 * 发送测试事件——函数在仪表板中执行 * 在功能中杀死工作人员 - 重新启动工作人员，功能从上一步恢复 *（第 2 层+）重新启动 Docker — Inngest 状态被保留 * (launchd) 重启 Mac——worker 和 Inngest 都会自动回来 ## 设置脚本（curl-first）对于自动设置，用户可以运行：卷曲-sL joelclaw.com/scripts/inngest-setup.sh |巴什或者具有特定级别：卷曲-sL joelclaw.com/scripts/inngest-setup.sh | bash -s -- 2 该脚本是幂等的，可以检测现有状态，并为具有类型化事件的工作人员提供支架。 ## 决策链（压缩 ADR）该技能的架构由架构决策记录链支持。根据权衡上下文的需要展开。 **ADR-0010 → ADR-0029 → 当前状态** 决定|选择|关键权衡|链接 ---|---|---|--- 工作流引擎| Ingest（自托管）|步骤级耐用性与复杂性。 Cron+scripts 没有每步重试。 | [ADR-0010]() 容器运行时 | Colima（VZ框架）|取代 Docker 桌面。免费、无头、内存较少。 | [ADR-0029]() 用于 3 个容器的 k8s |是（科利马州塔洛斯）|协调循环 + 多节点未来的 380MB 开销。 Docker Compose = 没有自我修复功能。 | [joel-deploys-k8s]() 服务命名 | `inngest-svc` 不是 `inngest` | k8s 注入 `INNGEST_PORT` 环境变量。二进制需要整数，获取 URL。 |来之不易的调试工人运行时 |包子 + 霍诺 |冷启动速度比 Node.js 更快。 Hono = 最小 HTTP。启动 KeepAlive 以实现持久性。 |实用选择步骤数据模式|声明检查（文件路径）|步输出有大小限制。将大数据写入磁盘，在步骤之间传递路径。 |收录文档触发审计|心跳 cron 审计员 |无声触发漂移使升级功能中断了好几天。现在每 15 分钟审核一次。 | [ADR-0037]() ## 学分 * [Inngest]() — 工作流引擎 * [joelclaw.com/inngest-is-the-nervous-system]() — 架构叙述 * [joelclaw.com/self-hosting-inngest-background-tasks]() — 人类摘要

本地摄取

包含技能